MQ/204 functions reference

Overview

Functions make it possible to reply to requests that specify a reply to queue and/or a reply to queue manager, and to aid in manipulating the MQ/204 entities. Since Model 204 entity names do not have to match their external or system names, the following functions enable the user to find out the external name of a Model 204 message queue or queue manager.

$BUFFER_ functions

These SOUL functions return the current position, size, and use of the Universal Buffer for individual users:

• $BUFFER_POSITION (formerly $MQ_BUFFER_POSITION)
• $BUFFER_SIZE (formerly $MQ_BUFFER_SIZE)
• $BUFFER_USED (formerly $MQ_BUFFER_USED)

Code that uses the former function names with the MQ prefix has been retained for compatibility with previous versions.

For more information about these functions, refer to the following wiki topics:

• $Buffer_Position
• $Buffer_Size
• $Buffer_Used
• Images

$MQ_FIND_QUEUE_ENTITY function

Function

Returns the name of the queue entity that is associated with the reply to queue and reply to queue manager. You can use this function when a request message specifies a reply to queue manager and a reply to queue; these are fields in the MQMD data structure.

Alias

$MQ_FIND_Q_ENTITY

Syntax

$MQ_FIND_QUEUE_ENTITY(extqueueman | %qvariable, extqueue | %variable)

Where

• extqueueman or %qvariable is the external name of a queue manager, which can be a literal string enclosed in single quotation marks or a %qvariable.
• extqueue or %variable is the external name of a queue. which can be a literal string enclosed in single quotation marks or a %variable.

Example

%QUEUENAME = $MQ_FIND_QUEUE_ENTITY('extqueueman', 'extqueue' IF (%QUEUENAME = '') THEN PRINT 'SOME ERROR MESSAGE' or %QUEUENAME = $MQ_FIND_Q_ENTITY('extqueueman', 'extqueue') IF (%QUEUENAME = '') THEN PRINT 'SOME ERROR MESSAGE'

Usage

$MQ_FIND_QUEUE_ENTITY function determines if a queue is defined for the specified queue and queue manager combination:

• If a queue is defined, $MQ_FIND_QUEUE_ENTITY returns its name.
• If no such queue has been defined, then a 0-length string is returned.
• If multiple queue entities are mapped to the specified combination, the first one found that the user is accessing is returned, based on searching the entities in the order that they were defined.
• If the user is not accessing any of them, then the first matching entity found is returned, based on searching them in the order of definition.

$MQ_FIND_QUEUEMANAGER_ENTITY function

Function

Returns the name of the queue manager entity. Because the queue manager names are defined by the system manager, they might not be known to the application developers, who need to know them to code them on MQCMIT or MQBACK.

Alias

$MQ_FIND_QM_ENTITY

Syntax

$MQ_FIND_QUEUEMANAGER_ENTITY(queueEntname | %variable)

Where

queueEntname or %variable is the name of a queue to look up, as a literal string enclosed in single quotation marks or a %variable.

Example

%QUEUEMANAGERNAME=$MQ_FIND_QUEUEMANAGER_ENTITY('queueEntname')

or

%QUEUEMANAGERNAME=$MQ_FIND_QM_ENTITY('queueEntname')

Usage

The name of the specified queue entity is looked up:

• If the queue does not exist, a null string is returned.
• If the queue exists, the name of its queue manager is returned.

$MQ_LAST_QUEUEMANAGER_ENTITY function

Function

Returns the name of the queue manager most recently accessed.

Alias

$MQ_LAST_QM_ENTITY

Syntax

$MQ_LAST_QUEUEMANAGER_ENTITY

Example

%QUEUEMANAGERNAME=$MQ_LAST_QUEUEMANAGER_ENTITY

or

%QUEUEMANAGERNAME=$MQ_LAST_QM_ENTITY

Usage

If no queue manager has yet been accessed, the function returns a 0-length string. This is most useful after a statement that processes multiple queue managers returns an error (MQCMIT, MQBACK).

$MQ_MESSAGE_LEN function

Function

Returns the actual message length of the last MQGET from or MQPUT or MQPUT1 to WebSphere MQ.

Syntax

$MQ_MESSAGE_LEN

Where

Message length can be greater than the size of the BUFFER area (if an MQGET returned a truncated message). This is the same as the value returned in MSGLEN=%mvar on an MQGET statement.

Usage

Although WRITE IMAGE ON BUFFER changes the contents of the BUFFER area, it does not involve an interaction with WebSphere MQ, and hence does not change the value of $MQ_MESSAGE_LEN.

If...	Value of $MQ_MESSAGE_LEN is...
MQ/204 is not linked in	-1
At the start of a request	-1
At the start of a request running in an APSY subsystem with AUTOCOMMIT=NO	Same as the value at the end of the previous request (or -1, if this is the first request).
Before a user performs any MQGET or MQPUT/MQPUT1	-1
MQGET or MQPUT/MQPUT1	Set by the statement.
Other statements or commands	Unchanged.
Last message failed	0

$MQ_PENDING_UPDATES function

Function

Returns a Boolean result indicating whether a user has made SYNCPOINT updates (controlled by MQBACK and MQCMIT statements) to a specified queue manager.

Syntax

IF ($MQ_PENDING_UPDATES('queuemanEntname' | %variable)) THEN

or

IF ($MQ_PENDING_UPDATES) THEN

Where

queuemanEntname is a literal string enclosed in single quotation marks or %variable specifying the name of a queue manager.

Usage

If the user has done syncpoint gets or puts that have not yet been committed or backed out, the function returns true (1), otherwise it returns false (0).

If no argument is specified, then the Boolean result returned covers all queue managers being accessed.

$MQ_QUEUENAME function

Function

Returns the external queue name for a specified queue.

Alias

$MQ_QNAME

Syntax

%REALNAME=$MQ_QUEUENAME('queueEntname' | %variable)

Where

queueEntname is a literal string enclosed in single quotation marks or a %variable

Usage

The $MQ_QUEUENAME function can be useful for:

• Reporting errors
• Retrieving the queue name that WebSphere MQ assigned to a local dynamic queue when the input dynamicq ends with an asterisk (*) for the OPEN QUEUE statement.

$MQ_QUEUEMANAGERNAME function

Function

Returns the external queue manager name for a specified queue manager.

Alias

$MQ_QMNAME('queuemanEntname' | %variable)

Syntax

%REALNAME=$MQ_QUEUEMANAGERNAME('queuemanEntname' | %variable)

Where

queuemanEntname is a literal string enclosed in single quotation marks or a %variable.

Usage

The $MQ_QUEUEMANAGERNAME function can be useful for error reporting.

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