Using the content of XAPLDIAG

The RACF access control module returns a parameter, XAPLDIAG, that Db2 and other licensed programs can use to trap and obtain diagnostic information.

When the RACF access control module issues the RACROUTE REQUEST=FASTAUTH macro for authorization checking, depending on the AUDIT options used with the check, the module can record the resulting SAF return code, RACF return code, and RACF reason code in XAPLDIAG. Each invocation of the RACF access control module can issue multiple RACROUTE REQUEST=FASTAUTH macros, but the module evaluates each return code generated and determines the single correct return code to send to Db2.

The RACF access control module can store up to 20 sets of return codes from RACROUTE REQUEST=FASTAUTH macros in XAPLDIAG, allowing the results of a specific RACROUTE REQUEST=FASTAUTH macro to be determined.

The XAPL parameter list can be captured using Db2 trace record IFCID 314. In addition, the return code and corresponding reason code (EXPLRC1 and EXPLRC2) for authorization failures are captured in Db2 trace record IFCID 140.

The content of XAPLDIAG depends on the return code and reason code from the RACF access control module. The return and reason codes in XAPLDIAG are in the same order as the checks that are described in the rules table for each privilege. You can use this order to determine which checks failed and which checks granted access.

If EXPLRC1=4 and ECPLRC2=14 (decimal), the ALESERV failed and the module made no RACROUTE REQUEST=FASTAUTH checks. In this case the first word of XAPLDIAG contains the non-zero ALESERV return code.
Otherwise, each word of XAPLDIAG can contain a SAF return code, RACF return code, and RACF reason code corresponding to a non-zero return code from a RACROUTE REQUEST=FASTAUTH macro. Information related to non-zero return codes is stored in XAPLDIAG beginning with the first word until information related to all non-zero return codes has been stored, or until the XAPLDIAG area has filled. XAPLDIAG contains 20 words, allowing information related to 20 FASTAUTH requests to be stored for an invocation of the RACF access control module. If more than 20 FASTAUTH requests are issued, only the first 20 sets of return codes are stored.

DBADM authorization checking for the CREATE VIEW privilege can result in more than 20 FASTAUTH requests because a CREATE VIEW request can reference tables, or a combination of tables and views, from multiple databases. Db2 passes the names of all the databases referenced in the CREATE VIEW using a database list pointed to by XAPLDBSP. If SYSCTRL or SYSADM authorization checking does not grant the CREATE VIEW privilege and the XAPLCRVW field indicates that DBACRVW is enabled, the RACF access control module checks the user's DBADM authorization for each database in the list. The result of each DBADM check is placed in the XAPLDBDA field associated with each database. The RACF access control module updates XAPLDBDA with the following codes:

Y: Access to the database is allowed.
N: Access to the database is not allowed.
U: RACF was unable to return a decision. This occurs when the FASTAUTH request returns a SAF return code of X'04'.

The database list pointed to by XAPLDBSP is made up of four-word database information structures mapped by the XAPLDBS macro.

XAPLDBNP DS F     PTR TO NEXT DATABASE INFORMATION STRUC
XAPLDBNM DS CL8   DATABASE NAME
XAPLDBDA DS CL1   'Y' - IS DBADM
XAPLDBIM DS CL1   'Y' - IS AN IMPLICIT DATABASE
XAPLRSV5 DS CL2   RESERVED - UNUSED

Although DBADM checks can be done for multiple databases, only the results of the first 20 FASTAUTH requests are stored in XAPLDIAG. The results of all DBADM checking for each database is contained in the XAPL parameter list and is available using Db2 trace record IFCID 314.

The RACF access control module truncates the SAF return codes and RACF return codes to one byte, and the RACF reason code to two bytes, before storing them in XAPLDIAG. The format of each word in XAPLDIAG is:

xxyyzzzz

where:

xx: is the 1-byte SAF return code
yy: is the 1-byte RACF return code
zzzz: is the 2-byte RACF reason code