CSF_SERVICE_EXIT - ICSF callable services exit

The ICSF callable services exit CSF_SERVICE_EXIT can be used to generate statistics for all ICSF callable services. This exit point occurs after the callable service finished processing, but before the service returns control to the application program. The intent of this exit is for statistics generation.

Controlling the exit routine through the dynamic exits facility

ICSF defined CSF_SERVICE_EXIT to the dynamic exits facility. You can refer to the exit by the name CSF_SERVICE_EXIT. You can use the EXIT statement of the PROGxx parmlib member, the SETPROG EXIT operator command, or the CSVDYNEX macro to control this exit and its exit routines.

If you do not associate any exit routines with CSF_SERVICE_EXIT in the PROGxx parmlib member, the system defaults to having no exit routine.

To limit the number of times the exit routine abnormally ends before it becomes inactive, use the ADDABENDNUM and ABENDCONSEC parameters on the CSVDYNEX REQUEST=ADD macro or the ABENDNUM and CONSEC parameters of the SETPROG EXIT operator command or of the EXIT statement of the PROGxx parmlib member. An ABEND is counted when both of the following conditions exist:
  • The exit routine does not provide recovery or the exit routine does provide recovery, but percolates the error.
  • The system allows a retry; that is, the recovery routine is entered with bit SDWACLUP off.

By default, the system disables the exit routine after two consecutive ABENDs.

Exit routine environment

CSF_SERVICE_EXIT receives control in the following environment:
  • Enabled for I/O and external interrupts.
  • In supervisor state with PSW key 0.
  • In AMODE(31) or AMODE(64), depending on the AMODE of the exit routine.
  • In AR mode.
  • In cross-memory mode with P = ICSF's address space and S = user's address space. Home might or might not equal secondary.
  • With no locks held.
  • Task or SRB mode.

If the callable service was started in AMODE(64) and an exit routine, which is AMODE(31), needs to access the user's parameters, the exit routine needs to switch to AMODE(64). Regardless of AMODE, the exit routine must not rely on the high 32 bits of any general register having a specific value on entry.

An exit routine can change characteristics (AMODE, ASC mode, locks-held state, cross-memory state, and so on) during its processing. However, the exit routine must return with the same characteristics as on entry. If you plan to access the user's parameters, you must write the exits in a language that can access ALET-qualified variable. This is because you are in AR mode and all the user's parameters, including the parameter list itself, are ALET-qualified. In particular, parameters that are passed into a service are in the user's address space, which you can access with an ALET of 1 (secondary).

Exit recovery

If an exit routine ABENDs and does not have recovery that retries, the system records the error to LOGREC and ICSF calls any exit routines that remain to be called. Whether the exit routine continues to be started depends on the ABEND processing of the dynamic exits facility.
Note: ICSF recommends, for system performance reasons, that the exit not establish recovery unless it modifies critical resources.

Entry specifications

ICSF passes the address of the IXIB (ICSF exit interface block) to exit CSF_SERVICE_EXIT.

The contents of the registers on entry to the exit are as follows.
Register
Contents
R0
N/A
R1
Address of IXIB - ICSF exit interface block.
R2 - R12
N/A
R13
Address of 144-byte save area.
R14
Return address.
R15
Entry point address of exit.
AR0
First 4 bytes of 8-byte PARAM area that is provided by the exit routine owner on CSVDYNEX ADD.
AR1
Second 4 bytes of 8-byte PARAM area that is provided by the exit routine owner on CSVDYNEX ADD.
Parameter list contents: Register 1 contains the address of the ICSF exit interface block (IXIB), which resides in the primary address space (ICSF's address space). The IXIB is mapped by macro CSFZIXIB and the layout is shown in Table 1.
Table 1. IXIB control block format
Offset (Dec) Number of bytes Description
0 4 Parmlist with a single entry that points to the IXIB.
4 4 EBCDIC ID.
8 2 Version number of this IXIB.
10 1 Flags
X'80' Bit = 1
Caller is AMODE(31).
X'40' Bit = 1
Caller is AMODE(64).
11 1 PSW key is in the first 4 bits.
12 4 Address of 2048-byte work area.
16 2 IBM assigned service number.
18 2 Installation service number.
20 4 Reserved.
24 8 Service name.
32 8 Original caller's R1.
40 4 Return code from service.
44 4 Reason code from service.
48 16 STCKE value before service called.
64 16 STCKE value after service called.
80 32 Reserved.

Note on original caller's R1

Each ICSF callable service has a unique parameter list. For a description of each service's parameter list, see z/OS Cryptographic Services ICSF Application Programmer's Guide.

Note on exit behavior

Exit routines that are registered to CSF_SERVICE_EXIT must not change any parameters, including the IXIB or anything it points to.