Subcommands

DEFAULT Subcommand
[DEFAULT | qtagname | QTAG starttag…]
The DEFAULT subcommand specifies a qualified tag that is used to identify the page definition.
DEFAULT
This keyword is used only when the layout type is either PAGEHEADER or PAGETRAILER, and no name is needed. Only one default PAGEHEADER or PAGETRAILER can be specified in a PAGEFORMAT.
qtagname
The qtagname is a defined qualified tag. It is defined by the DEFINEqtagnameQTAG command at the beginning of the page definition.
QTAGstarttag
This is an explicit Qualified Tag. It is defined by coding a series of start tags separated by commas. A start tag is an XML data element name. Put the start tag in quotes if you want to preserve its case. Otherwise it is folded to upper case.

Example of XML Data and Associated Page Definition with Start Tags

<person>
  <name>
    <first>Justin</first>
    <last>Case</last>
  </name>
</person>



PAGEDEF  xxx…;
   DEFINE lname QTAG 'person','name', 'last';
        ⋮
   Pageformat x …
      XLAYOUT lname POSITION…
         ⋮
   Pageformat y …
      XLAYOUT QTAG 'person','name','last' POSITION …
         ⋮

In Figure Example of XML Data and Associated Page Definition with Start Tags, person, name, and first are start tags. The qualifying tag for the data item Case is 'person','name','last'. In the page definition, both XLAYOUT commands address the same XML data item, Case.

Layout Type Subcommand
[BODY [GROUP | NOGROUP] 
       [XSPACE {0 | n [IN | MM | CM | POINTS | PELS]}] |
 PAGEHEADER [CONTINUE] | 
 PAGETRAILER [CONTINUE] |
 GRPHEADER [CONTINUE] [XSPACE {0 | n [IN | MM | CM | POINTS | PELS]}]]
Specifies the layout type.
BODY
The BODY layout type is used for the majority of data in your database. This is the default.
GROUP
The GROUP parameter indicates that the existing group header should be saved and used for subsequent pages.
NOGROUP
The NOGROUP parameter indicates that the active group header record should be discarded and not reprinted on subsequent pages. This is the default
XSPACE
XSPACE indicates the amount of extra space from the position of the layout to the bottom of the group header area. This allows the user to identify the amount of eXtra space in excess of one text line being used by the header so that the baseline moves down and the following group data is not placed on top of the header area. This space is not calculated by PPFA and must be explicitly defined by the user.
PAGEHEADER
This layout type specifies a header that is to be printed on each new page. The baseline position of this layout is normally in the top margin, but can be anywhere on a logical page. If RELATIVE is specified, the position is considered to be relative to the page origin. The header usually contains the customer's name, address, account number, and so forth. Only one default PAGEHEADER layout can be specified in a PAGEFORMAT and no input record data can be specified in a default layout.
CONTINUE
The CONTINUE parameter indicates that this XLAYOUT command is a continuation of the Page Header definition. The formation of the Page Header may require the data from more than one data element. This is done by specifying the CONTINUE parameter.
PAGETRAILER
This layout type specifies a trailer that is to be printed on each new page. The baseline position of this layout is normally in the bottom margin, but can be located anywhere on a logical page and can be specified as RELATIVE. Only one default PAGETRAILER layout can be specified in a PAGEFORMAT and no input record data is processed with a default layout. It may contain the name of the form or a footnote.
CONTINUE
The CONTINUE parameter indicates that this XLAYOUT command is a continuation of the Page Trailer definition. The formation of the Page Trailer may require the data from more than one data element. This is done by specifying the CONTINUE parameter.
GRPHEADER
This layout type specifies a header that is to be printed at the beginning of a group of data. If a logical page eject occurs before the group of data ends, the header is printed after the top margin on each new page until the group ends. The baseline position of this layout can be specified as RELATIVE. It may include column headings.
CONTINUE
The CONTINUE parameter indicates that this XLAYOUT command is a continuation of the Group Header definition. The formation of the Group Header may require the data from more than one data element. This is done by specifying the CONTINUE parameter.
XSPACE
XSPACE indicates the amount of extra space from the position of the layout to the bottom of the group header area. This allows the user to identify the amount of extra space in excess of one text line being used by the header so that the baseline moves down and the following group data is not placed on top of the header area. This space is not calculated by PPFA and must be explicitly defined by the user. See Figure Example of XSPACE (shaded space shows group header area):

Example of XSPACE

Example of XSPACE.
Once a Group Header record is processed and is still active when leaving the PAGEFORMAT, the group header record is saved by the presentation services program. Whenever the same PAGEFORMAT is re-invoked, this saved group header record is presented again if the first body record after re-invoking the PAGEFORMAT selects a Body record that has the Group Indicator on.
NEWPAGE Subcommand
NEWPAGE

This parameter indicates that a new page should be started with this layout name. If this is a header or trailer layout, the print position is moved to the start of a new page before this header or trailer becomes the active header or trailer.

DELIMITER Subcommand
DELIMITER [C | X] 'bytes'

The delimiter is a one or two byte code specified in either character or hex indicates a delimiting character within the customer's database and is used to separate fields. PPFA does not translate these characters. Hex characters must be entered in uppercase within the quotation marks.

PRINTDATA Subcommand
PRINTDATA [YES | NO]

Specifies whether the line of data associated with the current LAYOUT should be printed. The PRINTDATA subcommand is useful when the data stream is interspersed with lines of comments, blank lines, or lines without data that are not meant to be printed.

YES
Specifies that the data for the current XLAYOUT is printed. YES is the default.
NO
Specifies that the data for the current XLAYOUT is not printed.
DIRECTION Subcommand
DIRECTION {ACROSS | DOWN | BACK | UP}

Specifies the print direction of the line relative to the upper-left corner as you view the logical page. Not all printers can print in all print directions. For more information about your printer, refer to your printer documentation.

If DIRECTION is not specified, the direction specified in the PAGEFORMAT command is used. Observe that this direction is additive to the direction specified in the PAGEFORMAT command. See PAGEFORMAT Command .

ACROSS
The layout direction is rotated 0 degrees relative to the direction specified in the PAGEFORMAT (the layouts are oriented in the same direction as the page).
DOWN
The layout direction is rotated 90 degrees relative to the direction specified in the PAGEFORMAT.
BACK
The layout direction is rotated 180 degrees relative to the direction specified in the PAGEFORMAT.
UP
The layout direction is rotated 270 degrees relative to the direction specified in the PAGEFORMAT.

POSITION Subcommand
POSITION [ABSOLUTE | RELATIVE]{LEFTMARGIN | 
        SAME | [+ | -] horiz [IN | MM | CM | POINTS | PELS]} 
           [ABSOLUTE | RELATIVE] {TOPMARGIN | 
                                NEXT | 
        SAME | [+ | -] vert [IN | MM | CM | POINTS | PELS]}

Specifies the starting position of the layout in the printout. This is for use in positioning FIELD, DRAWGRAPHIC, andENDGRAPHIC text and graphics. If Relative is specified or POSITION is not specified, the baseline of the Position is relative to the previous LAYOUT position.

  1. For PAGEHEADER RCD: The baseline position can be anywhere on a logical page, but cannot be specified as Relative.
  2. For PAGETRAILER, GROUPHEADER, and BODY RCDs: The baseline position can be anywhere on a logical page and can be specified as RELATIVE.
ABSOLUTE
Specifies that the following horizontal position value is to be processed as an absolute value.
RELATIVE
Specifies that the following horizontal position value is to be processed as a value relative to the current inline position.
horizontal position
LEFTMARGIN
Specifies this line starts at the position specified as the horizontal (x) value in the previous LEFTMARGIN subcommand within this page definition.
SAME
Specifies this line starts at the same horizontal offset position as the previously coded XLAYOUT. If applied to the first XLAYOUT of a logical page, the horizontal position is 0, which is the default.
Note: This parameter is not valid with RELATIVEhorizontal.
=
Alternate for SAME.
horiz
Specifies the horizontal offset from the left side of the logical page. The value is a number with up to three decimal places. The valid options for horiz are described in the SETUNITS command for the horizontal value.
ABSOLUTE
Specifies that the following vertical position value is to be processed as an absolute value.
RELATIVE
Specifies that the following vertical position value is to be processed as a relative value. The XLAYOUT is positioned relative to the last XLAYOUT placed on the page.
    Note:
  1. When using RELATIVE positioning, PPFA does not flag off-the-page conditions for the position of a XLAYOUT or for any overlays, segments or objects placed relative to that XLAYOUT. XLAYOUTs that fall outside the bounds of the logical page are flagged by the print server at run time.
  2. When specifying RELATIVE, use the minus sign to indicate any negative values for the XLAYOUT vertical position; you may use the plus sign to indicate positive values. If no sign is used, a positive value is assumed.
  3. The DIRECTION for a relative XLAYOUT must be ACROSS. Fields associated with a relative XLAYOUT must have the same DIRECTION as the XLAYOUT and must match the PAGEFORMAT DIRECTION.
  4. If RELATIVE is specified with SAME as the vert value, the relative value in the XLAYOUT is +0.
  5. RELATIVE positioning is allowed on a XLAYOUT command only if the XLAYOUT and all its associated FIELD commands are formatted to print in the same direction as the PAGEFORMAT. That is, the DIRECTION parameter in the XLAYOUT and any associated FIELD commands must specify (or default to) ACROSS. The DIRECTION in the PAGEFORMAT or PAGEDEF command may be any allowable value: ACROSS, DOWN, BACK, or UP.
vertical position
TOPMARGIN
Specifies that the XLAYOUT is placed in the position specified as the vertical (y) value in the TOPMARGIN subcommand within this page definition.
NEXT
Specifies the layout is to be positioned down (on the logical page) one line from the previous field. The LINESP subcommand of the SETUNITS command establishes the distance from one line to the next.

When NEXT is specified for the first XLAYOUT of a logical page, the starting position of the line is one line down from the top of the logical page, as defined by the TOPMARGIN subcommand.

Note: The down direction is determined by the direction of the logical page (as specified in the page format), not the XLAYOUT direction. NEXT is, therefore, mainly useful in ACROSS XLAYOUT commands.

SAME
Specifies this XLAYOUT starts at the same vertical position as the previous XLAYOUT.
=
Alternate for SAME.
vert
Specifies the vertical offset from the top side of the logical page. The value options for vert are described in the SETUNITS command for the vertical value.
ENDSPACE Subcommand
ENDSPACE n [IN | MM | CM | POINTS | PELS]

If the remaining body space is less than the value specified, ENDSPACE causes a logical page eject to be executed. This can be used, for example, on a GRPHEADER layout to ensure that a group header does not print at the end of a page without the first data record of the group. ENDSPACE does not include the space within the bottom margin (specified on the PAGEDEF or PAGEFORMAT command). This indicator is ignored on a PAGEHEADER or PAGETRAILER layout.

COLOR Subcommand
COLOR colorname
Specifies an OCA or defined color for the text of this field. This subcommand is recognized only by printers that support multiple-color printing. Refer to your printer publication for information about the colors that can printed.
colorname
Values for colorname can be a defined color (see DEFINE COLOR Command), or an OCA colorname. Values for OCA colornames are:
  • NONE
  • DEFAULT
  • BLACK
  • BLUE
  • BROWN
  • GREEN
  • RED
  • PINK (or MAGENTA)
  • TURQ (or CYAN)
  • YELLOW
  • DARKBLUE (or DBLUE)
  • ORANGE
  • PURPLE
  • MUSTARD
  • GRAY
  • DARKGREEN (or DGREEN)
  • DARKTURQ (DTURQ, or DCYAN, or DARKCYAN)
The color choices depend on the printer.

If you do not enter one of these colors, the default color for that printer is used. NONE is the color of the medium. DEFAULT is the printer default color.

Note: In some printer manuals, the color turquoise (TURQ) is called cyan, and the color pink (PINK) is called magenta.

PPFA supports the following synonyms:

  • CYAN for TURQ
  • DARKCYAN for DARKTURQ
  • DBLUE for DARKBLUE
  • DCYAN for DARKTURQ
  • DGREEN for DARKGREEN
  • DTURQ for DARKTURQ
  • MAGENTA for PINK

Note: Do not specify both an OCA color with the COLOR sub-parameter and an extended color model on the same XLAYOUT command. The output is device dependent and may not be what you expect.
Color Model Subcommands
[RGB rvalue gvalue bvalue} |
 HIGHLIGHT hvalue [COVERAGE cvalue] [BLACK bvalue] |
 CMYK cvalue mvalue yvalue kvalue |
 CIELAB lvalue [(–)] c1value [(–)] c2value]
These subcommands specify the color of print for this field supported in MO:DCA for the Red/Green/Blue color model (RGB), the highlight color space, the Cyan/Magenta/Yellow/Black color model (CMYK), and the CIELAB color model.
RGBrvalue gvalue bvalue
Three RGB integer values are used. The first (rvalue) represents a value for red, the second (gvalue) represents a value for green, and the third (bvalue) represents a value for blue. Each of the three integer values may be specified as a percentage from 0 to 100.
Note: An RGB specification of 0/0/0 is black. An RGB specification of 100/100/100 is white. Any other value is a color somewhere between black and white, depending on the output device.
HIGHLIGHThvalueCOVERAGEcvalueBLACKbvalue
Indicates the highlight color model. Highlight colors are device dependent.

You can use an integer within the range of 0 to 65535 for the hvalue.

Note: An hvalue of 0 indicates that there is no default value defined; therefore, the default color of the presentation device is used.

COVERAGE indicates the amount of coverage of the highlight color to be used. You can use an integer within the range of 0 to 100 for the cvalue. If less than 100 percent is specified, the remaining coverage is achieved with the color of the medium.

Note: Fractional values are ignored. If COVERAGE is not specified, a value of 100 is used as a default.

BLACK indicates the percentage of black to be added to the highlight color. You can use an integer within the range of 0 to 100 for the bvalue. The amount of black shading applied depends on the COVERAGE percentage, which is applied first. If less than 100 percent is specified, the remaining coverage is achieved with black.

Note: If BLACK is not specified, a value of 0 is used as a default.

CMYK cvalue mvalue yvalue kvalue
Defines the cyan/magenta/yellow/black color model. cvalue specifies the cyan value. mvalue specifies the magenta value. yvalue specifies the yellow value. kvalue specifies the black value. You can use an integer percentage within the range of 0 to 100 for any of the CMYK values.
CIELABLvalue(−)c1value(−)c2value
Defines the CIELAB model. Use a range of 0.00 to 100.00 with Lvalue to specify the luminance value. Use signed integers from -127 to 127 with c1value and c2value to specify the chrominance differences.

Lvalue, c1value, c2value must be specified in this order. There are no defaults for the subvalues.

    Note:
  1. Do not specify both an OCA color with the COLOR sub-parameter and an extended color model on the same XLAYOUT command. The output is device-dependent and may not be what you expect.
  2. Do not specify two extended color model subcommands on the same XLAYOUT command.

FONT Subcommand
FONT name1 [, name2]

Defines the font to be used for the layout.

name1
Specifies the name of a font used to print the data. This font must have been defined in a previous FONT command in this page definition.

If Shift-Out, Shift-In (SOSI) processing is used, name1 must be the single-byte font.

name2
Specify only when using Shift-Out, Shift-In (SOSI) processing to dynamically switch between a single-byte font and a double-byte font within the layout. name2 must be the double-byte font.
    Note:
  1. If this subcommand is not specified in the print data, the print server uses the font indicated. Otherwise, the print server selects a default font.
  2. name2 is only valid with EBCDIC data.
OBJECT Subcommand
OBJECT lname [0 0 | relX relY] Other OBJECT Parameters

Specifies the local name of an object that is to be positioned and oriented relative to the location specified in the XLAYOUT command in which the OBJECT subcommand was named. The OBJECT, as identified by the lname parameter, must have been defined by an OBJECT command.

Note: Multiple page/image objects used without specifying a page using OBPAGE will default to using the first page in the object.
You may place multiple objects on the same XLAYOUT command and you may place the same object multiple times. Each placement must have its own set of placement parameters, as follows:
lname
Specifies the local name of an object that is up to 16 alphanumeric characters in length. The lname parameter is used to match the XLAYOUT OBJECT subcommand to its definition from the OBJECT command. An object must be defined with this internal name by the OBJECT command.
relX relY
Specifies the number of units (inches, mm, and so on) that are added to the position of the current XLAYOUT to position the top-left corner of the object. The values for the horizontal and vertical positioning are limited by the type of printer used and the L-units specified with the PELSPERINCH parameter on the PAGEDEF or PAGEFORMAT command.

Each position specification can be a positive or negative number with up to three decimal places. The units specified can be one of the following: IN, MM, CM, POINTS, or PELS.

OBSIZE
OBSIZE {USEOBJ | wd [unit] hg [unit]}

Specifies the size of the object placement area. When no OBSIZE is specified, the default is the size specified in the object. If no size is specified in the object, the size of the page is used. The page width is as specified on the PAGEDEF or PAGEFORMAT commands, or it defaults to 8.3 inches by 10.8 inches.

USEOBJ
Specifies that the size measurements specified in the object are to be used. If no size is specified in the object, the size of the page is used, which is the length and width as specified on the PAGEDEF or PAGEFORMAT commands, or it defaults to 8.3 inches by 10.8 inches.
wd
Specifies the width of an object placement area as a number with up to three decimal places. The allowable width may vary with the type of printer used and the L-units specified with the PELSPERINCH parameter on the PAGEDEF or PAGEFORMAT command.
unit
Specifies a unit of measurement for the width parameter. 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.
hg
Specifies the height of the object placement area as a number with up to three decimal places. The allowable height may vary with the type of printer used and the L-units specified with the PELSPERINCH parameter on the PAGEDEF or PAGEFORMAT command.
unit
Specifies a unit of measurement for the height parameter. 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.
OBMAP
OBMAP {LEFT | TRIM | FIT | CENTER | REPEAT | FILL}

Specifies mapping options. The OBMAP parameter defines the mapping of the object to the object placement area. If OBMAP is not coded, the mapping option within the object is used. If the object does not contain a mapping option, then the print server sets it to the created default for the container type.

Each object type (OBTYPE on the OBJECT command) dictates the allowable mapping options for that type. When it can, PPFA issues a message when these rules are violated. However, in the case of an object type of page segment (OBTYPE=PSEG), PPFA does not know what types of objects are contained in it; therefore, PPFA cannot enforce the restrictions. See OBJECT Command for a description of the restrictions.

LEFT
Specifies that the object is positioned at the upper, left-hand corner of the object placement area, as defined or defaulted by the relX, relY, OBCHPOS, and OBCVPOS parameters. Any portion of the object that falls outside the object placement area as defined by the OBSIZE parameter is not trimmed and could cause an exception condition by the presentation system.
TRIM
Specifies position and trim. The object is positioned at the upper, left-hand corner of the object placement area, as defined or defaulted by the relX, relY, OBCHPOS, and OBCVPOS parameters. Any portion of the object that falls outside the object placement area as defined by the OBSIZE parameter is trimmed.
FIT
Specifies scale to fit; this is the default value if the OBMAP parameter is not coded. The object is to be scaled to fit within the object placement area, as defined by the OBSIZE parameter. The center of the object is placed in the center of the object placement area and the object is scaled up or down to fit the block. Scaling in the horizontal and vertical directions is symmetrical. The FIT parameter ensures that all of the data in the object is presented in the object placement area at the largest possible size. The object is not trimmed.
CENTER
Specifies that the center of the object be positioned at the center of the object placement area. Any portion of the object that falls outside the object placement area is trimmed.
REPEAT
Specifies that the origin of the data object be positioned with the origin of the object placement area. The object is then replicated in the X and Y directions. If the last replicated data does not fit in the object area, it is trimmed to fit.
FILL
Specifies that the center of the data object be positioned coincident with the center of the object placement area. The data object is then scaled, so that it totally fills the object placement area in both the X and Y directions. This may require that the object be asymmetrically scaled by different scale factors in the X and Y directions.

OBCHPOS
OBCHPOS {USEOBJ | x-pos}

Specifies the horizontal offset of the object contents within the object placement area as a number.

USEOBJ
Specifies that the offset value from the object is to be used. If no value is set in the object, the value defaults to 0.
x-pos
Specifies a positive or negative number. The valid options for x-pos are described in the SETUNITS command for the horizontal value.
OBCVPOS
OBCVPOS {USEOBJ | y-pos}

Specifies the vertical offset of the object contents within the object placement area, as defined by the OBSIZE parameter. The OBCHPOS parameter is used only in LEFT and TRIM mapping of the object into the object placement area.

USEOBJ
Specifies that the offset value from the object is to be used. If no value is set in the object, the value defaults to 0.
y-pos
Specifies a positive or negative number. The valid options for y-pos are described in the SETUNITS command for the vertical value.
OBROTATE
OBROTATE {0 | 90 | 180 | 270}

Specifies the object rotation with respect to the current LND's coordinate system.

OBCOLOR
OBCOLOR color-name

Specifies the color to be used as the default color or initial color for the object placement area. The OBCOLOR parameter is used only for objects of the PSEG, GOCA, BCOCA, IOCA, PTOCA and OTHER type.

colorname
Values for colorname can be a defined color (see DEFINE COLOR Command) or one of the OCA color spaces listed below.
  • NONE
  • DEFAULT
  • BLACK
  • BLUE
  • BROWN
  • GREEN
  • RED
  • PINK (or MAGENTA)
  • TURQ (or CYAN)
  • YELLOW
  • DARKBLUE (or DBLUE)
  • ORANGE
  • PURPLE
  • MUSTARD
  • GRAY
  • DARKGREEN (or DGREEN)
  • DARKTURQ (DTURQ, or DCYAN, or DARKCYAN)
OBPAGE
OBPAGE n

Specifies the page number of a multipage object or file to be presented. n is the page number. A number from 1 to 999999999 (9 digits) is valid.

OBCPSS
OBCPSS PSS

Specifies the presentation space size to be used for the object. OBCPSS may be specified once. If OBCPSS is specified but no PSS value is entered, an error message will be issued.

PSS
Specifies the presentation space size. Values for PSS can be:
  • mediabox — Specifies MediaBox
  • cropbox — Specifies CropBox
  • bleedbox — Specifies BleedBox
  • trimbox — Specifies TrimBox
  • artbox — Specifies ArtBox
OVERLAY Subcommand
OVERLAY Xname [0 0 | relX relY] [OVROTATE {0 | 90 | 180 | 270}]

Specifies the name of an overlay that is to be positioned relative to the location specified in the XLAYOUT command in which the OVERLAY subcommand was named. The PAGEFORMAT OVERLAY command may contain the named overlays. The maximum number of overlays specified for a PAGEFORMAT , including the XLAYOUT OVERLAY subcommand, is 254.

Specifies the electronic overlay that is to be used with this subgroup.

Xname
Specifies the user-access name as defined in the OVERLAY command.
    Note:
  1. PPFA checks for duplication of local names. If there is a duplication, the page definition is generated, but a warning message is issued.
  2. PPFA does not check for duplicate user-access names.
relX relY
Specifies the number of units (inches, mm, and so on) that are added to the position of the layout to position the top-left corner of the overlay. The values for horizontal and vertical may be (+) or (-). The maximum value is + or - 32760 L-units. For example: 
OVERLAY NAME1 2 in 1 in
OVERLAY NAME2 5 mm 1 mm
Note: Any offset coded in the overlay itself is added to this offset.
OVROTATE
Specifies the rotation of the placed overlay with respect to the x-axis of the page.

See FORMDEF Command for an OVROTATE example, which is presented in the FORMDEF description.

SEGMENT Subcommand
SEGMENT Xname [0 0 | relX relY]

Specifies the name of a segment that is to be positioned relative to the location specified in the XLAYOUT command in which the SEGMENT subcommand was named. The PAGEFORMAT SEGMENT command can contain the named segments. The maximum number of segments specified for a PAGEFORMAT including the XLAYOUT SEGMENT subcommand is 127.

Specifies the page segment that is to be used with this subgroup.

Xname
Specifies the user-access name as defined in the SEGMENT command.
    Note:
  1. PPFA checks for duplication of local names. If there is a duplication, the page definition is generated, but a warning message is issued.
  2. PPFA does not check for duplicate user-access names.
relX relY
Specifies the number of units (inches, mm, and so on) that are added to the position of the layout to position the top-left corner of the page segment. The values for horizontal and vertical may be (+) or (-). The maximum value is + or - 32760 L-units. For example: 
SEGMENT MYSEG1 2 in 1 in
SEGMENT MYSEG1 5 mm 1 mm

Parent topic: XLAYOUT Command (XML)