Exit Program for a Customized Separator Page
Required Parameter Group:
| 1 | Separator data | Output | Char(*) |
| 2 | Separator data length | Input | Binary(4) |
| 3 | Separator information | Input | Char(*) |
| 4 | Separator information length | Input | Binary(4) |
QSYSINC Member Name: ESPBLSEP
An exit program can be specified on the separator program parameter of the printer device description. If a separator exit program is specified on the printer device description, the system printer writer calls this program to create the separator page. This separator page is used instead of the system separator page.
Authorities and Locks
None.
Required Parameter Group
- Separator data
- OUTPUT; CHAR(*)
The separator data consists of two parts:
- Options that control how the separator data is to be printed
- User-generated separator data
See the Separator Data Format for more information.
- Separator data length
- INPUT; BINARY(4)
The length of the space used to pass separator data from the exit program.
- Separator information
- INPUT; CHAR(*)
Information that may be used to generate the separator data.
See the Separator Information Format for more information.
- Separator information length
- INPUT; BINARY(4)
The length of the space used to pass separator information to the exit program.
Separator Data Format
The following table shows the information passed from the exit program to create the customized separator page for the printer writer. The printer writer takes the information and data, and prints the separator page.
See Field Descriptions for more information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Transform option |
| 10 | A | CHAR(2) | Reserved |
| 12 | C | BINARY(4) | Page rotation |
| 16 | 10 | BINARY(4) | Page length |
| 20 | 14 | BINARY(4) | Page width |
| 24 | 18 | BINARY(4) | Lines per inch |
| 28 | 1C | BINARY(4) | Characters per inch |
| 32 | 20 | BINARY(4) | DBCS Characters per inch |
| 36 | 24 | CHAR(10) | DBCS characters rotation |
| 46 | 2E | CHAR(10) | Page size measurement method |
| 56 | 38 | CHAR(10) | Print quality |
| 66 | 42 | CHAR(10) | Overlay name |
| 76 | 4C | CHAR(10) | Overlay library name |
| 86 | 56 | CHAR(98) | Reserved |
| 184 | B8 | BINARY(4) | Length of user-generated data |
| 188 | BC | BINARY(4) | Record length of user data |
| 192 | C0 | CHAR(*) | User-generated separator data |
Field Descriptions
Each field is only valid when the transform option field is specified as *FCFC. Otherwise, the field is ignored.
Characters per inch. The number of characters (in tenths) to be printed per inch.
The possible values are:
| 50 | 5 characters per inch |
| 100 | 10 characters per inch |
| 120 | 12 characters per inch |
| 133 | 13.3 characters per inch |
| 150 | 15 characters per inch |
| 167 | 16.7 characters per inch |
| 180 | 18 characters per inch |
| 200 | 20 characters per inch |
Any other value, or a value not supported by the particular printer, will result in 10 characters per inch.
DBCS character rotation. Whether double-byte character set (DBCS) characters are to be rotated 90 degrees counterclockwise before printing. The possible values are *YES and *NO. The default value is *NO.
DBCS characters per inch. The number of double-byte characters to be printed per inch.
The possible values are:
| -1 | One-half of the characters-per-inch value |
| -2 | 20 double-byte characters per 3 inches |
| 5 | 5 characters per inch |
| 6 | 6 characters per inch |
| 10 | 10 characters per inch |
If any other value is used, the characters are printed at one-half of the characters-per-inch (*CPI) value.
Length of user-generated data. The number of bytes of data (contained in the user-generated separator data field) passed from the user exit program.
The length of the user-generated separator data cannot exceed 8096 bytes for printers configured AFP(*NO). A value greater than 8096 causes the system separator page to be printed.
Lines per inch. The number of lines (in tenths) to print per vertical inch.
The possible values are:
| 30 | 3 lines per inch |
| 40 | 4 lines per inch |
| 60 | 6 lines per inch |
| 75 | 7.5 lines per inch |
| 80 | 8 lines per inch |
| 90 | 9 lines per inch |
Any other value, or a value not supported by the particular printer, will result in 6 lines per inch.
This parameter is output from the exit program and is only valid when the Transform Option is specified as *FCFC. Otherwise this parameter is ignored.
Page length. The length of the separator page. The page length can be specified in inches, centimeters, or rows depending on the page size measurement method field.
A zero indicates the page length of the spooled file should be used. A nonzero page length value is valid only when the page width field is also set to a nonzero value. Otherwise, the page length is ignored.
Inches and centimeters are specified in 1/100ths. The value 1100 indicates a page length of 11 inches when the page size measurement method field is *INCH.
Page size measurement method. The measurement method used for the page length and page width fields.
The possible values are:
| *INCH | The page size is specified in 1/100ths of an inch. |
| *CM | The page size is specified in 1/100ths of a centimeter. |
| *ROWCOL | The page size is specified in row and column format. |
Page width. The width of the separator page. The page width can be specified in inches, centimeters, or rows depending on the page size measurement method field.
A 0 indicates the page width of the spooled file should be used. A nonzero page width value is valid only when the page length field is also set to a nonzero value. Otherwise, the page width is ignored.
Inches and centimeters are specified in 1/100ths. The value 850 indicates a page width of 8.5 inches when the page size measurement method field is *INCH.
Overlay library name. The name of the library containing the separator overlay.
The possible values are:
| *LIBL | The library list of the job that created the file locates the overlay. |
| library name | This library is searched for the overlay. |
If no value is returned from the exit program, *LIBL is assumed.
Overlay name. The name of the separator overlay (the material that prints on the front side of each separator page).
The possible values are:
| *NONE | The separator does not use an overlay. |
| Overlay Name | The name of the overlay to print with the separator. |
If no value is returned from the exit program, *NONE is assumed. Otherwise this parameter is ignored.
Page rotation. The degree of rotation of the text on the page, with respect to the way the form is loaded into the printer.
The possible values are:
| 0 | No rotation is done. Printing starts at the edge loaded into the printer first, and is parallel to that edge. |
| 90 | Text is rotated 90-degrees clockwise from the 0-degree writing position. |
| 180 | Text is rotated 180-degrees clockwise from the 0-degree writing position. |
| 270 | Text is rotated 270-degrees clockwise from the 0-degree writing position. |
If no valid value is returned from the exit program, 0 is assumed.
Print quality. The print quality that is used when printing the separator.
The possible values are:
| *STD | Standard |
| *DRAFT | Draft |
| *DEVD | Print quality determined by printer hardware setting |
| *FASTDRAFT | Fast draft |
| *NLQ | Near-letter quality |
If no valid value is returned from the exit program, *DEVD is assumed. Otherwise this parameter is ignored.
Record length of user data. The length of the *FCFC format records in the user-generated separator data field.
Reserved. An ignored field.
Transform option. Whether the user-generated data is to be transformed into commands recognized by the printer.
The possible values are:
| *FCFC | The first character of every record is an
American National Standards printer control character.
The supported control characters and their functions follow:
All other control character values are treated as blanks and result in the record printing on the next line. Channel values are not supported. |
||||||||
| *NONE | User-supplied data is in its final form. No transform operation is done, and the data must contain the appropriate commands corresponding to the printer data stream type. |
For the printer data stream type field of *SCS and *IPDS, data stream commands controlling the drawer, rotations, and fonts may be sent to the printer before the user-generated data. This puts the printer in the same state as it is when system default separators are printed. The commands controlling the drawer are based on the SEPDRAWER parameter of the Start Printer Writer (STRPRTWTR) command. The remaining controls are set to defaults or have values set from the spooled file attributes of the spooled file that prints next.
For a printer data stream type of *AFPDS, the initial commands are not sent to the printer and the user must include all commands needed to define an AFPDS document.
User-generated separator data. The data that prints on the separator page. The format of this text is dependent on the transform option and the printer data stream type fields. When *FCFC has been specified for the transform option, the data must be in the *FCFC format. When *NONE is specified for the transform option, the data (text and controls) must be in the format specified by the printer data stream type field.
Separator Information Format
The following table shows the information passed from the printer writer to the exit program. This information is used to create a customized separator page. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(16) | Internal job identifier |
| 16 | 10 | CHAR(16) | Internal spooled file identifier |
| 32 | 20 | CHAR(10) | Job name |
| 42 | 2A | CHAR(10) | User name |
| 52 | 34 | CHAR(6) | Job number |
| 58 | 3A | CHAR(10) | Spooled file name |
| 68 | 44 | BINARY(4) | Spooled file number |
| 72 | 48 | CHAR(10) | Printer device name |
| 82 | 52 | CHAR(10) | Printer data stream type |
| 92 | 5C | CHAR(10) | Type of separator |
| 102 | 66 | CHAR(8) | Job system name |
| 110 | 6E | CHAR(7) | Spooled file create date |
| 117 | 75 | CHAR(1) | Reserved |
| 118 | 76 | CHAR(6) | Spooled file create time |
| 124 | 7C | CHAR(50) | Reserved |
Field Descriptions
Internal job identifier. The internal identifier of the job that owns the spooled file that prints next. Only the IBM® i APIs use this identifier. The identifier is not valid following an initial program load (IPL). If you attempt to use it after an IPL, an exception occurs.
Internal spooled file identifier. The internal identifier of the spooled file that prints next. This value is used as input to other programs to improve the performance of locating the spooled file on the system. Only the IBM i APIs use this identifier. The identifier is not valid following an IPL. If you attempt to use it after an IPL, an exception occurs.
Job name. The name of the job that created the spooled file that prints next.
Job number. The number of the job that created the spooled file that prints next.
Job system name. The name of the system where the job that created the spooled file ran.
If the separator data length is less than 124 bytes, the exit program should assume *ONLY.
Printer device name. The name of the printer device description for the writer that was started.
Printer data stream type. The type of data stream recognized by the printer writer. When the transform option is specified as *NONE, this field must be used to determine the format of the user-generated separator data field.
The possible values are:
| *AFPDS | Advanced Function Presentation™ data stream |
| *IPDS | Intelligent Printer Data Stream™ |
| *SCS | Systems Network Architecture (SNA) character stream |
Reserved. An ignored field.
Spooled file create date. The date the spooled file was create on the system in the format CYYMMDD. See field Date file opened in API QUSRSPLA under field descriptions for more information on the date format.
If the separator data length is less than 124 bytes, the exit program should assume *ONLY.
Spooled file create time. The time the spooled file was created on the system in the format HHMMSS. See field Time file opened in API QUSRSPLA under field descriptions for more information on the time format.
If the separator data length is less than 124 bytes, the exit program should assume *ONLY.
Spooled file name. The name of the spooled file that prints next.
Spooled file number. The spooled file number of the spooled file that prints next.
Type of separator. The type of separator you want printed.
The possible values are:
| *FILE | Separator printed before each copy of a spooled file. |
| *JOB | Separator printed between spooled files created by different jobs. |
User name. The name of the user that created the spooled file that prints next.
Exit program introduced: V2R3
[ Back to top | Print APIs | APIs by category ]