COMMAND

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.