Defining page formats

A page format contains formatting controls for your data set that indicate where and how text, and optionally, page overlays and page segments are to be placed on the page. The page format is defined relative to the origin of the sheet specified in the form definition. A page format can specify one of three types of data:

• Traditional line data, which might contain CCs and TRCs
• Record format line data, which contains record IDs and might contain CCs
• XML data

All page formats in the page definition must specify the same type of data. If you do not specify a type of data, the page format assumes you are using traditional line data. For information about using types of line data, see Line data or see Advanced Function Presentation: Programming Guide and Line Data Reference, S544-3884. For information about using XML data, see XML data.

A page format can contain the following information:

• Size of the page area to be formatted, specified as the width and height of the page (required)
• Print direction
• Relative print line positioning
• Options for already formatted print records
• Formatting options for individual fields in print records
• Fonts
• Conditional processing

Page size

The page size, width, and height are defined in the page format. This area is called the logical page. All the text and images contained in your print data set must fit within the boundaries of this logical page.

The logical page should cover the entire area of the physical form on which your data can print. If you are printing multiple-up applications (in which two or more pages of application data are formatted on the same side of a physical form), you must make your logical page large enough to contain all the pages of application data (this applies only to multiple-up formatting for which a page definition is used; it does not apply to N_UP printing).

Characters or images that extend outside the boundaries of the logical page cannot be printed. Whether you receive error messages indicating the characters or images were not printed depends on the value in the DATACK parameter. For more information, see DATACK.

Be careful when positioning text near the top or bottom of the logical page area. The position you specify for character data in your page definition is the position at which the baseline of the characters are printed.¹⁰ When you position character data in a page definition, be sure to leave room for the characters and their ascenders and descenders. For example, never place a character 0 inches down from the top of the page.

Also be careful not to extend data off the right side of the page, which can happen if your print lines are too long, or if you used a font that is too large to fit within your page area.

In most cases you do not need to be concerned with placing characters too near the left margin of the page. Characters are positioned from the front or leading edge of their baseline, so that a character can be placed at the exact left edge of the logical page. Italic fonts, however, can extend off the left edge of the page because they are kerned to tuck under the adjacent characters. Some italic characters extend a few pels to the left of their character space origin. Therefore, when you print with an italic font, be sure to position the text line a few pels to the right of the left edge of the logical page.

For more information about character baselines and positioning, see IBM AFP Fonts: Font Summary for AFP Font Collection, S544-5633 or z/OS Font Collection.

Print direction

The page format assigns a print direction to the lines of text in the logical page. The print direction can be one of four inline directions supported by AFP printers:

• ACROSS—oriented 0° from the page origin
• DOWN—oriented 90° from the page origin
• BACK—oriented 180° from the page origin
• UP—oriented 270° from the page origin

In addition to print direction, AFP text can be printed in four character rotations: 0°, 90°, 180°, and 270°. Each of these character rotations is specified relative to the print direction. Unless you specify otherwise, a 0° rotation is used with any print direction you select for your page definition. For more information about print direction and character rotation, see Printing AFP data in different directions and character rotations.

Not all AFP printers can print in every combination of print direction and character rotation. For information about the print orientations your printer supports, see the documentation provided with the printer.

Figure 2 shows the different print directions possible on AFP printers. For information about the relationship between print direction and page origin, see Page position.

Figure 28. Pages printed in two directions on continuous-forms paper

Relative print line positioning in a page definition

Relative print line is a function of the page definition that lets formatting float on the page. In some earlier releases of PSF, all page definition formatting was tied to a specific position on the page. With relative print line, values in the print data carriage control byte can determine different formatting to be applied to the current page position. This function lets the application change record formatting, print line spacing, fonts, overlays, and page segments at any page position, without writing MO:DCA-P structured field commands in the print data.

Relative print line provides increased formatting flexibility. It also preserves the benefit of using page definition formatting, which lets you make changes to the printed output without changing the application program that generates that output.

In many cases, using a page definition to format can reduce the time required to develop and test an application. However, relative print line does not eliminate application development requirements: the application must write print records that can take advantage of the formatting capability.

Page format options for formatted print records

When the print data set contains records that are already formatted into output print lines, you can specify additional formatting options in the page format. For this type of data stream, you can use the page format to:

• Specify the number of print lines per page
• Specify the number and starting position for a group of lines on a page
• Specify how carriage controls in the data are to be processed
• Specify the position on the page at which channel codes in the data are to start
• Change line spacings for groups of lines within the page
• Select fonts for the entire page or for groups of lines or fields on a page
• Provide a list of fonts for selection by table reference characters (TRCs) in the data
• Change print directions of one or more lines
• Change the character rotation of a font for one or more lines
• Define and place fields of constant text on each page with the variable data
• Define, place, and select fonts for fields of variable data
• Indicate variable data fields to be generated as bar codes
• Define conditional processing tests on the input record to effect formatting changes
• Include page segments or overlays anywhere on a page
• Provide a list of page segments to be mapped in the printer
• Provide a list of page overlays to be included by the print data set
• Select multiple colors, if the printer supports multiple colors
  Note:

  Not all printers support multiple colors. For information about color support for your printer, see the documentation provided with the printer.
• Specify an absolute or relative position for records, fields, or objects

Page format options for formatting fields

You can use the page definition not only to place records that are formatted into print lines, but also to format individual fields within print records. The page format specifies the position, the print direction, and the font for each individual field that you want printed. You can also prevent fields in the print record from printing, by simply not specifying them in the page format. You can use field formatting to change the output for formatted print records that you are currently printing, or you can use field formatting to print unformatted print records that are not formatted into print lines but that contain only the data to be printed.

This capability of AFP enables an application program to generate only the variable data to be printed. The data fields in the print record can be generated in any sequence by the program. Specifications in the page format let you use each field more than one time, if you so choose, and place a field at any position on the page. Because the format of the printed output can be changed without affecting the application program, maintaining applications is easier. In addition, provided that all of the necessary data fields are contained in the print records, new report formats can be created from an existing application by simply creating a new page definition or page format.

When you format fields from application print records, the page format can be used to:

• Define conditional processing tests based on individual fields in the data.
• Specify the starting position and length in the print record for each field to be formatted.
• Place each field on the page with absolute or relative positioning.
• Specify different print directions for fields within the page, and, optionally, character rotation.
• Select fonts for each field.
• Identify fields that can be suppressed (that is, not printed) on some copies of output or in some transmissions of the output data set.
• Identify fields to be generated as bar codes.
• Define and place fields of constant text on each page with the variable data.
• Select a color for each field, if the printer supports multiple colors.
  Note:

  Not all printers support multiple colors. For information about color support for your printer, see the documentation provided with the printer.

Formatted and unformatted print records can be used together in an application program to add formatting flexibility.

Fonts

You can specify fonts in a page format in several ways:

• You can name a single font for printing all the text on the page.
• You can name different fonts for use with groups of lines, a single line, or data fields in a record.
• You can add a character rotation parameter to a specified font to rotate characters in the inline print direction, as described in Printing AFP data in different directions and character rotations.
• You can specify fonts in a font list for selection by including table reference characters (TRCs) in the data.

If your JCL specifies a page definition that specifies one or more fonts, those fonts are used instead of fonts named in the JCL CHARS parameter (see CHARS) or UCS parameter (see UCS). If you want to select FOCA fonts with the JCL CHARS parameter, do not use a page definition that names fonts.

If you are using the default page definition for a printer, you can select fonts with the JCL CHARS or UCS parameter, even if the default page definition specifies a font.¹¹ A default page definition modified by the CHARS or UCS parameter is classified as a modified-default page definition.

If you are using TRCs to select fonts, you can specify the fonts either in a font list in the page format, or in the JCL CHARS parameter. For rules that might affect your decision about where to specify fonts, see Using table reference characters to select fonts.

You can use the PPFA FONT command to select either raster fonts or outline fonts. You can also specify scaling information and size for outline fonts. Coordinate the line spacing with the size of the font you are using.

When the page definition specifies record format processing, font specifications external to the page definition are ignored.

Conditional processing

You can use the conditional-processing function to:

• Define tests to be performed on fields in selected input records. These tests are called conditions.
• Specify actions that you want PSF to perform when certain conditions are met.

The actions PSF can conditionally perform are:

• Activating a different copy group. You can do this to change options such as offset stacking and bin selection.
• Activating a different page format. You can do this to change options such as print direction and line spacing.
• Starting a new page.
• Starting a new sheet.

You can also specify when PSF is to perform the conditional actions:

• Before the current line is formatted
• Before the current subpage is formatted
• After the current line is formatted
• After the current subpage is formatted

Because you can specify that PSF is to change processing options before the current line or subpage, you can test an input record and change the processing options before that record is printed. For example, you can specify that when the contents of a certain field in a record are different from the contents of the corresponding field in the preceding record, PSF starts printing on a new page.

Conditional processing for multiple-up applications

The printable portion of a sheet can be divided into sections called subpages, each having the appearance of a smaller printed page, as in Figure 29. Subdividing the printed page in this way is called multiple-up printing. In the figure, the traditional line data is printed with subpages to give the appearance of four separate pages. Do not confuse multiple-up printing with N_UP printing, which places up to four actual logical pages of data on one side of a sheet.

Figure 29. One logical page divided into four subpages

You can use multiple-up processing with or without defining sections of the page as subpages. However, you must define subpages to perform conditional processing either before or after one of the subdivisions (subpages) of a multiple-up page. You can only use multiple-up printing with traditional line data.

With the IBM® Page Printer Formatting Aid program, you can identify the input records that form a subpage. For more information, see Page Printer Formatting Aid: User’s Guide.

Multiple conditions

With conditional processing you can specify more than one condition and corresponding action for the same input record. You can also specify conditions and actions for more than one line in a subpage. If your page definition contains such multiple conditions, more than one of the conditions can be met.

PSF handles multiple conditions as follows:

• If you define multiple conditions for the same input record, PSF performs the specified action for the first condition that is met. PSF will not perform any other conditional actions for that input record.
• If you define conditions for more than one input record in the same subpage, and if a condition is met that specifies that PSF is to take an action after the current subpage is formatted, PSF will not perform any other conditional actions for subsequent records in that subpage.

Reprocessing

Reprocessing occurs when PSF is requested to perform an action either before the current line is formatted or before the current subpage is formatted. In these cases, PSF must reprocess one or more input records, perhaps using a new copy group or page format.

While reprocessing records, PSF does not perform some conditional actions that would require additional reprocessing. Because of these restrictions, you might get unexpected results.

When PSF reprocesses records because a condition specified that PSF was to perform an action before the current line, this restriction applies:

• PSF does not perform actions specified to occur either before the line or before the subpage. This restriction is in effect only for the one input record being reprocessed.

When PSF reprocesses records because a condition specified that PSF was to perform an action before the current subpage, these restrictions apply:

• PSF does not perform actions specified to occur before the current subpage. This restriction is in effect for all of the input records in the current subpage.
• PSF does not perform actions specified to occur before the current line. This restriction is in effect only for the first input record in the current subpage.