Installation exit control blocks
Because the installation exits that PSF supports can be written
in either assembly language or C language, the installation exit control
blocks must also be provided in both assembly language and C language.
During PSF installation, the source code for the assembler control
blocks is installed into SYS1.MACLIB and the source code for the corresponding
C header files is installed into SYS1.SAPSHDR.H. Table 30 lists
the assembly language name and the corresponding C header file name
for each installation exit control block.
Note:
Unless otherwise
specified, the assembly name of a control block is used in this information to
represent either the assembly control block or the C control block.
When PSF calls an exit routine, register 1 points to a one-word
parameter list that contains the address of the APSGEXTP area. This
area contains the address of the APSUECA exit-communication area,
pointers to JSPA, and pointers to the input records associated with
Exit 4, Exit 6, Exit 7, and Exit 16. When the exit routine returns
to PSF, PSF does not check register 15 for a return code.
Table 30. Installation exit control blocks| Assembler Name | C Name | Description |
|---|
| APSGEXTP | APSGEXTC | Installation exit parameter area | | APSLCRL | APSUCRLC | Concatenated retrieval list | | IEFDOKEY | APSUDOKC | Dynamic output key mapping | | IEFDOTUM | APSUDOTC | Dynamic output text unit mappings | | APSUECA | APSUECAC | Exit-communication area | | IAZIDX | APSUIDXC | Index table | | IEFJESCT | APSUJESC | Job Entry Subsystem communication table | | IEFJMR | APSUJMRC | Job management record | | IAZJSPA | APSUJSPC | Job separator page data area | | APSUXP16 | APSUP16C | Installation Exit 16 parameter area | | APSURLST | APSURLSC | Exit 7 resource list | | APSUSEPC | Separator exits header file | | APSUSEP | Separator exits header file for APSUC01 and APSUC02 | | APSUSEPP | Separator exits header file for APSUC01P and APSUC02P | | IEFSJTRC | APSUSJCC | SJF SWBTUREQ Services return and reason codes | | IEFSJTRP | APSUSJTC | SJF SWBTUREQ retrieve and parameter list | | IFASMFR | APSUSMFC | SMF records macro | APSGEXTP area
The format of APSGEXTP is shown in Figure 76. Values
in parentheses are in hexadecimal.
For information about the contents of XTP7, see Figure 95.
Figure 76. Format of the APSGEXTP area
Offsets Type Length Name Description
0 (0) Structure 40 APSGEXTP PSF-exit-parameter area
===============================================================================
The following fields provide input to the installation exit processor routines.
===============================================================================
0 (0) Address 4 XTPECAP Exit-communication-area address.
4 (4) Address 4 XTPJSPAP Pointer to JES separator page
area of the last data set
(with a separator, might be zero).
8 (8) Address 4 XTPRECP Pointer to input record.
12 (C) Signed 4 XTPRECL Input-record length.
===============================================================================
The following fields are set by the installation exit processor routines to
provide an interface back to PSF. On input to processors, XTPRIXP points to a
record index entry. On output, if the processor indicates "write index",
XTPRIXP must point to the newly created index header.
===============================================================================
16 (10) Character 4 * Reserved.
20 (14) Address 4 XTPRIXP Pointer to record table index.
24 (18) Unsigned 1 XTPPIND Processing indicator.
25 (19) Bitstring 1 XTP4FLAG Exit 4 or Exit 14 flags.
1... .... XTP4NTY PSF will send end-of-transmission
(EOT) indicator to Exit 4.
.1.. .... XTP4NEOT Normal EOT has occurred.
..1. .... XTP4ABNE Abnormal EOT has occurred.
...1 .... XTP4NCAL Call Exit 4 one time.
When this flag is set ON, Exit 4 will
not be called again until EOT or the
next copy of the data set or the next
data set. This flag is reset when
Exit 4 is called for the first record
of the next copy of the data set or
the next data set.
.... 1... XTP4CONV Do line-mode conversion. When
this flag is set on, 3800 Line-
Mode Conversion is activated.
This flag is reset when
Exit 4/14 is called for the
first record of the
transmission.
.... .1.. XTP4WINA Wide or narrow paper flag. This
flag is only used when XTP4CONV
is set on (3800 Line-Mode
Conversion is active) and the
printer is in cut-sheet
emulation mode. When this flag
is set on, landscape pages are
generated for printing in cut-
sheet emulation mode. When this
flag is set off, portrait pages
are generated for printing in
cut-sheet emulation mode. This
flag is reset when Exit 4/14 is
called for the first record of
the transmission (the next copy
of the data set or the next
data set).
.... ..1. XTP4LMRG Line merge flag. This flag is
only used when XTP4CONV is set
on (3800 Line-Mode Conversion is
active). When this flag is set
on, PSF performs the line merge
function like the 3800 printer
in “line mode.”
This flag is reset when Exit
4/14 is called for the first
record of the transmission.
.... ...1 * Reserved.
26 (1A) Character 4 * Reserved.
30 (1E) Bitstring 1 XTP5FLAG Exit 5 SMF 6 flags.
1... .... XTP5NEWS Processing JESNEWS data set.
.111 1111 * Reserved.
31 (1F) Unsigned 1 XTP4DPLX Duplex value. This field is
only valid when XTP4CONV is set on
(3800 Line-Mode Conversion is active).
0 = Not specified (defaults to
formdef value)
1 = Simplex
2 = Normal duplex
3 = Tumble duplex
This field is set to zero when
Exit 4/14 is called for the
first record of the transmission.
32 (20) Unsigned 2 XTP4XOFF Set horizontal offset-
pels at 240 pels/inch.
Valid only when
XTP4CONV is set ON.
34 (22) Unsigned 2 XTP4YOFF Set vertical offset-
pels at 240 pels/inch.
Valid only when
XTP4CONV is set ON.
36 (24) Character 4 * Reserved.
============================================================================
The following fields provide input to the installation Exit 6 (message exit)
============================================================================
0 (0) Structure 24 XTP6 Exit 6 input record.
0 (0) Character 8 XTP6PROC FSA identifier:
The label of the PRINTDEV statement.
8 (8) Character 8 XTP6MSG Message ID (APSXXXXI).
16 (10) Character 1 XTP6TYPE Message TYPE.
W=WTO: Most WTO messages
are asynchronous. Async
messages belong to the data
set on the printer, which may
be different from the one
being processed by PSF.
XTPJSPAP points to the JSPA
related to the data set
currently being processed by PSF.
17 (11) Bitstring 1 XTP6FLAG Exit 6 indicators
1... .... XTP6INTP Message is targeted for the
interrupt message page.
.111 1111 * Reserved.
18 (12) Character 1 XTP6FLG1 Exit 6 processing indicators.
1... .... XTP6TFSA Terminate the FSA. PSF will
complete the processing of the
current data set (the one
being processed by PSF, which
may be different from the one
on the printer), and terminate
the FSA.
.1.. .... XTP6HOLD Release the data set currently
being processed by PSF to JES,
and mark the data set as
unprintable.
..1. .... XTP6TJOB Terminate the job associated with
the interrupt message page.
...1 1111 * Reserved.
19 (13) Bitstring 1 XTP6ACT Action to be taken by PSF:
Set by PSF on input;
can be altered by the exit.
If XTP6ACT is set to 0 by the
exit, the message is
suppressed.
1... .... XTP6WTO Put msg to op. console.
.1.. .... XTP6SEC Put msg to sec. console.
..1. .... XTP6PAP Put msg to paper (msg data set).
...1 1111 * Reserved.
20 (14) Character 4 * Reserved.
============================================================================
The fields for installation Exit 7 (DSECT) are found in the appendix for
"Field Descriptions for Exit 7".
============================================================================
0 (0) Structure 233 XTP7 Exit 7 input record.
============================================================================
The following fields are used for installation Exit 8 (Line-Mode Migration)
============================================================================
0 (0) Structure 10 XTP8 Exit 8 input record.
0 (0) Character 1 XTP8FLAG Exit 8 flags.
1... .... XTP8MIG Do Line-Mode Migration for a 4245
FCB flag. When this flag is set on,
Line-Mode Migration is activated
for a 4245 FCB (FCB2). This flag is
reset when Exit 8 is called.
.1.. .... XTP8MIG4 Do Line-Mode Migration for a 4248
FCB flag. When this flag is set on,
Line-Mode Migration is activated
for a 4248 FCB (FCB4). This flag is
reset when Exit 8 is called.
..1. .... XTP8PBSP Honor page boundary spacing. When
this flag is set on, page boundary
spacing is honored in Line-Mode
Migration. This flag is reset when
Exit 8 is called.
...1 1111 * Reserved.
1 (1) Character 9 * Reserved.
Exit-communication areas: APSUECA and APSUECE
APSGEXTP provides addressability to the exit-communication area
(APSUECA) and to its extension (APSUECE). These areas provide the
interface among the exit routines.
The format of APSUECA is shown in Figure 77. Values enclosed
in parentheses are in hexadecimal.
Figure 77. Format of exit-communication area, APSUECA
Offsets Type Length Name Description
0 (0) Structure * APSUECA Exit-Communication Area.
0 (0) Character * ECABASE Base section of ECA.
0 (0) Character 4 ECAID Control-block ID set to the
character string UECA.
4 (4) Signed 4 ECALEN Length of exit-communication area.
8 (8) Character 6 ECAPTF Relative PTF date.
14 (E) Character 2 ECAREL Release level.
16 (10) Signed 4 ECARCODE RRB PUT return code.
20 (14) Address 4 ECAUCOMP Address of exit APSUCOM table.
24 (18) Address 4 ECAPUTP Address of exit PUT routine.
28 (1C) Address 4 ECABLKP Address of exit block-letter routine.
32 (20) Address 4 ECASABP Address of APSPFSAB. (PSF usage only.)
36 (24) Address 4 ECAECEP Address of exit-communication
extension.
40 (28) Address 4 ECAMARP 3800 -3/8 migration aid
pointer.
44 (2C) Character 4 ECAFORM Form name in output JCL
(FORMS= ).
48 (30) Bitstring 1 ECAMFCS Mark form carrier strip flag.
49 (31) Character 6 ECARNDM Separator page random number.
55 (37) Character 1 ECAFLAG ECA flags.
1... .... ECAMFTRL Mark forms inhibit flag for
job trailer.
0 = job trailers may be
marked.
1 = do not mark job trailers.
=================================================================================
The combination of these ECALSTDS and ECAFSTDS flags and their meanings are:
00 = Middle data set (not first or last data set)
01 = First data set
10 = Last data set
11 = Only data set
=================================================================================
.1.. .... ECALSTDS Last data set.
0 = Not the last data set of the job.
1 = Last data set of job.
..1. .... ECAFSTDS First data set.
0 = Not the first data set of the job.
1 = First data set of the job.
...1 .... ECACUTSH Cut-sheet output.
0 = Not cut-sheet output.
1 = Cut-sheet output - Either cut-
sheet printer or continuous
forms printer with BTS.
.... 1... ECADUPEN Duplex enabled.
0 = Duplex not enabled.
1 = Duplex enabled - Duplex available
from at least one media source.
.... .111 * Reserved.
56 (38) Address 4 ECARECAD Address of a record to be put
to PSF from an exit processor.
60 (3C) Signed 4 ECARECLN Length of exit record.
64 (40) Bitstring 1 ECADRF Record description flags.
1... .... ECADSR Indicates data-stream record.
.1.. .... ECALMR Indicates line-mode record.
..1. .... ECAANSI Record contains ANSI control
characters.
...1 .... ECAMACH Record contains machine
control characters.
.... 1... * Reserved (PSF use only).
.... .1.. * Reserved (PSF use only).
.... ..1. * Reserved (PSF use only).
.... ...1 ECAOPJ OPTCD=J used for record.
65 (41) Signed 1 ECAPTYPE Product type of call:
1 = PSF (ECAPSF)
2 = Download (ECADOWN)
3 = AFP Download Plus (ECAAFPDP)
66 (42) Signed 2 ECATRNC Transmission count.
68 (44) Bitstring 1 ECAFLAGS Exit-control flags.
1... .... ECASLANT Slant letters requested.
.1.. .... ECALJUST Left-align block letter
lines.
..1. .... ECAPBLK Performance-block letters.
...1 1111 * Reserved.
69 (45) Bitstring 1 * Reserved.
70 (46) Signed 2 ECAGWRK General-use work field.
72 (48) Character 8 ECABLKIN Input to block letter routine.
80 (50) Character 72 ECAUSAVE Exit processor's save area.
152 (98) Character 72 ECAGSAVE General-use exit save area.
224 (EO) Character 72 ECABSAVE 24-bit interface return save area.
296 (128) Character 72 ECAMSGSV Exit 6 (message) exit save area.
368 (170) Character 72 ECARSCSV Exit 7 (resource) exit save area.
440 (1B8) Character 72 ECACSAVE C exit routine save area.
512 (200) Character * ECAWKBUF The work buffer (ECAWKBUF)
length depends on a field in
APSUCOM. Minimum length of
the ECA, including the work
buffer, is 2039 bytes.The
The minimum length of the
work buffer is 1599 bytes.
If you do not want PSF to generate separator pages, delete or modify
the separator-page exits. For information about how to do this, see Programming with separator-page exits.
The format of APSUECE is shown in Figure 78. Values
enclosed in parentheses are in hexadecimal.
Figure 78. Format of exit-communication area extension, APSUECE
Offsets Type Length Name Description
0 (0) Character * APSUECE Exit extension.
0 (0) Character 4 ECEID Control Block ID set 'UECE'.
4 (4) Signed 4 ECELEN Length of ECE.
8 (8) Character 6 ECEPTF Relative PTF date.
14 (E) Character 2 ECEREL Release level.
16 (10) Address 4 ECEFECAP Addr of FSA ECA, used by
Exits 1-4, 6, 7, 8, 14, 15, 16.
20 (14) Address 4 ECENECAP Addr of NST ECA, used by Exit 5.
24 (18) Character 8 ECEPRMD PRMODE defined in JCL output.
32 (20) Character 4 ECEFLASH Flash defined in JCL output.
36 (24) Character 8 ECEDPDEF PAGEDEF defined in PRINTDEV.
44 (2C) Character 8 ECEDFDEF FORMDEF defined in PRINTDEV.
52 (34) Address 4 ECEFSSWK FSS work area printer.
56 (38) Character 8 ECEPDEVK PRINTDEV SWB token.
64 (40) Character 8 ECEOUTTK Print data set SWB token.
72 (48) Character 8 ECEJDVTN Print data set JDVT name.
80 (50) Character 2 ECEPRTT Printer type (eg. X'3800')
that the device is emulating
(from the IPDS STM).
82 (52) Character 1 ECEPRTM Printer model number (e. g.
X'03') that the device is
emulating (from the IPDS STM).
83 (53) Bitstring 1 ECEFLAG Exit flags.
1... .... ECEJESS JES supports Enhanced SYSOUT
Support (ESS) JCL.
.1.. .... ECERPM RPM is attached.
..1. .... ECEDPF DPF is attached.
...1 .... ECEPSFD PSF Direct is attached.
.... 1... ECEWPM WPM is attached.
.... .111 * Reserved.
84 (54) Character 8 ECEFORM Form name in output JCL (FORMS= ).
92 (5C) Character 4 ECEPRTDT Printer device type, stamped
on the printer in EBCDIC
(from the IPDS OPC, or IPDS
STM if none in the OPC).
96 (60) Character 3 ECEPRTMD Printer model number, stamped on
the printer in EBCDIC (from the
IPDS OPC, or IPDS STM if not in
the OPC).
99 (63) Character 1 * Reserved.
100 (64) Address 4 ECEBTBL Address of block letter tables.
Do not modify ECEBTBL; it is used
by APSUBLK.
104 (68) Signed 4 ECEJOBLP Logical pages in job.
108 (6C) Signed 4 ECEJOBIM Impressions (sides) in job.
112 (70) Signed 4 ECEJOBPP Physical sheets in job.
116 (74) Address 4 ECEWKPTR Address of exit work area.
120 (78) Signed 4 ECEWKLEN Length of exit work area.
124 (7C) Address 4 ECETUPTR SWBTU address.
128 (80) Signed 4 ECETULEN SWBTU length.
132 (84) Signed 4 ECEREC Logical record count (doesn't include
header or trailer page records).
136 (88) Signed 4 ECELPCNT Logical page count (includes header
and trailer pages).
140 (8C) Signed 4 ECEPPCNT Physical sheet count (includes header
and trailer sheets).
144 (90) Signed 4 ECEDSCNT Physical duplex sheet count (includes
header and trailer sheets).
148 (94) Signed 4 ECESSCNT Physical simplex sheet count (includes
header and trailer sheets).
152 (98) Signed 4 ECENUP1C Physical N_UP 1 sheet count (includes
header and trailer sheets).
156 (9C) Signed 4 ECENUP2C Physical N_UP 2 sheet count (includes
header and trailer sheets).
160 (A0) Signed 4 ECENUP3C Physical N_UP 3 sheet count (includes
header and trailer sheets).
164 (A4) Signed 4 ECENUP4C Physical N_UP 4 sheet count (includes
header and trailer sheets).
168 (A8) Signed 2 ECESCPY Separator copy count.
170 (AA) Signed 2 ECETXMS Total transmission required.
=================================================================================
The following addresses are valid only for assembler exits.
=================================================================================
172 (AC) Address 4 ECEX01P Address of Exit 1.
176 (B0) Address 4 ECEX02P Address of Exit 2.
180 (B4) Address 4 ECEX03P Address of Exit 3.
184 (B8) Address 4 ECEX04P Address of Exit 4.
188 (BC) Address 4 ECEX05P Address of Exit 5.
192 (C0) Address 4 ECEX06P Address of Exit 6.
196 (C4) Address 4 ECEX07P Address of Exit 7.
200 (C8) Address 4 ECEX08P Address of Exit 8.
204 (CC) Address 4 ECEX09P Reserved.
208 (D0) Address 4 ECEX10P Reserved.
212 (D4) Address 4 ECEX11P Reserved.
216 (D8) Address 4 ECEX12P Reserved.
220 (DC) Address 4 ECEX13P Reserved.
224 (E0) Address 4 ECEX14P Address of Exit 14
(in direct print mode only).
228 (E4) Address 4 ECEX15P Address of Exit 15.
232 (E8) Address 4 ECEX16P Address of Exit 16
(in direct print mode only).
236 (EC) Signed 4 ECEIMPS Impressions (sides)
printed for the data set.
240 (F0) Character 12 ECEDSID FSI GETDS data set ID.
252 (FC) Address 4 ECELMO Reserved for LMO.
256 (100) Address 4 ECEPUTC Address of APSUPUTC.
260 (104) Address 4 ECEBLKC Address of APSUBLKC.
264 (108) Character 8 ECEFSSNM FSS name (writer proc name).
272 (110) Character 4 ECEFCB FCB name in OUTPUT JCL.
276 (114) Character 12 * Reserved.
If repositioning is required, PSF can enter the exit routines for
header pages (Exit 1 and Exit 3) more than once, but the header pages
might not reprint unless the repositioning calls for the header pages
to reprint. When PSF enters either Exit 1 or Exit 3, PSF sets ECATRNC
to the current transmission count, which can be used to determine
whether the exit has been reentered. An installation exit should not
attempt to skip pages or duplicate pages if the exits are reentered;
such an attempt might interfere when PSF is repositioning for error
recovery.
The following fields are described in more detail:
- ECEFSSWK
- Address of 32 bytes of functional subsystem (FSS) storage.
This
address is passed to all exits in the same address space. When multiple
functional subsystem applications (FSAs) are running in an FSS, the
same address is passed to all the FSAs.
The exits can use this
storage to communicate among different FSAs or to save data between
FSA sessions. This storage is not freed until the FSS is stopped.
The
FSS storage is for the exclusive use of the exits. PSF does not read
or modify this storage.
The exit must serialize the use of the
FSS storage, because more than one FSA subtask (or an FSA and the
NST subtask) can be active at the same time in the FSS address space.
- ECEOUTTK
- The scheduler work block (SWB) token for the OUTPUT JCL statement
of the print data set.
PSF uses ECEOUTTK to retrieve the keywords
specified in the OUTPUT JCL statement of the print data set.
JES
passes this token to PSF in the functional subsystem interface (FSA)
GETDS parameter list (IAZFSIP).
For more information about
SWBs and how to use the SWB token to retrieve keywords, see z/OS MVS Using the Functional Subsystem Interface.
Note:
The SWB contains JCL values merged from the DD statement,
the OUTPUT statement, and the JES defaults according to the resource
hierarchy. JES merges the values before allocating the print data set to
PSF. When the JCL values are returned, therefore, there is no way
to determine whether a particular value was specified on the print data set or
defaulted to by JES.
- ECEPRTT
- ECEPRTT contains the printer device type that the printer is
functionally emulating, as provided in the IPDS Sense Type and Model command.
The functional emulation extends only as far as IPDS deviations and PSF software
dependencies for the support of certain functions. Not all of the
functions supported are identical.
- ECEPRTM
- ECEPRTM contains the printer model that the printer is functionally
emulating, as provided in the IPDS Sense Type & Model command. The functional
emulation extends only as far as IPDS deviations and PSF software dependencies
for the support of certain functions. Not all of the functions supported
are identical.
- ECEPRTDT
- ECEPRTDT contains the printer device type, as provided in the IPDS Obtain Printer
Characteristics Product Identifier Self-Defining Field; that field
is in the XOA-OPC command. If the printer does not contain a device
type in that field, ECEPRTDT matches ECEPRTT, and ECEPRTMD matches
ECEPRTM.
- ECEPRTMD
- ECEPRTMD contains the printer model, as provided in the IPDS Obtain Printer
Characteristics Product Identifier Self-Defining Field. If the printer
does not contain a model in that field, ECEPRTDT matches ECEPRTT,
and ECEPRTMD matches ECEPRTM.
- ECEWKPTR
- The address of a local work area
for the PSF and AFP Download Plus exits.
ECEWKPTR can be used as a local
work area by installation-written exits. The work area length is 1024
bytes.
The separator exits supplied by PSF exits use this area.
If those exits are used, therefore, this area should not be used to
retain data across exit invocations.
- ECETUPTR
- The address of the SWBTU for the print data set’s OUTPUT JCL
statement.
You can use the SWBTUREQ macro to obtain the JCL parameters
specified for the print data set. The SWBTU address is input to the
SWBTUREQ macro. ECETULEN contains the SWBTU length.
The separator
exits supplied by PSF contain an example of how to start the SWBTUREQ
macro.
For more information about the SWBTUREQ macro, see z/OS® MVS™ Programming: Authorized Assembler Services Reference.
Note:
The SWBTU contains JCL values merged from the DD statement,
the OUTPUT statement, and the JES defaults according to the resource
hierarchy. JES merges these values before allocating the print data set to
PSF. When the JCL values are returned, therefore, there is no way
to determine whether a particular value was specified on the print data set or
defaulted to by JES.
- ECELPCNT
- The logical page count, including header and trailer pages.
The header page is added to the count after APSUX01 has returned to
PSF while the trailer page is added after APSUX02 has returned.
- ECEPPCNT
- The physical sheet count, including header
and trailer sheets. The header sheet is
added to the count after APSUX01 has returned to PSF while the trailer sheet is added after APSUX02 has returned.
- ECEDSCNT
- The physical duplex sheet count, including header and trailer
sheets. The header sheet is added to the count after APSUX01 has returned
to PSF while the trailer sheet is added after APSUX02 has returned.
- ECESSCNT
- The physical simplex sheet count, including header and trailer
sheets. The header sheet is added to the count after APSUX01 has returned
to PSF while the trailer sheet is added after APSUX02 has returned.
- ECENUP1C
- The physical N_UP 1 sheet count, including header and trailer
sheets. The header sheet is added to the count after APSUX01 has returned
to PSF while the trailer sheet is added after APSUX02 has returned.
- ECENUP2C
- The physical N_UP 2 sheet count, including header and trailer
sheets. The header sheet is added to the count after APSUX01 has returned
to PSF while the trailer sheet is added after APSUX02 has returned.
- ECENUP3C
- The physical N_UP 3 sheet count, including header and trailer
sheets. The header sheet is added to the count after APSUX01 has returned
to PSF while the trailer sheet is added after APSUX02 has returned.
- ECENUP4C
- The physical N_UP 4 sheet count, including header and trailer
sheets. The header sheet is added to the count after APSUX01 has returned
to PSF while the trailer sheet is added after APSUX02 has returned.
|
PSF for z/OS: Customization
Copyright IBM Corporation 1990, 2014