ILE COBOL Programmer's Guide

Describing Printer Files

Once you have named the printer file in the Environment Division, you must then describe the printer file through a file description entry in the Data Division. See the WebSphere Development Studio: ILE COBOL Reference for a full description of the File Description Entry. Use the Format 4 File Description Entry to describe a printer file.

Printer files can be program-described or externally described. Program-described printer files are assigned to a device of PRINTER. Externally described printer files are assigned to a device of FORMATFILE. Using FORMATFILE allows you to exploit the AS/400 function to its maximum, and using PRINTER allows for greater program portability.

The use of externally described printer files has the following advantages over program-described printer files:

Use of the ADVANCING phrase for FORMATFILE files causes a compilation error to be issued. Advancing of lines is controlled in a FORMATFILE file through DDS keywords, such as SKIPA and SKIPB, and through the use of line numbers.

Describing Program-Described Printer Files

Program described printer files must be assigned to a device of PRINTER. A simple file description entry in the Data Division that describes a program described printer file looks as follows:

FD  print-file.
01  print-record               PIC X(132).

Using the LINAGE Clause to Handle Spacing and Paging Controls

You can request all spacing and paging controls be handled internally by compiler generated code by specifying the LINAGE clause in the file description entry of a program described printer file.

FD  print-file
    LINAGE IS integer-1 LINES
           WITH FOOTING AT integer-2
           LINES AT TOP integer-3
           LINES AT BOTTOM integer-4.
01  print-record               PIC X(132).

Paper positioning is done only when the first WRITE statement is run. The paper in the printer is positioned to a new physical page, and the LINAGE-COUNTER is set to 1. When the printer file is shared and other programs have written records to the file, the ILE COBOL WRITE statement is still considered to be the first WRITE statement. Paper positioning is handled by the ILE COBOL compiler even though it is not the first WRITE statement for that file.

All spacing and paging for WRITE statements is controlled internally. The physical size of the page is ignored when paper positioning is not properly defined for the ILE COBOL compiler. For a file that has a LINAGE clause and is assigned to PRINTER, paging consists of spacing to the end of the logical page (page body) and then spacing past the bottom and top margins.

Use of the LINAGE clause degrades performance. The LINAGE clause should be used only as necessary. If the physical paging is acceptable, the LINAGE clause is not necessary.

Describing Externally Described Printer Files (FORMATFILE)

Externally described printer files must be assigned to a device of FORMATFILE. The term FORMATFILE is used because the FORMAT phrase is valid in WRITE statements for the file, and the data formatting is specified in the DDS for the file. A simple file description entry in the Data Division that describes an externally described printer file looks as follows:

FD  print-file.
01  print-record.
    COPY DDS-ALL-FORMATS-O OF print-file-dds.

Create a DDS for the FORMATFILE file you want to use. For information on creating a DDS, refer to the Database and File Systems category in the iSeries 400 Information Center at this Web site -http://publib.boulder.ibm.com/pubs/html/as400/infocenter.htm.

Once you have created the DDS for the FORMATFILE file, use the Format 2 COPY statement to describe the layout of the printer file data record. When you compile your ILE COBOL program, the Format 2 COPY will create the Data Division statements to describe the printer file. Use the DDS-ALL-FORMATS-O option of the Format 2 COPY statement to generate one storage area for all formats.

When you have specified a device of FORMATFILE, you can obtain formatting of printed output in two ways:

  1. Choose the formats to print and their order by using appropriate values in the FORMAT phrases specified for WRITE statements. For example, use one format once per page to produce a heading, and use another format to produce the detail lines on the page.
  2. Choose the appropriate options to be taken when each format is printed by setting indicator values and passing these indicators through the INDICATOR phrase for the WRITE statement. For example, fields may be underlined, blank lines may be produced before or after the format is printed, or the printing of certain fields may be skipped.

The LINAGE clause should not be used for files assigned to FORMATFILE. If it is, then a compile time error message is issued indicating that the LINAGE clause has been ignored.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]