CMD (Issue a command to IBM MQ with response)

This format issues commands to the IBM MQ command server. A response is returned to the issuing EXEC.

Command

Parameters

IMFEXEC CMD

‘MQ command’

ALTUSER(user ID)

TYPE(mqs)

LM(queue manager name)

RESPONSE(msgid1,msgid2,...)

[DELAY|DLY(nnnnn)]

WAIT(30|nnnn)

PCF(yes|no)

QM(queue manager name)

CQ(command queue name)

STEM( )

DEBUG

Related topic

BMC-AMI-Ops-Automation-for-MQ-IMFEXEC-statements

The following table describes the parameters:

For more information about the parameters described in this table, see IBM manual MQ Application Programming Reference.


Parameters

Function

Notes

MQ command

A valid IBM MQ command

This parameter:

  • Is required
  • Has no default value

The MQ command can be up to 256 characters long.

ALTUSER

The name of an alternate userid to be used by IBM MQ for security checking the OPEN and PUT of the command

This parameter:

  • Is not required
  • Has no default value

  • Can be either the word RACF, a user ID, or the characters *NOALT*

    When *NOALT* is specified, no global AlternateUserid is applied to the command.

  • Causes the user ID specified to be placed in the object descriptor AlternateUserid field
  • Causes PUT1 options MQPMO_DEFAULT_CONTEXT and MQPMO_ALTERNATE_USER_AUTHORITY to be specified for the command

Use of this parameter assumes that you have set up the security environment so that the BBI-SS PAS security ID has Alternate User Authority.

TYPE

Type of IMFEXEC CMD

This parameter:

  • Is required
  • Uses a default of MVS

You must code TYPE(mqs) in order to issue the command to a MQ command server.

LM

Local IBM MQ queue manager name

This parameter uses the default IBM MQ manager name.

This parameter is required except for Rule-initiated EXECS where the event type is IBM MQ. For Rule-initiated EXECS where the event type is IBM MQ, the default queue manager is the queue manager for which the Rule fired.

You can issue IBM MQ commands to any IBM MQ queue manager that is on the same z/OS system as BMC AMI Ops Automation. If this parameter is not specified, the default queue manager will be used.

RESPONSE

Allows you to specify from 1 to 8 message IDs

This parameter:

  • Is not required
  • Has no default value

Each message ID may contain up to 16 characters including wildcard characters. An example message ID is ‘CSQN205I’. If this parameter is coded, only command response messages that match at least one of the message IDs will be returned to the EXEC. Do not code this parameter if you want to receive all the command response messages.

DELAY|DLY


Specifies that the command executes in nnnnn seconds of time

Valid values are 0 to 99999 seconds.

The default value is 0 seconds, which means the command is executed with no delay. In addition, the DELAY|DLY parameter includes the following conditions:

  • You can use either DELAY and DLY.
  • A non-zero delay request will fail when you specify any parameters that request command response.
  • You cannot specify a delay with the RESPONSE, WAIT, and STEM parameters.
  • The delay request is no longer valid after an IPL or bouncing the PAS.

WAIT

A number from 5 to 9999 (in seconds)

This parameter:

  • Is not required
  • Uses a default value of 30

Number of seconds that the IMFEXEC CMD waits for IBM MQ command response messages. BMC AMI Ops Automation for MQ need not always wait this number of seconds; in fact, the EXEC will continue processing as soon as all IBM MQ command response messages have been received. Unless you are experiencing problems with a slow IBM MQ command server, do not code this parameter.

PCF

With this parameter, you can specify whether to issue commands in PCF format

Valid values are YES or NO.

This parameter:

  • Is not required
  • Uses a default value of NO

When PCF=YES, BMC AMI OpsA issues commands in PCF (Programmable Command Format) format. You need to code this parameter only when issuing commands to a distributed IBM MQ queue manager.

QM

With this parameter, you can specify the name of a IBM MQ queue manager to which you want to send a command

This parameter:

  • Is not required
  • Has no default value
  • Supports 1 to 48 characters and this queue manager can be z/OS or distributed

This field is case sensitive (others are automatically upper cased).

BMC AMI OpsA issues the command through the local IBM MQ queue manager specified (or defaulted) by the LM( ) parameter.

CQ

The name of the system command queue at the remote IBM MQ queue manager

This parameter:

  • Is not required
  • Has no default value

Specify the name of the system command queue (1 to 48 characters) of the remote IBM MQ queue manager. For example, the queue SYSTEM.ADMIN.COMMAND.QUEUE is used for many distributed IBM MQ queue managers.

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:

  • 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.

Important

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 (.), BMC AMI OpsA processing ignores the period. For example, specifying STEM(MYVAR.) produces the same result as specifying STEM(MYVAR).

Using this parameter overrides the creation of MGLNn 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.

DEBUG

Specifies that debugging messages should be written to the journal to aid in diagnosing a problem with the command

DEBUG has no parameters.

In addition, note the following information:

  • The number of MQ response messages that are received from the request is stored in one of two types of variables, depending on the parameters you specify. If you

    • Do not specify the STEM( ) parmeter, command response messages are returned in TSO variables named MQLNxxxx

      For example, MQLN1 contains the first response message, and MQLN2 contains the second, and so on). Up to 9999 response messages are supported. The maximum size of each MQLNxxxx variable (response message) is 13000 characters.

    • Specify the STEM( ) parameter, command response messages are returned in REXX stem TSO variables, where the value of stem.0 resolves to the number of lines that are 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

  • The CSQ9022I message (for example, CSQ9022I @MQS1CPF CSQMDRTS ‘DISPLAY QUEUE’ NORMAL COMPLETION) contains embedded single quotation marks and nondisplayable characters, which can cause problems when using IMFEXEC MSG and some other commands.

    One solution to this problem is to translate the single quotation marks and invalid characters to other characters using the REXX TRANSLATE function. Refer to Examples-retrieving-responses-to-an-MQ-command for an illustration.

  • BMC AMI OpsA creates a permanent dynamic queue, ‘B BOMVAO.EXEC.REPLY.aossid.qmgrssid’. This queue is modeled after the IBM-supplied SYSTEM.COMMAND.REPLY.MODEL, which is defined by CSQ4INP2 with the SHARE attribute. BMC AMI OpsArequires this Share attribute to allow multiple EXECs to concurrently retrieve response messages from MQ.

  • The first z/OS MQ command response message (CSQN205I) carries the count of the MQ command response messages as well as the return and reason codes for the command. Since the number of response messages is known, there is no need to specify it.

  • BMC AMI OpsA destructively reads all MQ command responses (for example, the number of messages specified in CSQN205I) for this IMFEXEC CMD before returning control to the EXEC.

  • If MQ detects an error with the command, IMFEXEC CMD fails with IMFCC=12. If you get this failure, retrieve all the MQ response messages and inspect the CSQN205I message carrying the MQ return and reason codes. In addition, inspect the MQ messages that follow the CSQN205I message. These messages provide more descriptions about the error.

  • BMC AMI OpsA inserts the name of the user into the UserIdentifier field of the Message Descriptor code as follows:

    • When a terminal session user invokes the EXEC, the TS user ID is used.
    • When a Rule invokes the EXEC, the RACF user ID of the BBI-SS PAS is used.
    • When a CALLX timer request invokes the EXEC, the user ID is inserted from one of the following sources, selected in the order listed:
      • IMFC SET REQ=CALLX command USRID parameter
      • The user ID associated with the BLK statement
      • The AUTOID= statement as specified in BBPARM member BBIISPxx
    • When an EXEC invokes another EXEC with WAIT(YES) specified and the invoking EXEC is scheduled by a CALLX timer request, the user ID of the invoking EXEC is used
    • For all the methods that can schedule an EXEC, the UserIdentifier is the same as the user ID that scheduled the EXEC

    In addition to using the UserIdentifier, BMC AMI OpsA uses the AlternateUserid if either the global value has been requested by way of the MQALTUSR parameter or the ALTUSER() parameter is specified (see the table in Action-Specification-for-MQS-panels). If ALTUSER(*NOALT*) is specified, no AlternateUserid is used.

  • BMC AMI OpsA issues remote commands through the local MQ queue manager specified (or defaulted) in the LM( ) parameter. The remote MQ queue manager must be connected to this local MQ queue manager. In addition, one of the following requirements must be met at each MQ queue manager:
    • There is a queue manager alias to the other MQ queue manager.
    • There is a transmission queue with the name of the other MQ queue manager.
    • The queue manager's default transmission queue (DEFXMITQ) contains the name of an existing transmission queue that will get the message to the targeted queue manager.

One of the following completion code is returned in the IMFCC variable:


Value

Description

0

Successful completion

4

Time out occurred while waiting for MQ command response messages. IMFNOL contains the number of response message received so far.

8

IBM MQ returned error

12

Buffer too small

16

Syntax error

20

Variable Processing routine not found

This section contains the following topic:


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*