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).