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:
- For conversational transactions there are separate values for the initial
MQCIH value and the value on the vector.
- If the WebSphere MQ application is sending a message in response to a request
vector, the value in the MQCIH is ignored.
- 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).