QUEUE_QUERY

QUEUE_QUERY

Query on a message queue.

Syntax
QUEUE_QUERY Example 1
QUEUE_QUERY Example 2

Syntax

CALL QUEUE_QUERY(queueId, etype, msgtype,
attachFlag, rc <, deliveryKey>);

Where... Is type... And represents...

queueId N queue identifier

etype C event type of received message

msgtype N message type of received message

attachFlag N attachment flag

rc N return code

deliveryKey N (optional) delivery key

Where...	Is type...	And represents...
queueId	N	queue identifier
etype	C	event type of received message
msgtype	N	message type of received message
attachFlag	N	attachment flag
rc	N	return code
deliveryKey	N	(optional) delivery key

The QUEUE_QUERY CALL routine queries the queue for a message. If the queue was opened with the POLL attribute and there are no messages on the queue, the query will return immediately and set the event type to NO_MESSAGE. If the queue was not opened with the POLL attribute and there is no message on the queue, the query will block until an event is received on the queue.

Etype is the event type and the variable that is passed in should have a length of at least 17, so that it can be updated with any of the supported event types. Upon return, etype will have one of the following values:

DELIVERY: Message received.
NO_MESSAGE: No message on the queue.
ERROR: Queue has been closed or deleted.
END_OF_QUEUE: End of queue has been reached.

Anytime a DELIVERY entry type is returned, the user is required to call QUEUE_GETHDR to retrieve the header information before any subsequent sends or queries will be allowed for this particular queue. It should be noted that this behavior differs from the SCL interface because the SCL interface returns the header information on the query call itself.

The msgtype parameter is (optionally) set by the user when the message is sent and is surfaced on the query. When surfaced by the query, the message type can be used to determine how many and what type of parameters should be used in receiving the actual message from the QUEUE_RECV CALL routine.

The attachFlag parameter is updated upon return from the query. If the event type is DELIVERY, attachFlag indicates whether any attachments were included with the message. If attachments were included with the message, attachFlag is set to 1. Otherwise, it will be set to 0. If attachments were included with the message, the CALL routine QUEUE_COMPLETE must be called at some point to indicate that the attachment receipt is complete. Subsequent queries will be prohibited until it is called. QUEUE_COMPLETE must be called even if no attachments were actually accepted.

If an error or a warning condition is encountered during the query, a non-zero return code is returned in the rc parameter. Use the SYSMSG() function to print the message that is associated with the non-zero rc.

If the NOTICE queue attribute is in effect, the deliveryKey parameter is required on the query. Set deliveryKey to 0 and call QUEUE_QUERY followed by QUEUE_GETHDR to retrieve the header information of the next message on the queue. If there is a message on the queue, the event type will be set to DELIVERY and the header information will be returned, including msgtype. In addition, deliveryKey will be updated. This key can be used at a later time to retrieve this message from the queue. To retrieve the actual message, QUEUE_QUERY should be called again, this time specifying the deliveryKey parameter that was returned on the initial query.

If the queue was opened without the NOTICE attribute, the deliveryKey parameter should not be specified.

QUEUE_QUERY Example 1

This example queries a Queue where the queue was opened in FETCH mode that has the POLL attribute set.

call queue_query(queueId, etype, msgtype, 
                 attachFlag, rc);
if (etype = "DELIVERY") then do;
     
      /**********************************/
      /* gethdr required if DELIVERY    */
      /**********************************/
   desc = "";
   resp = "";
   dt = 0;
   corr = 0;
   origin = "";
   security = "";
   call queue_gethdr(queueId, desc, resp, 
                     dt, origin, security, 
                     corr, rc);

   if (msgtype = 1) then do; 
      /**********************************/
      /* receive parameters             */
      /**********************************/
   end;
end;

   /*************************************/
   /* no message                        */
   /*************************************/
else if (etype = "NO_MESSAGE") then do;
end;

QUEUE_QUERY Example 2

This example queries on a Queue where the queue was opened with the NOTICE attribute. If the message type is 4, then call query again to retrieve the actual message on the queue.

key = 0;
call queue_query(queueId, etype, msgtype, 
                 attachFlag, rc, key);

call queue_gethdr(queueId, desc, resp, 
                  dt, origin, security, 
                  corr, rc);

if (etype eq "DELIVERY") then do;
   if (msgtype eq 4) then do;
         /*******************************/
         /* specify key value returned  */
         /* by the initial query        */
         /*******************************/
      call queue_query(queueId, etype, msgtype, 
                       attachFlag, rc, key);
     end;
end;

Chapter Contents
Previous
Next
Top of Page