COMMAND

You can use COMMAND functions in monitor programs to issue commands from the instrumentation facility interface (IFI).

Begin program-specific programming interface information.You can submit any Db2 command, including the following trace commands:
  • 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.

Figure 1. Starting a trace using IFI
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
⋮

End program-specific programming interface information.