OVERLAY (Overlay) keyword in printer files

Use this record-level keyword to print an overlay.

The format of the keyword is:

OVERLAY([(library-name | &library-name-field)/overlay-name] | 
         &overlay-name-field]
         position-down | &position-down-field
         position-across | &position-across-field
         [(*ROTATION  rotation-field) | &rotation-field-name)])

The overlay-name, position-down, and position-across parameters are required.

Use the optional library-name parameter to further qualify the overlay. If you do not specify the library-name parameter, *LIBL is used to search for the overlay at print time.

Note: If an application uses private resources (for example, fonts, page segments, overlays, or GDF files not distributed with the system), be aware of the following information. When referencing these resources, if you specify *LIBL or you do not specify a library name, the resources must be available through the library list used by the application creating the spooled file.

You can specify the library-name, overlay-name, position-down, position-across, and rotation parameters as constants, program-to-system fields, or a combination of both, as shown in the following examples:

[library-name/]overlay-name...
[library-name/]&field1...
[&field2/]overlay-name...
[&field3/]&field4...

When you specify the library-name as a program-to-system field, the field must exist in the same record format as the OVERLAY keyword. It must be defined as length of 10, data type A (character), and usage P (program-to-system).

When you specify the overlay-name as a program-to-system field, the field must exist in the same record format as the OVERLAY keyword. It must be defined as length of 8, data type A (character), and usage P (program-to-system).

When you specify the position-down or position-across as program-to-system fields, the fields must be defined as length 5 with 3 decimal positions, data type S, and usage P. A program-to-system field for rotation must be defined as length 3 with 0 decimal positions, data type S and usage P.

The position-down parameter defines the vertical starting point of the overlay relative to the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command. Valid values are 0 to 57.790 cm (0 to 22.750 in.).

The position-across parameter defines the horizontal starting point of the overlay relative to the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command. Valid values are 0 to 57.790 cm (0 to 22.750 in.).

Note: The UOM parameter on the CRTPRTF command determines the units of measure for the position-down and position-across parameter values. If the value specified for a parameter is outside the valid range, it is flagged when the spooled file is created.

An error message is issued at print time if the overlay does not fit on the page.

The optional rotation parameter allows you to specify a rotation value for the overlay. Valid values are 0, 90, 180 and 270. It is specified as an expression of the form (*ROTATION rotation). Consider the following additional points about the rotation parameter:

If the rotation parameter is omitted, then overlays are not automatically rotated when using the PAGRTT parameter on the printer file. See the iSeries™ guide to output book for information about overlays.
The following IBM^® printers support the rotation parameter:
- Infoprint^® 60
- Infoprint 2000
- Infoprint 3000
- Infoprint 4000
- Infoprint Hi-Lite Color Printer, model 4005-HCI
These printers must be at ucode level 9.2 or later.

Specify DEVTYPE(*AFPDS) on the CRTPRTF command when OVERLAY is specified in the file. If DEVTYPE is changed to anything other than *AFPDS, the keyword is ignored and a warning message is issued at print time.

When the OVERLAY keyword is specified on a record format, all fields within the record format must be positioned using the POSITION keyword.

An error message is issued if a constant field is specified in a record format where the OVERLAY keyword is also specified.

You can specify this keyword multiple times on a record.

A maximum of 10 overlays can be used on a single page.

Overlays are not automatically rotated when using the PAGRTT keyword or the PAGRTT parameter on the printer file.

You cannot specify OVERLAY with the following keywords:

SPACEA
SPACEB
SKIPA
SKIPB

Option indicators are valid for this keyword.

Example 1

The following example shows how to specify the OVERLAY keyword.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A*
     A          R REC1                      OVERLAY(MYLIB/OVL04 1.234 14.62)
     A*
     A          R REC2                      OVERLAY(&LIB/&OVLS &POSD &POSA);
     A            LIB           10A  P
     A            OVLS           8A  P
     A            POSD           5S 3P
     A            POSA           5S 3P
     A*
     A          R REC3                      OVERLAY(MYOVL 11.219 0.2)
     A                                      OVERLAY(YOUROVL 7.3 9.27)
     A*
     A          R REC4
     A  01                                  OVERLAY(MYLOGO 0.0 3.01)
     A*
     A          R REC5                      OVERLAY(&LIB2/&OVL2 &POSD2 &POSA2 +
     A                                      (*ROTATION 90))
     A            LIB2          10A  P
     A            OVL2           8A  P
     A            POSD2          5S 3P
     A            POSA2          5S 3P
     A*
     A

Note: The UOM parameter on the CRTPRTF command determines the units of measure for the parameter values.

REC1 prints overlay OVL04 found in library MYLIB. The overlay prints 1.234 units down and 14.62 units across from the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command.

REC2 allows the application program to specify the library by setting program variables LIB and overlay name by setting program variables OVLS. The application specifies the overlay position at run time by setting POSD and POSA.

REC3 prints two overlays. MYOVL prints 11.219 units down and 0.2 units across from the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command. YOUROVL prints 7.3 units down and 9.27 units across from the margins specified on the CRTPRTF command. Both overlays are located using *LIBL.

REC4 prints MYLOGO only if indicator 01 is on.

REC5 allows the application program to specify the library by setting field LIB2 and specify overlay name by setting field OVL2. The overlay position is specified by the application at run time by setting POSD2 and POSA2. The overlay rotation is set to a value of 90 degrees.

Example 2

The second coding example uses DDS and P-fields.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8

      *
                R REC1                      OVERLAY(&MYLIB/&MYOVL +
                                            &OFFD &OFFA
      *
                MYLIB         10A  P
                MYOVL          8A  P
                OFFD           5S 3P
                OFFA           5S 3P

The following example illustrates the location of the overlay using the previous DDS code. The application program specifies the library by setting field MYLIB and specifies overlay name by setting field MYOVL. The application program also sets a value of 2 in field OFFD and a value of 2 in field OFFA. Both the FRONTMGN and BACKMGN parameters on the CRTPRTF command are set to 2.

An illustration of the results produced by Example 2. The overlay is
positioned 4 units down and 4 units across, 2 units down and across from a
margin of 2 units down and across.