This topic contains Product-sensitive
Programming Interface and Associated Guidance Information.
This section summarizes the RACROUTE macros used
by CICS® to invoke the ESM, and the control points
at which they are issued.
Some of these calls may not always be issued, because
CICS reuses entries for users already signed on.
- RACROUTE
- This is the "front end" to the macros described below; it
invokes the MVS™ router.
- RACROUTE REQUEST=VERIFY
- This macro is issued at operator sign-on (with the parameter ENVIR=CREATE),
and at signoff (with the parameter ENVIR=DELETE). It creates or destroys
an ACEE (access control environment element). It
is issued at the following CICS control points (it is also issued
(with the parameter ENVIR=VERIFY) early in normal sign-on through
EXEC CICS SIGNON, but this call is ignored by RACF®):
Each of the following control points relates to ENVIR=CREATE:
- Normal sign-on through EXEC CICS SIGNON
- Sign-on of the default userid DFLTUSER
- Sign-on of preset-security terminal
- Sign-on of MRO session
- Sign-on of LU6.1 session
- Sign-on of LU6.2 session
- Sign-on for XRF tracking of any of the above
- Sign-on associated with the userid on an attach request (for all
operands of ATTACHSEC except LOCAL).
Each of the following control points relates to ENVIR=DELETE:
- Normal sign-off through EXEC CICS SIGNOFF
- Sign-off when deleting a terminal
- Sign-off when TIMEOUT expires
- Signoff when USRDELAY expires
- Sign-off of MRO session
- Sign-off of LU6.1 session
- Sign-off of LU6.2 session
- Sign-off for XRF tracking of any of the above.
- Sign-off associated with the userid on an attach request (for
all operands of ATTACHSEC except LOCAL).
- RACROUTE REQUEST=VERIFYX
- This macro creates and deletes an ACEE in a single call. It is
issued at the following control points:
- Sign-on, as an alternative to VERIFY, when an optimized sign-on
is performed for subsequent attach sign-ons across an LU6.2 link with
ATTACHSEC(VERIFY) or ATTACHSEC(PERSISTENT).
- When an invalid password or PassTicket is presented.
When a login process involving
password verification, such as the EXEC CICS VERIFY PASSWORD command,
is used to log in a user, and the original attempt to verify the password
using the RACROUTE VERIFY=EXTRACT macro has failed.
- RACROUTE REQUEST=FASTAUTH
- This macro is issued during resource checking, on behalf of a
user who is identified by an ACEE. It is the high-performance form
of REQUEST=AUTH, using in-storage resource profiles, which does not
cause auditing to be performed. It is issued at the following CICS
control points:
- When attaching a local transaction
- When checking link security for transaction attach
- Transaction validation for an MRO task
- CICS resource checking
- Link security check for a CICS resource
- Transaction validation for EDF
- Transaction validation for the transaction being tested (by EDF)
- DBCTL PSB scheduling resource security check
- DBCTL PSB scheduling link security check
- Remote DL/I PSB scheduling resource check
- When checking a surrogate user authority
- QUERY SECURITY with the RESTYPE option.
- When an enterprise bean invokes the isCallerInRole() method.
- When checking the authority of a user to invoke an enterprise
bean method.
- RACROUTE REQUEST=AUTH
- This macro provides a form of resource checking with a larger
pathlength, and causes auditing to be performed. It is used as follows:
- After a call to FASTAUTH indicates an access failure that requires
logging.
- When a QUERY SECURITY request with the RESCLASS option is used.
This indicates a request for a resource for which CICS has not built
in-storage profiles.
- RACROUTE REQUEST=LIST
- This macro is issued to create and delete the in-storage profile
lists needed by REQUEST=FASTAUTH. (One REQUEST=LIST macro is required
for each resource class.) It is issued at the following CICS control
points:
- When CICS security is being initialized
- When an EXEC CICS PERFORM SECURITY REBUILD command is issued
- When XRF tracks either of these events.
- RACROUTE REQUEST=EXTRACT
This macro is issued when
a login process involving password verification, such as the EXEC
CICS VERIFY PASSWORD command, is used to log in a user. If the password
cannot be verified using this macro, CICS subsequently issues the
RACROUTE REQUEST=VERIFYX macro. 
The RACROUTE
REQUEST=EXTRACT macro is also issued, with the parameters SEGMENT=CICS,CLASS=USER,
and with the SEGMENT=BASE,CLASS=USER parameters to obtain the national
language and user name, at all the following control points:
- Normal sign-on through EXEC CICS SIGNON
- Sign-on of the default userid DFLTUSER
- Sign-on of preset security terminal
- Sign-on of MRO session
- Sign-on of LU6.1 session
- Sign-on of LU6.2 session
- Sign-on for XRF tracking of any of the above
- Sign-on associated with the userid on an attach request (for all
operands of ATTACHSEC except LOCAL).
It can be used to verify the user's password when an entry in
the user table is reused within the USRDELAY period.
It is
also issued (with the parameters SEGMENT=SESSION,CLASS=APPCLU) during
verification of LU6.2 bind security, at the CICS control point for
bind of an LU6.2 sessions.
There is no RACF user exit for REQUEST=EXTRACT,
and no installation parameter data is passed. Any customization must
be done using the MVS router exit, ICHRTX00.
For a detailed description of these macros, see the z/OS
Security Server RACROUTE Macro Reference.