MSG_RECEIVE
This Activity will receive a message from a supported message brokering system such as IBM MQ Series. Refer to 2.3.9 Messaging Configuration for further information on this Activity and the pre-requisites for using it.
The MSGCONFIG parameter specifies the name of a messaging configuration that identifies, amongst other things, the address of and credentials for the messaging system and queue from which the messageis to be received.
The message contents are received into a file. The location and name of the received file is determined by the configuration in conjunction with the parameter values.
In addition, message properties can be received in comma-separated form into a second file. The location and name of the CSV file is determined by the configuration in conjunction with the parametervalues.
In all cases, parameter values, if specified, override values in the configuration.
When no message is available to be received (after waiting for the interval specified by the WAITTIME parameter, if used), the activity ends normally but the output parameters containing message attributes are not filled. The value of the MSGRCVCOUNT output parameter may be used to determine whether a message was received.
INPUT Parameters:
MSGCONFIG : Required
This parameter must contain the name of a messaging configuration. This configuration can be created and maintained using the Messaging Configurations option in the LANSA Composer client software. Amongst other things, the messaging configuration specifies the address, queue name and security credentials to be used with the message broker system. If this parameter is not provided or is not foundor is Inactive, this Activity will return an error and processing will be abandoned
WAITTIME: Optional
Specifies the length of time (in milliseconds) that the activity will wait for a qualifying message to arrive in the message queue if one is not immediately available when the activity is processed.
The default value is -1 which means that the activity does not wait for the arrival of a message if one is not immediately available when the activity is processed.
You may also specify a special value of 0 (zero) which means that the activity waits indefinitely for a message to arrive. You should understand that this value may cause the activity and hence the processing sequence in which it is contained to stall indefinitely if no message is sent to the message queue. Other than by the arrival of a message, such a processing sequence run may only be terminated by terminating the job, the subsystem in which the job is running or the system.
ENCODING: Optional
Use the ENCODING when the received message is a Unicode TextMessage. The default value is UTF-8.
MSGFOLDER: Optional
Use the MSGFOLDER to specify the folder to which the file containing the received message contents will be written. If specified, this parameter overrides the Receive folder value in the messaging configuration.
You can leave this parameter unspecified and specify a fully qualified MSGFILENAME.
When neither the folder nor the MSGFILENAME are specified, the file will be created in \x_lansa.
MSGFILENAME: Optional
The name to be given to the file containing the received message contents. Use in conjunction with MSGFOLDER or the Receive folder in the configuration. If specified, this parameter overrides the Receive file name value in the messaging configuration.
When a filename is not specified, the file's name will be auto generated in the format:
<system setting prefix><number>
PTYFILENAME: Optional
The name to be given to the file containing the received message properties. When this parameter has no value but message properties are received, the file will have the same name as the MSGFILENAMEwith the extension CSV appended to it.
The file will be created in the Message Properties Receive file path, if specified in the messaging configuration (Message Properties tab). If not, it will be created in the MSGFOLDER. Otherwise itwill be created in \x_lansa.
SELECTOR: Optional
A message selector to be passed to the MQSeries system. Only valid for MQSeries message queue on an IBM i server. The message selector is used to select which message is to be received by the activity. If specified, only messages matching the specified criteria will be received by the activity. Otherwise, messages will not be filtered.
OUTPUT Parameters:
MESSAGEID:
The message ID of the received message as returned by the message broker system.
MSGRCVCOUNT:
The received message count. If a message is received successfully, the value will be one (1). Otherwise the value will be zero (0).
MSGFILENAMEOUT:
The full path and file name of the file to which the received message contents were written.
PTYFILENAMEOUT:
The full path and file name of the file to which the received message properties were written.