IBM MQ Get

The Get activity is used to retrieve a message from a configured queue. Messages can be retrieved based on filter criteria specified in the input document.

The Get activity can be used to:
  • Check the queue with a wait interval. The activity waits on the queue for the specified interval, then returns whether or not a message is received.
  • Check the queue without a wait interval. The activity checks the queue and returns immediately, regardless of whether a message is read.
  • Listen indefinitely on the queue. The activity returns a message if one is available, or waits forever for a message to arrive.

General

The General tab of the Get 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 connects this activity with the queue manager that has access to the desired queue.

Click the icon to select a usable connection for the activity.

Destination Y Enter the name of the queue on which this get operation is performed. This field can be dynamically provided in the input schema and is not required here.
Dynamic Destination N Select the Dynamic Destination checkbox to enable dynamic destinations for this operation. This enables the Dynamic Destination Model field.
Dynamic Destination Model Y Enter the name of the model queue which the queue manager uses as a template when constructing this dynamic destination.
Message Content Type N Choose the way that the message body is represented in the output schema.
  • Binary: the message is an array of bytes suitable for use by the Data Conversion Palette activities.
  • Text: the message is a string. 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. Values for this schema are displayed in the Output tab.
Message Body Fields Y Provide the schema to be used in the Output tab, and at run time to encode the contents of this message. This field is only available if Schema is selected in the Message Content Type field.
Close Option N Select the close option for this Get activity. These options are for use with permanent dynamic queues only.
  • NONE: no action is taken.
  • DELETE: deletes the queue, if it is empty. If the queue is not empty, no action is taken.
  • PURGE: deletes the queue and any messages in it.

If the Get activity is being performed on a permanent dynamic queue and the intention is for the queue to be deleted, you can choose either DELETE or PURGE. DELETE deletes the queue if it is empty, and PURGE deletes the queue and any messages that are in it.

Note: Do not select DELETE or PURGE for permanently defined queues. Depending on your security access, this might delete them.
Access Mode N Select the access mode for the queue:
  • QDEFAULT: it accepts the access mode established when the queue is created.
  • SHARED: other listeners can access the queue in this mode.
  • EXCLUSIVE: other listeners cannot access the queue in this mode. If another IBM MQ application has the queue open, this activity fails.
Fail If Quiescing N Select this checkbox to cause the activity to fail and exit if the queue manager attempts to quiesce. A failure to do so causes quiesce operations to take much longer. This checkbox is selected by default.
GMO Convert N Causes the get message option MQGMO_CONVERT to be used for this get operation. It causes the queue manager to convert string and numeric fields using the characterSet and encoding elements before the data is copied to the message buffer.
Wait Forever N If the Wait Forever checkbox is selected, the Get activity waits forever for a message in the queue. If the Wait Forever checkbox is cleared, the Wait Timeout field is enabled and the waitinterval node of the input schema is observed and overrides the values in the Wait Timeout field.
Note: If a Get activity is configured to wait forever, it does so even after the application is set to stop using the administrator or shell command. To release the connection and close the destination, it is necessary to stop the appNode on which this application is running.
Wait Timeout Y The number of milliseconds this activity waits for a message before failing.

This field is not available if the Wait Forever checkbox is selected.

Application Properties N Select the application properties resource to be used to map the output of this Get activity. Application properties are similar to regular message header fields except that the name and type of the fields can be determined by a predefined schema. If the received message contains properties, they are mapped according to this schema.
To use application properties, create a generic XML schema composed of a node with simple elements inside it and map that schema 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 output schema.

For information about this facility, see the IBM CICS bridge documentation.

IMS Bridge Header N Enable to allow the activity to participate in IMS bridge applications. The MQIIH header is presented on the output schema.

See the IBM IMS bridge documentation for information about this facility.

Property Control N Select one of the following settings:
  • AS_Q_DEF
  • COMPATIBILITY
  • IN_HANDLE
  • FORCE_MQRFH2

After selecting one of these options, you can use the Get activity to inter-operate with various versions of IBM MQ applications. Which option to use depends on the sending application. See the section entitled "MQGMO message property option setting" in the IBM MQ documentation for detailed information.

Logger Name Y Enter the name of any logger which has been configured for the run time to write to. If no logger name is provided, then the default one is used. The activity writes informational messages to the log depending on how the logger is configured.

Description

A short description for the Get activity.

Multi-Message

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

Field Module Property? Description
Multi-Message Support N This value can be None, BatchGroup or CustomGroup.
  • None: in this mode, the Get activity operates as though it is expecting a non-logical ordinary message from the queue. However, there is no way to prevent it from getting the first member of a logical message if it exists. The Complete Message, and Get Ordered fields apply. If the activity is not in a local transaction and the Explicit Commit checkbox is clear, it operates without a syncpoint for efficiency.
    Note: The Syncpoint Used indicator is off.
  • BatchGroup: in this mode, the get operation is expecting to get either a group of individual messages (in which case the Batch Size field controls how many messages are retrieved) or a Logical Message. This operation implies a unit of work and the entire batch is processed as a single unit of work unless the unit of work is extended by the use of a local transaction. Because it is not possible to filter out logical messages, if a normal message is fetched and then a logical message is encountered, the entire logical message is included with the normal message in one operation regardless of the Batch Size value. If the intention is to process Logical Messages only, set the batch size to 1. The Complete Message and Get Ordered fields are in effect.
  • CustomGroup: in this mode, the activity gets a single message from the queue and stores the context of this message for subsequent use. This mode is intended to be used in a loop to iteratively process the contents of a Logical Message. The output schema field groupStatus indicates whether the message is in a group and whether or not is the last message with the contents: MSG_IN_GROUP, MSG_NOT_IN_GROUP, MSG_LAST_IN_GROUP. This field is used to determine when to terminate the loop. Unless the activity is in a local transaction, it commits the contents of each get as they are performed.
  • CustomSegmented: in this mode, the activity gets a single segment of a segmented message from the queue and stores the context of this message for subsequent use. This mode is intended to be used in a loop to iteratively process the contents of a Segmented Message. The output schema field lastSegment indicates whether the currently fetched message is the last one in the group or not. If it is set to true for the last message, this value can be used to terminate a loop on the segmented message. Unless the activity is used in a local transaction, it commits the contents of each get as they are performed. The activity is specifically intended to be used in a loop to process the contents of a segmented message where the entire message is too large to fit into memory.
Batch Size Y If BatchGroup mode is in effect, this field becomes enabled. Enter the number of discrete messages which are to make up this batch get. The output schema contains a node for each message retrieved. If a timeout occurs while the batch is incomplete, then the incomplete batch is processed and no exception is thrown.
Complete Message N Selecting the Complete Message checkbox causes the Get activity to wait for a logical message to be complete before returning any of the messages. When the Complete Message checkbox is cleared, a logical message needs not be complete for the get to work, which is handy for processing damaged messages, or messages which are intended to be processed as they are written to the queue. It has no effect on non-logical messages. A message is considered to be complete when all members are committed to the queue by the sending application.
Get Ordered N When the Get Ordered checkbox is selected, it requires that a logical message be processed in the order it is written to the queue. Therefore, the first get in a message requires that message number 1 be present, so it must be disabled to process partial (damaged) logical messages. The queue must be indexed for this to work. If the queue is not indexed, this option is dynamically switched off.
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 checkbox 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 this checkbox 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 is a status indicator only and does not represent any configuration information. It indicates whether the activity runs with a syncpoint in effect and therefore require a subsequent commit operation. Every effort has been made to avoid unnecessary commits. The flag might be off if the activity is in a local transaction, but there is still a syncpoint in place on behalf of the transaction, so it is irrelevant in that case.

Input

Activity Pooling

The Activity Pooling tab allows the activity to pool all the MQ resources associated with the get 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 Get activity:

Input Item Module Property? Description
InteractionInput N 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) which are relevant to input.
  • destination: override the destination queue name with the string specified in this field.
  • destqmgr: the name of the remote queue manager from which to fetch the message.
    Note: The queue managers involved must be configured with the necessary sender and receiver channels in place and started.
  • correlationId: provide a correlation identifier for this message by mapping a byte array to this field. The XPath statement tib: string-to-base64 ("correlationid") is sufficient to populate this field. The provided correlation ID is used to filter messages from the queue.
  • 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, it is used to filter the get results.
  • groupId: specify a group ID. If a single message is placed in the queue using a specific group ID, then this message can be filtered and received by a Get activity after this activity maps the correct group ID there. This field is provided for use as an extra filter field only.
  • 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.
  • waitinterval: specify a new get timeout value for this operation only. It is the number of milliseconds that the operation waits before timing out. If the Wait Forever checkbox in the General tab is selected , this field is ignored.

Output

The following table lists the output items for the Get activity:

Output Item Module Property? Description
Batch N If BatchGroup is selected for this activity, this Batch node is the high level item for the activity and contains a number of InteractionOutput nodes equal to or less than the Batch Size parameter depending on how many messages are available within the timeout period. If a get in the BatchGroup mode encounters a logical message on the queue, even after processing one or more single messages, an entire logical message is retrieved as part of the get operation. This might cause the output node to exceed the size of the Batch Size parameter. It is good practice to design the application such that queues containing logical messages contain only logical messages.
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 output.
  • destination: to document the destination for this message. If the queue is a dynamic queue, the generated name is reported here.
  • destqmgr: the name of the remote queue manager supplied in the input schema.
  • correlationId: to document the message correlation ID, if any.
  • messageId: to document the message ID.
  • groupId: to document the group ID.
  • characterSet: to document the character set the queue manager uses to process this message.
  • alternateUserId: to document the alternate user ID used in this operation, if any.
  • accountingToken: the accounting token provided by the sending application.
  • applicationIdData: application ID data. This is the application data provided by the sender of the message.
  • applicationOriginData: origin data as provided by either the sender of the message or the queue manager.
  • putApplicationType: the type of the application that puts the message.
    Documented enumerations are: 
    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
MQAT_NO_CONTEXT
  • putApplicationName: application name data as provided by either the sender of the message or the queue manager.
  • userId: the effective user ID used to connect to the queue manager.
  • replyToQueueName: the name of the queue to which a reply is sent. If the type of the message is Request, then this is the name of the queue that the application sends the reply message to.
  • replyToQmgrName: the name of the remote queue manager for this message's reply-to destination, if one is provided.
  • format: to describe the nature of the data in the message. The sender of the application can use standard names (these names are prefixed by the MQ text) or application-generated names. If the message originates from a TIBCO ActiveMatrix BusinessWorks Plug-in for IBM MQ application, this is an empty string.
  • expiry: the expiration time (in tenths of a second), after which the message is eligible to be discarded by the queue manager.

    The default value of -1 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 numerical value of the report field.
  • encoding: to document the numerical value of the encoding field. This encoding is used for extracting numerical data from the message if the numbers are in properties or a message body schema.
  • messageType: enumerated value indicating the 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: if the message is a Report message, this field defines the nature of the report. Defaults to 0 for non-report messages.
  • 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. It can contain any 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.
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.
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.

lastMessageInGroup N This field is displayed in the output schema after clicking CustomGroup in the Multi-Message Support area .

In a custom group, this flag indicates the last message in the group.

lastSegment N This field is displayed in the output schema after clicking CustomSegmented in the Multi Message Support area.

In a segmented message, this flag indicates the last message in the group.

responsetimemillisec N To indicate how long it takes to receive the message. This value includes any time spent waiting on an empty queue.

Fault

The Fault tab lists the possible exceptions that occur in the Get activity:

Error Schema Element Data Type Description
msg String The descriptive text provided by this exception object.
msgCode String If the message has a BW message code, it is mapped to this field.
mqCompCode String If the message originates as an IBM MQ API exception, then that exception's completion code is here.
mqReasonCode String If the message originates as an IBM MQ API exception, then that exception's reason code is here.
mqErrorCode String If the message originates as an IBM MQ API exception, then that exception's error code is here.