WebSphere MQ Browse

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

The queue is opened in browse mode, and the results of the first message are returned. To retrieve subsequent messages, the activity must be placed in a loop. If no more messages on the queue satisfy the filter criteria, the activity fails with fault message code 50217. Interception of this fault by a fault handler allows the process to gracefully exit the browse loop.

The Browse activity can be used to check the queue with or without a wait interval. The activity waits on the queue for the specified interval, then returns whether or not a message is received.

General

The General tab of the Browse 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 operation is performed. This field can be dynamically provided in the input schema and is not required here.
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.
Fail If Quiescing N Select this check box 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 check box is selected by default.
GMO Convert N Causes the get message option MQGMO_CONVERT to be used for this 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.
Application Properties N Select the application properties resource to be used to map the output of this Browse 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 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.
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 Browse activity to inter-operate with various versions of WebSphere MQ applications. Which option to use depends on the sending application. See the section entitled "MQGMO message property option setting" in the IBM WebSphere 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 Browse activity.

Input

The following table lists the input items for the Browse 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 browse 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 Browse 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 userid used in this operation, if any.
  • waitinterval: specify a new browse timeout value for this operation only. It is the number of milliseconds that the operation waits before timing out.

Output

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

Output Item Module Property? Description
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 userid 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
  • 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 WebSphere 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.
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 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 Browse 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 a WebSphere MQ API exception, then that exception's completion code is here.
mqReasonCode String If the message originates as a WebSphere MQ API exception, then that exception's reason code is here.
mqErrorCode String If the message originates as a WebSphere MQ API exception, then that exception's error code is here.