MQREAD
The MQREAD function returns a message from a specified MQSeries® location (return value of VARCHAR) without removing the message from the queue.
- receive-service
- An expression that returns a value that is a built-in character
string or graphic string data type that is not a LOB. The value of
the expression must not be an empty string or a string with trailing
blanks. The expression must have an actual length that is no greater
than 48 bytes. The value of the expression must refer to a service
point that is defined in the SYSIBM.MQSERVICE table. A service point
is a logical end-point from where a message is sent or received. Service
point definitions include the name of the MQSeries queue manager and queue. For more
information about MQSeries Application
Messaging, see SQL Programming.
If receive-service is not specified or the null value, DB2®.DEFAULT.SERVICE is used.
- service-policy
- An expression that returns a value that is a built-in character
string or graphic string data type that is not a LOB. The value of
the expression must not be an empty string or a string with trailing
blanks. The expression must have an actual length that is no greater
than 48 bytes. The value of the expression must refer to a service
policy that is defined in the SYSIBM.MQPOLICY table. A service policy
specifies a set of quality-of-service options that are to be applied
to this messaging operation. These options include message priority
and message persistence. For more information about MQSeries Application Messaging, see SQL Programming.
If service-policy is not specified or the null value, DB2.DEFAULT.POLICY is used.
- correl-id
- An expression that returns a value that is a built-in character
string or graphic string data type that is not a LOB. The expression
must have an actual length that is no greater than 24 bytes. The value
of the expression specifies the correlation identifier that is associated
with this message. A correlation identifier is often specified in
request-and-reply scenarios to associate requests with replies. The
first message with a matching correlation identifier is returned.
For more information about MQSeries Application
Messaging, see SQL Programming.
A fixed length string with trailing blanks is considered a valid value. However, when the correl-id is specified on another request such as MQSEND, the identical correl-id must be specified to be recognized as a match. For example, specifying a value of 'test' for correl-id on MQRECEIVE does not match a correl-id value of 'test ' (with trailing blanks) specified earlier on an MQSEND request.
If correl-id is not specified or is an empty string or the null value, a correlation identifier is not used, and the message at the beginning of the queue is returned.
The result of the function is a varying-length string with a length attribute of 32000. The result can be null. If no messages are available to be returned, the result is the null value.
The CCSID of the result is the default CCSID at the current server.
Notes
Prerequisites: In order to use the MQSeries functions, IBM® MQSeries for IBM i must be installed, configured, and operational.
Example
- This example reads the message at the head of the queue specified
by the default service (DB2.DEFAULT.SERVICE),
using the default policy (DB2.DEFAULT.POLICY).
SELECT MQREAD () FROM SYSIBM.SYSDUMMY1 - This example reads the message at the head of the queue specified
by the service "MYSERVICE" using the default policy (DB2.DEFAULT.POLICY).
SELECT MQREAD ('MYSERVICE') FROM SYSIBM.SYSDUMMY1 - This example reads the message at the head of the queue specified
by the service "MYSERVICE", and using the policy "MYPOLICY".
SELECT MQREAD ('MYSERVICE','MYPOLICY') FROM SYSIBM.SYSDUMMY1 - This example reads the first message with a correlation id that
matches '1234' from the head of the queue specified by the service
"MYSERVICE" using the policy "MYPOLICY".
SELECT MQREAD ('MYSERVICE','MYPOLICY','1234') FROM SYSIBM.SYSDUMMY1