Invoking the IBM MQ utility program on z/OS

Use this topic to understand how to invoke CSQUTIL, the format of its parameters, and its return codes.

The CSQUTIL utility program runs as a z/OS batch program, below the 16 MB storage line. Specify the resources that the utility is to work with in the PARM parameter of the EXEC statement of the JCL.
Figure 1. How to invoke the CSQUTIL utility program
// EXEC PGM=CSQUTIL,PARM=

where PARM= expands to:

PARM= ' QMGRnameQSGname,DSGname,DB2ssidQMGRname,QSGname,DSGname,DB2ssid '


PARM parameters

    QMGRname
    Specifies the 1- to 4-character name of the queue manager or queue sharing group to which CSQUTIL is to connect.

    If you specify the name of a queue sharing group, CSQUTIL connects to any queue manager in that group

    QSGname
    Specifies the 1- to 4-character name of the queue sharing group from which CSQUTIL is to extract definitions.

    DSGname
    Specifies the 8-character name of the Db2 data-sharing group from which CSQUTIL is to extract definitions.

    db2ssid
    Specifies the 4-character name, or group attach name, of the Db2 database subsystem to which CSQUTIL is to attach for stand-alone functions.

    Which PARM parameters do we need?
    Figure 1 shows that we can specify one of four options on the PARM statement. The option you specify depends on the function we need to implement, as follows:

    • Use PARM= (or omit it all together) if we are using only offline functions, and not QSGDISP(GROUP) or QSGDISP(SHARED).
    • Use PARM=' QMGRname ' only if you intend to use functions that require the queue manager to be running, such as COPY and COMMAND.
    • Use PARM=' QSGname,DSGname,db2ssid ' if you intend to use the SDEFS function with either QSGDISP(GROUP) or QSGDISP(SHARED) specified. This is because CSQUTIL requires access to Db2 to perform the SDEFS function in this situation.
    • Use PARM=' QMGRname,QSGname,DSGname,db2ssid ' if you intend to combine the previous two functions in one CSQUTIL job.

    If you specify a queue manager name as blanks, CSQUTIL uses the name of the default queue manager specified for z/OS batch programs in CSQBDEFV. The utility then uses this queue manager for the whole job step. When the utility connects to the queue manager, the authorization of the "signed-on user name"? is checked to see which functions the invocation is allowed to use.

    You specify the functions required by statements in the SYSIN data set according to these rules:

    • 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 statement must start on a new line.
    • 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 keywords of statements are not case-sensitive. However, some arguments, such as queue name, are case sensitive.

    The utility statements refer to the default or explicitly named DDnames for input and output. Your job can use the COPY and LOAD functions repeatedly and process different page sets or queues during a single run of the utility.

    All output messages are sent to the SYSPRINT data set, which must have a record format of VBA and a record length of 125.

    While running, CSQUTIL uses temporary dynamic queues with names of the form SYSTEM.CSQUTIL.*


Return codes

When we are using the COMMAND verb to issue MQSC commands, we must use FAILURE(CONTINUE) so any failure in the commands that are issued give a non-zero return code. The default is FAILURE(IGNORE) and the return code from the command is always zero.

When CSQUTIL returns to the operating system, the return code can be:

    0
    All functions completed successfully.

    4
    Some functions completed successfully, some did not, or forced a sync point.

    8
    All the attempted functions failed.

    12
    No functions attempted; there was a syntax error in the statements or the expected data sets were missing.

In most cases, if a function fails or is forced to take a sync point, no further functions are attempted. In this case, the message CSQU147I replaces the normal completion message CSQU148I.

See the usage notes for each function for more information about success or failure.


Syncpoints

The queue management functions used when the queue manager is running operate within a syncpoint so that, if a function fails, its effects can be backed out. The queue manager attribute, MAXUMSGS, specifies the maximum number of messages that a task can get or put within a single unit of recovery.

MAXUMSGS should normally be set to a low value, both to protect against looping applications, and because there might be a very large processor cost in committing many messages.

The utility forcibly takes sync points as required and issues the warning message CSQU087I. If the function later fails, the changes already committed are not backed out. Do not just rerun the job to correct the problem or you might get duplicate messages on your queues. Instead, use the current depth of the queue to work out, from the utility output, which messages have not been backed out. Then determine the most appropriate course of action. For example, if the function is LOAD, you can empty the queue and start again, or we can choose to accept duplicate messages on the queues.

To avoid such difficulties if the function fails, but at the risk of incurring a large processor cost, set MAXUMSGS to be greater than:

  • The number of messages in the queue, if we are working with a single queue.
  • The number of messages in the longest queue in the page set, if we are working with an entire page set.

Use the DISPLAY QSTATUS command to find out the value of the CURDEPTH attribute, which is the current depth of the queue. To find out the value of MAXUMSGS, use the DISPLAY QMGR MAXUMSGS command.

Parent topic: IBM MQ utility program (CSQUTIL) on z/OS