The MQRECEIVE function returns a
message from the MQSeries® location specified by receive-service, using
the quality of service policy service-policy.
Performing this operation removes the message from the queue associated
with receive-service. If the correl-id is specified, then the first message with a matching correlation
identifier will be returned. If correl-id is not
specified, then the message at the head of the queue will be returned.
The data type of the result is VARCHAR (32000). If no
messages are available to be returned, the result is the null value.
Syntax
>>-MQRECEIVE---------------------------------------------------->
>--(--+----------------------------------------------------------+--)-><
'-receive-service--+-------------------------------------+-'
'-,--service-policy--+--------------+-'
'-,--correl-id-'
The schema is DB2MQ for non-transactional message
queuing functions, and DB2MQ1C for one-phase commit transactional
MQ functions.
Function parameters
- receive-service
- A string containing the logical MQSeries destination from which the message is received. If
specified, the receive-service must refer
to a Service Point defined in the DB2MQ.MQSERVICE table. A service
point is a logical end-point from which a message is sent or received.
Service points definitions include the name of the MQSeries Queue Manager and Queue. If receive-service is not specified, the DB2.DEFAULT.SERVICE
is used. The maximum size of receive-service is 48 bytes.
- service-policy
- A string containing the MQSeries Service Policy to be used in the handling of this
message. If specified, service-policy must
refer to a policy defined in the DB2MQ.MQPOLICY table. A service policy
defines a set of quality of service options that should be applied
to this messaging operation. These options include message priority
and message persistence. If service-policy is not specified, the default DB2.DEFAULT.POLICY is used. The maximum size
of service-policy is 48 bytes.
- correl-id
- A string containing an optional correlation identifier to be associated
with this message. The correl-id is often
specified in request and reply scenarios to associate requests with
replies. If not specified, no correlation id will be specified. The
maximum size of correl-id is 24 bytes.
Authorization
One of the following authorities is required
to execute the function:
- EXECUTE privilege on the function
- DATAACCESS authority
- DBADM authority
- SQLADM authority
Default PUBLIC privilege
In a non-restrictive
database, EXECUTE privilege is granted to PUBLIC when the function
is automatically created.
Examples
Example 1: This example receives
the message at the head of the queue specified by the default service
(DB2.DEFAULT.SERVICE),
using the default policy (DB2.DEFAULT.POLICY).
VALUES MQRECEIVE()
Example 2: This example receives the message
at the head of the queue specified by the service "MYSERVICE" using
the default policy (DB2.DEFAULT.POLICY).
VALUES MQRECEIVE('MYSERVICE')
Example 3: This example receives the message
at the head of the queue specified by the service "MYSERVICE" using
the policy "MYPOLICY".
VALUES MQRECEIVE('MYSERVICE','MYPOLICY')
Example 4: This example receives 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".
VALUES MQRECEIVE('MYSERVICE','MYPOLICY','1234')