IBM MQ RequestReply

The RequestReply activity performs the combined operations of putting a request message into a queue, and then listening on the indicated response queue for the reply.

Because the RequestReply activity depends on the request being committed to the request queue, this activity does not participate in local transaction semantics. This also means that this activity does not share a connection resource with activities in a local transaction because it can unexpectedly commit resources under the control of the local transaction.

General

The General tab of the RequestReply activity contains the following fields:

Field Module Property? Description
Name N The name to be displayed as the label for the activity in the process.
Connection Y The connection resource which associates this activity with the queue manager that has access to the desired queue.
Destination Y The name of the queue into which the message is placed. If the queue is to be created dynamically, enter the name of the dynamic queue. The name must follow the MQSeries rules for dynamic queue names.

If the queue name has been dynamically mapped using the input schema's destination field, this field is not required.

Message Content Type N Select the type of message content:
  • Binary: if Binary is selected, string content can still be sent, but it must be translated to binary through an XPath expression.
  • Text: string data can be directly mapped onto the message. The message is decoded using characterSet for the message, or 819 if none is provided. Characterset 819 is the Java API default.
  • Schema: the message is formatted according to the schema provided in the Message Body Fields field. Input values for this schema are displayed in the input editor.
Message Body Fields Y Provide the schema to be used in the Input tab, and at run time to encode the contents of this message.
Reply To Destination Y Specify a reply queue on which the RequestReply activity performs a get immediately after sending a request. The activity waits for the number of milliseconds specified in the waitinterval element of the input schema.

The queue name which is placed into the message header's Reply To Destination field. If this queue is dynamic, it is created before the put is performed, and the name of the temporary queue is set in the request message.

Dynamic ReplyToDestination N A flag that enables the creation of a dynamic queue.

When selected, the Dynamic ReplyToDest Model field is enabled, and the reply queue is dynamically created based on the model in the Dynamic ReplyToDest Model field. If a dynamic reply queue is specified, it is created during the put operation so that it is available to the responding application.

Dynamic ReplyToDest Model Y Specify the model after which the reply queue is to be patterned.

This field is enabled only when the Dynamic ReplyToDestination checkbox is selected.

Fail If Quiescing N Select this checkbox to cause the activity to fail if the queue manager attempts to quiesce during the operation. This prevents the queue manager quiesce from being delayed by this activity.
Application Properties N Select the Application Properties resource to be included as part of this message. Application properties are similar to regular message header fields except that the name and type of these fields can be determined by a predefined schema.
To use application properties, create a generic XML schema composed of a node with simple elements inside it and map it to this field. See the IBM MQ documentation for property types supported by the level of client you have installed.
Note: A failure to observe cardinality results in errors processing the input or output schema.
CICS Bridge Header N When enabled causes the input and output schemas to include the CICS bridge header: MQCIH. By mapping fields onto this header in accordance with the IBM CICS bridge for IBM MQ, it is possible to invoke CICS programs and run transactions which display screens. See the IBM Knowledge Center resources at https://www.ibm.com/support/knowledgecenter/SSGMCP_4.2.0/com.ibm.cics.ts.wmq.bridge.doc/topics/zc12190_.html for more information on how to interact with the CICS bridge. The specific fields related to the MQCIH header are not described in the input and output schemas section. See the relevant IBM documentation for this.
IMS Bridge Header N When enabled causes the input and output schemas to include IMS bridge header: MQIIH. By mapping fields onto this header in accordance with the IBM MQ bridge for IMS, it is possible to invoke IMS programs and transactions. See the IBM Knowledge Center resources at https://www.ibm.com/support/knowledgecenter/SSFKSG_9.0.0/com.ibm.mq.pro.doc/q004310_.htm for more information on how to interact with the IMS bridge. The specific fields to the MQIIH header are not described in the input and output schemas section. See the relevant IBM documentation for this.
Logger Name Y Loggers are configured in an XML file used at run time. The runtime logger configuration is specified by the -Dlogback.configurationFile parameter of either the deployed application instance or of the debugger instance. After the logger is configured, it can be named here to cause informational messages to be written there. See the TIBCO ActiveMatrix BusinessWorks documentation for more details about how to configure loggers.

Description

A short description for the RequestReply activity.

Advanced

The Advanced tab of the RequestReply activity contains the following fields:

Field Module Property? Description
Message Priority Y Set the priority of the message as it is to be retrieved by the queue manager. The values range from 0 to 9.
Message Expiration Y The time, in tenths of a second, that the message persists in the queue before being deleted by the queue manager.

Values range from 0 to 2147483647.

The default is 0, which means the message never expires.

Generate Correlation Id N Select this checkbox to cause the queue manager to generate a unique correlation identifier for the message when it is sent. This means that the message identifier, which is always generated, is copied to the correlation identifier field.
Note: If this option is enabled, the queue manager overlays any correlation identifier that is mapped in the input schema.
Persistence N Determines whether messages on the queue manager persist across restarts.
Select one of the following settings:
  • AS_QUEUE_DEF: it uses the persistence level defined in the queue definition.
  • PERSISTENT: it ensures that the message persists if the queue manager fails or restarts.
  • NOT_PERSISTENT: not persistent.
Context Support N The input fields of a put operation fall into categories based on their context. Many fields are always present, but others are only present if the context relevant to that field is chosen. This is because the queue manager must grant the user the authorization to update these fields.
Select one of the following settings:
  • Default: the input schema conforms to the fields accessible to a user with the default authority.
  • Identity: the input schema conforms to the fields accessible to a user with the Set Identity Context authority.
    The new fields are:
    • accountingToken
    • applicationIdData
    • userId
  • All: the input schema conforms to the fields accessible to a user with the Set Identity Context and Set All Context authorities.
    The new fields (also to those provided by Identity) are:
    • applicationOriginData
    • putApplicationType
    • putApplicationName

Input

Activity Pooling

The Activity Pooling tab allows the activity to pool all the MQ resources associated with the request reply activity at the process level.

The Activity Pooling tab contains the following fields:

Field Global Variable Description
Pool Activity N Select the Pool Activity checkbox to activate pooling for the client objects used by this activity. Selecting this option causes pooling to be done at a higher level than merely pooling the connection. All destinations used by the activity are kept open and the connection resource specified are not pooled in the usual way even if that resource has pooling enabled. This option is used when the server to which you are connected experiences very high latency such that opening, closing, and pooling of connections cause unacceptable performance degradation.

The primary consideration for choosing pooling parameters is the number of available connections to the queue manager. Choose values that do not create unnecessary resource consumption in the queue manager, and leave available connections for other applications (including other pooled connections and activities, remember that the application might be deployed on multiple engine instances).

Pool Max Y Determines the maximum number of connections in the pool. When this limit is reached, subsequent activities fail with the following message:

"Activity Pool is exhausted: [Timeout waiting for idle object] Either enlarge the pool, allow it to grow, or increase the blocking time."

Pool Max Idle Y Determines the maximum number of idle connections in the pool. When the number of unused connections reaches this number, the idle connections are disconnected and closed, freeing resources on the server. Amounts over the Max Connections value are ignored.
Exhausted Action N Select one of the following options:

● FAIL - The activity fails immediately after the pool is exhausted.

● BLOCK - The activity waits for the "Pool Wait" interval before failing. If an MQ client is available before the timeout, the activity acquires it.

● GROW - The pool grows past its maximum parameters.

Pool Wait Y If exhausted action is set to "BLOCK", the pool waits for the "Pool Wait" interval for an activity to become available before failing.

The following table lists the input items for the RequestReply activity:

Input Item Module Property? Description
InteractionInput N This input schema field is the root node for all the input provided to the activity.
mqproperties N The node containing all the message header fields (plus the destination override) that are relevant to the put side of the operation. Note that any values mapped to the filtering fields (messageId, correlationId, and groupId) are subsequently used to filter the get side of the operation.
  • destination: specify a destination here to override the queue name from the configuration panels. With it, the queue can be dynamically specified.
  • destqmgr: destination queue manager name. The name of the queue manager on which this queue is located.
    Note: A transmission queue and a sender channel must be configured for this queue manager in order for it to work.
  • correlationId: provide a correlation identifier for this message by mapping a byte array to this field. The XPath expression tib:string-to-base64 ("correlationid") is sufficient to populate this field. If a correlation ID is provided, then the activity filters the reply queue using the same correlation ID.
  • messageId: specify a message ID. This value overrides the default value generated by the queue manager. The rules are the same as for correlationId. If a message ID is provided, then the activity filters the reply queue using the same message ID.
  • groupId: specify a group ID for a message if the message is part of a group. If a group ID is provided, then the activity filters the reply queue using the same group ID.
  • characterSet: set the IBM Coded Characterset ID of this message. Valid values are:
    • 850: The commonly used ASCII codeset.
    • 819: The ISO standard ASCII codeset.
    • 37: The American EBCDIC codeset.
    • 1200: Unicode.
    • 1208: UTF-8.

      The queue manager might apply this codeset when doing conversions for the purpose of creating report messages.

  • alternateUserId: to document the alternate user ID used in this operation, if any.
  • accountingToken: provide a binary (base 64 encoded) accounting token to be used on host systems to assist in accounting for resources used by the application.
  • applicationIdData: provide a string that can be used on all end points to identify this application.
  • applicationOriginData: provide information related to the originating application node for this message.
  • putApplicationType: provide either one of the IBM documented application type enumerators for this application or one of your choosing. See the IBM MQ documentation for the meaning of the documented application types. These are the documented enumerations: 
    MQAT_AIX          MQC.MQAT_AIX          0x06   
MQAT_CICS         MQC.MQAT_CICS         0x01
MQAT_DOS          MQC.MQAT_DOS          0X05      
MQAT_IMS          MQC.MQAT_IMS          0X03
MQAT_MVS          MQC.MQAT_MVS          0X02
MQAT_OS2          MQC.MQAT_OS2          0X04
MQAT_OS400        MQC.MQAT_OS400        0X08   
MQAT_QMGR         MQC.MQAT_QMGR         0X07   
MQAT_UNIX         MQC.MQAT_UNIX         0X06
MQAT_WINDOWS      MQC.MQAT_WINDOWS      0X09   
MQAT_JAVA         MQC.MQAT_JAVA         0X1C  
MQAT_UNKNOWN      MQC.MQAT_UNKNOWN   -1 or 0XFFFFFFFF   
MQAT_NO_CONTEXT   MQC.MQAT_NO_CONTEXT   0X00   
MQAT_CICS_VSE     MQC.MQAT_CICS_VSE     0X0A
MQAT_VMS          MQC.MQAT_VMS          0X0C   
MQAT_GUARDIAN     MQC.MQAT_GUARDIAN     0X0D   
MQAT_VOS          MQC.MQAT_VOS          0X0E  
MQAT_DEFAULT      MQC.MQAT_DEFAULT      0X1C   
MQAT_NSK          MQC.MQAT_NSK          0X0D   
MQAT_CICS_BRIDGE  MQC.MQAT_CICS_BRIDGE  0X15   
MQAT_NOTES_AGENT  MQC.MQAT_NOTES_AGENT  0X16   
MQAT_WINDOWS_NT   MQC.MQAT_WINDOWS_NT   0X0B   
MQAT_IMS_BRIDGE   MQC.MQAT_IMS_BRIDGE   0X13   
MQAT_XCF          MQC.MQAT_XCF          0X14
  • putApplicationName: provide information about the originating application in this field.
  • userId: provide the user ID to be used when authorizing this message as it traverses the messaging system. For operations with report options, this field is mandatory. If a value is not provided here, it is taken from the connection resource if one is available there, and from the environment if it is not.
  • replyToQueueName: this field overrides the Reply To Destination field provided in the General tab. This is the destination on which the Get side of the operation waits after sending the request. If neither the configuration value nor this field is provided, then the activity fails with an MQRC_MISSING_REPLY_TO_Q error.
  • replyToQmgrName: destination queue manager name. Because IBM MQ does not support a get operation in a remote queue, this field is ignored. The reply must come back from the same queue manager to which the activity is connected.
  • format: describes the nature of the data in the message. It defaults to " ", or MQFMT_NONE. A user defined format can be used to assist the receiving application in decoding the message, for example, in the selection of a Data Conversion parse activity for this message type.
  • expiry: indicates the length of time (in tenths of a second) that the message is kept in the queue before being deleted. Defaults to -1, which means there is no expiration. This field overrides the configuration value for expiry if it is mapped. Permissible values are a positive integer or -1.
  • priority: the priority (from 1 to 9) of the message. This field overrides a configuration value for priority if it is mapped.
  • reportOptionPan: set this boolean field to add the value Positive Acknowledgment to the report field of the message. This field is an application only field and is not acted upon by the queue manager.
  • reportOptionNan: set this boolean field to add the value Negative Acknowledgment to the report field of the message. This field is an application only field and is not acted upon by the queue manager.
  • report: because this activity always sends a request type message, report options are not available. If any report options are provided here, they are reset to zero by the queue manager.
  • encoding: this is the encoding field for the message and it specifies the representation used for numeric values in the application message data. This applies to binary, packed decimal and floating point data. This encoding is used when processing of fields mapped by a message body schema. For specific values, see the MQMessage encoding field in the IBM MQ documentation.
  • waitinterval: specify the number of milliseconds that the RequestReply activity waits for the response after sending the request before throwing a timeout exception. To wait indefinitely, define a -1 in this field using the statement xsd:int(-1).
appProperties N Contains fields that correspond to the schema as it is defined in the application properties resource that is mapped to this activity. Application properties are included in an MQRFH2 header which is dynamically added to the message.
Note: This node is only displayed if a properties resource is specified for the activity.
messageFields N This element is present when Schema is selected from the Message Content Type list of the General tab. The contents of the mapped schema are present in this node for mapping purposes.
dynamicProperties N
  • dynamic property: these properties are exactly the same as those mapped through the appProperties node with the exception that no special schema is required to map them. A dynamicProperties node is created for each property in the message which was not mapped by the appProperties schema mechanism. If no appProperties schema is in place, all properties are dynamic.
  • name: the name of the property.
  • value: the string type value of the property.
  • type: the type for the property. The valid types are "string", "boolean", "short", "integer", "long", "float", "double", and "byte".
bytes N Present if Binary is selected in the Message Content Type area. Map the main content of the message body here. In general, this is the output of a Plug-in for Data Conversion render activity, but it can be any array of bytes. If string data is to be mapped to this field, use the XPath function tib:string-to-base64 to convert it to bytes.
text N Present if Text is selected in the Message Content Type area. A string mapped to this field is converted to bytes using the character set specified for the message.

Output

The following table lists the output items for the RequestReply activity:
Note: Some of these fields are missing or inaccurate if the Asynchronous Mode is used.
Output Item Module Property? Description
InteractionOutput N The root node for all the output provided by the activity.
mqproperties N The node containing the message fields relevant to the get side of the request/reply operation. Any fields which relate to filtering messages (messageId, correlationId, and groupId) which are mapped on the input schema are used to filter the response presented here.
  • destination: to document the destination for this message. If the queue is a dynamic queue, the generated name is reported here.
  • destqmgr: to document the destination queue manager as it is specified in the reply message. Because get operations must occur on the queue manager to which the activity is connected, this destination queue manager is always that same queue manager.
  • correlationId: to document the correlation ID, if any.
  • messageId: to document the message ID.
  • groupId: to document the group ID, if any.
  • characterSet: to document the character set used by the queue manager to process this message. This character set is also the character set used to extract string data from the message.
  • alternateUserId: as provided in the input schema.
  • accountingToken: as provided in the input schema.
  • applicationIdData: as provided in the input schema.
  • applicationOriginData: as provided in the input schema.
  • putApplicationType: as provided in the input schema.
  • putApplicationName: as provided in the input schema.
  • userId: the effective user ID used to connect to the queue manager.
  • replyToQueueName: normally null for this activity type because the output of this activity represents a reply.
  • replyToQmgrName: destination queue manager name. The name of the queue manager on which this queue is located.
  • format: the format of the message. This field is normally used to help the receiving application parse the payload. The value can be one of the IBM standard formats or an custom application specific value.
  • expiry: to indicate the number of tenths of a second that the message is kept in the queue before being deleted. Defaults to -1, which means there is no expiration.
  • priority: the priority (from 1 to 9) with which the message is sent.
  • reportOptionPan: reflects the value of the Positive Acknowledgment bit of the report field. This field is an application only field and is not acted upon by the queue manager.
  • reportOptionNan: reflects the value of the Negative Acknowledgment bit of the report field. This field is an application only field and is not acted upon by the queue manager.
  • report: to document the report field in the message as it is received.
  • encoding: to document the encoding field in the message as it is received. This encoding is used to extract any numerical data from the message.
  • waitinterval: the number of milliseconds the RequestReply activity waits for the response to the request sent by this activity.
  • messageType: enumerated value of the chosen message type:
    • 8 is Datagram.
    • 2 is Reply.
    • 4 is Report.
    • 1 is Request.
  • backoutCount: the number of times this message is backed out before being committed.
  • feedback: for a Report message received by a WMQ Get or Listener activity, this field defines the nature of the report. The field is unused with a value of 0 in Put activities.
  • version: to document the version of the message. This Plug-in supports type 2 messages only.
  • putDateTime: the time that the request message is placed into the queue.
  • groupStatus: to indicate whether the message is part of a logical message. It can contain any one of the following:
    • MSG_IN_GROUP
    • MSG_NOT_IN_GROUP
    • MSG_LAST_IN_GROUP
appProperties N This field maps the application properties present in the received message to the schema attached to the activity. Properties which are missing or not present in the schema are not shown here.
messageFields N Contains the message body formatted using Schema in the Message Content Type field of the General tab.

This field is displayed for schema-based messages only.

dynamicProperties N
  • dynamic property: these properties are exactly the same as those mapped through the appProperties node with the exception that no special schema is required to map them. A dynamicProperties node is created for each property in the message which was not mapped by the appProperties schema mechanism. If no appProperties schema is in place, all properties are dynamic.
  • name: the name of the property.
  • value: the string type value of the property.
  • type: the type for the property. The valid types are "string", "boolean", "short", "integer", "long", "float", "double", and "byte".
bytes N If the activity is configured to use binary messages, then this field contains the output body of the message. Typically, this byte array is to be mapped as input to a TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion parse activity.

This field is only displayed when Binary is selected in the Message Content Type area.

text N If the activity is configured to use text for the payload, this field is present and contains the contents of the message decoded as a string.

This field is only displayed when Text is selected in the Message Content Type area.

responsetimemillisec N To indicate, in milliseconds, how long it takes to send the message.

Fault

The Fault tab lists exceptions that occur in the RequestReply activity:

Error Schema Element Data Type Description
msg String The TIBCO ActiveMatrix BusinessWorks Plug-in for IBM MQ error message.
msgCode String The TIBCO ActiveMatrix BusinessWorks Plug-in for IBM MQ error code.
mqCompCode String This is the original MQException's completion code, if it is an MQException that triggers the fault.
mqReasonCode String This is the original MQException's reason code, if it is an MQException that triggers the fault.
mqErrorCode String If the message originates as an IBM MQ API exception, then that exception's error code is here.

The elements listed below occur only for the MqReqReply error schema.

Error Schema Element Data Type Description
mqReqReplyCorrId Byte Array If the message originates as an IBM MQ API exception, then that exception's request reply correlation id is here.
mqReqReplyMsgId Byte Array If the message originates as an IBM MQ API exception, then that exception's request reply message id is here.