These system exits are used to control the layout of header/trailer pages for printouts.
In particular, the exit routines can be used to suppress the standard output of the SPOOL system, replace it by one of several alternative outputs, or initiate an alternative output in addition to the standard output.
Alternative outputs for header or trailer pages are made available by systems support. They can be requested by the user by means of the HEADER-EXIT-NUMBER and TRAILER-EXIT-NUMBER operands in the PRINT-DOCUMENT command. The standard output can be modified by a user text (HEADER-PAGE-TEXT operand in the PRINT-DOCUMENT command) independently of an exit routine.
Example
A standard name must be defined, e.g.
HEADERPAGETEXT.n,
This name denotes a SAM or ISAM file or a job variable. It can be used to store texts, which in turn can be accessed using the command:
PRINT-DOCUMENT ...,LAYOUT-CONTROL=*PARAMETERS(COVER-PAGES= -
*PARAMETERS(HEADER-EXIT-NUMBER=...))
The exit routine must access the file: $userid.HEADERPAGETEXT.n
and enter the text in the buffer for the header page. No selection is made until the exit routine has been called. These exit routines save and restore all registers.
The routines are called:
if no header/trailer page was created
to restore the management buffer in cases where a header/trailer page already exists
Header page exit (091)
The following information is passed to the exit routine:
R1 = A(EX091 parameter area) R12 = A(TPR program manager) R13 = A(save area) R14 = A(indirect return) R15 = A(exit routine)
dd | cc | bb | aa |
A return code concerning execution of EX091 and EX092 is passed in the standard header:
aa=maincode1
bb=maincode2
cc=subcode1
dd=subcode2
X'aa' | Meaning |
00 | No header/trailer page |
01 | Print system header/trailer page without changes |
02 | Print specified alternative header/trailer page |
03 | Print the system header/trailer page without changes and the specified alternative header/trailer page |
04 | Only for exit 92. No trailer page. The last feed to vertical tab “channel 1” should be suppressed |
DSECT
A DSECT or CSECT for the parameter area (address transferred in register 1) can be generated by means of the EX091 macro (“prefix” must not be longer than 3 characters):
EX091 D
*
* SPOOL HEADER PAGE ROUTINE EXIT PARAMETER LIST
*
IHD MFCHK MF=D,DMACID=E91,ALIGN=F,SUPPORT=(C,D),ENTRY=NO, C
PREFIX=I,MACID=E91,DNAME=C
IHD DSECT ,
*,##### PREFIX=I, MACID=E91 #####
*
* STANDARD HEADER RETURN INFORMATION
*
IBEG DS 0H
FHDR MF=(C,I),EQUATES=NO
DS 0A
IFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER
*
IIFID DS 0A 0 INTERFACE IDENTIFIER
IFCTU DS AL2 0 FUNCTION UNIT NUMBER
* BIT 15 HEADER FLAG BIT,
* MUST BE RESET UNTIL FURTHER NOTICE
* BIT 14-12 UNUSED, MUST BE RESET
* BIT 11-0 REAL FUNCTION UNIT NUMBER
IFCT DS AL1 2 FUNCTION NUMBER
IFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER
*
IRET DS 0A 4 GENERAL RETURN CODE
ISRET DS 0AL2 4 SUB RETURN CODE
ISR2 DS AL1 4 SUB RETURN CODE 2
ISR1 DS AL1 5 SUB RETURN CODE 1
IMRET DS 0AL2 6 MAIN RETURN CODE
IMR2 DS AL1 6 MAIN RETURN CODE 2
IMR1 DS AL1 7 MAIN RETURN CODE 1
IFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH
*
*
* EQUATES FOR EXIT RETURN INFORMATION IN &P.MR1
*
IEXNH EQU 0 NO HEADER PAGE OUTPUT
IEXSY EQU 1 SYSTEM HEADER UNALTERED
IEXAL EQU 2 ALTERNATIVE HEADER
IEXBO EQU 3 SYSTEM AND ALTERNATIVE HEADER
*
* INPUT FIELDS FOR THE INPUT EXIT ROUTINE
*
IPRTYP DS C PRINTER TYPE
ILINES EQU X'20' LINES PRINTER TYPE
IPAGES EQU X'21' PAGE PRINTER TYPE
ILOADL EQU X'22' LOADABLE LINE PRINTER TYPE 753
IRBP EQU X'23' RBP PRINTER TYPE 753
IRSOPB EQU X'24' PUBLIC RSO PRINTER 753
IRSOPR EQU X'25' PRIVATE RSO PRINTER 753
IAPAPR EQU X'26' APA PRINTER
IPUNCH EQU X'30' PUNCH TYPE 753
ICLTYP DS C CALL TYPE
INORM EQU X'01' NORMAL CALL 754
IRETRY EQU X'02' RETRY 754
INOBUF EQU X'04' NO BUFFER 754
ISMLHD EQU X'08' SMALL HEADER 802
DS CL2 RESERVED
ISCB@ DS A SCB ADDRESS
ISYIB@ DS A SYSTEM BUFFER
ILNPG DS F # OF LINES PER PAGE
ICHLN DS F # OF CHAR. PER LINE
*
* OUTPUT FIELDS FROM THE INPUT EXIT ROUTINE
*
IUSOB@ DS A USER BUFFER ADDRESS
IUSOBL DS F USER BUFFER LENGTH
ISKIP# DS F # SKIP RECORDS
ISYDF DS F SYSTEM DUPL FACT
IUSDF DS F USER DUPL FACT
DS CL12 RESERVED FOR EXTENSION
*
* INPUT FIELDS FOR THE INPUT EXIT ROUTINE
*
IPIR DS A PRINTER INFORMATION RECORD ADDR. 756
IDVTYP DS AL1 DEVICE TYPE 756
DS XL1 HW ALIGNMENT
IFREQ# DS H SEPARATOR PAGES FREQUENCE # 865
* FREQ# IS INPUT / OUTPUT 865
IFWFR@ DS A ADDR OF 10 FREE FW FOR EXIT 091 865
DS 2F RESERVED - FREE FOR USE 865
ILEN EQU *-IHD ROUTINE EXIT P/L LENGTH
Field contents when calling the exit routine:
IPRTYP | Output device | |
ILINES | line printer | |
IPAGES | laser printer / page printer | |
ILOADL | printer with loadable VFB | |
IRSOPB | RSO public printer | |
IRSOPR | RSO private printer | |
IAPAPR | APA printer | |
ICLTYP | Type of call | |
INORM | normal call | |
IRETRY | retry: required when the memory area for the alternative header page has been destroyed or not set up correctly. | |
INOBUF | no system standard header page: no buffer address ISYIB@ is transferred. The exit routine can initiate an alternative output (ILNPG and ICHLN, see below). | |
FSMLHD | short header page (after a job is aborted) | |
ISCB@ | Address of SPOOL control block (SCB). | |
ISYIB@ | Address of system buffer. | |
ILNPG | Number of lines per header page. | |
ICHLN | Number of characters per line on header page. | |
The exit routine can supply values to the following fields: | ||
IUSOB@ | Class 3 memory address at which the alternative header page is available. | |
IUSOBL | Buffer length used for the alternative header page corresponding to the buffer area requested by the exit routine with $GETMEM. | |
ISKIP# | Number of records in the alternative header page which are to be skipped, i.e. not printed, in the event of a retry. | |
ISYDF | Iteration factor for the output of the standard header page. Default value: 1. | |
IUSDF | Iteration factor for the output of the alternative header page. | |
IPIR | Address of the special printer information record. | |
IDVTYP | Device type | |
Trailer page exit (092)
The exit routine is provided with the following information:
R1 = A(EX092 parameter area) R12 = A(TPR program manager) R13 = A(save area) R14 = A(indirect return) R15 = A(exit routine)
DSECT
A DSECT or CSECT for the parameter area (address in R1) can be generated by means of the EX092 macro (“prefix” must not be longer than 3 characters):
EX092 D
*
* SPOOL TRAILER PAGE ROUTINE EXIT PARAMETER LIST
*
ITR MFCHK MF=D,DMACID=E92,ALIGN=F,SUPPORT=(C,D),ENTRY=NO, C
PREFIX=I,MACID=E92,DNAME=C
ITR DSECT ,
*,##### PREFIX=I, MACID=E92 #####
*
* STANDARD HEADER RETURN INFORMATION
*
IBEG DS 0H
FHDR MF=(C,I),EQUATES=NO
DS 0A
IFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER
*
IIFID DS 0A 0 INTERFACE IDENTIFIER
IFCTU DS AL2 0 FUNCTION UNIT NUMBER
* BIT 15 HEADER FLAG BIT,
* MUST BE RESET UNTIL FURTHER NOTICE
* BIT 14-12 UNUSED, MUST BE RESET
* BIT 11-0 REAL FUNCTION UNIT NUMBER
IFCT DS AL1 2 FUNCTION NUMBER
IFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER
*
IRET DS 0A 4 GENERAL RETURN CODE
ISRET DS 0AL2 4 SUB RETURN CODE
ISR2 DS AL1 4 SUB RETURN CODE 2
ISR1 DS AL1 5 SUB RETURN CODE 1
IMRET DS 0AL2 6 MAIN RETURN CODE
IMR2 DS AL1 6 MAIN RETURN CODE 2
IMR1 DS AL1 7 MAIN RETURN CODE 1
IFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH
*
*
* EQUATES FOR EXIT RETURN INFORMATION IN &P.MR1
*
IEXNT EQU 0 NO TRAIL. PAGE OUTPUT
IEXSY EQU 1 SYSTEM TRAIL. UNALTERED
IEXAL EQU 2 ALTERNATIVE TRAILER PAGE
IEXBO EQU 3 SYSTEM AND ALTERNATIVE TRAILER
* INPUT FIELDS FOR THE INPUT EXIT ROUTINE
*
IPRTYP DS C PRINTER TYPE
ILINES EQU X'20' LINES PRINTER TYPE
IPAGES EQU X'21' PAGE PRINTER TYPE 753
ILOADL EQU X'22' LOADABLE LINE PRINTER TYPE 753
IRBP EQU X'23' RBP PRINTER TYPE 753
IRSOPB EQU X'24' PUBLIC RSO PRINTER 753
IRSOPR EQU X'25' PRIVATE RSO PRINTER 753
IAPAPR EQU X'26' APA PRINTERS
IPUNCH EQU X'30' PUNCH TYPE 753
ICLTYP DS C CALL TYPE
INORM EQU X'01' NORMAL CALL 754
IRETRY EQU X'02' RETRY 754
INOBUF EQU X'04' NO BUFFER 754
DS CL2 RESERVED
ISCB@ DS A SCB ADDRESS
ISYIB@ DS A SYSTEM BUFFER
ILNPG DS F # OF LINES PER PAGE
ICHLN DS F # OF CHAR. PER LINE
*
* OUTPUT FIELDS FROM THE INPUT EXIT ROUTINE
*
IUSOB@ DS A USER BUFFER ADDRESS
IUSOBL DS F USER BUFFER LENGTH
ISKIP# DS F # SKIP RECORDS
ISYDF DS F SYSTEM DUPL FACT
IUSDF DS F USER DUPL FACT
DS CL12 RESERVED FOR EXTENSION
*
* INPUT FIELDS FOR THE INPUT EXIT ROUTINE
*
IPIR DS A PRINTER INFORMATION RECORD ADDR. 756
IDVTYP DS AL1 DEVICE TYPE 756
DS CL11 RESERVED FOR EXTENTION 756
ILEN EQU *-ITR ROUTINE EXIT P/L LENGTH
Field contents when calling the exit routine:
YDDXMAIN | Indicator for the main case | |
IPRTYP | Output device | |
ILINES | line printer | |
IPAGES | laser printer / page printer | |
ILOADL | printer with loadable VFB | |
IRBP | RBP printer | |
IRSOPB | RSO public printer | |
IRSOPR | RSO private printer | |
IAPAPR | APA printer | |
ICLTYP | Type of call | |
INORM | normal call | |
IRETRY | retry: required when the memory area for the alternative trailer page has been destroyed or not set up correctly. | |
INOBUF | no system standard trailer page: no buffer address ISYIB@ is transferred. The exit routine can initiate an alternative output (ILNPG and ICHLN, see below). | |
FSMLHD | short trailer page (after a job is aborted) | |
ISCB@ | Address of SPOOL control block (SCB). | |
ISYIB@ | Address of system buffer. | |
ILNPG | Number of lines per trailer page. | |
ICHLN | Number of characters per line on trailer page. | |
The exit routine can supply values to the following fields: | ||
IUSOB@ | Class 3 memory address at which the alternative trailer page is available. | |
IUSOBL | Buffer length used for the alternative trailer page corresponding to the buffer area requested by the exit routine with $GETMEM. | |
ISKIP# | Number of records in the alternative trailer page which are to be skipped, i.e. not printed, in the event of a retry. | |
ISYDF | Iteration factor for the output of the standard trailer page. | |
IUSDF | Iteration factor for the output of the alternative trailer page. | |
IPIR | Address of the special printer information record. | |
IDVTYP | Device type | |
Structure of the buffer for header/trailer pages
Alternative output
In order to set up an alternative output, the exit routine must reserve a buffer in class 3 memory. The header/trailer pages are made up of records of variable length, i.e. prefixed by a 4-byte record length field. The first 4 bytes of the buffer contain, left-justified, the buffer length used (maximum length: 32767 bytes = X’7FFF’).
where:
bl: buffer length used
rl: record length/line length + 4
_: blank (X' 40')
x: code character for type of output (only evaluated internally by SPOOL), X’0A’ printer
record: for PRINT output: 1 byte print control character (see table) + text
X' 40': No feed before printing
X' 41': 1 line feed before printing
X' 42': 2 line feeds before printing
X' 43': 3 line feeds before printing
Other control characters may lead to undesired results, as they are not interpreted by every device type.
System header page
The header page format depends on the size of the paper and the character set used. The number of lines which can be output on one printed page is determined as follows:
Maximum number of lines = Paper format in inches * lines / inches
Exception: in the case of laser printers, if the header page is output under LOOP control, the number of lines is preset by the VFB.
The lines of the header page are printed according to the order of priority described below (depending on the maximum number of lines).
Order of priority:
Address and identification field (24 lines) User text (10 lines) + 2 blank lines (in "oversize" letters) Job name (10 lines) + 2 blank lines (in "oversize" letters) User ID (10 lines) + 2 blank lines (in "oversize" letters) Account number (10 lines) + 2 blank lines (in "oversize" letters)
If fewer than 24 lines are available, no standard header page is printed. The exit routine can, however, take appropriate action.
Each print line is stored as a variable-length record, i.e. with a leading record length field (4 bytes). Blank lines contain a blank (X’40’) as the record contents.
Example
Format of a standard header page, contingent upon character and line density
Format (page size): 9 x 11 inches
Character set A: 15 characters/inch; 8 lines/inch (= 15 cpi / 8 lpi)
Character set B: 12 characters/inch; 6 lines/inch (= 12 cpi / 6 lpi)
Character set A | Character set B | |
Number of characters per line Number of lines per page | 11 * 15 = 165 9 * 8 = 72 | 11 * 12 = 132 9 * 6 = 54 |
Header page format: | ||
Address field (24 lines) | blank lines: 48 | blank lines: 30 |
Job name (10 + 2 lines) | blank lines: 36 | blank lines: 18 |
User ID (10 + 2 lines) | blank lines: 24 | blank lines: 6 |
Account number (10 + 2 lines) | blank lines: 12 | blank lines: - |
Comments | The entire header | Account number missing |
Length of asterisk lines | 165 '*' | 132 '*' |
Paper feed
After the system trailer page has been printed, the next page is positioned to the first line. This also applies if the header/trailer page is not printed.
Notes on application
The optimum exploitation of the exits described above assumes appropriate cooperation between systems support and the customers, e.g. a standard name for a SAM or ISAM file (or even a job variable). Both privileged and nonprivileged users can use this file to set up an alternative header page.
Example of the format of a standard name:
HEADERPAGETEXT.n, 0 <= n <= 2147.483.639
The alternative header page can be printed using the PRINT-DOCUMENT command (operand HEADER-EXIT-NUMBER=n) or PRNTDOC macro (operand COVPAGE).
The exit routine must then access the file $userid.HEADERPAGETEXT.n and provide the header page buffer with the alternative text.
Whether a header/trailer page is printed depends on the number of characters that can be printed per line.
If separate output blocks are provided by exits 091/092, class 3 memory is required. The memory is released by SPOOL, not by the exits.