Setting fields in the MQMD and MQCIH structures (3270)

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. See also Managing MsgId and CorrelId in a unit of work (3270).

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
The value must be MQFMT_CICS.
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 resources.

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 3270 bridge are as follows:

MQCIH.ADSDescriptor
This field applies to 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, set this value to MQCADSD_SEND + MQCADSD_RECV + MQCADSD_MSGFORMAT. This ensures 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.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 are 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, enter the same value in the MQCIH and the first vector.
The first byte of this field is set to the value in the CICS copybook DFHAID.
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 start the 3270 transaction.

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.ConversationalTask
See the WebSphere MQ Application Programming Reference for details.
MQCIH.Facility
Set this to MQCFAC_NONE in the first message in a pseudoconversation, and also set the MQCIH.FacilityKeepTime to a non zero value. The bridge returns a facility token in the first message, and this value must be used in all subsequent inbound messages in the pseudoconversation.
MQCIH.FacilityKeepTime
If you are sending more than a single message in a pseudoconversation, set this to a non zero value (in seconds) 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.

Set the value of MQCIH.Facility to MQCFAC_NONE in the first message in order to receive a facility token from the bridge.

MQCIH.FacilityLike
Either use the default value of four spaces, or 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.Flags
Set the value to MQCIH_PASS_EXPIRATION to pass the remaining expiry time to the reply message.
MQCIH.Format
Set the value to CSQCBDCI. This informs the bridge that any data following the MQCIH is inbound to the bridge, and might need to be converted. The bridge sets the value of MQCIH.Format in the outbound message, which is returned to the reply queue to CSQCBDCO.
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_TRANSACTION if you are using the 3270 bridge.
MQCIH.RemoteSysid
Set to blank on the first message of a pseudo conversation unless you require the request to be processed on a specific CICS system. Set to the value returned in the first reply message in subsequent messages in the pseudo conversation.
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.
MQCIH.TransactionId
This is the transaction identifier of the user 3270 transaction to be run by the bridge task. The first message must specify the first transaction to be started. Set this field in subsequent messages to the value of MQCIH.NextTransactionId that is returned in the preceding reply message.
MQCIH.UOWControl
This controls the unit of work processing performed by the bridge. See also Managing MsgId and CorrelId in a unit of work (3270).