Setting fields in the MQMD and MQCIH structures (DPL)

Your CICS(R) bridge application must set a number of fields in the MQMD and the MQCIH in order to use the bridge successfully. You need to consider the open options and the put message options that you use for the bridge request queue if the bridge monitor is started with authorization levels of VERIFY_UOW or VERIFY_ALL.

Setting the MQMD fields

Fields in the MQMD that can affect the operation of the CICS bridge need to be initialized in your application program:

MQMD.CorrelId
For MQPUTs to the request queue, set the value to MQCI_NEW_SESSION in the first or only message in a unit of work. On subsequent messages in the unit of work, set the value to the MQMD.MsgId that WebSphere MQ set in your message descriptor when you put your first message to the request queue.

For MQGETs from the reply queue, use the value of MQMD.MsgId that WebSphere MQ set in your message descriptor when you put your most recent message to the request queue, or specify MQCI_NONE.

MQMD.Expiry
Set a message expiry time based on how long you want your application to wait for a reply. You are recommended to set a reasonable value for your enterprise. Set the MQCIH flags to propagate the remaining expiry time to the reply message.
MQMD.Format
Set the value to MQCICS if you include an MQCIH in the message you send to the bridge request queue; otherwise set it to the format of the data following.
MQMD.MsgId
For MQPUTs to the request queue, set MsgId to a unique value for the unit of work, or to MQMI_NONE.

For MQGETs from the reply queue, use the value of MQMD.MsgId that WebSphere MQ set in your message descriptor when you put your first message to the request queue.

MQMD.ReplyToQ
Set the value to the name of the queue where you want the bridge to send reply messages.
MQMD.UserIdentifier
This field is only used when the bridge monitor is running with authorization levels of IDENTIFY, VERIFY_UOW, or VERIFY_ALL. If you use any of these, set the value to the user ID that is checked for access to the CICS DPL program.

Add the value MQOO_SET_IDENTITY_CONTEXT to the open options when you open the bridge request queue, and also add the value MQPMO_SET_IDENTITY_CONTEXT to the put message options when you send a message to the queue.

If you use this field with one of the VERIFY_* options, you must also initialize the MQCIH.Authenticator field. Set it to the value of the password or passticket associated with the user ID.

Setting the MQCIH fields

The MQCIH contains both input and output fields; see the WebSphere MQ Application Programming Reference for full details of this structure. The key input fields that you need to initialize in your application program when you use the CICS DPL bridge are as follows:

MQCIH.Authenticator
This field only applies if you are using an authorization level of VERIFY_UOW or VERIFY_ALL.

Set the value to the password or passticket that is to be associated with the user ID in the MQMD.UserIdentifier field. Together, the values are used by the external security manager to determine whether the user is authorized to link to the DPL program.

If using passtickets, the Applid used for generating the passticket must be the same as the PASSTKTA keyword values used when starting the bridge monitor.

MQCIH.Flags
Set to MQCIH_PASS_EXPIRATION to pass the remaining expiry time to the reply message.

Set to MQCIH_REPLY_WITHOUT_NULLS to remove trailing null characters ('00'X) from the reply message.

Set to MQCIH_SYNC_ON_RETURN to specify the SYNCONRETURN option on the EXEC CICS LINK command.

You can combine the values by adding them together.

MQCIH.Format
Specifies the format of the data following the MQCIH structure. If the data is character data use MQFMT_STRING; if no conversion is needed use MQFMT_NONE.
MQCIH.GetWaitInterval
If you allow this to default, the bridge task GET WAIT interval for messages within a unit of work is the value specified on the WAIT parameter when the bridge monitor was started. If you also allow the WAIT parameter to default, the GET WAIT interval is unlimited.
MQCIH.LinkType
Specify MQCLT_PROGRAM if you are using the DPL bridge.
MQCIH.OutputDataLength
This field applies only to the DPL bridge and sets the length of data returned by the program.
MQCIH.RemoteSysId
Leave this field blank unless you need the request processed by a specific CICS system.
MQCIH.ReplyToFormat
Set this to MQFMT_NONE (the default value) if your application and the bridge are running in the same CCSID and encoding environment. Otherwise, set the value to the format of the COMMAREA data returned.
MQCIH.TransactionId
Use the default value (four spaces) unless you want the bridge to run the DPL program under a transaction code other than the default value of CKBP.
MQCIH.UOWControl
This controls the unit of work processing performed by the bridge. Allowed values are described in the WebSphere MQ Application Programming Reference. See also Managing MsgId and CorrelId in a unit of work (DPL).