Subcommands

COMMENT Subcommand
COMMENT ' qstring'…

Specifies a user comment. This string comment is placed in the NOP structured field of the page definition.

'qstring'
Specifies a quoted set of strings from 1 to 255 characters in total length.
WIDTH Subcommand
WIDTH {8.3 IN | n [unit]}

Defines the width of the logical page.

n
A number with up to three decimal places is used. The width may vary according to the type of printer being used. For more information, refer to your printer documentation. The default is 8.3 IN.
unit
Specifies a unit of measurement for the WIDTH subcommand. The choices are IN, MM, CM, POINTS, or PELS.
Note: If no unit is specified, the default is the most recent SETUNITS command value or IN (inch) if a SETUNITS command has not been issued.
HEIGHT Subcommand
HEIGHT {10.8 IN | n [unit]}
Defines the height of the logical page.
n
A number with up to three decimal places is used. The height may vary according to the type of printer being used. For more information, refer to your printer documentation. The default is 10.8 IN.
unit
Specifies a unit of measurement for the HEIGHT subcommand. The choices are IN, MM, CM, POINTS, and PELS.
Note: If no unit is specified, the default is the most recent SETUNITS command value or IN (inch) if a SETUNITS command has not been issued.
LINEONE Subcommand (Traditional)
LINEONE x-pos y-pos
Specifies the values for the MARGIN and TOP parameters used in the POSITION subcommand of the PRINTLINE command.
x-pos
Specifies the offset from the left edge of the logical page (margin position). The valid options for x-pos are described in the SETUNITS command for the horizontal value.
Note: If no unit is specified, the default is the most recent SETUNITS command value or IN (inch) if a SETUNITS command has not been issued.
y-pos
Specifies the vertical offset from the top of the logical page (top line position). The valid options for y-pos are described in the SETUNITS command for the vertical value.
Note: If no unit is specified, the default is the most recent SETUNITS command value or IN (inch) if a SETUNITS command has not been issued.
DIRECTION Subcommand
DIRECTION {ACROSS | DOWN | BACK | UP}
Specifies the print direction of the logical page. Not all printers can print in all print directions. For more information, refer to your printer documentation.
Note: Some printers have a different media origin and require different direction settings than most page printers. For printing in the landscape page presentation when using wide forms, the PRESENT subcommand must be specified on the FORMDEF command to produce readable output. Alternatively, if you have existing page definitions, the UP direction can be used in the page definition without changes to the form definition to produce the same result.
ACROSS
The page is printed with the characters added left to right in each line, and the lines added from the top to the bottom.
DOWN
The page is printed with the characters added to the page from top to bottom, and the lines added from the right to the left.
BACK
The page is printed with the characters added to the page from right to left, and the lines added from the bottom to the top.
UP
The page is printed with the characters added to the page from bottom to top, and the lines added from the left to the right.

For Record Format and XML, DIRECTION affects the meaning of the following new margin parameters:

  • If the DIRECTION is ACROSS, then TOPMARGIN refers to the margin in the short end of the physical page where the tops of the characters point toward that same short end.
  • If the DIRECTION is DOWN, then TOPMARGIN refers to the margin in the long end of the physical page where the tops of the characters point toward that same long end.

REPLACE Subcommand
REPLACE {NO | YES}
Specifies whether this page definition is to replace an existing one with the same resource name in the library.
NO
This page definition does not replace one with the same resource name in the library.

If a page definition with the same resource name does not exist in the library, this page definition is stored.

YES
If a page definition with the same resource name already exists in the library, this page definition replaces it.

If a page definition with the same resource name does not exist in the library, this page definition is stored.

PELSPERINCH Subcommand
PELSPERINCH n
Specifies the Logical Units in pels per inch for this page definition. Use the PELSPERINCH parameter to tell PPFA the pel resolution of your printer to generate more exact object placements.
n
Specifies an integer number between 1 and 3,276, which determines the Logical Units in pels per inch.
Note: If the L-Units are not specified on this page definition, they are defaulted to 240 pels per inch.

PELSPERINCH example

     PAGEDEF xmp01 replace yes
       PELSPERINCH 300 ;

       PAGEFORMAT P1
          width  7 in
          height 3 in;
        PRINTLINE;

       PAGEFORMAT P2
          width  7 in
          height 3 in
          PELSPERINCH 1200;
        PRINTLINE;

In the example above, the page definition xmp01 has specified L-Units as 300 pels per inch. Because the PAGEFORMAT P1 does not specify L-Units, it inherits 300 pels per inch. PAGEFORMAT P2 does specify L-Units as 1200 pels per inch.

The width and height in PAGEFORMAT P1 ( 7 in, 3 in) produces internal and structured field values of 2100 and 900, whereas in PAGEFORMAT P2 the same code produces values of 8400 and 3600, because of the difference in L-Units.

TOPMARGIN Subcommand (Record Format and XML)
TOPMARGIN n [IN | MM | CM | POINTS | PELS]
Specifies the amount of space to be reserved at the top of the page. The default is 80% of the current line spacing.
BOTMARGIN Subcommand (Record Format and XML)
BOTMARGIN n [IN | MM | CM | POINTS | PELS]
Specifies the amount of space to be reserved at the bottom of the page. Only PAGETRAILER data can be written into this area. If a graphic has not been ended at the time information is being placed in the bottom margin, the graphic is ended prior to the bottom margin. The default is 0.
LEFTMARGIN Subcommand (Record Format and XML)
LEFTMARGIN n [IN | MM | CM | POINTS | PELS]
Specifies the amount of space to be reserved at the left of the page. This is to be used only in conjunction with the DRAWGRAPHIC commands. Although PPFA collects the left margin information, it uses the value only within PPFA to define an area. The value itself is not passed in the datastream. The default is 0.
RIGHTMARGIN Subcommand (Record Format and XML)
RIGHTMARGIN n [IN | MM | CM | POINTS | PELS]
Specifies the amount of space to be reserved at the right of the page. This is only to be used in conjunction with the DRAWGRAPHIC commands. Although PPFA collects the right margin information, it uses the value only within PPFA to define an area. The value itself is not passed in the datastream. The default is 0.
SOSIFONTS Subcommand
SOSIFONTS sbcs-font , dbcs-font
The SOSIFONTS subcommand causes a Single-Byte Character Set (SBCS) font and a Double-Byte Character Set (DBCS) font to be mapped in a manner that will allow the proper font switching when Shift-in and Shift-out control sequences are encountered in printed text.
sbcs-font
A Single-Byte Character Set font. This font will be selected by the print server when a Shift-In (SI) control byte is encountered in text being presented.
dbcs-font
A Double-Byte Character Set font. This font will be selected by the print server when a Shift-Out (SO) control byte is encountered in text being presented.

There are four ways to use SOSI fonts in a Traditional page definition:

  1. In the PAGEDEF, using the FONT placement subcommand to specify both the SBCS and DBCS fonts to be used. To use this method, define both a single-byte and double-byte font with the FONT or DOFONT commands. Then reference both fonts on the FONT subcommand on the FIELD, PRINTLINE, and so forth commands, separated by a comma. The single-byte font goes first. For example: 
    Pagedef sosiP1 replace yes;
  FONT sb1 GT10 SBCS;
  FONT db1 M40F DBCS;
  PAGEFORMAT PF1;
    PRINTLINE POSITION 1 in 1.2 in FONT sb1,db1;
  2. In the PAGEDEF, using the PAGEFORMAT subcommand SOSIFONTS to ensure that a single byte font is mapped first and a double byte font is mapped second in the PAGEFORMAT. To use this method, code both a single-byte and double-byte font with the FONT command. Then use the SOSIFONTS subcommand on the PAGEFORMAT command with the desired SBCS font coded first and the desired DBCS font coded next. For example: 
    Pagedef sosiL1 replace yes;
  FONT sb1 GT10 SBCS;
  FONT db1 M40F DBCS;
  PAGEFORMAT PF1 SOSIFONTS sb1,db1;

    PRINTLINE POSITION 1 in 1.2 in;
    Note: The SOSIFONTS subcommand can also be coded on the PAGEFORMAT command. Any PAGEFORMATs that do not code a SOSIFONTS subcommand will inherit from the PAGEDEF.
  3. Specify fonts using the CHARS JCL parameter and no fonts in the PAGEDEF or no PAGEDEF using the default PAGEDEF. Using this method the first font defined in the CHARS is a SBCS font and the second is a DBCS font.
  4. Use the TRCREF command to defined the SBCS font as 0 and the DBCS font as 1. Do not specify a FONT subcommand on PRINTLINE, FIELD, and other commands when using this method. This method used only with a Traditional page definition. For example: 
    Pagedef sosiL1 replace yes;
  FONT sb1 GT10 SBCS;
  FONT db1 M40F DBCS;
  PAGEFORMAT PF1;
    TRCREF 0 FONT sb1;
    TRCREF 1 FONT db1;
    PRINTLINE;

You cannot mix Data Object fonts (defined with the DOFONT command) with FOCA fonts (defined with the FONT command) in the page definition in any but the first method of specifying SOSI fonts.

There are three ways to use SOSI fonts in a Record Format or XML page definition:

  1. In the PAGEDEF, using the FONT placement subcommand to specify both the SBCS and DBCS fonts to be used. To use this method, you define both a single-byte and double-byte font with the FONT and DOFONT commands. Then you reference both fonts on the FONT subcommand on the FIELD, XLAYOUT, LAYOUT, and so forth commands, separated by a comma. The single-byte font goes first. For example: 
    Pagedef sosiP1 replace yes;
  FONT sb1 GT10 SBCS;
  FONT db1 M40F DBCS;
  PAGEFORMAT PF1;
    LAYOUT 'L1' POSITION 1 in 1.2 in FONT sb1,db1;
  2. In the PAGEDEF, using the PAGEFORMAT subcommand SOSIFONTS to insure that a single byte font is mapped first and a double byte font is mapped second in the PAGEFORMAT. To use this method, code both a single-byte and double-byte font with the FONT command. Then you use the SOSIFONTS subcommand on the PAGEFORMAT command with the desired SBCS font coded first and the desired DBCS font coded next. For example: 
    Pagedef sosiL1 replace yes;
  FONT sb1 GT10 SBCS;
  FONT db1 M40F DBCS;
  PAGEFORMAT PF1 SOSIFONTS sb1,db1;

    LAYOUT 'L1' POSITION 1 in 1.2 in;
    Note: The SOSIFONTS subcommand can also be coded on the PAGEFORMAT command. Any PAGEFORMATs that do not code a SOSIFONTS subcommand will inherit from the PAGEDEF.
  3. Define fonts using the CHARS and no fonts in the PAGEDEF or no PAGEDEF using the default PAGEDEF. Using this method the first font defined in the CHARS is a SBCS font and the second is a DBCS font.

You cannot mix Data Object fonts (defined with the DOFONT command) with normal FOCA fonts (defined with the FONT command) in the page definition in any but the first method of specifying SOSI fonts. That is only when you specify both fonts on the placement command.

UDType Subcommand
UDType {EBCDIC | ASCII | UTF8 | UTF16}
Identifies the encoding of your data.
EBCDIC
Single-byte EBCDIC code page 500. This is the default value for XML page definitions on z/OS.
ASCII
Single-byte ASCII code page 819. This is the default value for XML page definitions on Windows.
UTF8
Unicode encoding form UTF-8 toleration mode (surrogates are allowed).
UTF16
Unicode encoding form UTF-16.
Note: The PAGEDEF is created in UTF-16BE (Big Endian). If the data is in UTF16LE, PSF translates it to UTF-16BE before processing.

For traditional and record format page definitions, there is no default value. This means that no data type information is added to the page definition.

UDType on the PAGEDEF command is used for several things:

  1. To allow PPFA to translate fixed text to the specified UDType from either ASCII or EBCDIC according to the platform on which the PPFA compile is done.
  2. To set the default for all DOFONT (Data Object Font) commands so you do not have to code UDType on each DOFONT command.
  3. To pass encoding information to the printer for converting non-UTF16 user data to UTF16 when using a DOFONT command. (True Type is an example of a DOFONT).
  4. To allow PSF or ACIF to know to look for a Byte Order Mark (BOM) when your data type is UTF8 or UTF16 and contains a BOM.

If the data does not match the platform data type, PPFA translates the following constant page definition data to the encoding specified by UDType:

  • FIELD command text (all page definitions)
  • CONDITION text (all page definitions)
  • LAYOUT command 'record ID' (Record Format page definition only)
  • LAYOUT command delimiter (Record Format page definition only)
  • XLAYOUT command starttags (XML page definition only)
  • XLAYOUT command delimiter (XML page definition only)
  • DEFINE QTAG command start tags (XML page definition only)
  • FIELD attribute names (XML page definition only)

    Note:
  1. For data with a Byte Order Mark (BOM), you must specify UDType, and the BOM must be the first two bytes (UTF16) or three bytes (UTF8) in the first line data record following any CC or TRC bytes. A BOM in the data is required if the data is UTF16 Little Endian.
  2. If the UDType parameter is specified, all of the user data processed by this page definition must be of that data type. Having data that is not of the specified encoding type could lead to improper translation of that data which would, for example, not allow the text in a CONDITION statement to be matched to the data.
  3. If UDType is not coded on the PAGEDEF, then the UDType on the DOFONT command or TYPE on the FONT command determines the translation, but only for the data placed by that font.
  4. If you have multiple data type encodings in a data file, you must not code UDType on the page definition. Instead, for Data Objects Fonts, code UDType on the DOFONT command for the fonts that place the individual fields or records. And for regular FOCA fonts, you use fonts of the type matching the data for the individual fields or records.
  5. If you use ACIF to generate your print document and the NEWLINE ENCODING value does not agree with the UDType subcommand on the PAGEDEF command, ACIF issues a warning message but continues processing the file.
  6. The UDType coded on the PAGEDEF is inherited by the DOFONT if NONE is coded on the DOFONT command. And, if no UDType is coded on either the PAGEDEF or the DOFONT, the DOFONT defaults to the platform encoding.
  7. The UDType coded or not coded on the PAGEDEF does not affect the FONT command inheritance of data type, or in any way except to provide translation for fixed text being placed by the FONT command.
  8. If UDType is not the same as the UDType coded on the DOFONT command, PPFA issues an error message and no page definition is generated.
  9. To use multiple font mappings for a line in ASCII, UTF8, or UTF16 you must use the FIELD command, since automatic font switching for single and double byte text is only done for EBCDIC data.
  10. SBCS, DBCS, TYPE, and UDTYPE are different parameters that can affect fonts. TYPE indicates this is an ASCII or EBCDIC font being defined to use for printing. UDTYPE, which is not on the FONT command, indicates this is the type of the user’s data, ASCII or EBCDIC. SBCS and DBCS indicate what type of character set the defined font uses, single byte (SBCS) or double byte (DBCS).
  11. If UDTYPE is coded on the PAGEDEF and an ID name or text is explicitly defined with another type, an error results and the page definition is not generated. In the next example: 
    PAGEDEF cmr1is replace yes UDTYPE ASCII; 
FONT  varb  gt10; 
SETUNITS  LINESP .25 in;  
PAGEFORMAT  rept1  TOPMARGIN .25 in BOTMARGIN  .25 in; 
LAYOUT E'startpage' BODY  NEWPAGE POSITION .25 in NEXT font varb;
    For PAGEDEF with UDTYPE ASCII and LAYOUT with E'startpage', the ASCII type does not match the 'E' (EBCDIC) type.
RECIDLEN Subcommand (Record Format)
RECIDLEN 10 | n
Specifies the length of the Record Descriptor ID in bytes. The Record Descriptor ID is also known as the LAYOUT name. If the RECIDLEN parameter is not coded on a PAGEFORMAT command, it inherits the value from the specified or default value on the page definition. If the RECIDLEN parameter is not coded on a PAGEDEF command, the default length is 10 bytes.
n
Specifies that the record ID on the LAYOUT command is to be n bytes long. The allowable value of n is 1 to 250. UTF-16 data characters are 2 bytes long, allowing up to 125 UTF-16 characters. Any record ID on a LAYOUT command that is less than this length is padded to the specified length with blanks of the type specified or defaulted in the UDType subcommand on the PAGEDEF command. A record ID that is longer than n is flagged as an error by PPFA and no page definition is generated.
Note: If the User Data Type (UDType) is UTF16 and n is odd, it is rounded up to the next even number.
Parent topic: PAGEDEF Command