This C/370 program can be used to remotely link to a CICS program over MQ. LSMQHBIN uses IBM WebSphere MQ for z/OS product.
Clients using LSMQHBIN are expected to send binary data in the MQ payload. The client is responsible for formatting the data according to the target CICS program expectations. LSMQHBIN does not perform any translation over the data. This means it is the client responsibility to perform such conversions as Ascii to Ebcdic, host numeric encoding, etc. LSMQHBIN has a very minimal footprint on the mainframe.
LSMQHBIN is associated with a CICS transaction that is triggered when messages are received in a designated request queue. A sample MQDEFJCL JCL is provided to guide you thru setting up such an MQ CICS trigger.
LSMQHBIN relies on specialized libraries, delivered as C370 programs to provide messaging, tracing and CICS link functionalities to both COMMAREA and CONTAINERS driven programs.
The call diagram looks like this:
------------
---->| LSMSGLIB |
| ------------
| ------------
| --->| LSLNKCOM |
| | ------------
------------ | ------------ |
| LSMQHBIN |------->| LSLNKBIN |----|
------------ | ------------ |
| | ------------
| --->| LSLNKCTN |
| ------------
| ------------
---->| LSCOMLOG |
------------
Another program, called LSMQCBIN is also provided as an optional optimization when activity becomes high and you don't want each new message to start a CICS transaction. The controller will limit the number of started transactions.
- CICS TS 2.3 (6.3.0 Command language translator) and TS 3.1 (6.4.0)
- C/370 for OS/390 V2 R10
- WebSphere MQ for z/os 5.3
LSMQHBIN serves clients using the LegStar cmqrt library. This library formats the MQ payload as compact binary.
LSMQHBIN expects the following standard MQ message descriptor fields:
| replyToQueueName | Mandatory | Where replies will be stored (including errors) |
| replyToQueueManagerName | Optional | The MQ Manager for the reply queue. |
| messageId | Mandatory | A unique message identifier. Will be propagated back as a correlationId in the reply. |
| correlationId | Optional | If you send a non null correlation ID it will be returned as the correlation ID. Otherwise, the message ID will be returned as correlation ID. |
In addition, these optional context headers can be specified:
| applicationIdData | Optional | Characters 1 to 5: + Turns traces on in CICS if value is 'true'. Characters 6 to 22: + The trace ID to prefix log traces. |
| userId | Optional | Informational, propagated on replies. |
Upon reply, any error will be signaled back with an MQ content that starts with the "LSOKERR0" eye catcher characters. The eye catcher is followed by a human readable error message in EBCDIC.
Errors trapped by LSMQHBIN are also logged into CICS CESE TD Queue which usually points to CEEMSG.
If no errors occured, the reply data will be binary.