WebSphere 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, it is possible for applications to 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 check box to enable the creation of a dynamic queue. When selected, the Dynamic Destination Model field is enabled. Dynamic queues are ones which are created as needed and destroyed when the lifespan dictated by the model is reached.
Dynamic Destination Model Y Select the Dynamic Destination check box 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:
  • 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.
Message Type N Select the type of the message that is to be sent:
  • Datagram
  • Request
  • Reply
  • Report

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 check box is enabled if Request is selected in the Message Type field.

When this check box 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 check box is selected.

Fail If Quiescing N Select this check box 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 check box 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 WebSphere 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.
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 Put activity.

Multi-Message

The Multi-Message tab of the Put activity contains the following fields:

Field Module Property? Description
Multi-Message Support N Select the level of support this activity is to have for batch groups and logical messages.
Select one of the following settings:
  • None: the input schema provides only for a single message and it is put without a sync-point. This is the fastest operation configurable.
  • Batch: the input schema is configured for batch messages. Multiple nodes are sent as separate messages and committed as a single unit of work.
  • BatchGroup: the input schema is configured for batch but all the messages provided are sent as a single logical message group.
  • CustomGroup: in this mode, the input schema is configured for a single message, and the lastMessageInGroup field is provided. In this mode, the activity must be used in a loop to create a logical message group. On the last pass through the loop, the lastMessageInGroup field of the input schema must be set to true to terminate the group.

    Unless the activity is in an MQ Local Transaction, each member of the logical message is committed as the activity ends. If an error occurs, an incomplete logical message can be left in the queue. It is therefore good practice to use a local transaction to commit an entire logical message at once.

  • CustomSegmented: in this mode, the input schema is configured for a single message and the lastSegment field is present to indicate when the last segment of the segmented message is sent. In this mode, the Put activity must be used in a loop to send a segmented grouped message. This is useful if the entire message cannot be held in memory and must be processed a segment at a time.
    Unless the activity is in an MQ Local Transaction, each member of the segmented message is committed as the activity ends. If an error occurs, an incomplete logical message can be left in the queue. It is therefore good practice to use a local transaction to commit an entire segmented message at once.
    Note: CustomGroup or CustomSegmented options must be used in a loop because the activity stores the message object for use as context when sending the next message.
Segmentation N Select the segmentation behavior for this put operation.
Select one of the following settings:
  • None: the message is not segmented and the queue manager cannot segment the message.
  • Explicit: this enables the Max Segment Size field and segments the message configured in the input schema into as many segments as necessary to send the whole message.
  • QueueManager: the message is sent with flags set so that the queue manager can segment it to suit the buffer sizes of any channels encountered on the way to the destination.
  • Both: the message is explicitly segmented by Max Segment Size and flags are set supporting the queue manager to further segment the message if necessary.
Max Segment Size Y If Explicit or Both is enabled, this field is enabled. Enter the maximum size in bytes that any segment of this message can consume (not including the size of the header on each segment).

Default: 0

Explicit Commit N Every attempt is made within the plug-in to avoid unnecessary commits because of the overhead involved. However, you might select the check box to force the creation of a unit of work and subsequent commit. The commit happens after any application properties and message body fields have been processed, so selecting the check box protects you from removing a message from the queue only to fail while processing the contents. Message contents can cause failures if, for example, the encoding or character set is inappropriate for the data, or the schema used to process the message is in error.
Syncpoint Used N This field is not a configuration field, rather it is an indication of whether a syncpoint is required for the operation. Non-syncpoint operations are significantly faster than syncpoint ones, however the overhead of a syncpoint is much less significant for large batches.
Note: If an activity is inside a local transaction, this field is unaware of that fact. In that case, a syncpoint is always in effect for the local transaction.

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, mean that the message never expires.

Values range from -1 to 2147483647.

Generate Correlation Id N Select this check box 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 check box 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:
  • 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 (in addition to those provided by Identity) are:
    • applicationOriginData
    • putApplicationType
    • putApplicationName
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:
  • NONE: the report is not enabled.
  • NO_DATA: the body of the message does not accompany the report.
  • WITH_DATA: the first 100 bytes of the message body accompanies the report.
  • FULL_DATA: the entire body of the message accompanies the report.

Reports are delivered to 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:
  • NONE: the report is not enabled.
  • NO_DATA: the body of the message does not accompany the report.
  • WITH_DATA: the first 100 bytes of the message body accompanies the report.
  • FULL_DATA: the entire body of the message accompanies the report.

Reports are delivered to 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:
  • NONE: the report is not enabled.
  • NO_DATA: the body of the message does not accompany the report.
  • WITH_DATA: the first 100 bytes of the message body accompanies the report.
  • FULL_DATA: the entire body of the message accompanies the report.

Reports are delivered to 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:
  • NONE: the report is not enabled.
  • NO_DATA: the body of the message does not accompany the report.
  • WITH_DATA: the first 100 bytes of the message body accompanies the report.
  • FULL_DATA: the entire body of the message accompanies the report.

Reports are delivered to 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 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.
  • When selected, the correlation ID of the sent message is copied to the correlation ID field of the report message.
  • When cleared, the message ID of the sent message is copied to the correlation ID field of the report message.
Asynchronous Put* N Select this check box 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 WebSphere documentation for the put message option MQPMO_ASYNC_RESPONSE for more information regarding the risks of using this option.

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 input.
  • 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.
  • messageId: specify a message ID. This value overrides the default value generated by the queue manager. The rules are the same as for correlationId.
  • groupId: specify a group ID. The queue manager overrides the group ID for any message composed of multiple physical messages. However, if the intention is to send a single message and use the groupId element as an additional filter by the receiving application, then mapping a group ID here meets that requirement. The rules are the same as that for correlationId.
  • 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 userid 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 WebSphere 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: specify the name of a queue that the target application can use as a destination for its response. This enables the common "request response" pattern. If the queue is a dynamically created one, it is created by the Put activity and is closed at the end of the process that creates it. Therefore, any get for the reply must be done in the same process; otherwise, the queue will be deleted by the queue manager.
  • replyToQmgrName: destination queue manager name. The name of the queue manager on which this queue is located.
    Tip: A transmission queue and a sender channel must be configured for this to work.
  • 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: this is the report options field for the message. If nothing is entered, then the report options as configured in the Advanced tab are used to populate it at run time. However, if a number is mapped here, it is logically OR'ed with the results of processing the report options. It is provided to enable the use of report options not configurable in the Advanced tab.
  • 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 fields is mapped by a message body schema. For specific values, see the MQMessage encoding field in the WebSphere MQ documentation.
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. Create one node for each property to be placed on the message. Note that if the name of a dynamic property collides with a property from the appProperties node, the dynamic property takes precedence.
  • 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".
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 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.
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:
Note: Some of these fields are missing or inaccurate if the Asynchronous Mode is used.
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 a subsequent activity.
  • 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 remote queue manager specified for the put operation.
  • 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.
  • 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: same as input.
  • replyToQmgrName: destination queue manager name. The name of the queue manager on which this queue is located.
    Tip: A transmission queue and a sender channel must be configured for this to work.
  • format: the character string placed into the format element by the sending application.
  • 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 contents of the report field in the returned message.
  • encoding: to document the numerical value of the encoding field. This encoding is used for extracting numerical data from the message if those numbers are in properties or a message body schema.
  • 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 was 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 message is placed into the queue.
  • groupStatus: to indicate whether the message is part of a logical message.
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 TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ error message.
msgCode String The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere 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.