MQI calls in IMS applications

Use this information to learn about the use of MQI calls on Server applications and Enquiry applications.

This section covers the use of MQI calls in the following types of IMS applications:

• Server applications
• Inquiry applications

Server applications

Here is an outline of the MQI server application model:

Initialize/Connect
.
Open queue for input shared
.
Get message from IBM MQ queue
.
Do while Get does not fail
.
If expected message received
Process the message
Else
Process unexpected message
End if
.
Commit
.
Get next message from IBM MQ queue
.
End do
.
Close queue/Disconnect
.
END

Sample program CSQ4ICB3 shows the implementation, in C/370, of a BMP using this model. The program establishes communication with IMS first, and then with IBM MQ :

main()
----
Call InitIMS
If IMS initialization successful
Call InitMQM
If IBM MQ initialization successful
Call ProcessRequests
Call EndMQM
End-if
End-if

Return

The IMS initialization determines whether the program has been called as a message-driven or a batch-oriented BMP and controls IBM MQ queue manager connection and queue handles accordingly:

InitIMS
-------
Get the IO, Alternate and Database PCBs
Set MessageOriented to true

Call ctdli to handle status codes rather than abend
If call is successful (status code is zero)
While status code is zero
Call ctdli to get next message from IMS message queue
If message received
Do nothing
Else if no IOPBC
Set MessageOriented to false
Initialize error message
Build 'Started as batch oriented BMP' message
Call ReportCallError to output the message
End-if
Else if response is not 'no message available'
Initialize error message
Build 'GU failed' message
Call ReportCallError to output the message
Set return code to error
End-if
End-if
End-while
Else
Initialize error message
Build 'INIT failed' message
Call ReportCallError to output the message
Set return code to error
End-if

Return to calling function

The IBM MQ initialization connects to the queue manager and opens the queues. In a message-driven BMP this is called after each IMS syncpoint is taken; in a batch-oriented BMP, this is called only during program startup:

InitMQM
-------
Connect to the queue manager
If connect is successful
Initialize variables for the open call
Open the request queue
If open is not successful
Initialize error message
Build 'open failed' message
Call ReportCallError to output the message
Set return code to error
End-if
Else
Initialize error message
Build 'connect failed' message
Call ReportCallError to output the message
Set return code to error
End-if

Return to calling function

The implementation of the server model in an MPP is influenced by the fact that the MPP processes a single unit of work per invocation. This is because, when a syncpoint (GU) is taken, the connection and queue handles are closed and the next IMS message is delivered. This limitation can be partially overcome by one of the following:

• Processing many messages within a single unit-of-work This involves:
  • Reading a message
  • Processing the required updates
  • Putting the reply
  in a loop until all messages have been processed or until a set maximum number of messages has been processed, at which time a syncpoint is taken.

  Only certain types of application (for example, a simple database update or inquiry) can be approached in this way. Although the MQI reply messages can be put with the authority of the originator of the MQI message being handled, the security implications of any IMS resource updates need to be addressed carefully.

• Processing one message per invocation of the MPP and ensuring multiple scheduling of the MPP to process all available messages.

  Use the IBM MQ IMS trigger monitor program (CSQQTRMN) to schedule the MPP transaction when there are messages on the IBM MQ queue and no applications serving it.

  If trigger monitor starts the MPP, the queue manager name and queue name are passed to the program, as shown in the following COBOL code extract:

  * Data definition extract
  01 WS-INPUT-MSG.
  05 IN-LL1         PIC S9(3) COMP.
  05 IN-ZZ1         PIC S9(3) COMP.
  05 WS-STRINGPARM      PIC X(1000).
  01 TRIGGER-MESSAGE.
  COPY CMQTMC2L.
  *
  * Code extract
  GU-IOPCB SECTION.
  MOVE SPACES TO WS-STRINGPARM.
  CALL 'CBLTDLI' USING GU,
  IOPCB,
  WS-INPUT-MSG.
  IF IOPCB-STATUS = SPACES
  MOVE WS-STRINGPARM TO MQTMC.
  *  ELSE handle error
  *
  * Now use the queue manager and queue names passed
  DISPLAY 'MQTMC-QMGRNAME     ='
  MQTMC-QMGRNAME OF MQTMC '='.
  DISPLAY 'MQTMC-QNAME       ='
  MQTMC-QNAME  OF MQTMC '='.
  

The server model, which is expected to be a long running task, is better supported in a batch processing region, although the BMP cannot be triggered using CSQQTRMN.

Inquiry applications

A typical IBM MQ application initiating an inquiry or update works as follows:

• Gather data from the user
• Put one or more IBM MQ messages
• Get the reply messages (you might have to wait for them)
• Provide a response to the user

Because messages put on to IBM MQ queues do not become available to other IBM MQ applications until they are committed, they must either be put out of syncpoint, or the IMS application must be split into two transactions.

If the inquiry involves putting a single message, we can use the no syncpoint option; however, if the inquiry is more complex, or resource updates are involved, you might get consistency problems if failure occurs and we do not use syncpointing.

To overcome this, we can split IMS MPP transactions using MQI calls using a program-to-program message switch; see IMS/ESA® Application Programming: Data Communication for information about this. This allows an inquiry program to be implemented in an MPP:

Initialize first program/Connect
.
Open queue for output
.
Put inquiry to IBM MQ queue
.
Switch to second IBM MQ program, passing necessary data in save
pack area (this commits the put)
.
END
.
.
Initialize second program/Connect
.
Open queue for input shared
.
Get results of inquiry from IBM MQ queue
.
Return results to originator
.
END