ICMD call

Format

Parameters

aib

Specifies the application interface block (AIB) used for this call. This parameter is an input and output parameter.

The following fields must be initialized in the AIB:

AIBID

Eye catcher. This 8-byte field must contain DFSAIBbb.

AIBLEN

AIB lengths. This field must contain the actual length of the AIB that the application program obtained.

AIBOALEN

I/O area length. This field must contain the length of the I/O area that is specified in the call list. This field is not changed by IMS.

AIBOAUSE

Length of data returned in the I/O area. This parameter is an output parameter.

Your program must check this field to determine whether the ICMD call returned data to the I/O area. When the only response to the command is a DFS058 message indicating either COMMAND IN PROGRESS or COMMAND COMPLETE, the response is not returned.

When partial data is returned because the I/O area is not large enough, AIBOAUSE contains the length required to receive all of the data, and AIBOALEN contains the actual length of the data.

i/o area

Specifies the I/O area to use for this call. This parameter is an input and output parameter. The I/O area should be large enough to hold the largest command passed from the AO application to IMS, or command response segment passed from IMS to the AO application. If the I/O area is not large enough to contain all of the data, IMS returns partial data.

The general format of your I/O work area on an ICMD call is:

LLZZ/VERB KEYWORD1 P1 KEYWORD2 P2, P3.

LL

Two-byte field containing the length of the command text, including LLZZ.

ZZ

Two-byte field reserved for IMS.

/ or CRC

Indicates an IMS command follows. CRC (Command Recognition Character) rather than a slash (/) is used in the DBCTL environment.

VERB

The IMS command you are issuing.

KEYWORDX

Keywords that apply to the command being issued.

PX

Parameters for the keywords you are specifying.

. (Period)

End of the command.

The length of a command is limited by the size of the I/O area; the size is specified in the IOASIZE parameter in the PSBGEN macro during PCB generation. LL is the length of the command text. The size of the I/O area is the length of the actual command text, plus 4 bytes for LLZZ. The minimum size of the I/O work area is 132 bytes.

The fifth byte must be a "/" (or CRC for DBCTL), and the verb must follow immediately. The /BROADCAST and /LOOPTEST commands must have a period between the command segment and text segment, and must be preceded by an LLZZ field that includes the size of the text. Comments can be added by placing a period (.) after the last parameter.

Restriction: When issuing the /SSR command, do not code an end-of-command indicator (period) as shown in IMS Version 15 Operations and Automation. If a period is used, it is considered part of the text.

Usage

ICMD enables an AO application to issue an IMS command and retrieve the first command response segment.

When using ICMD, put the IMS command that is to be issued in your application's I/O area. After IMS has processed the command, it returns the first segment of the response message to your AO application's I/O area to retrieve subsequent segments (one segment at a time), using the RCMD call.

Some IMS commands that complete successfully result in a DFS058 COMMAND COMPLETE message. Some IMS commands that are processed asynchronously result in a DFS058 COMMAND IN PROGRESS message. For a command entered on an ICMD call, neither DFS058 message is returned to the AO application. The AIBOAUSE field is set to zero to indicate no segment was returned. So, your AO application must check the AIBOAUSE field along with the return and reason codes to determine if a response was returned.

Related reading: For more information on the AOI exits, see IMS Version 15 Exit Routines.

The following table shows, by IMS environment, the types of application programs that can issue ICMD. ICMD is also supported from a CPI-C driven application.

See IMS Version 15 Operations and Automation for a list of commands that can be issued using the ICMD call.

Restrictions

A CPI-C driven program must issue an APSB (allocate PSB) call before issuing ICMD.