Auditing SPI commands

Configuration defines the initial state of a CICS® region but it can be changed by system programming interface (SPI) commands. RACF® SMF type 80 records can be used to audit the commands that are issued by an operator but they do not identify what options were used on these commands and what was changed as a result.

The DFHAP1900 message

The system programming interface commands SET, PERFORM, ENABLE, DISABLE, RESYNC, which can change resource definitions dynamically, are audited. When these commands are issued, message DFHAP1900 is written to the CADS transient data queue (TDQ) and contains information about the parameters that are used in the command.

All SPI commands are audited with message , except as follows:
  • SET TERMINAL
  • FEPI SET commands
  • PERFORM SHUTDOWN (already recorded by message DFHTM1715)
  • CREATE (already recorded by existing messages, unless the NOLOG option is used on this command)

CICS starts to audit the SPI commands after message DFHSI1517 is issued, indicating that control is given to CICS. When SPI auditing becomes available in the region, message DFHAP1901 is issued and written to the CADS TDQ. This configuration means that during system initialization, SPI commands that are issued during PLT processing are not audited.

When you use CEMT or CECI commands, some options might be added or changed. The audit message shows the command that was issued, which might be different from the command you entered.

When you issue operator commands with generic parameters by using CEMT, CICS Explorer®, CICSPlex® SM WUI, or EXEC CPSM commands, each command is audited as if it was entered separately. For example, if you have 2000 programs and enter the command CEMT SET PROGRAM(*) ENABLE, 2000 separate messages are logged.

If you are not interested in the messages, disable them by directing TDQ CADS to a dummy TDQ. See Using dummy transient data queues.

SPI commands that can be audited

The system programming interface commands SET, PERFORM, ENABLE, DISABLE, RESYNC can change resource definitions dynamically. An incorrect entry can cause the CICS system to fail. When diagnosing a problem, it is important to know whether resources were changed. System administrators and anyone who manages audit records can audit certain system programming interface commands which dynamically change system resources.

Audit messages

When a system resource is changed by one of the audited system programming interface commands, a new message DFHAP1900 is written to a transient data queue CADS. The CADS transient data queue is an indirect queue that is defined in the DFHDCTG group, which is part of DFHLIST. The messages are written in a human readable form.

The messages contain the following information:
  • Time
  • Application ID
  • Netname
  • Transaction identification
  • User ID
  • Details of the command, including attribute name and value
  • RESP response code
  • RESP2 response code
Example 1
The command CEMT SET SYSTEM MAXTASKS(250) is entered from terminal TC99. For a normal response, the following message is written to the CADS queue: 
DFHAP1900 I 11/11/2011 11:11:11 IYK3ZC76 IYCWTC99 CNTEST7
CEMT SET SYSTEM MAXTASKS(250) RESP(NORMAL) RESP2(0)
Example 2
The command CECI SET FILE(TEMP) OPEN is entered from terminal TC99. The response is: Open/close failed EIBRESP=+0000000012 EIBRESP2=+0000000018. The audit message is written as: 
DFHAP1900 I 11/11/2011 11:11:11 IYK3ZC76 IYCWTC99 CNTEST7
CECI SET FILE(TEMP) OPEN RESP(FILENOTFOUND) RESP2(18)

Where possible, the CVDA value is used in the message instead of the code to improve the readability of the audit messages.

Example 3
The command CECI SET FILE(TEMP) ENABLESTATUS(ENABLED). The audit message is written as: 
DFHAP1900 I 11/11/2011 11:11:11 IYK3ZC76 IYCWTC99 CNTEST7
CECI SET FILE(TEMP) ENABLESTATUS(ENABLED) RESP(FILENOTFOUND) RESP2(18)

When you use CEMT, WUI or Explorer operator commands with generic parameters, each command is audited as if it was entered separately. For example, if you have 2000 programs and enter the command CEMT SET PROGRAM(*) ENABLE, 2000 separate messages are logged. Similarly, if you enter the command CEMT SET PROGRAM(*) NEWCOPY when you are not authorized for SET PROGRAM, 2000 RACF failure messages are logged. So many messages might flood the CSSL queue so audit messages should be redirected to another queue. As each command is logged as if it were entered separately, you can search the log for a single program name to aid problem determination.

When you use CEMT or CECI commands, some options can be added or changed. The audit message shows the command that was issued, which might be different than the command you entered.

Note: The audit message can be disabled by directing the messages to a dummy transient data queue. See Using dummy transient data queues.

User IDs in audit messages

The user ID displayed in audit messages is dependent upon the security that is active within the context in which the command is issued. If the command is issued under the control of CICSPlex SM, you have several settings that affect which user ID is used, as illustrated in the following table:
Table 1. User IDs in audit messages
EYUPARM in CMAS SIT parm in CICS region where request is initiated User ID in audit message
SEC(YES) SEC=YES Authenticated user ID
Note: The authenticated user ID depends on how, and where, the request to issue the command was initiated, as illustrated in Table 2.
SEC(YES) SEC=NO Default user ID for CMAS
SEC(NO) SEC=NO Default user ID for CICS Region where command is issued
SEC(NO) SEC=YES Invalid combination
Table 2. Authenticated user ID
Where request is initiated Authenticated user ID
WUI User ID used to sign on to the WUI
CICSPlex SM API Batch Job User ID under which the Job connects to CICSPlex SM, by default this is the user under which the job is run.
CICSPlex SM API Application User ID under which the task connects to CICSPlex SM, by default this is the user under which the task is running in the CICS.
Region Explorer (CMCI) User ID specified in the Connection Credentials.
Note: If security is not active in the WUI, users can log on through the Web User Interface by using any string value for a user ID. The default user ID of MAS or CMAS is displayed in the audit message, and therefore cannot be used to identify the user that entered the command.

For more information on CICS user security, see How it works: Identification in CICS.

SPI commands that are not audited

Some SPI commands are not audited:
  • SET TERMINAL
  • FEPI SET commands
  • PERFORM SHUTDOWN (already handled by message DFHTM1715)
  • CREATE (already recorded by existing messages)
  • SET ASSOCIATION USERCORRDATA

When CICS starts auditing SPI commands

Auditing of the SPI commands starts after message DFHSI1517 is issued, indicating that control is given to CICS. When SPI auditing becomes available in the region, message DFHAP1901 is issued, indicating that it is active.

This means that during system initialization, SPI commands that are issued during PLT processing are not audited.