Filter
Top Products
Using CICS API commands in an early verification routine
An early verification routine can use CICS application programming interface (API)
commands, provided it obeys the following interface rules:
v The routine must be written in assembler.
v Entry to the routine must be via the DFHEIENT macro, which saves the caller’s
registers and establishes a CICS early verification API environment.
v Exit from the routine must be via the DFHEIRET macro, which releases the CICS
early verification API environment and restores the caller’s registers.
v The routine must be link-edited with the special security domain API stub,
DFHXSEAI, instead of the normal CICS API stub, DFHEAI0. The CICS early
verification stub causes linkage to a special interface routine that is aware of the
SAF interface linkage requirements, and saves the current CICS command
environment. In addition, the standard EXEC interface stub DFHEAI should also
be included, immediately before the early verification routine, with an ORDER
statement:
INCLUDE SYSLIB(DFHXSEAI)
INCLUDE SYSLIB(DFHEAI)
ORDER DFHEAI,verify-program,DFHEAI0
ENTRY verify-program
The DFHEIENT and DFHEIRET macros are inserted by the CICS translator unless
you specify
*ASM XOPTS(NOPROLOG,NOEPILOG)
as the first statement of the program. The DFHEIENT macro assumes that register
15 points to its first executable instruction.
Upon return from the DFHEIENT macro, a CICS storage area mapped by the
DFHEISTG macro has been established. The pointer DFHEIBP (and the register
specified in the EIBREG parameter of DFHEIENT) contains the address of an
EXEC interface block (EIB). DFHEICAP contains the pointer to the original
parameter list supplied by the SAF interface.
Return and reason codes from the early verification routine
Before returning control, the early verification routine should set a return code and
reason code in fields SAFPRRET and SAFPRREA of the SAF parameter list. It
should also pass a value to be returned as the SAF return code in a register that is
specified in the RCREG keyword of the DFHEIRET macro that is used to exit the
program. These return codes are examined by the CICS signon function, and any
non-zero value in SAFPRRET is interpreted as a verification failure and causes the
signon to fail. A zero return code allows the signon to proceed, and eventually CICS
issues a RACROUTE REQUEST=VERIFY,ENVIR=CREATE macro in supervisor state and
under control of the CICS resource-owning TCB. It is only at this invocation that
CICS accepts an ACEE address from the external security manager.
Chapter 31. Invoking an external security manager 799