Use the COMMAND function of CSQUTIL on z/OS

We can use the COMMAND function of CSQUTIL to direct commands to the queue manager.

Use the COMMAND function to:
  1. Pass commands from an input data set to the queue manager.
  2. Produce a list of DEFINE commands that describe the objects in a queue manager. The commands can be used to keep a record of the object definitions or to regenerate all or part of a queue manager's objects as part of a migration from one queue manager to another.
  3. Produce a list of commands to change or delete a set of objects in a queue manager.
  4. Make a client channel definition file.
The queue manager specified in the PARM parameter of the EXEC statement must be running.

Command management (COMMAND)

COMMANDDDNAME( ddname1)MAKEDEF( ddname2)MAKEDEL( ddname2)MAKEREP( ddname2)MAKEALT( ddname2)DATA(ddname4)TGTQMGR( qmgrname)RESPTIME(30)RESPTIME( nnn) MAKECLNT( ddname3)CCSID( ccsid) FAILURE(IGNORE)FAILURE(CONTINUE)FAILURE(STOP)

If we use FAILURE (IGNORE) the job step always obtains return code 0.

If we use FAILURE (STOP) or FAILURE (CONTINUE) the job step obtains return code 8 if there were any non zero return codes from the statements.

You should use FAILURE (STOP) or FAILURE (CONTINUE) to report any errors in the definitions.


Keywords and parameters

    DDNAME(ddname1)
    Specifies that the commands are to be read from a named input data set. If this keyword is omitted, the default DDname, CSQUCMD, is used.

    ddname1 specifies the DDname that identifies the input data set from which commands are to be read.

    MAKEDEF(ddname2), MAKEDEL(ddname2), MAKEREP(ddname2), MAKEALT(ddname2)
    Specify that commands are to be generated from any DISPLAY object commands in the input data set. The commands that are generated are:

      MAKEDEF
      DEFINE NOREPLACE, with all the attributes and values returned by the DISPLAY commands. For the queue manager object, an ALTER command is generated with all the attributes and values. For channel authentication records, a SET command is generated.

      Both CSQUTIL SDEFS and the CSQUTIL COMMAND with the MAKEDEF option can be used to produce a set of MQSC commands to re-create the objects currently defined in the queue manager.

      The difference between the two is that CSQUTIL COMMAND must be run against an active queue manager and is most appropriate for regular backup of object definitions, whereas CSQUTIL SDEFS can be used to re-create definitions for a queue manager that is not currently running. This makes the CSQUTIL SDEFS option more appropriate for recovery scenarios.

      MAKEDEL
      DELETE. For local queues, NOPURGE is used. For channel authentication records, a SET command with ACTION(REMOVE) is used
      MAKEREP
      DEFINE REPLACE, with any keywords and values from the data set specified by the DATA keyword. For channel authentication records, a SET command with ACTION(REPLACE) is used.
      MAKEALT
      ALTER, with any keywords and values from the data set specified by the DATA keyword. For channel authentication records, a SET command with ACTION(REPLACE) is used.

    Only one of these keywords may be specified. If these keywords are omitted, no commands are generated.

    ddname2 specifies the DDname that identifies the output data set in which the DEFINE, DELETE or ALTER commands are to be stored. The data set should be RECFM=FB, LRECL=80. This data set can then be used as input for a later invocation of the COMMAND function or it can be incorporated into the initialization data sets CSQINP1 and CSQINP2.

    DATA(ddname4)
    ddname4 specifies a data set from which command keywords and values are to be read, and appended to each command generated for MAKEREP or MAKEALT.
    TGTQMGR(qmgrname)
    Specifies the name of the z/OS® queue manager where you want the commands to be performed. This option is not supported for use with queue managers on distributed platforms. You can specify a target queue manager that is not the one you connect to. In this case, you would normally specify the name of a remote queue manager object that provides a queue manager alias definition (the name is used as the ObjectQMgrName when opening the command input queue). To do this, you must have suitable queues and channels set up to access the remote queue manager.

    The default is that commands are performed on the queue manager to which you are connected, as specified in the PARM field of the EXEC statement.

    RESPTIME(nnn)
    Specifies the time in seconds to wait for a response to each command, in the range 5 through 999.

    The default is 30 seconds.

    MAKECLNT(ddname3)

    Specifies that a client channel definition file is generated from any DISPLAY CHANNEL commands in the input data set that return information about client-connection channels, and any DISPLAY AUTHINFO commands that return information about authentication information objects for which the LDAPUSER and LDAPPWD attributes are not set.

    If this keyword is omitted, no file is generated.

    Important: The MAKECLNT utility is now stabilized at the IBM® WebSphere MQ Version 7.1 level. You should use the runmqsc command using the -n option; see runmqsc (run MQSC commands) for further information.

    ddname3 specifies the DDname that identifies the output data set in which the generated file is to be stored; the data set should be RECFM=U, LRECL=6144. The file can then be downloaded as binary data to the client machine by a suitable file transfer program.

    CCSID(ccsid)
    Specifies the coded character set identifier (CCSID) that is to be used for the data in a client channel definition file. The value must be in the range 1 through 65535; the default is 437. We can only specify CCSID if you also specify MAKECLNT. Note: IBM MQ assumes that the data is to be in ASCII, and that the encoding for numeric data is to be MQENC_INTEGER_REVERSED.
    FAILURE
    Specifies what action to take if an IBM MQ command that is issued fails to execute successfully. Values are:

      IGNORE
      Ignore the failure; continue reading and issuing commands, and treat the COMMAND function as being successful. This is the default.

      CONTINUE
      Read and issue any remaining commands in the input data set, but treat the COMMAND function as being unsuccessful.

      STOP
      Do not read or issue any more commands, and treat the COMMAND function as being unsuccessful.


Examples

This section gives examples of using the COMMAND function for the following:

    Issuing commands

    In Figure 1, the data sets referenced by DDnames CSQUCMD and OTHER contain sets of commands. The first COMMAND statement takes commands from the default input data set MY.COMMANDS(COMMAND1) and passes them to the queue manager. The second COMMAND statement takes commands from the input data set MY.COMMANDS(OTHER1), which is referenced by DDname OTHER, and passes them to the queue manager.

    Figure 1. Sample JCL for issuing IBM MQ commands using CSQUTIL
    //COMMAND EXEC PGM=CSQUTIL,PARM='CSQ1'
//STEPLIB  DD   DISP=SHR,DSN=thlqual.SCSQANLE
//         DD   DISP=SHR,DSN=thlqual.SCSQAUTH
//CSQUCMD  DD DSN=MY.COMMANDS(COMMAND1),DISP=SHR
//OTHER    DD DSN=MY.COMMANDS(OTHER1),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
* THE NEXT STATEMENT CAUSES COMMANDS TO BE READ FROM CSQUCMD DDNAME
COMMAND
* THE NEXT SET OF COMMANDS WILL COME FROM 'OTHER' DDNAME
COMMAND DDNAME(OTHER)
* THE NEXT STATEMENT CAUSES COMMANDS TO BE READ FROM CSQUCMD
* DDNAME AND ISSUED ON QUEUE MANAGER CSQ2 WITH A RESPONSE TIME
* OF 10 SECONDS
COMMAND TGTQMGR(CSQ2) RESPTIME(10)
/*

    Making a list of DEFINE commands
    In Figure 2, the data set referenced by DDname CMDINP contains a set of DISPLAY commands. These DISPLAY commands specify generic names for each object type (except the queue manager itself). If you run these commands, a list is produced containing all the IBM MQ objects. In these DISPLAY commands, the ALL keyword is specified to ensure that all the attributes of all the objects are included in the list, and that all queue sharing group dispositions are included.Note: Failing to issue DISPLAY STGCLASS as the first command can result in a set of definitions that will not be successfully processed by the queue manager, as STGCLASS definitions must be defined before the associated queue objects are defined. MAKEDEFS generate output based on the order of the input DISPLAY commands.

    The MAKEDEF keyword causes this list to be converted into a corresponding set of DEFINE NOREPLACE commands (ALTER for the queue manager). These commands are put into a data set referenced by the ddname2 parameter of the MAKEDEF keyword, that is, OUTPUT1. If you run this set of commands, IBM MQ regenerates all the object definitions in the queue manager.

    Figure 2. Sample JCL for using the MAKEDEF option of the COMMAND function
    //QDEFS   EXEC PGM=CSQUTIL,PARM='CSQ1'
//STEPLIB  DD   DISP=SHR,DSN=thlqual.SCSQANLE
//         DD   DISP=SHR,DSN=thlqual.SCSQAUTH
//OUTPUT1  DD   DISP=OLD,DSN=MY.COMMANDS(DEFS)
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
COMMAND DDNAME(CMDINP) MAKEDEF(OUTPUT1)
/*
//CMDINP   DD *
DISPLAY STGCLASS(*) ALL QSGDISP(QMGR)
DISPLAY STGCLASS(*) ALL QSGDISP(GROUP)
DISPLAY CFSTRUCT(*) ALL

DISPLAY QUEUE(*) ALL QSGDISP(QMGR)
DISPLAY QUEUE(*) ALL QSGDISP(GROUP)
DISPLAY QUEUE(*) ALL QSGDISP(SHARED)
DISPLAY TOPIC(*) ALL QSGDISP(QMGR)
DISPLAY TOPIC(*) ALL QSGDISP(GROUP)
DISPLAY NAMELIST(*) ALL QSGDISP(QMGR)
DISPLAY NAMELIST(*) ALL QSGDISP(GROUP)
DISPLAY PROCESS(*) ALL QSGDISP(QMGR)
DISPLAY PROCESS(*) ALL QSGDISP(GROUP)
DISPLAY CHANNEL(*) ALL QSGDISP(QMGR)
DISPLAY CHANNEL(*) ALL QSGDISP(GROUP)
DISPLAY AUTHINFO(*) ALL QSGDISP(QMGR)
DISPLAY AUTHINFO(*) ALL QSGDISP(GROUP)
DISPLAY CHLAUTH('*') ALL
DIS SUB(*) SUBTYPE(ADMIN) ALL DISTYPE(DEFINED)

DISPLAY QMGR ALL

/*

    Making a list of ALTER commands

    In Figure 3, the data set referenced by DDname CMDINP contains a DISPLAY command that will produce a list of all local queues with names beginning "ABC".

    The MAKEALT keyword causes this list to be converted into a corresponding set of ALTER commands, each of which includes the data from the data set referenced by DDname CMDALT. These commands are put into a data set referenced by the ddname2 parameter of the MAKEALT keyword, that is, OUTPUTA. If you run this set of commands, all the local queues with names beginning "ABC" will be disabled for PUT and GET.

    Figure 3. Sample JCL for using the MAKEALT option of the COMMAND function
    //QALTS  EXEC PGM=CSQUTIL,PARM='CSQ1 '
//STEPLIB  DD DISP=SHR,DSN=thlqual.SCSQANLE
//         DD DISP=SHR,DSN=thlqual.SCSQAUTH
//OUTPUTA  DD DISP=OLD,DSN=MY.COMMANDS(ALTS)
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
COMMAND DDNAME(CMDINP) MAKEALT(OUTPUTA) DATA(CMDALT)
/*
//CMDINP DD *
DISPLAY QLOCAL(ABC*)
/*
//CMDALT DD *
PUT(DISABLED) +
GET(DISABLED)
/*

    Making a client channel definition file

    In Figure 4, the data set referenced by DDname CMDCHL contains a DISPLAY CHANNEL command and a DISPLAY AUTHINFO command. The DISPLAY commands specify a generic name and the ALL keyword is specified to ensure that all the attributes are included.

    The MAKECLNT keyword converts these attributes into a corresponding set of client channel definitions. These are put into a data set referenced by the ddname3 parameter of the MAKECLNT keyword, that is, OUTCLNT, which is ready to be downloaded to the client machine.

    Figure 4. Sample JCL for using the MAKECLNT option of the COMMAND function
    //CLIENT  EXEC PGM=CSQUTIL,PARM='CSQ1'
//STEPLIB  DD   DISP=SHR,DSN=thlqual.SCSQANLE
//         DD   DISP=SHR,DSN=thlqual.SCSQAUTH
//OUTCLNT  DD   DISP=OLD,DSN=MY.CLIENTS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
COMMAND DDNAME(CMDCHL) MAKECLNT(OUTCLNT)
/*
//CMDCHL   DD *
DISPLAY CHANNEL(*) ALL TYPE(CLNTCONN)
DISPLAY AUTHINFO(*) ALL
/*


Usage notes for CSQUTIL COMMAND

  1. The rules for specifying commands in the input data set are the same as for the initialization data sets:

    • The data set must have a record length of 80.
    • Only columns 1 through 72 are significant. Columns 73 through 80 are ignored.
    • Records with an asterisk (*) in column 1 are interpreted as comments and are ignored.
    • Blank records are ignored.
    • Each command must start on a new record.
    • A trailing - means continue from column 1 of the next record.
    • A trailing + means continue from the first non-blank column of the next record.
    • The maximum number of characters permitted in a command is 32 762.
    With the additional rule:

    • A semicolon (;) can be used to terminate a command; the remaining data in the record is ignored.
    See Building command scripts for more information about the rules for building IBM MQ commands.
  2. The output from a DISPLAY QMGR command contains all the queue manager attributes. Using the DISPLAY QMGR command as part of MAKEDEF might generate an ALTER command that cannot be issued before the channel initiator is active.

    Since setting PSCLUS(DISABLED) can only be done if the channel initiator is active, it might be necessary to modify the resulting ALTER command so that it does not attempt to set PSCLUS(DISABLED) until the channel initiator is active.

  3. If you specify the MAKEDEF keyword:

    • In the input data set, the DISPLAY commands for objects must contain the ALL parameter so that the complete definition of each object is produced. See Figure 2.
    • To obtain a complete definition, you must DISPLAY the following:

      • queues
      • topic
      • namelists
      • process definitions
      • channels
      • storage classes
      • authentication information objects
      • CF structures
      • channel authentication records
      • queue manager
      Note: DEFINE commands are not generated for any local queues that can be identified as dynamic, or for channels that were defined automatically.
    • Do not specify the same MAKEDEF data set for more than one COMMAND function, unless its DD statement specifies a sequential data set with DISP=MOD.
  4. If you specify the MAKEREP, MAKEALT, or MAKEDEL keywords:

    • In the input data set, include DISPLAY commands that select the set of objects for which you want to generate commands.
    • For MAKEREP and MAKEALT, the data (if any) from the data set specified by the DATA keyword is appended to each generated command, exactly as entered. The format of the data set and the rules for specifying command data are the same as for the command input data set. Because the same data is appended to each command, if you want to process several sets of objects, you will need to use several separate COMMAND functions, each with a different DATA data set.
    • Commands are not generated for channels that were defined automatically.

  5. If you specify the MAKEDEF, MAKEREP, MAKEALT, or MAKEDEL keywords, commands are generated only for objects reported by the target queue manager (as specified by the TGTQMGR keyword or defaulted), even if CMDSCOPE is used in the DISPLAY commands. To generate commands for several queue managers in a queue sharing group, use a separate COMMAND function for each.

    In a queue sharing group, queues, processes, channels, storage classes and authentication information objects should each have two DISPLAY commands, one with QSGDISP(QMGR) and one with QSGDISP(GROUP). Queues should have a third with QSGDISP(SHARED). It is not necessary to specify QSGDISP(COPY) because the required commands will be generated automatically when the commands for objects with QSGDISP(GROUP) are issued.

  6. Do not specify the same MAKEDEF, MAKEREP, MAKEALT, or MAKEDEL data set for more than one COMMAND function, unless its DD statement specifies a sequential data set with DISP=MOD.
  7. If you specify the MAKECLNT keyword:

    • In the input data set, the display commands for channels and authentication information objects must contain the ALL parameter so that the complete definition of each channel and authentication information object is produced.
    • If the DISPLAY commands return information for a particular channel more than once, only the last set of information is used.
    • Do not specify the same client definition file data set for more than one COMMAND function, unless its DD statement specifies a sequential data set with DISP=MOD.
  8. The results of DISPLAY commands used in conjunction with MAKEDEF, MAKEREP, MAKEALT, MAKEDEL or MAKECLNT are also sent to SYSPRINT.
  9. If you specify the FAILURE keyword, a command is determined to be a success or failure according to the codes returned in message CSQN205I. If the return code is 00000000 and the reason code is 00000000 or 00000004, it is a success; for all other values it is a failure.
  10. The COMMAND function is determined to be a success only if both:

    • All the commands in the input data set are read and issued and get a response from IBM MQ, regardless of whether the response indicates successful execution of the command or not.
    • Every command issued executes successfully, if FAILURE(CONTINUE) or FAILURE(STOP) is specified.
    If COMMAND fails, no further CSQUTIL functions are attempted.
  11. You need the necessary authority to use command server queues (SYSTEM.COMMAND.INPUT, SYSTEM.COMMAND.REPLY.MODEL, and SYSTEM.CSQUTIL.*) and to use the IBM MQ commands to issue.