MQRECEIVE

The MQRECEIVE function returns a message from a specified MQSeries® location and removes the message from the queue.

>>-MQRECEIVE(-+----------------------------------------------------------+-)-><
              '-receive-service--+-------------------------------------+-'     
                                 '-,--service-policy--+--------------+-'       
                                                      '-,--correl-id-'

The schema is DB2MQ.

The MQRECEIVE function returns a message from the MQSeries location specified by receive-service, using the quality-of-service policy defined in service-policy. Performing this operation removes the message from the queue that is associated with receive-service.

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 DB2MQ.MQSERVICE table. A service point is a logical end-point from which a message is sent or received. A service point definition includes the name of the MQSeries queue manager and the name of the queue. See MQSeries Application Messaging Interface for more details.

If receive-service is not specified or is the null value, DB2.DEFAULT.POLICY 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 DB2MQ.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. See MQSeries Application Messaging Interface for more details.

If service-policy is not specified or is 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. Only those messages with a matching correlation identifier are returned.

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 correl-id must be specified the same to be recognized as a match. For example, specifying a value of 'test' for correl-id for this function does not match a correl-id value of 'test ' (with trailing blanks) specified earlier on an MQSEND request.

If correl-id is not specified, is an empty string, or is 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 of length attribute of 4000. The result can be null. The result is null if no messages are available to return.

The CCSID of the result is the system CCSID that was in effect at the time that the MQSeries function was installed into DB2®.

Example 1: Retrieve the message from beginning of the queue specified by the default service (DB2.DEFAULT.SERVICE), using the default policy (DB2.DEFAULT.POLICY).

   SELECT MQRECEIVE()
     FROM SYSIBM.SYSDUMMY1;

The message at the beginning of the queue is returned as VARCHAR(4000) and is deleted from the queue. The queue is specified by the default service and using the default policy.

Example 2: Retrieve the first message from the beginning of the queue specified by the service MYSERVICE, using the default policy, DB2.DEFAULT.POLICY.

   SELECT MQRECEIVE('MYSERVICE')
     FROM SYSIBM.SYSDUMMY1;

The message at the beginning of the queue is returned as VARCHAR(4000) and is deleted from the queue. The queue is specified by the service MYSERVICE using the default policy, DB2.DEFAULT.POLICY. End of change

Example 3: Retrieve the message from the beginning of the queue specified by the service MYSERVICE, using the policy MYPOLICY.

   SELECT MQRECEIVE('MYSERVICE','MYPOLICY')
     FROM SYSIBM.SYSDUMMY1;

The message at the beginning of the queue is returned as VARCHAR(4000) and the message is deleted from the queue. The queue is specified by the service MYSERVICE using the policy MYPOLICY. End of change

Example 4: Retrieve the first message with a correlation identifier that matches '1234' from the beginning of the queue specified by the service MYSERVICE, using the policy MYPOLICY.

   SELECT MQRECEIVE('MYSERVICE','MYPOLICY','1234')
     FROM SYSIBM.SYSDUMMY1;

The first message with CORRELID of '1234' from the beginning of the queue is returned as VARCHAR(4000) and is deleted from the queue. The queue is specified by MYSERVICE and using MYPOLICY.