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:
$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.