The Queue Attributes sample on z/OS

The Queue Attributes sample is a conversational-mode CICS® application that demonstrates the use of the MQINQ and MQSET calls.

It shows how to inquire about the values of the InhibitPut and InhibitGet attributes of queues, and how to change them so that programs cannot put messages on, or get messages from, a queue. You might want to lock a queue in this way when you are testing a program.

To prevent accidental interference with your own queues, this sample works only on a queue object that has the characters CSQ4SAMP in the first eight bytes of its name. However, the source code includes comments to show you how to remove this restriction.

Source programs are supplied in the COBOL, assembler, and C languages (see Table 2 ). The assembler-language version of the sample uses reenterable code. To do this, you will notice that the code for each MQI call in that version of the sample includes the MF keyword; for example:

CALL MQCONN,(NAME,HCONN,COMPCODE,REASON),MF=(E,PARMAREA),VL

(The VL keyword means that we can use the CICS Execution Diagnostic Facility (CEDF) supplied transaction for debugging the program.) For more information about writing reenterable programs, see Coding in System/390 assembler language. To start the application, start your CICS system and use the following CICS transactions:

• For COBOL, MVC1
• For assembler language, MAC1
• For C, MCC1

We can change the name of any of these transactions by changing the CSD data set mentioned in step 3.

Design of the sample

When you start the sample, it displays a screen map that has fields for:

• Name of the queue
• User request (valid actions are: inquire, allow, or inhibit)
• Current status of put operations for the queue
• Current status of get operations for the queue

The first two fields are for user input. The last two fields are filled by the application: they show the word INHIBITED or the word ALLOWED.

The application validates the values that you enter in the first two fields. It checks that the queue name starts with the characters CSQ4SAMP and that you entered one of the three valid requests in the Action field. The application converts all your input to uppercase, so we cannot use any queues with names that contain lowercase characters.

If you enter inquire in the Action field, the flow through the program logic is:

1. Open the queue using the MQOPEN call with the MQOO_INQUIRE option
2. Call MQINQ using the selectors MQIA_INHIBIT_GET and MQIA_INHIBIT_PUT
3. Close the queue using the MQCLOSE call
4. Analyze the attributes that are returned in the IntAttrs parameter of the MQINQ call and move the words INHIBITED or ALLOWED, as appropriate, to the relevant screen fields

If you enter inhibit in the Action field, the flow through the program logic is:

1. Open the queue using the MQOPEN call with the MQOO_SET option
2. Call MQSET using the selectors MQIA_INHIBIT_GET and MQIA_INHIBIT_PUT, and with the values MQQA_GET_INHIBITED and MQQA_PUT_INHIBITED in the IntAttrs parameter
3. Close the queue using the MQCLOSE call
4. Move the word INHIBITED to the relevant screen fields

If you enter allow in the Action field, the application performs similar processing to that for an inhibit request. The only differences are the settings of the attributes and the words displayed on the screen.

When the application opens the queue, it uses the default connection handle to the queue manager. ( CICS establishes a connection to the queue manager when you start your CICS system.) The application can trap the following errors at this stage:

• The application is not connected to the queue manager
• The queue does not exist
• The user is not authorized to access the queue
• The application is not authorized to open the queue

For other MQI errors, the application displays the completion and reason codes.