MQ/204 and SOUL statements

Overview

SOUL supports MQ/204 as follows:

• OPEN and CLOSE statements support opening and closing queues.
• Set of statements have syntax that closely parallels the WebSphere MQ API for getting and putting messages, and committing and backing out WebSphere MQ transactions.
• MODIFY statement can change defaults on an open queue or alter the size and contents of the data buffer.
• $Functions manipulate queues and queue managers.
• READ IMAGE and WRITE IMAGE statements can manipulate the data buffer.

A SOUL statement with a name that matches a WebSphere MQ API function has a one-to-one correspondence between that SOUL statement and the API call.

To permit an application full flexibility in handling errors, MQ/204 SOUL statements set $STATUS and $STATUSD return codes. See Error handling with $STATUS and $STATUSD.

CLOSE QUEUE statement

Function

Closes a queue that was previously opened with an OPEN QUEUE statement.

Syntax

CLOSE QUEUE {%variable | M204queue-name | external-qmanager:external-queue} [DELETE | DELETE_PURGE | ?%variable]

Where

• Queue to operate on is specified as:

  Queue as...	Specifies...
  %variable	Queue name.
  M204queue-name	Queue name as a literal without quotation marks.
  external-qmanager:external-queue	External name of a queue manager that contains the remote queue to process and the external name of the remote queue.

• DELETE or DELETE_PURGE and ?%variable are the delete options, determined by the attributes assigned in the model queue. A queue with a delete option accepts no more messages or requests and is closed as follows:

  Delete option	For local dynamic queue	Deletes the queue...
  DELETE	Permanent	When no more messages are on the queue and no uncommitted GET or PUT requests are outstanding.
  DELETE_PURGE	Temporary	Purges all outstanding messages and requests.
  ?%variable	Permanent or temporary	At runtime, according to the delete option selected. See Using runtime options.

Usage

The CLOSE QUEUE statement performs an MQCLOSE call. If the queue manager is in a drain state, it also performs an MQDISC call.

Deleting local dynamic queues

When a temporary local dynamic queue is closed, the queue is deleted, along with any messages that may still be on it, regardless of the options parameter. This is true even if uncommitted MQGET, MQPUT, or MQPUT1 calls, issued using this or another handle, are outstanding against the queue; uncommitted updates that are lost do not cause the unit of work of which they are a part to fail.

After either a temporary or permanent local dynamic queue is deleted, any call (other then a CLOSE QUEUE statement) that attempts to refer to that queue fails with reason code MQRC_Q_DELETED.

When a CLOSE QUEUE statement is issued to delete a permanent local dynamic queue, a security check is made to ensure that the user identifier is authorized to delete the queue.

No check is made when a temporary local dynamic queue is deleted.

Reusing dynamic queue names

After you issue a CLOSE QUEUE DELETE or CLOSE QUEUE DELETE PURGE statement for a queue name, you can reuse the queue name. For example, to reuse the dynamic queue name, CCA1, issue the following statements:

CLOSE QUEUE CCA1 DELETE_PURGE OPEN QUEUE CCA1 DYNAMICQNAME=XNAME MODEL=XMODEL

MQ/204 CLOSE statement and the QUEUE keyword

MQ/204 has an upward compatibility issue that is caused by supporting the keyword QUEUE on CLOSE statements. If you have a Model 204 file or group named QUEUE and you issue the SOUL CLOSE statement with it, this might conflict with the CLOSE QUEUE statement, because the FILE and GROUP keywords are optional on SOUL CLOSE statements.

To address this issue, the parsing of the CLOSE statement identifies the case of a file or group named QUEUE. If CLOSE is followed by the keyword QUEUE, the system looks ahead for a token following the word QUEUE:

If...	The statement is assumed to be...
Token is found	MQ/204 CLOSE QUEUE statement.
No token is found after the word QUEUE	CLOSE for a file or group named QUEUE.

Note: If the MQ/204 feature is not linked in, CLOSE statement parsing is unaffected.

MODIFY QUEUE statement

Function

Alters the current default option(s) for an open queue for the issuing user.

Syntax

MODIFY QUEUE {%variable | name | external_qmanager:external_queue} {[option...] [?%variable...]}

Where

• Queue to operate on is specified as:

Queue as...	Specifies
%variable	Queue name
name	Literal without quotation marks
external_qmanager:external_queue	External name of a queue manager that contains the remote queue to process and the external name of the remote queue

• option is one or more of the following options. See MQ/204 options for commands and statements for a full discussion of each option:
  • ACCEPT_TRUNCATED_MSG or NO_ACCEPT_TRUNCATED_MSG
  • ALL_MSGS_AVAILABLE or NOT_ALL_MSGS_AVAILABLE (default)
  • CONTEXT
  • EXPIRY
  • FAIL_IF_QUIESCING or NO_FAIL_IF_QUIESCING
  • FORMAT
  • LOGICAL_ORDER or NOT_LOGICAL_ORDER (default)
  • MSGTYPE
  • PERSISTENT or NOT_PERSISTENT
  • PERSISTENCE_AS_Q_DEF
  • SYNCPOINT or NO_SYNCPOINT
  • PRIORITY or PRIORITY_AS_Q_DEF
  • REPLY_QMGR
  • REPLY_QUEUE
  • REPORT
  • WAIT or NO_WAIT
  • WAIT_TIME
• ?%variable specifies option(s) of the MODIFY QUEUE statement to compile at evaluation time. For more information on ?%variables, see Using runtime options.

Usage

Options that apply to MQGET, MQPUT, and MQPUT1 statements can be specified in the DEFINE QUEUE command, and defaults for MQGET and MQPUT statements can be specified in an OPEN QUEUE statement.

You can override defined options by specifying the desired options directly on an MQGET, MQPUT, or MQPUT1 statement.

If you are repeatedly overriding DEFINE QUEUE command options, you might prefer to alter the current options for an open queue using the MODIFY QUEUE statement.

MQBACK statement

Function

Backs out pending WebSphere MQ transaction(s), called SYNCPOINT update(s) by WebSphere MQ, on all queue managers or a particular queue manager. This operation is independent of Model 204 file transactions.

Syntax

MQBACK [queuemanentname | %qmvariable]

Where

queuemanentname or %qmvariable specify to back out a particular queue manager.

Usage

The MQBACK statement operates on active WebSphere MQ transactions for the issuing user only. Active WebSphere MQ transactions for other users are not affected.

An MQBACK statement without a queue manager specified backs out all active transactions for all queue managers, processing in alphabetical order by name. You can back out a particular queue manager by specifying its name as a literal without surrounding quotation marks or in a %variable.

If a failure occurs when processing multiple queue managers, the operation stops at the queue manager that had the error. You can use the $MQ_LASTQUEUEMANAGER_ENTITY function to determine which queue manager had the error.

MQCMIT statement

Function

Commits pending WebSphere MQ transactions, called SYNCPOINT update(s) by WebSphere MQ, on all queue managers or a particular queue manager. This operation is independent of Model 204 file transactions.

Syntax

MQCMIT [queuemanentname | %qmvariable]

Where

queuemanentname or %qmvariable specify to commit all updates to a particular queue manager.

Usage

The MQCMIT statement operates on active WebSphere MQ transactions for the issuing user only. Active WebSphere MQ transactions for other users are not affected.

You can limit the commit to a particular queue manager by specifying its name as a literal without surrounding quotation marks or in a %variable.

MQCMIT statement without a queue name specified commits all active transactions for all queue managers, processing in alphabetical order by name.

If a failure occurs when processing multiple queue managers, the operation stops at the queue manager that had the error. You can use the $MQ_LASTQUEUEMANAGER_ENTITY function to determine which queue manager had the error.

MQGET statement

Function

Retrieves a message from a currently open queue.

Syntax

MQGET {(image[,image]...) | %variable | BUFFER | MQ_BUFFER} [RFH2=(image | BUFFER)] [FROM] {%qvariable | entname | external_queuemanager:external_queue} [BUFLEN={%bvar | n}] [MSGLEN=%mvar] [[option...] [?%variable...]]

Where

• image or %variable or BUFFER (formerly and still accepted MQ_BUFFER) specifies the target into which the message data is placed. You can specify up to 10 images.

  If the target is...	Then...
  image	Image item READLEN is filled in with the number of bytes of message data read into the image
  %variable	Number of bytes read can be obtained with $LEN
  BUFFER (formerly and still accepted MQ_BUFFER)	Message is simply left in the Universal Buffer, where is remains intact until the next MQ/204 statement is issued
  RFH2=(image | BUFFER)	Java RFH2 header can be accommodated.

• FROM clause identifies the queue to operate on as specified:

Queue as...	Specifies...
%qvariable	Queue name
entname	Literal without quotation marks
external_qmanager:external_queue	External name of a queue manager that contains the remote queue to process and the external name of the remote queue

• BUFLEN can determine the destination size of BUFFER area in bytes, as follows:
  • If BUFLEN was specified and the size of your BUFFER area is less than BUFLEN, BUFFER area is resized to the value of BUFLEN. Otherwise BUFFER size is unchanged.
  • If BUFLEN was not specified:

  Destination byte size for...	Is...
  String %variable	Declared length of the %variable.
  Image	Maximum length of the image.
  Multiple images	Sum of the individual image sizes.

  If the size of your BUFFER area is less than the destination size, the existing BUFFER area is deleted and a new BUFFER area allocated, with a size equal to the destination size.

• option is one or more of the following options. See MQ/204 options for commands and statements for a full discussion of each option:
  • ACCEPT_TRUNCATED_MSG or NO_ACCEPT_TRUNCATED_MSG
  • ALL_MSGS_AVAILABLE_ or NOT_ALL_MSGS_AVAILABLE (default)
  • BROWSE_FIRST
  • BROWSE_MSG_UNDER_CURSOR
  • BROWSE_NEXT
  • CONVERT or NO_CONVERT
  • CORRELID=value
  • DESCRIPTOR=image
  • FAIL_IF_QUIESCING or NO_FAIL_IF_QUIESCING
  • GROUPID=%variable
  • GSTATUS=%variable
  • LOCK or UNLOCK
  • LOGICAL_ORDER or NOT_LOGICAL_ORDER (default)
  • MATCH_CORREL_ID (default) or NOT_MATCH_CORREL_ID
  • MATCH_GROUP_ID
  • MATCH_MSG_ID (default) or NOT_MATCH_MSG_ID
  • MATCH_MSG_SEQ_NUMBER
  • MATCH_MSG_TOKEN
  • MARK_SKIP_BACKOUT
  • MSGID=value
  • MSGTOKEN=%variable
  • MSG_UNDER_CURSOR
  • NEW_CORREL_ID
  • SEQUENCE=%variable
  • SYNCPOINT or NO_SYNCPOINT or SYNCPOINT_IF_PERSISTENT
  • WAIT or NO_WAIT
  • WAIT_TIME=value
  • ?%variable specifies options of the MQGET statement to compile at evaluation time.
    For more discussion of ?%variables, see Using runtime options.

Analyzing an MQGET statement

When you issue an MQ/204 MQGET statement, the WebSphere MQ MQGET is issued. WebSphere MQ places a message or part of a message in your BUFFER area and returns:

• Actual length of the message that was retrieved or partially retrieved
• Completion code and reason code that qualifies the completion code
• The length of the message is recorded as follows:

Argument or function	Is set to...
$BUFFER_USED	Length of the data retrieved into BUFFER area
$MQ_MESSAGE_LEN	Actual length of the message
MSGLEN=%mvar	Actual length of the message

• If the completion code indicates successful completion:

If the destination is...	Then...
BUFFER area	$BUFFER_POSITION is set to 1.
Anything other than BUFFER area	Message is copied from BUFFER area to the destination.
Image or images	Each READLEN is set.

$BUFFER_POSITION is set to the byte after the last byte copied.

• If the completion code indicates unsuccessful completion:
  • $STATUS is set appropriately
  • $STATUSD is set to the WebSphere MQ reason code
  • $BUFFER_POSITION is set to 1
  • No further processing is done

Using the BUFFER area

Data transfers between WebSphere MQ and Model 204 are performed via the BUFFER area. You can perform all MQ/204 operations without directly referencing the BUFFER area. However, for maximum flexibility, you can directly manipulate the contents of the BUFFER area using the following statement forms:

• MQGET BUFFER
• MQPUT BUFFER
• READ IMAGE FROM BUFFER
• WRITE IMAGE ON BUFFER

Each user thread of MQ/204 has only one BUFFER area, which is private to that thread. BUFFER area resides in a separately allocated area of memory; it does not occupy space in the user's server, nor in CCATEMP. BUFFER area is allocated automatically for you when required, and deallocated when you log off.

When an MQGET statement retrieves a message from WebSphere MQ to a %variable, image, or image list, the data is first moved from WebSphere MQ to BUFFER area, and then copied to the %variable, image, or image list. When an MQPUT or MQPUT1 statement sends a message from a %variable, image, or image list to WebSphere MQ, the data is first copied from the %variable, image, or image list to BUFFER area and then moved to WebSphere MQ.

Handling the end of a request

• Under the usual circumstances, at request end, the user's BUFFER area remains allocated but its contents are cleared.
• In an APSY subsystem with AUTOCOMMIT=NO, the user's BUFFER area remains allocated and its contents are unchanged.

Usage

Options in common with OPEN QUEUE and DEFINE QUEUE statements inherit default values from the OPEN QUEUE statement, which in turn inherits from the queue:

• If DESCRIPTOR=image is specified, the MQMD message descriptor is returned, even if the MQGET failed. However, if the MQGET failed, the contents of image might or might not be meaningful, depending on the nature of the failure.
• After a get operation with BUFFER, the data can be loaded into an image with an extension to the READ IMAGE statement. See Universal Buffer statements.
• When a local dynamic queue is deleted, any MQGET statements with the WAIT option that are outstanding against the queue are canceled and reason code MQRC_Q_DELETED is returned.

Using the browse options

On queues open for browsing only, if neither BROWSE_FIRST nor BROWSE_NEXT is specified, then the default operation of MQGET is BROWSE_FIRST on the first MQGET after the OPEN QUEUE and BROWSE_NEXT on all subsequent MQGET statements.

On queues open for both browsing and input, if neither BROWSE_FIRST nor BROWSE_NEXT is specified, then, as the MQGET statement retrieves messages, they are deleted from the queue. This is consistent with the behavior of the WebSphere MQ API.

• On get operations, the READLEN item of each image is set. If the data runs out before filling all the images, then READLEN is set to zero for the remaining images.
• If BUFLEN is specified, BUFLEN is used to limit the number of bytes retrieved from WebSphere MQ.
• MSGLEN is an output %variable; its value before the MQGET is irrelevant.

Truncated messages

Truncation of messages can occur at two different points:

• When the data is moved from WebSphere MQ to the BUFFER area ($STATUS=12):

  ($MQ_MESSAGE_LEN > $BUFFER_USED)

• When the data is copied from the BUFFER area to the destination ($STATUS=14):

  ($MQ_MESSAGE_LEN = $BUFFER_USED)

If truncation occurs when the data is moved from WebSphere MQ to the BUFFER area, the setting of the ACCEPT_TRUNCATED_MSG option determines whether or not WebSphere MQ leaves the message on the queue; or, if in browse mode, whether or not WebSphere MQ advances the browse cursor.

Error handling consideration

MQGET statement processing always retrieves the message from WebSphere MQ into the user's BUFFER area.

• If the WebSphere MQ call fails, $STATUS is set to 12, $STATUSD is set to the WebSphere MQ reason code, and the operation ends.
• If the call succeeds, the message is copied from the BUFFER area into the target: %variable, image, or image list.
• If the target is not large enough to hold the message retrieved, $STATUS is set to 14 to indicate truncation; otherwise, $STATUS is set to 0 to indicate success.

Under some circumstances, the WebSphere MQ call can fail but still return a message or part of a message. In those cases, $STATUS is set to 12, $STATUSD is set to the WebSphere MQ reason code, but the operation continues and the message is copied from the BUFFER area into the target.

If the target is not big enough to hold the message (or partial message) retrieved, $STATUS is not reset to 14, but instead retains its original value. In other words, $STATUS and $STATUSD always report the first error, and the subsequent error is not explicitly reported.

The circumstances under which a WebSphere MQ MQGET statement can fail, but still return a message or part of a message are:

WebSphere MQ reason code	Message
2079	TRUNCATED_MSG_ACCEPTED
2080	TRUNCATED_MSG_FAILED
2110-2120	Various conversion errors

If an MQGET statement returns $STATUS=12 and $STATUSD=2079, or 2080, or 2110-2120, and the target is a %variable, image or image list, then the program must determine whether the message was truncated when copied to the target. You cannot use $STATUS=14.

You can use the following after an initial error to determine if truncation also occurred.

IF ($BUFFER_POSITION LE $BUFFER_USED) THEN * We truncated moving from the buffer to the %variable * or image target ELSE * We have $BUFFER_POSITION = $BUFFER_USED + 1 * We didn't truncate moving the buffer to the %variable * or image target END IF

Note: In the case of $STATUSD=2079 or 2080, the message was truncated when moved from WebSphere MQ to the BUFFER area, but could not have been truncated again when copied from the BUFFER area to the target.

Handling an incoming message with an RFH2 header

If you expect the incoming message to contain an RFH2 header, use the RFH2=(image | BUFFER) option. You can specify an image into which the header will be copied, or you can specify BUFFER, in which case the RFH2 header is left in the BUFFER, preceding the data.

The RFH2 header, if the target is an image, is copied from the buffer to an image, but the RFH2 header is not removed from the buffer; it still precedes the data.

• If the target for the RFH2 header specified BUFFER, the RFH2 header is simply left at the beginning of the buffer.
• If the target of the data is specified as an image or %variable, the data is copied from its position behind the RFH2 header (if present) to the image or %variable.
• If the target of the data is specified BUFFER, it is left in place in the buffer behind the RFH2 header.

In all cases where the RFH2 header is involved, the buffer after the operation contains the RFH2 header followed by the data, and $BUFFER_POSITION variable has the position (=offset+1) of the data, if the data is left in the buffer, or beyond the data if the data has been copied to an image, image list or variable.

The $BUFFER_USED has the total length of RFH2 header and data.

Using RFH2 keyword with MQGET

In all cases of GET, MSGLEN is set to the length of the data received, excluding the length of the RFH2 header, if any.

GET target	RFH2 in image	RFH2 in buffer
Data in image or %variable	$BUFFER_USED set to length of RFH2 header, plus length of data. $MQ_MESSAGE_LEN set to length of data. $BUFFER_POSITION set to byte beyond last byte of data copied. RFH2 copied to image. Data copied to image or %variable.	$BUFFER_USED set to length of RFH2 header, plus length of data. $MQ_MESSAGE_LEN set to length of data.$BUFFER_POSITION set to byte beyond last byte of data copied. Data copied to image or %variable.
Data in buffer	$BUFFER_USED set to length of RFH2 header + length of data. $MQ_MESSAGE_LEN set to length of data. $BUFFER_POSITION set to first byte of data (the byte beyond the RFH2 header). RFH2 copied to image.	$BUFFER_USED set to length of RFH2 header + length of data. $MQ_MESSAGE_LEN set to length of data. $BUFFER_POSITION set to first byte of data (the byte beyond the RFH2 header).

MQPUT statement

Function

Places a message on a currently open queue.

Syntax

MQPUT {(image[,image1]...) | %variable | 'string' | BUFFER | MQ_BUFFER} [RFH2=(image | BUFFER)] [ON] {%qvariable | entname | external_qmanager:external_queue} [BUFLEN= {%bvar | n}] [[option...] [?%variable...]]

Where

• image or %variable or BUFFER (formerly and still accepted MQ_BUFFER) specifies the target into which the message data is placed. You can specify up to 10 images.

  If the target is...	Description
  Image	To swap images in and process serially. You can specify up to 10 images.
  %variable	Current value of variable.
  'string'	Literal with quotation marks.
  BUFFER (formerly, and still accepted as MQ_BUFFER)	Message is preloaded in the Universal Buffer area.
  RFH2=(image | BUFFER)	Java RFH2 header can be accommodated.

• Queue to operate on is:

Queue as...	Specifies...
%qvariable	Queue name.
entname	Literal without quotation marks.
external_qmanager:external_queue	External name of a queue manager that contains the remote queue to process and the external name of the remote queue.

• BUFLEN specifies in bytes, %bvar or n, the size of BUFFER area.
• option is one or more of the following options:
  • ACCOUNTINGTOKEN
  • APPLIDENTITYDATA=value
  • APPLORIGINDATA=value
  • CONTEXT=value or NO_CONTEXT
  • CORRELID=value
  • DESCRIPTOR=image
  • DEFAULT_CONTEXT
  • EXPIRY=value
  • FAIL_IF_QUIESCING or NO_FAIL_IF_QUIESCING
  • FEEDBACK=value
  • FORMAT=value
  • GROUPID=%variable
  • GSTATUS=%variable
  • LOGICAL_ORDER or NOT_LOGICAL_ORDER (default)
  • MSGID=value
  • MSGTYPE=value
  • PASS_ALL_CONTEXT
  • PASS_IDENTITY_CONTEXT
  • PERSISTENT or NOT_PERSISTENT
  • PERSISTENCE_AS_Q_DEF
  • PRIORITY=value or PRIORITY_AS_Q_DEF
  • PUTAPPLNAME=value
  • PUTAPPLTYPE=value
  • PUTDATE=value
  • PUTTIME=value
  • REPLY_QMGR=name
  • REPLY_QUEUE=name
  • REPORT=options
  • SEQUENCE=%variable
  • SET_ALL_CONTEXT
  • SET_IDENTITY_CONTEXT
  • SYNCPOINT or NO_SYNCPOINT
  • USERIDENTIFIER='value '
• ?%variable specifies option(s) of the MQPUT and MQPUT1 statements to compile at evaluation time.

Usage

If an MQPUT or MQPUT1 statement sends a message from a %variable, image, or image list to WebSphere MQ, the data is first copied from the %variable, image, or image list to the BUFFER area, and then copied to WebSphere MQ.

MQPUT and MQPUT1 processing

When WebSphere MQ MQPUT or MQPUT1 is issued, WebSphere MQ:

• Copies the message from the user's BUFFER area
• Returns a completion code and reason code (qualifies the completion code)

Irrespective of the completion code:

• $MQ_MESSAGE_LEN is set to the length of the message
• $BUFFER_POSITION is set to 1

If the completion code does not indicate successful completion, $STATUS is set appropriately, and $STATUSD is set to the WebSphere MQ reason code.

Usage notes for options

• Options in common with the DEFINE QUEUE command and the OPEN QUEUE statement inherit default values from the OPEN QUEUE statement, which in turn inherits from the queue.
• You can specify the following identity context options only if you also specify the SET_ALL_CONTEXT or SET_IDENTITY_CONTEXT option:
  • ACCOUNTINGTOKEN
  • APPLIDENTITYDATA
  • USERIDENTIFIER
• You can specify the following origin context parameters only if you also specify the SET_ALL_CONTEXT option:
  • APPLORIGINDATA
  • PUTAPPLNAME
  • PUTAPPLTYPE
  • PUTDATE
  • PUTTIME
• If DESCRIPTOR=image is specified, the MQMD message descriptor is returned, even if the MQPUT or MQPUT1 failed. However, if the MQPUT or MQPUT1 failed, the contents of image might or might not be meaningful, depending on the nature of the failure.
• On each MQPUT statement, the message context is set by specifying one of the following, mutually exclusive options.
  • DEFAULT_CONTEXT
  • NO_CONTEXT
  • PASS_ALL_CONTEXT
  • PASS_IDENTITY_CONTEXT
  • SET_ALL_CONTEXT
  • SET_IDENTITY_CONTEXT

  If none of the previous options is specified, WebSphere MQ applies its own default, which is DEFAULT_CONTEXT. For more information on message context see Applying date and time-stamps to messages.

Managing BUFFER area

If the message source is BUFFER area:

If...	Then...
$BUFFER_USED=0	Operation returns $STATUS=26
BUFLEN=%bvar was not specified	Message length is $BUFFER_USED
BUFLEN=%bvar was specified	Message length is the minimum of $BUFFER_USED and %lvar

If the source is anything other than BUFFER area, the source size is determined:

For	Size is...
String %variable	Current length of the %variable
Image	Maximum length of the image
Multiple images	Sum of the individual image sizes

If the size of the user's BUFFER area is less than the message length, the existing BUFFER area is deleted and a new BUFFER area allocated, with a size equal to the message length.

The message is copied from the source to the BUFFER area.

If BUFLEN=%bvar was...	Message length is...
Not specified	Source size
Specified	Minimum of the source size and %lvar

$BUFFER_USED is set to the message length.

Applying date and time-stamps to messages

Each WebSphere MQ message is associated with two origin context fields called PUTDATE and PUTTIME, which act as a date-stamp and time-stamp, respectively, when a message is posted to a queue.

When a message is put on a queue, these fields are usually filled in. Any WebSphere MQ-enabled program issuing a WebSphere MQ MQPUT statement can explicitly set values for these fields, or alternatively (and most commonly), the values can be set by the WebSphere MQ queue manager.

In MQ/204, you explicitly set values for these fields by specifying the option PUTDATE and/or PUTTIME on the MQPUT and MQPUT1 SOUL statements. The queue manager sets values for those fields, if you do not specify those options.

When a message is received from a queue, the values of these fields that were set by the message originator are passed in the WebSphere MQ message descriptor, MQMD. In MQ/204, you can obtain a copy of the message descriptor by specifying option DESCRIPTOR=imagname on the MQGET SOUL statement. The MQMD is not available to you, if you do not specify this option.

If you decide to set or inspect the values of the PUTDATE and PUTTIME fields in your own application, read the IBM manual WebSphere MQ Application Programming Reference to understand the format of these fields when their values are set by a WebSphere MQ queue manager. In particular, according to this manual:

"Greenwich Mean Time (GMT) is used for the PutDate and PutTime fields, subject to the system clock being set accurately to GMT. On OS/2, the queue manager uses the TZ environment variable to calculate GMT."

If you set PUTDATE and PUTTIME in your own applications, WebSphere MQ lets you use any date or time format, any time zone, or even invalid values. Rocket strongly recommends, however, that you adhere to the default format used by WebSphere MQ.

Handling an outgoing message with an RFH2 header

Use the RFH2 option if you want the outgoing message to include an RFH2 header.

You can specify an image from which the header will be copied, or you can specify BUFFER, in which case the RFH2 header must be at the start of the BUFFER (position = 1), ahead of the data if that is also sourced from the BUFFER.

• If the RFH2 keyword is present, the FORMAT field will be set to MQHRF2.
• If the RFH2 keyword is present, but there is no valid RFH header in the specified image or buffer, the statement will fail with $STATUS = 47.

The RFH2 header, if specified, is taken from an image and placed in the buffer, or, if BUFFER is specified, is presumed to be at position 1 in the buffer (this will be checked).

• The data, if sourced from an image or %variable, is copied to the buffer so that it immediately follows the RFH2.
• If the data is sourced from the buffer, it is presumed to follow the RFH2 (if the RFH2 header is also sourced from the buffer), or is copied so that it follows the RFH2 header (if the RFH2 header is sourced from an image).

In all cases where the RFH2 header is involved, the buffer after the operation contains the RFH2 header followed by the data.

Using RFH2 keyword with MQPUT

PUT source	RFH2 from image	RFH2 from buffer
Data from image or %variable	The RFH2 is copied to the buffer. Then the data is appended to the RFH2 header in the buffer.	The beginning of the buffer is checked for a valid RFH2 header. The data is appended to the RFH2 header in the buffer.
Data from buffer	The data is copied downwards in the buffer to make way for the RFH2 header, which is then copied to the beginning of the buffer.	The RFH2 is assumed to precede the data in the buffer. The beginning of the buffer is checked for a valid RFH2 header.

In all cases of PUT:

• $BUFFER_POSITION is ignored, and set to 1 after the operation.
• $BUFFER_USED is set to the length of RFH2 header, plus the length of data.
• $MQ_MESSAGE_LEN set to length of data.
• MSGLEN set to length of data.
• $BUFFER_POSITION set to first byte of data beyond the RFH2 header.

MQPUT1 statement

Function

Places one message on a queue that is not currently open. The MQPUT1 statement is a combination of OPEN QUEUE, MQPUT, and CLOSE QUEUE. It is the most efficient way to put a single message on a queue.

Syntax

MQPUT1 {(image [,image1]...) | %variable | 'string' | BUFFER | MQ_BUFFER} [ON] {%qvariable | entname | external_qmanager:external_queue} [option ...]

Where

• image, %variable, 'string', or BUFFER (formerly, and still accepted, MQ_BUFFER) area specified contains the message data. (See Queue security processing.)

This message source...	Specifies...
image	To swap images in and process serially. You can specify up to 10 images.
%variable	Current value of variable.
'String'	Literal with quotation marks.
BUFFER (or MQ_BUFFER) area	Message is preloaded in the Universal Buffer area.

• Queue to operate on is specified as:

Queue as...	Specifies...
%qvariable	Queue name.
entname	Literal without quotation marks.
external_qmanager:external_queue	External name of a queue manager that contains the remote queue to process and the external name of the remote queue.

• option is one or more of the options.

  Options are the same as those for MQPUT with one addition: the PASS_USER_CONTEXT option. See the list in MQPUT statement.

  Also, LOGICAL_ORDER is not a permitted option for MQPUT1.

  MQPUT1 inherits options directly from the queue, because it does its own open and is completely independent from the OPEN QUEUE statement.

Usage

• The security considerations discussed in Queue security processing apply to MQPUT1 as well.
• If the queue named in an MQPUT1 statement is already open, the statement is processed regardless; there is no error.
• On each MQPUT statement, the message context is set by specifying one of the following mutually exclusive options:
  • DEFAULT_CONTEXT
  • NO_CONTEXT
  • PASS_ALL_CONTEXT
  • PASS_IDENTITY_CONTEXT
  • SET_ALL_CONTEXT
  • SET_IDENTITY_CONTEXT

  If none of the previous options is specified, WebSphere MQ applies its own default, which is DEFAULT_CONTEXT. For more information on message context, see Applying date and time-stamps to messages.

OPEN QUEUE statement

Function

Opens a previously defined queue.

Syntax

OPEN QUEUE {%variable | entname | external_qmanager:external_queue} [[DYNAMICQNAME=%variable | literal] [MODEL=%variable | literal]] [[option...] [?%variable...]]

Where

• Queue to operate on is specified as:

  Queue as...	Specifies...
  %variable	Queue name.
  entname	Literal without quotation marks.
  external_qmanager:external_queue	External name of a queue manager that contains the remote queue to process and the external name of the remote queue.

• DYNAMICQNAME keyword value is the internal Model 204 name from a DEFINE QUEUE command of a preallocated WebSphere MQ model queue that was defined with the WebSphere MQ MQQDT_PERMANENT_DYNAMIC or MQQDT_TEMPORARY_DYNAMIC attribute. See Local dynamic queue support.

  You can specify a DYNAMICQNAME value in one of the following ways:

  • Give the fully qualified name. It will be placed in the DYNAMICQNAME field of the WebSphere MQ MQOD structure.
  • Specify a prefix of less than 33 characters for the name, followed by an asterisk (*). The queue manager generates the rest of the name.

    For example, you might want each user to use a certain prefix, or you might want to give a special security classification to queues with a certain prefix in their name.

  • Let the queue manager generate the full name. To use this method, specify an asterisk (*) in the first character position of the DYNAMICQNAME field.

  You must specify the DYNAMICQNAME and MODEL keywords together, otherwise MQ/204 issues the following message:

  M204.2516: MQ/204 OPTION ERROR: options REQUIRE options

• MODEL keyword value is the internal, Model 204 name of the model queue.

  When you specify the MODEL keyword you must also specify the DYNAMICQNAME keyword, otherwise MQ/204 issues the following message:

  M204.2516: MQ/204 OPTION ERROR: options REQUIRE options

• option is one or more of the following options. See MQ/204 options for commands and statements for a full discussion of each option:
  • ACCEPT_TRUNCATED_MSG or NO_ACCEPT_TRUNCATED_MSG
  • ALL_MSGS_AVAILABLE or NOT_ALL_MSGS_AVAILABLE (default)
  • ALLOW_PASS_ALL_CONTEXT
  • ALLOW _PASS_IDENTITY_CONTEXT
  • ALLOW_SET_ALL_CONTEXT
  • ALLOW_SET_IDENTITY_ONTEXT
  • BROWSE
  • CONTEXT
  • EXPIRY
  • FAIL_IF_QUIESCING or NO_FAIL_IF_QUIESCING
  • FORMAT
  • INPUT_AS_Q_DEF (default for local queues) or INPUT_EXCLUSIVE or INPUT_SHARED
  • LOGICAL_ORDER or NOT_LOGICAL_ORDER (default)
  • MSGTYPE
  • OUTPUT (default for remote queues)
  • PASS_USER_CONTEXT
  • PERSISTENT or NOT_PERSISTENT or PERSISTENCE_AS_Q_DEF
  • PRIORITY or PRIORITY_AS_Q_DEF
  • REPLY_QMGR
  • REPLY_QUEUE
  • REPORT
  • SAVE_ALL_CONTEXT
  • WAIT or NO_WAIT
  • WAIT_TIME
• ?%variable specifies option(s) of the OPEN QUEUE statement to compile at evaluation time. For more discussion of ?%variables, see Using runtime options.

Usage

The queue manager for the queue must already be started. If the queue is the first queue that the user is opening for a queue manager, then MQ/204 attempts to connect the user to the queue manager prior to opening the queue. This statement performs a WebSphere MQ MQOPEN operation, and manages connections to the queue managers as needed using MQCONN and MQDISC.

Simultaneous input and output are supported, as are browse and output.

MQ/204 OPEN statement and QUEUE keyword

MQ/204 has an upward compatibility issue that is caused by supporting the keyword QUEUE on OPEN statements. If you have a Model 204 file or group named QUEUE and you use the SOUL OPEN statement with it, this might conflict with the OPEN QUEUE statements, because the FILE and GROUP keywords are optional on OPEN statements.

To address this issue, the parsing of OPEN statements identifies the case of a file or group named QUEUE. If OPEN is followed by the keyword QUEUE, the system looks ahead for a token following the word QUEUE:

If...	The statement is assumed to be...
Token is found	MQ/204 OPEN QUEUE statement.
No token is found after the word QUEUE	OPEN for a file or group named QUEUE.

Note: If the MQ/204 feature is not linked in, OPEN statement parsing is unaffected.

Specifying a local dynamic queue name

The name of the model queue in the WebSphere MQ ObjDesc parameter is replaced with the name of the local dynamic queue created when the call has completed.

When a local dynamic queue is created via MQOPEN, Model 204 calls the routines to set up control blocks as if the user had entered the DEFINE QUEUE dynamic-queue command and is updated with the fully resolved name in the instances where the local dynamic queue name ended with an asterisk.

When you issue an OPEN QUEUE statement that did not create the local dynamic queue by referencing a model queue, a partially qualified name prefix cannot compile.

Opening a remote queue

You can open a remote queue with only the remote queue default option, OUTPUT, set. All other options are invalid.

Universal Buffer statements

The following statements manage the size and contents of the Universal Buffer:

• The Modify Buffer statement, formerly MODIFY MQ_BUFFER, manages the size of the Universal Buffer, and it also keeps messages or overwrites them with fill characters.
• The Read Image statement reads data until the Universal Buffer is exhausted.
• The Write Image statement loads data into the Universal Buffer prior to a PUT operation that specifies BUFFER.

See also

• MQ/204 overview
• MQ/204 architecture and environment
• MQ/204 queue management
• MQ/204 data conversion and handling
• MQ/204 messages
• MQ/204 monitoring and troubleshooting
• MQ/204 command reference
• MQ/204 and SOUL statements
• MQ/204 options for commands and statements
• MQ/204 functions reference
• MQ/204 programming