CMD Type(IMP) — Issue IMSPlex commands

This command format issues IMSPlex commands.

When requested, a response to the command is returned to the issuing EXEC.

IMSPlex commands can be issued to some or all IMS regions that are part of any IMSPlex with available Structured Call Interface (SCI) address space on the MVS system where the MainView AutoOPERATOR PAS is running. There is no requirement for all these IMS regions to be defined as targets in the BBIJNT00 member. The MainView AutoOPERATOR PAS does not have to be connected to an IMS.

To issue an IMSPlex command from an EXEC specify the command by using the IMFEXEC CMD statement with TYPE(IMP); for example

IMFEXEC CMD '/QUERY IMSPLEX' TYPE(IMP) ROUTE(*) IMSPLEX(IMS3)

Command	Parameters
CMD	'/IMSPlex command' TYPE(IMP) ROUTE() [COUNT(0\|nnnn)] IMSPLEX(name) [WAIT(30\|n)] [STEM( )]

Command output is placed in LOCAL variables LINE1 through LINE nnnn and the originating IMS name is returned in variable ORIGIN_LINE1 through ORIGIN_LINEnnnn where nnnn is the last line of returned data. The variable IMFNOL contains the value of nnnn. These variables must be retrieved by using the VGET command before they can be used.

However, for REXX EXECs, you can specify the optional STEM parameter. If you specify the STEM parameter, the output is returned in REXX stem TSO variables where the value of stem.0 resolves to the number of lines returned. For example, if you specify STEM(MYINFO), the following sets of variables are returned to the EXEC:

MYINFO.0 contains the number of variables in the array.
MYINFO.1 through nnnn contains the response messages segment information.
ORIGIN_MYINFO.1 through nnnn contains the names of the IMS where this line of response originated.

Refer to Table 1 for more information about the STEM parameter.

Note

Specifying COUNT(0) causes the command to be issued without a response.

Parameters	Function	Notes
'/IMSPlex command or IMS classic command supported by IMS OM'	specifies the command to be issued is enclosed in single quotation mark	maximum length of the IMS command is 252 bytes Note: For a list of OM supported classic and new IMSPlex commands, refer to section 'Commands Supported by the OM API' in the IBM manual IMS Commands Reference.
TYPE	specifies that the EXEC issues IMSPlex commands	is a required keyword where you must specify IMP to issue IMSPlex commands If this parameter is not specified, the command will be issued as an MVS command.
ROUTE(ims1, ims2, ...)	lists the OM clients (IMS control regions) in the IMSPlex to which the command is sent	optional keyword that if not specified, the command is issued to all members of the IMSPlex that have registered to process this command For example, if you specify ROUTE(*), the command is sent to all IMS systems in the IMSPlex If you specify ROUTE(IMS1,IMS2), the command is sent to IMS1 and IMS2. Note: If the IMSROUTE parameter is set to LOCAL in the UBBPARM member AAOPRMxx, the command is sent only to the IMS control region connected to this AutoOPERATOR PAS when: ROUTE() is not specified IMSPLEX() specifies the name of the IMSplex that includes the IMS control region connected to this AutoOPERATOR PAS
COUNT	specifies the number of response lines to be retrieved	is the numeric value between 0-9999 This keyword is optional. If this keyword is not specified, all response lines (up to 9999) will be returned within the WAIT interval.
IMSPLEX	specifies the name of an IMSPlex that is to receive and process the command	1-5 character identifier for the IMSPlex This keyword is required. IMSPlex commands can be issued against any IMSPlex with available SCI address space on the MVS system where the AutoOPERATOR PAS is running.
WAIT(5-nnnn\|30)	The maximum amount of time, in seconds, to wait for a command response	numeric value between 5-9999. This keyword is optional and if WAIT is not specified, the default is 30 seconds. Some IMSPlex commands require longer time to return a response. For those commands specify an appropriate WAIT value, for example, WAIT(300). Specifying a longer wait time could cause potential delays in automation. If the wait time expires, it does not affect the execution of the command.
STEM	Command responses are returned in REXX stem TSO variables where the value of stem.0 resolves to the number of lines returned.	specify a stem root name for the REXX stem variable In addition: The maximum length of the value that you can specify is 8 characters. The value must conform to standard REXX variable naming rules. Compound REXX stem variables are not supported. This keyword is optional. Note: This parameter is valid only for REXX EXECs. It does not work in CLISTs. If the stem name that is provided ends in a period (.), MainView AutoOPERATOR processing ignores the period. For example, specifying STEM(MYVAR.) produces the same result as specifying STEM(MYVAR). Using this parameter overrides the creation of LINEn variables in the LOCAL variable pool. The REXX stem variable is only defined as a TSO variable. If you want to use the variables as LOCAL variables, you must first use IMFEXEC VPUT to move these variables to the LOCAL pool. These REXX stem variables conform to all TSO/E REXX coding standards for stem variables.

IMSPlex commands are issued by way of the IMS Operations Manager (OM) internal interface, which returns the response to the issuing EXEC. OM routes the command to all clients within the IMSPlex that have registered to process this command and returns the consolidated response.

Condition codes are listed in the following table.

Table 1. Condition codes

IMFCC Value	Condition	IMFRC Value	Reason
0	Command successfully issued. Response returned.	0	n/a
4	Command partially responded within WAIT time	0	n/a
8	Command error	4	Syntax error occurred
		8	Invalid IMSPLEX command was specified
		12	IMS OM authorization failed
		16	IMS OM error occurred. See the OM return and reson codes in the IBM manual IMS Common Service Layer Guide and Reference.
12	Internal error	0	Plex Leave failed
16	Target error	4	Plex inactive
		8	Plex list failed
		12	SCI address space not available
		16	OM address space not available
		20	Plex join failed

The IMSPlex (SCI or OM) return and reason codes are returned in variables IMFIMPRC and IMFIMPRS after each IMSPlex command is issued. The variables contain the hexadecimal value of the OM Return and Reason codes. If the IMSPlex command is successful IMFCC is set to zero. If IMFCC is not equal to zero, review the contents of variables IMFIMPRC and IMFIMPRS to find information of the nature of the problem.

Note

The hexadecimal representation of the OM Return and Reason codes is documented in the section 'CSLOMCMD Return and Reason Codes' in the IBM manual IMS Common Service Layer Guide and Reference.

Example 1

This example requests information for the members that defined in IMSPlex PLX81.

/*REXX*/
'IMFEXEC CMD '/DIS ACT' TYPE(IMP) IMSPLEX(PLX81)'
DO I = 1 TO IMFNOL
   'IMFEXEC VGET LINE'I' LOCAL'
   'IMFEXEC VGET ORIGIN_LINE'I' LOCAL'
   'IMFEXEC MSG ''VALUE('ORIGIN_LINE'I)' 'VALUE('LINE'I)'''
END

CLIST example:

PROC 0
IMFEXEC CMD '/DIS ACT' TYPE(IMP) IMSPLEX(PLX81)
SET &I = 1
DO WHILE (&I LE &IMFNOL)
  IMFEXEC VGET (LINE&I ORIGIN_LINE&I) LOCAL
  SET &ORIGIN = &&ORIGIN_LINE&I
  SET &RESPON = &&LINE&I
  IMFEXEC MSG '&ORIGIN-&RESPON'
  SET &I = &I + 1
  END

Example 2

This REXX example issues Start command for database DBFSAMD1 on all IMS in IMSPlex PLX81 and waits 100 seconds for the response.

/* REXX */
'IMFEXEC CMD '/STA DB DBFSAMD1' TYPE(IMP) IMSPLEX(PLX81) WAIT(100)'
DO I = 1 TO IMFNOL
  'IMFEXEC VGET LINE'I' LOCAL'
  'IMFEXEC MSG 'Line'I'='VALUE('LINE'I)'''
END

Example 3

This REXX example issues Stop command for database IVPDB4 only for IMS AO8B and is not going to wait for a response.

/* REXX */
'IMFEXEC CMD '/STO DB IVPDB4' TYPE(IMP) ROUTE(AO8B) IMSPLEX(PLX81) COUNT(0)'
DO I = 1 TO IMFNOL
  'IMFEXEC VGET LINE'I' LOCAL'
  'IMFEXEC MSG 'Line'I'='VALUE('LINE'I)'''
END

Example 4

The following example EXEC is a duplicate of the EXEC in Example 1 but shows the STEM parameter specified.

/* REXX */
'IMFEXEC CMD '/QUERY IMSPLEX' TYPE(IMP) IMSPLEX(PLX81) STEM(WORK)'
DO I = 1 TO WORK.0
'IMFEXEC MSG 'Line'I'='WORK.I'''
END