When CICS® invokes the ESM, it passes information about the current CICS environment,
for use by an ESM exit program, in an installation data parameter
list. How your exit programs access the installation data parameter list
depends on whether or not your ESM is RACF®.
CICS (or another caller) passes information to your external security
manager in the ESM parameter list, the address of which can be calculated
using field SAFPRACP of the MVS™ router parameter list.
When the caller is CICS, the "INSTLN" field of the ESM parameter list
points to the installation data parameter list, which contains CICS-related
information that can be used by ESM exit programs.
The format of the ESM parameter list, and the actual name of the "INSTLN"
field, vary, depending on which CICS security event is being processed. (The "request
type" field (SAFPREQT) of the router parameter list shows why the ESM
is being called by indicating the RACROUTE REQUEST type.) Table 44 shows
how some formats of the ESM parameter list can be mapped using MVS macros.
Table 44. Mapping the ESM parameter list
RACROUTE
REQUEST type |
Parameter list
mapping macro |
INSTLN
field name |
VERIFY |
IRRPRIPL |
INITIPTR (X'10') |
AUTH |
ICHACHKL |
ACHKIN31 (X'20') |
FASTAUTH |
Not available |
Offset X'18' |
LIST |
Not available |
Offset X'0C' |
EXTRACT |
Not available |
None |
Note:
The INSTLN field points to the installation parameter list
only if you specify INSTLN on the ESMEXITS system initialization parameter.
The default value of
this parameter is NOINSTLN, which means that no installation data is passed.
If you are a RACF user, you can find the address of the installation
data parameter list directly from the RACF user exit parameter list. The name of
the relevant field in the user exit parameter list varies according to the
RACROUTE REQUEST type and the RACF user exit that is invoked. The relationships
between REQUEST type, exit name, and field name are shown in Table 45.
Table 45. Obtaining the address of the installation data parameter list
RACROUTE
REQUEST type |
RACF exit |
Exit list
mapping macro |
Parameter list
field name |
VERIFY |
ICHRIX01 |
ICHRIXP |
RIXINSTL |
VERIFY |
ICHRIX02 |
ICHRIXP |
RIXINSTL |
AUTH |
ICHRCX01 |
ICHRCXP |
RCXINSTL |
AUTH |
ICHRCX02 |
ICHRCXP |
RCXINSTL |
FASTAUTH |
ICHRFX01 |
ICHRFXP |
RFXANSTL |
FASTAUTH |
ICHRFX02 |
ICHRFXP |
RFXANSTL |
LIST |
ICHRLX01 |
ICHRLX1P |
RLX1INST |
LIST |
ICHRLX02 |
ICHRLX2P |
RLX2PRPA
See note 2. |
EXTRACT |
Not available |
Not available |
None |
Notes:
- The "xxxINSTL" field points to the installation parameter list
only if you specify INSTLN on the ESMEXITS system initialization parameter.
The default value of this parameter is NOINSTLN, which means that no installation
data is passed.
- RLX2PRPA contains the address of the ICHRLX01 user exit parameter
list (RLX1P). Field RLX1INST of RLX1P in turn points to the installation data
parameter list.
For full descriptions of the RACF exit parameter lists, see the OS/390 Security Server (RACF) Security Administrator’s Guide manual.
For more information about CICS security processing using RACF, see the CICS RACF Security Guide.
The installation data parameter list gives your ESM exit programs access
to the following information:
- The CICS security event being processed.
- Details of the current CICS environment. That is:
- The applid of the CICS region
- The common work area (CWA)
- The transaction being invoked
- The program being executed
- The CICS terminal identifier
- The VTAM® LU name
- The terminal user area.
You can map the installation parameter list using the macro DFHXSUXP. The
DSECT DFHXSUXP contains the following fields:
- UXPLEN
- A halfword containing the length of this parameter list in bytes.
- UXPARROW
- Arrow "eyecatcher" (>).
- UXPDFHXS
- The name of the owning component (DFHXS).
- UXPBLKID
- The name of the block identifier (UXPARMS).
- UXPPHASE
- Address of a 1-byte code that indicates the reason for the call to the
ESM (that is, the security event being processed). The code can have one of
the following values:
- DEFAULT_SIGN_ON (X'01')
- Signon of default userid
- PRESET_SIGN_ON (X'02')
- Signon of preset security terminal
- IRC_SIGN_ON (X'03')
- Link signon for IRC (MRO) links
- LU61_SIGN_ON (X'04')
- Link signon for LUTYPE6.1 links
- LU62_SIGN_ON (X'05')
- Link signon for APPC links
- XRF_SIGN_ON (X'06')
- XRF tracking of signon
- ATTACH_SIGN_ON (X'07')
- Attach-time signon of link user
- NON_TERMINAL_SIGN_ON (X'08')
- Signon of a non-terminal userid
- USER_SIGN_ON (X'10')
- Normal user signon
- PRESET_SIGN_OFF (X'22')
- Sign-off when terminal deleted
- LINK_SIGN_OFF (X'25')
- Sign-off when link is closed
- XRF_SIGN_OFF (X'26')
- XRF tracking of sign-off
- ATTACH_SIGN_OFF (X'27')
- End-of-task sign-off of link user
- NON_TERMINAL_SIGN_OFF (X'28')
- Sign-off of a non-terminal userid
- USER_SIGN_OFF (X'30')
- Normal user sign-off
- TIMEOUT_SIGN_OFF (X'31')
- Sign-off forced by the terminal abnormal condition program, or time-out
by the CSSC transaction
- USRDELAY_SIGN_OFF (X'32')
- Sign-off caused by expiry of USRDELAY interval
- DEFERRED_SIGN_OFF (X'33')
- Sign-off deferred to task end
- USER_ATTACH_CHECK (X'40')
- Transaction attach check for user
- LINK_ATTACH_CHECK (X'41')
- Transaction attach check for link
- EDF_ATTACH_CHECK (X'42')
- Transaction attach check for CEDF
- USER_COMMAND_CHECK (X'50')
- Command checking for user
- LINK_COMMAND_CHECK (X'51')
- Command checking for link
- EDF_COMMAND_CHECK (X'52')
- Command checking for EDF
- USER_RESOURCE_CHECK (X'60')
- Resource checking for user
- LINK_RESOURCE_CHECK (X'61')
- Resource checking for link
- EDF_RESOURCE_CHECK (X'62')
- Resource checking for EDF
- USER_SURROGATE_CHECK (X'68')
- Surrogate checking for user
- LINK_SURROGATE_CHECK (X'69')
- Surrogate checking for link
- EDF_SURROGATE_CHECK (X'6A')
- Surrogate checking for EDF
- USER_QUERY_CHECK (X'70')
- Query checking for user
- LINK_QUERY_CHECK (X'71')
- Query checking for link
- EDF_QUERY_CHECK (X'72')
- Query checking for EDF
- INITIALIZE_SECURITY (X'80')
- Initialization of CICS security
- REBUILD_SECURITY (X'81')
- CEMT or command-level SECURITY REBUILD
- XRF_TRACK_INITIALIZE (X'82')
- XRF tracking of initial or rebuild.
- UXPSUBSY
- Address of an area containing the CICS subsystem identifier.
- UXPAPPL
- Address of an area containing the CICS application ID.
Note:
When CICS is a member of a VTAM generic resource, the area pointed to
by UXPAPPL contains the generic, not the specific,
applid.
- UXPCWA
- Address of the Common Work Area.
- UXPTRAN
- Address of an area containing the transaction identifier.
- UXPPROG
- Address of an area containing the program name. The address may be zero
if no program name can be identified.
- UXPTERM
- Address of an area containing the terminal identifier. The address may
be zero if no terminal is associated with the request.
- UXPLUNAM
- Address of an area containing the VTAM LU name. The address may be zero if no
terminal is associated with the request, or the area may be blank if the terminal
is not a VTAM terminal.
- UXPTCTUA
- Address of the TCT user area.
- UXPTCTUL
- Address of a fullword containing the length of the TCTUA.
- UXPCOMM
- Address of a 2-word communication area.

[[ Contents Previous Page | Next Page Index ]]