ReadQueue

Use the ReadQueue activity to read messages from a data queue.

General

In the General tab of the ReadQueue activity, you can specify a data queue to read message from.

Field Process Property? Module Property? Description
Name No No The name to be displayed as the label for the activity in the process.
IBM i Connection No Yes Click to select an IBM i shared resource.

If no matching IBM i shared resources are found, click Create Shared Resource to create one. See Creating an IBM i Shared Resource for more details.

Data Queue Yes Yes The name of the data queue(*DTAQ) to read message from. The format of the data queue name is library_name/data_queue_name.

Type the data queue name manually, or click to open the Fetch Object dialog. All libraries are listed in the dialog, you can expand each library to view a list of available data queues.

Note:
  • If the data queue you specified in this field does not exist, after clicking verification, a Request data queue data_queue_name does not exist. Create a new request data queue? message is displayed in a pop-up window. Click OK to create a data queue on IBM i system, click Cancel to cancel creating a data queue.
  • The plug-in supports the wildcard queries, you can also use the *LIBL/data_queue_name format to specify a data queue.
Key Value Yes Yes Enter a value for the key.

If the length of the entered value is the same as the length of the key defined in the data queue, the ReadQueue activity filters the messages using the value.

If you enter nothing in this field, the ReadQueue activity will not filter messages.
Note: If the data queue you specified in the Data Queue field is not a keyed data queue, and you enter a value in this field, the verification will fail.
Browse Mode No No When enabled, this option will cause the activity to peek at the queue and return the message. The message is left on the queue, but its contents are presented in the activity's output. The compare semantics used to get the next message from the queue are exposed on the Input tab field "searchtype." If the activity is used in a loop, you can map the key from one read/browse operation onto the input of the next, and the "searchtype" is dynamically adjusted to process the messages on a queue in any desired key sequence.
Is Shared No No Select this check box to retrieve the messages which contains the shared message.
Shared Message Yes Yes

Enter the value of the shared message to retrieve the message containing this value from the data queue.

Note: This field is enabled when the Is Shared check box is selected.
MaxWaitTime Yes Yes The maximum time (in milliseconds) to wait if the data queue contains no messages. The default value is 0.

After the configuration, click Verify Queue to test whether the specified configuration results in a valid connection to the data queue.

Description

A short description of the ReadQueue activity.

Advanced

In the Advanced tab of the ReadQueue activity, you can customize a message schema to read the message from a data queue.

Click Initialize Schema to initialize a message schema. If the queue specified on the General tab is keyed, and the configuration has passed queue verification, a key field will automatically be inserted into the schema. If the shared message value has been specified on the General tab, and the configuration has passed queue verification, a sharedMessage field will automatically be inserted into the schema. To create a message schema, see Creating a Message Schema for more information. Click Copy to copy the message schema to another activity. Click Paste to overwrite the current schema with a schema copied from another activity.

Column Name Description
Input Source Select either a dedicated schema or binary output for the activity. If you select a dedicated schema, you can construct the format of the message in the wizard below. If you select binary output, the output schema presents fields for the key and raw bytes to be mapped. This is useful when parsing data via the Data Conversion Plug-in. The schema construction wizard is disabled if you select binary input.
Schema The schema that you want to define.
Note:
  • If the Is Shared check box is selected in the General tab, a sharedMessage item is displayed in this column. The data type of the shared message can only be Character.
  • If the data queue is a keyed data queue, and the verification is passed in the General tab, a key item is displayed in this column.
Description A short description of the parameter.
IBM i Type The data type of the parameter that is defined on an IBM i system.
Plugin Type The data type used in this plug-in corresponding to the data type on the IBM i system.
Sequence

Enter an integer for the corresponding item or schemaNode.

The entered value indicates the maximum occurrences of the attribute in the Output tab.

Directionality This field can be one of three values: "inout", "in", or "out." These values control whether the field will fall on the input, output, or both schema tabs for mapping purposes. It is only applicable for program and service program activities and should be defaulted to "inout" for all others.

Input

The input tab contains the following items:
Input Item Description
dataqueue The name of the data queue(*DTAQ) to read messages from. The format of the data queue name is library_name/data_queue_name.
Note: If you enter nothing in this item, the ReadQueue activity reads the message from the data queue you specified in the Data Queue field in the General tab.

If you enter a data queue name which is different from the data queue you specified in the Data Queue field in the General tab, the ReadQueue activity reads the message from the data queue in the Input tab.

key This field overrides the key field from the general tab. It is provided to facilitate runtime mapping of the key field, and is particularly useful when processing a queue with a ReadQueue activity in a loop.
searchtype This field controls the matching algorithm used when reading keyed messages from a queue. Acceptable values are:
  • EQ (equal)
  • NE (not equal)
  • LT (less than)
  • LE (less than or equal)
  • GT (greater than)
  • GE (greater than or equal)

If no value is provided, the matching algorithm defaults to EQ if there is a key, and GE if there is no key. If there is no key, a "null" key of all zeros is used.

Output

The following is the output for the activity:

Output Item Data Type Description
Success Boolean A value of true indicates the operation succeeded.

A value of false indicates the operation failed.

Results Complex If the operation is successful, the message content is filled in under the Results node. Otherwise, nothing is filled in under the Results node.

Fault

The Fault tab lists exceptions that are thrown by the ReadQueue activity:

Fault Thrown When...
IBMiPluginException The plug-in fails to get a status response due to a plug-in error.
ActivityTimedOutException The plug-in fails to get a status response due to a timeout error.
IBMiParameterConvertException The plug-in fails to convert the schema parameters.
IBMiRemoteException The plug-in fails to communicate with an IBM i system.