IBM MQ Put
The Put activity can place messages into a configured queue.
The four types of messages are as follows:
- Datagram: basic message.
- Request: a message for which the sending application expects a response and for which a Reply to Queue is required.
- Reply: a message sent in response to a received Request type message. Usually, the destination for this message has been mapped from the Reply To Queue field of the request message.
- Report: a message containing monitoring data. In most cases, report messages are generated by queue managers. However, applications can do so using this message type.
The activity is capable of sending any of the four message types to permanent or dynamic queues. The capabilities of the activity are determined by the configuration, with some runtime behaviors controlled by the input schema. The type of message being sent might determine what fields are applicable for the put operation.
Messages can be sent to predefined queues or dynamic queues. If the destination or the reply to queue is dynamic, you must specify a properly configured model queue. The queue manager constructs a dynamic queue based on that template. The name of a unique dynamic queue can be generated if the queue name provided ends with an asterisk (*). It makes sense to use such names only if it is possible to configure a receiving application with the name of the newly created queue. The name can be taken from the destination element in the Output tab.
General
The General tab of the Put 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 onto 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. |
| Dynamic Destination | N | Select this checkbox to enable the creation of a dynamic queue. When selected, the Dynamic Destination Model field is enabled. Dynamic queues are created as needed and destroyed when the lifespan dictated by the model is reached. |
| Dynamic Destination Model | Y | Select the
Dynamic Destination checkbox to enable this field.
Enter the name of a queue model for the queue manager to use as a template for creating this dynamic queue. |
| Message Content Type | N | Select the type of message content:
|
| 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. |
| Message Type | N | Select the type of the message that is to be sent:
If a Request message is selected, the Reply To Destination and Dynamic ReplyToDestination fields are enabled. |
| Reply To Destination | Y | This field is enabled for the
Request message type only.
The queue name which is placed into the message header's Reply To Destination field. If the reply to destination is dynamic, a queue is created and kept open until the end of the process. If an asterisk is the last character of the name, or no name is provided, the queue manager generates a name. The destination element in the Put activity's output schema documents this dynamically generated name, and the sent message also contains the name so that the receiving application knows where to send the response. |
| Dynamic ReplyToDestination | N | This checkbox is enabled if
Request is selected in the
Message Type field.
When this checkbox is 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, the dynamic reply queue is created during the put operation so that it is available to the responding application. The created destination exists until the end of the process, so any activity which replies to this request must do so before the process ends or the destination is deleted. |
| 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. This checkbox is selected by default. |
| 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 | Enable to allow the activity to participate in CICS bridge applications. The MQCIH header is presented on the input and output schemas.
Note: The "ProgramName" field, which is the first field in the schema is not part of the header but is used to compose the
LLZZ<ProgramName> section just before the message payload.
See the IBM CICS bridge documentation for information about this facility. |
| IMS Bridge Header | N | Enable to allow the activity to participate in IMS bridge applications. The MQIIH header is presented on the input and output schemas.
See the IBM IMS bridge documentation for information about this facility. |
| 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 of the Put activity.
Multi-Message
The Multi-Message tab of the Put activity contains the following fields:
Advanced
The Advanced tab of the Put 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. |
| Message Expiration | Y | The time, in tenths of a second, that the message persists in the queue before being deleted by the queue manager. The default,
0, as well as the value
-1, means that the message never expires.
Values range from -1 to 2147483647. |
| 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.
|
| Load Balance | N | Select this checkbox to enable load balancing when putting messages to suitably configured cluster queues. When it is enabled for a single message, option MQOO_BIND_NOT_FIXED is used to operate the destination. If the Put activity is for a logical message, the option MQOO_BIND_ON_GROUP is used and if the Put activity is likely to be for a message segment, the MQOO_BIND_ON_OPEN option is used. These options ensure that message groups are all put to the same queue manager. In other respects, the messages are distributed to queue managers according to the workload algorithms in effect for the cluster. |
| Persistence | N | Determines whether messages on the queue manager persist across restarts.
Select one of the following settings:
|
| 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 authorize the user to update these fields.
Select one of the following settings:
|
| Confirm on Arrival | N | Trigger a report message by using the
Confirm on Arrival type. The report is not enabled by default.
Report types are:
Reports are delivered in the reply to queue specified in the Report Reply Queue field. Because this field maps to the message's replyToQueueName field, reports are mutually exclusive with Request type messages. That is, if the message type is Request, a report confirmation is not sent. |
| Confirm on Delivery | N | Trigger a report message by using the
Confirm on Delivery type. The report is not enabled by default.
Report types are:
Reports are delivered in the reply to queue specified in the Report Reply Queue field. Because this field maps to the message's replyToQueueName field, reports are mutually exclusive with Request type messages. That is, if the message type is Request, a report confirmation is not sent. |
| Confirm on Exception | N | Trigger a report message by using the
Confirm on Exception type. The report is not enabled by default.
Report types are:
Reports are delivered in the reply to queue specified in the Report Reply Queue field. Because this field maps to the message's replyToQueueName field, reports are mutually exclusive with Request type messages. That is, if the message type is Request, a report confirmation is not sent. |
| Confirm on Expiry | N | Trigger a report message by using the Confirm on Expiry type. The report is not enabled by default.
Report types are:
Reports are delivered in the reply to queue specified in the Report Reply Queue field. Because this field maps to the message's replyToQueueName field, reports are mutually exclusive with Request type messages. That is, if the message type is Request, a report confirmation is not sent. |
| Report Reply Queue | Y | Enter the name of the queue to which Report messages are sent. This queue needs not to exist and is not checked, but can be selected using Choose a field value type on the right side of the field. The value entered here maps onto a message's replyToQueueName field. |
| Pass Correlation Id | N | Determines the setting for a report message’s correlation ID.
|
| Asynchronous Put* | N | Select this checkbox to achieve a modest improvement in the latency of the Put activity if your application can tolerate the potential for an unreported failure writing to the queue.
See the IBM MQ documentation for the put message option MQPMO_ASYNC_RESPONSE for more information regarding the risks of using this option. |
Activity Pooling
The Activity Pooling tab allows the activity to pool all the MQ resources associated with the put 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:
" |
| 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 values are ignored. |
| Exhausted Action | N | Select one of the following options:
|
| 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. |
Input
The following table lists the input items for the Put activity:
| Input Item | Module Property? | Description |
|---|---|---|
| Batch | N | This node is present when any of the multi-message modes are active based on the activity configuration. With it, the InteractionInput node can be duplicated any number of times to make up a composite batch for the put operation. |
| 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 input.
|
| If the CICS or IMS headers are selected on the general tab, then the contents of the MQCIIH or MQIIH headers are presented here. | N | Consult the IBM CICS and IMS bridge documentation for a description of these header fields. |
| dynamicProperties | N |
|
| 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. |
| 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 an 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. |
| lastMessageInGroup | N | This field is displayed in the input schema after clicking
CustomGroup in the
Multi-Message Support area.
In a custom group, it is up to the application to terminate the logical message by setting this field to TRUE on the last message. |
| lastSegment | N | This field is displayed in the input schema after clicking
CustomSegmented in the
Multi Message Support area.
In a custom group, it is up to the application to terminate the segmented message by setting this field to TRUE on the last message. |
Output
The following table lists the output items for the Put activity:
| Output Item | Module Property? | Description |
|---|---|---|
| Batch | N | This node is present when Batch or BatchGroup in the Multi-Message tab is selected. For each InteractionInput node present in the input schema, an InteractionOutput node is present here under the Batch node. |
| InteractionOutput | N | The root node for all the output provided by the activity. |
| mqproperties | N | The node containing all the message header fields (plus the destination override) which are relevant to input for subsequent activity.
|
| If the CICS or IMS headers are selected on the general tab, then the contents of the MQCIIH or MQIIH headers are presented here. | N | Consult the IBM CICS and IMS bridge documentation for a description of these header fields. |
| responsetimemillisec | N | To indicate, in milliseconds, how long it takes to send the message. |
Fault
The Fault tab lists exceptions that occur in the Put activity:
| Error Schema Element | Data Type | Description |
|---|---|---|
| msg | String | The ActiveMatrix BusinessWorks Plug-in for IBM MQ error message. |
| msgCode | String | The 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 | This is the original MQException's error code, if it is an MQException that triggers the fault. |