Setting fields in the MQMD and MQCIH structures

Your CICS 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.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 MQFMT_NONE.

MQMD.MsgId
For MQPUTs to the request queue, set the value to MQMI_NONE in every message.

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.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 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.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 will be checked for access to the CICS DPL program.

You must 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, the MQCIH.Authenticator field must also be initialized. 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. The input fields that you need to initialize in your application program when you use the CICS bridge are as follows.

MQCIH.Format
Set the value to "CSQCBDCI". This informs the bridge that any data following the MQCIH is inbound to the bridge, and may need to be converted. The bridge will set the value of MQCIH.Format in the outbound message, which is returned to the reply queue, to "CSQCBDCO".

MQCIH.UOWControl
This field controls the unit of work processing performed by the bridge. Allowed values are described in WebSphere MQ Application Programming Reference. Select the required value from the ones that are available, noting that most are valid for the DPL bridge only, and not for the 3270 bridge. See also Managing units of work for the CICS DPL bridge and Managing units of work for the CICS 3270 bridge.

MQCIH.GetWaitInterval
If you allow this to default, the bridge task GET WAIT interval for messages within a unit of work will be 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 will be unlimited.

MQCIH.LinkType
You must specify MQCLT_PROGRAM if you are using the DPL bridge, or MQCLT_TRANSACTION if you are using the 3270 bridge.

MQCIH.OutputDataLength
This applies only to the DPL bridge. See WebSphere MQ Application Programming Reference for details.

MQCIH.FacilityKeepTime
This applies to the 3270 bridge only. If you are sending more than a single message in a pseudoconversation, you must set this to a non zero value in the first message for the bridge to return a facility token. Successive transactions in a pseudoconversation can use the same facility token once it has been set in this way, ensuring that associated terminal areas - for example the TCTUA - are preserved for the period of the pseudoconversation.

Note also that the value of MQCIH.Facility must be set to MQCFAC_NONE in the first message in order to receive a facility token from the bridge.

MQCIH.ADSDescriptor
This field applies only to the 3270 bridge for transactions that use BMS SEND MAP and RECEIVE MAP calls. If this is the case, and the application that is sending bridge request messages is on a workstation, you must set this value to MQCADSD_SEND + MQCADSD_RECV + MQCADSD_MSGFORMAT. This will ensure that the vectors in the bridge request and reply messages are correctly converted between the different CCSID and encoding schemes of the workstation and the mainframe.

MQCIH.ConversationalTask
This applies to the 3270 bridge only. See WebSphere MQ Application Programming Reference for details.

MQCIH.Facility
This applies to the 3270 bridge only. Ensure that this is set to MQCFAC_NONE in the first message in a pseudoconversation, and also ensure that the MQCIH.FacilityKeepTime is set to a non zero value. The bridge will return a facility token in the first message, and this value must be used in all subsequent inbound messages in the pseudoconversation.

MQCIH.Authenticator
This field only applies if you are using an authorization level of VERIFY_UOW or VERIFY_ALL. VERIFY_UOW is available to both the 3270 bridge and the DPL bridge, but VERIFY_ALL is available only to the DPL bridge.

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 will be used by the external security manager to determine whether the user is authorized to start the 3270 transaction or link to the DPL program.

MQCIH.ReplyToFormat
Set this to MQFMT_NONE (the default value) if your application and the ridge are running in the same CCSID and encoding environment. Otherwise, set the value to MQFMT_CICS.

MQCIH.TransactionId
If you are using the DPL bridge, 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. See WebSphere MQ Application Programming Reference for details of how to specify a different transaction code.

If you are using the 3270 bridge, this is the transaction identifier of the user transaction that run as the bridge task. The first message must specify the first transaction to be started. You should set this field in subsequent messages to the value of MQCIH.NextTransactionId that is returned in the preceding reply message.

MQCIH.FacilityLike
You can either use the default value of four spaces, or you can specify the name of an installed terminal. You can find the names of installed terminals by entering the CICS command CEMT I TASK or a CEMT I TERM at a CICS terminal.

MQCIH.AttentionId
Set this field to a value representing the AID key expected by the transaction, if any, otherwise accept the default value of four spaces, which will appear to the CICS transaction as the ENTER AID key.

The inbound RECEIVE, RECEIVE MAP and CONVERSE vectors also have fields in which you can specify AID values. The value in the MQCIH is the value to which EIBAID is set to when the application is started. It represents the PF key used to start the transaction. The value in the inbound vector is the value used when the data is entered. For example, this would be the value of EIBAID after the EXEC CICS RECEIVE MAP instruction.

Notes:

  1. For conversational transactions there would be separate values for the initial MQCIH value and the value on the vector.

  2. If the WebSphere MQ application is sending a message in response to a request vector, the value in the MQCIH is ignored.

  3. In the case of pseudoconversational transactions, the same value should be entered in the MQCIH and the first vector.

The first byte of this field is set to the value in the CICS copybook DFHAID.

MQCIH.StartCode
Change the value of this field from the default value of MQCSC_NONE only if you are starting a 3270 transaction. The value you use depends on the nature of the transaction. Use a value of MQCSC_START if the transaction is started by an EXEC CICS START command without data, and it does not issue EXEC CICS RETRIEVE. Use a value of MQCSC_STARTDATA if the transaction is started by an EXEC CICS START command with data, and it issues EXEC CICS RETRIEVE. Otherwise, use a value of MQCSC_TERMINPUT.

© IBM Corporation 1993, 2002. All Rights Reserved