CMD Type(IMS) — Issue IMS command with response
This command issues IMS commands. A response is returned to the issuing EXEC.
How IMS generic commands are processed
When you use the IMFEXEC statement to issue generic IMS commands, by default command processing is performed within the MainView AutoOPERATOR address space. This topic describes how MainView AutoOPERATOR processes wildcards when they are used with generic IMS commands.
When MainView AutoOPERATOR processes the commands, you can use wildcard characters in generic IMS resource names. The plus sign (+) or the percent sign (%) represents a single character and the asterisk (*) represents more than one character.
If you need to specify more than one generic IMS resource name with an IMS command, you must specify the K() keyword at the end of the command. The K( ) keyword must contain the keyword or keywords to be issued with the IMS command, one or more blank spaces, or a null if no keywords exist. Do not specify the K( ) keyword with IMS commands that do not include at least one generic name.
Following are some examples for using the K( ) keyword:
/STA DB CUST* K(ACCESS=UP DBALLOC)
/STA DB BBFMDB4+ CUSTHI+M K()
You can have IMS process the commands instead of MainView AutoOPERATOR by specifying the at sign (@) after the forward slash (/) and before the IMS command
When you specify the IMS command using this format, the IMS command is passed to IMS where generic parameter substitution takes place. To switch back to MainView AutoOPERATOR generic command processing, remove the @ sign from the IMFEXEC CMD statement.
If you attempt to specify an IMS generic command or keyword that is not supported by IMS, the following message is issued:
Command | Parameters |
|---|---|
CMD | '/IMS command' [COUNT( 1|n)]TYPE(IMS) DBCMD(IMS| MVS) DBCTL(dbctltgt) [WAIT(30|n)] ALL ALLWAIT(1 - 9999) [STEM(stem)] |
Command output is placed in LOCAL variables LINE1 through LINEnnnn, where nnnn is the last line (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. Refer to the description about the STEM parameter in the table below for more information.
Parameters | Function | Notes |
|---|---|---|
'/IMS or DBCTL command' | command to be issued | maximum length of 252 bytes for the IMS command Note: The / (slash) designates this command format as an IMS or DBCTL command. The quotation marks indicate that a response is to be returned. For information about specifying IMS generic commands or using wildcard characters, refer to How IMS generic commands are processed. For an example of issuing generic commands with IMS generic parameter support, refer to Example 3 - Issuing IMS generic commands with IMS generic Parameter support. |
COUNT | maximum number of response segments | numeric value is in the range 1-9999 If you do not specify a value for COUNT, the value defaults to 1. If you specify ALL, the specified (or default) value of COUNT is overriden. When multiple response segments exist for a command, the response segments are represented with a multisegment message. The IMFEXEC CMD TYPE(IMS) stops waiting when any of the following conditions exists:
|
TYPE | command response designator | must be IMS This parameter is required. If this parameter is not specified, the command will be issued as an MVS command. |
DBCMD | overrides the global DBCTLCMD setting in BBPARM member AAOPRMxx | specify DBCMD(IMS) to issue the DBCTL command as an IMS command, or DBCMD(MVS) to issue the DBCTL command as an MVS command DBCMD(IMS) is valid only for DBCTL address spaces when the MainView AutoOPERATOR for IMS product is active in the PAS, and the PAS is connected to IMS DBCTL. When this parameter is not specified, the EXEC uses the global setting specified on the DBCTLCMD=[IMS | MVS] parameter in BBPARM member AAOPRMxx. Note: /MODIFY commands are always issued as MVS commands, regardless of settings for the DBCTLCMD parameter or DBCMD specification. For more information, see Issuing-DBCTL-commands-from-an-EXEC. |
DBCTL | DBCTL target address space name | required parameter when DBCTLCMD=MVS is specified in BBPARM member AAOPRMxx or when DBCMD(MVS) is specified in the EXEC. For more information, see Issuing-DBCTL-commands-from-an-EXEC. |
WAIT | maximum amount of time, in seconds, to wait for a command response | numeric value in the range 5-9999 When multiple response segments exist for a command, the response segments are represented with a multisegment message. The IMFEXEC CMD TYPE(IMS) stops waiting when any of the following conditions exists:
|
ALL | retrieves all responses | This parameter causes all other criteria to be ignored and to wait for further responses as long as responses continue to arrive within half-second intervals. |
ALLWAIT | specifies an interval to wait from 1 to 9999 seconds | ALLWAIT allows CMD processing to continue waiting in intervals (specified in seconds) until no responses are received within an interval of that length. If at least one response is received in that interval, processing continues for an additional interval. This processing is repeated until no responses are received within an interval, which may result in added wait time. Therefore small intervals of 1-5 are recommended. Processing waits 3 seconds as specified in ALLWAIT and then checks to see if any responses were received. If none, the command is terminated. If a response was received, processing waits an additional 3 seconds and checks again. This action is repeated until no responses are received within the specified interval. |
STEM | returns command responses in REXX stem TSO variables where the value of stem.0 resolves to the number of lines returned | (optional) Specify a stem root name for the REXX stem variable. In addition:
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. |
IMS commands are issued by way of the IMS internal interface, which returns the response to the issuing EXEC.
Condition codes are listed in the following table.
Value | Description |
|---|---|
0 | Complete command response was received within WAIT time. |
4 | Complete command response was received within WAIT time however, the number of response segments was less than the specified count. |
8 | Command response was not received and the WAIT time has expired. If the expected command response comprises more than one segment, consider increasing the value of the IMSMSTIM parameter in BBPARM member AAOPRMxx. Note that increasing the default value might delay Rules based automation for IMS multi-segment messages. |
12 | Target IMS is not active; no matching resource was found for generic command. |
Example 1
This example requests the transactions whose trancodes begins with TH and receives up to 20 response segments.
'IMFEXEC CMD '/DIS TRAN TH*' COUNT(20) TYPE(IMS)'
DO N = 1 to IMFNOL
'IMFEXEC VGET LINE'N' LOCAL'
'IMFEXEC MSG 'LINE'N'='VALUE('LINE'N)' ' '
END
EXIT
CLIST example:
SET I=1
SET SYSSCAN=0
SET AMPER=&
SET SYSSCAN=16
DO WHILE &I NG &IMFNOL
IMFEXEC VGET LINEI LOCAL
IMFEXEC MSG .. &LINEI &ER.&LINEI
SET I=&I+1
END
Example 2
This example utilizes the VDCL function to obtain the first 20 transactions starting with TH* and create ALERTs for those with nonzero PLCT. These ALERTs will be created with a key = current time in seconds and the text will include the transaction name and the PLCT value.
'IMFEXEC CMD '/DIS TRAN TH*' COUNT(20) TYPE(IMS)'
'IMFEXEC VDCL DISPLAY LIST (MSG A B C D E F G H I J K L M)'
KEY = TIME('S')
DO N = 1 TO IMFNOL
'IMFEXEC VGET LINE'N' INTO (DISPLAY) LOCAL'
IF (MSG = T02) & (F > 0) THEN DO
'ALERT 'KEY' ' 'TRAN = 'A' COUNT = 'F' ' FUNCTION(ADD)',
' QUEUE(TEST) ORIGIN(REGIS) COLOR(RED)'
END
END
EXIT
Example 3
This example shows how to issue the IMS command /DIS A with a response and process the LINE1...LINEI variables, which contain the response messages.
'IMFEXEC CMD '/DIS A' ALL TYPE(IMS)'
'IMFEXEC MSG 'IMFCC='IMFCC' IMFNOL='IMFNOL'''
DO I = 1 TO IMFNOL
'IMFEXEC VGET LINE'I' LOCAL'
'IMFEXEC MSG 'LINE'I'='VALUE('LINE'I)' ' '
END
EXIT
Example 4
In this example, MainView AutoOPERATOR issues the generic command /DIS TRAN and uses IMS generic parameter processing to display all APPC dynamic transactions starting with IDCF.
Note that the at (@) sign is specified after the slash (/) sign, which means IMS will perform the command processing.
'IMFEXEC CMD '/@DIS TRAN IDCF*' ALL TYPE(IMS)'
'IMFEXEC MSG 'IMFCC='IMFCC' IMFNOL='IMFNOL'''
DO I = 1 TO IMFNOL
'IMFEXEC VGET LINE'I' LOCAL'
'IMFEXEC MSG 'LINE'I'='VALUE('LINE'I)' ' '
END
EXIT
Example 5
The following example EXEC is a duplicate of the EXEC in Example 1 but shows the STEM parameter specified.
'IMFEXEC CMD '/DIS TRAN TH*' COUNT(20) TYPE(IMS) STEM(WORK)'
DO N = 1 to WORK.0
'IMFEXEC MSG 'LINE'N'='WORK.N' ' '
END
EXIT
Example 6
This example issues a command to IMS to start all databases whose names meet either of the following sets of conditions:
- names that consist of BBFMDB4 followed by any single character
- names that consist of CUSTHI, followed by any single character, followed by M.
The databases will be started with keyword ACCESS=UP.
To issue the same command without any keywords, you must replace K(ACCESS=UP) with K( ).
'IMFEXEC CMD '/STA DB BBFMDB4+ CUSTHI+M K(ACCESS=UP)' TYPE(IMS)'
DO N = 1 to IMFNOL
'IMFEXEC VGET LINE'N' LOCAL'
'IMFEXEC MSG 'LINE'N'='VALUE('LINE'N)' ' '
END
EXIT