 -----
 CICS Server for Websphere MQ
 -----

CICS MQ handler LSMQHBIN

* Overview:

 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-readme.html}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.

* Limitations:

  - LSMQHBIN does not support the INPUTMSG option of the LINK command.
 
* This program has been tested for:

  - 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

* How it works:

 LSMQHBIN serves clients using the {{{../legstar-cmqrt/index.html}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.   |
*-------------------------+-----------+--------------------------------------------------+
Standard MQ message descriptor fields

 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.        |
*-------------------+-----------+----------------------------------------------+
MQ context headers

 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.


   