Invoking the IBM MQ utility program

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 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 you need?

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

Use PARM= (or omit it all together) if you 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 you are using the COMMAND verb to issue MQSC commands, you 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.

The utility issues an MQCMIT call when the MAXUMSGS limit is reached and issues the warning message CSQU087I. If the utility later fails, the changes already committed are not backed out.

Do not just rerun the utility 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 you can choose to accept duplicate messages on the queues.

To avoid such difficulties if the function fails, there are two options:

1.Temporarily increase the value of MAXUMSGS to be greater than the number of messages in the:
- Queue, if you are working with a single queue.
- Longest queue in the page set, if you 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.

Then rerun the command, and after the utility has successfully run change MAXUMSGS back to what it was before.
Note: This approach is simpler but having a large number of messages in a single unit of work can incur a high CPU cost.
Use the utility to LOAD the messages to a temporary queue.
Note that you can delete the temporary queue in the event of failure and the job rerun.
Then use the MQSC MOVE command to move the messages from the temporary queue to the target queue. For example:
```
MOVE QL(tempq) TOQLOCAL(targetq) TYPE(ADD)
```
Once the command has completed successfully, you can delete the temporary queue.

This approach takes longer, but moves the messages in a number of small units of work so is more efficient in terms of CPU cost.