COMMAND
You can use COMMAND functions in monitor programs to issue commands from the instrumentation facility interface (IFI).
- START TRACE
- STOP TRACE
- DISPLAY TRACE
- MODIFY TRACE
You can execute commands asynchronously or synchronously. You can set a bit in the IFCA to specify how you want IFI to execute the commands. The following commands are affected:
- ALTER BUFFERPOOL
- SET LOG
- STOP DATABASE
- SET SYSPARM
Authorization
The primary authorization ID or one of the secondary authorization IDs of the process must have the appropriate authorization to issue the command. Otherwise the request is denied. An application program might have the authorization to issue Db2 commands, but not the authorization to issue READA requests.
In a data sharing group, if a command is issued through the IFI interface and executes on a different data sharing member from the member the issued the command, then the command executes under the user ID of the application process that issued the IFI call.
Syntax and options
A call to the COMMAND function has the following syntax:
CALL DSNWLI,('COMMAND ',ifca,return-area,output-area,buffer-info .),VL
- ifca
-
IFCA (instrumentation facility communication area) is an area of storage that contains the return code and reason code. IFCA indicates the following information:
- The success or failure of the request
- Diagnostic information from the Db2 component that executed the command
- The number of bytes moved to the return area
- The number of bytes of the message segments that did not fit in the return area
Some commands might return valid information despite a non-zero return code or reason code. For example, the DISPLAY DATABASE command might indicate that more information could have been returned than was allowed.
If multiple errors occur, the last error is returned to the caller. For example, if the command is in error and the error message does not fit in the area, the error return code and reason code indicate that the return area is too small.
If a monitor program issues START TRACE, the ownership token (IFCAOWNR) in the IFCA determines the owner of the asynchronous buffer. The owner of the buffer is the only process that can obtain data through a subsequent READA request.
- return-area
- When the issued command finishes processing, it places messages (if any) in the return area. The
messages are stored as varying-length records, and the total number of bytes in the records is
placed in the IFCABM (bytes moved) field of the IFCA. If the return area is too small, as many
message records as can fit are placed into the return area.
The monitor program should analyze messages that are returned by the command function.
- output-area
- Contains the varying-length command.
- buffer-info
- This parameter is required for starting traces to an OP buffer. Otherwise, it is not needed.
This parameter is used only on COMMAND requests. It points to an area that contains information
about processing options when a trace is started by an IFI call to an unassigned
OPn destination buffer. An OPn destination buffer is
considered unassigned if it is not owned by a monitor program.
If the OPn destination buffer is assigned, then the buffer information area is not used on a later START or MODIFY TRACE command to that OPn destination. .
When you use buffer-info on START TRACE, you can specify the number of bytes that can be buffered before the monitor program ECB is posted. The ECB is posted when the amount of trace data collected has reached the value that is specified in the byte count field. The byte count field is also specified in the buffer information area.
The following table summarizes the fields in the buffer information area.
Table 1. Buffer information area fields. This area is mapped by assembler mapping macro DSNDWBUF. Name Hex offset Data type Description WBUFLEN 0 Signed two-byte integer Length of the buffer information area, plus 4. A zero indicates the area does not exist. 2 Signed two-byte integer Reserved. WBUFEYE 4 Character, 4 bytes Eye catcher for block, WBUF. WBUFECB 8 Address The ECB address to post when the buffer has reached the byte count specification (WBUFBC). The ECB must reside in monitor key storage. A zero indicates not to post the monitor program. In this case, the monitor program should use its own timer to determine when to issue a READA request.
WBUFBC C Signed four-byte integer The records placed into the instrumentation facility must reach this value before the ECB can be posted. If the number is zero, and an ECB exists, posting occurs when the buffer is full.
Example COMMAND function call
This example issues a Db2 START TRACE command for MONITOR Class 1.
CALL DSNWLI,('COMMAND ',IFCAAREA,RETAREA,OUTAREA,BUFAREA),VL
⋮
COMMAND DC CL8 'COMMAND '
************************************************************************
* Function parameter declaration *
************************************************************************
* Storage of LENGTH(IFCA) and properly initialized *
************************************************************************
IFCAAREA DS 0CL180
⋮
************************************************************************
* Storage for length and returned info. *
************************************************************************
RETAREA DS CL608
************************************************************************
* Storage for length and Db2 Command *
************************************************************************
OUTAREA DS 0CL42
OUTLEN DC X'002A0000'
OUTCMD DC CL38'-STA TRAC(MON) DEST(OPX) BUFSIZE(1024)'
************************************************************************
* Storage of LENGTH(WBUF) and properly initialized *
************************************************************************
BUFAREA DS 0CL16
⋮