_query

_query

Query on a message queue.

Syntax
Example 1
Example 2

Syntax

CALL SEND(queueInst, '_query', etype, msgtype, header, attachlist, rc <, delivery_key;>);

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

etype C event type of received message

msgtype N message type of received message

header L delivery header list

attachlist L attachment list associated with message

rc N return code

delivery_key N (optional) delivery key

Where...	Is type...	And represents...
etype	C	event type of received message
msgtype	N	message type of received message
header	L	delivery header list
attachlist	L	attachment list associated with message
rc	N	return code
delivery_key	N	(optional) delivery key

The _query method 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. That is, the query will not return until a message is received on the queue.

The etype parameter represents the event type and will have one of the following values upon return from the query:

DELIVERY: message received.
NO_MESSAGE: no message on the queue.
ERROR: queue has been closed or deleted.
END_OF_QUEUE: end of queue.

The msgtype was set by the user when the message was sent. msgtype is surfaced on the query. This value is user-specified. 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 by using the _recv or _recvlist methods.

The header parameter is a delivery header that returns delivery information. A value of 0 may be passed in to indicate that the delivery information should not be surfaced by the query. Otherwise, header is passed into the _query as an empty SCL list. If a message event is returned, header is updated with the delivery information as a list of named items:

DESCRIPTOR: Descriptive, user-supplied text.
RESPONSE_QUEUE_NAME: User-supplied response queue name.
QUEUED_DATETIME: Queued date/time stamp.
ORIGIN_NAME: Originator's name.
SECURITY_NAME: Security name of originator.
CORRELATOR: User-supplied correlator value.

The attachlist parameter is a list of attachments that have been included with the message. A value of 0 may be passed in to indicate that the attachment list should not be surfaced by the query. In this scenario, the attachment list is never surfaced and so the attachments do not have to be received and accepted.

Otherwise, attachlist must be passed into the _query as an empty SCL list. If a message event is returned, attachlist is updated only if any attachments were included with the message. Only the attachment list is surfaced by the query; the attachments have not actually been transferred. If attachments are surfaced, actions must be taken to actually receive the attachments and to indicate that the receipt is complete. See Accepting Attachments for more information.

If an error or warning condition is encountered during the query, a non-zero return code is returned in the rc parameter. The return codes shown here are a defined set of warning or error conditions that can be checked by using the SYSRC macro, which is provided in the autocall library that is supplied by SAS Institute.

If rc is not one of the messages shown here, use SYSMSG() to determine the exact error message.

_SEREL

indicates that the query failed because the previous message (surfaced by previous query) has not been received. When a _query returns a message, no subsequent queries are allowed until the previous message is received by using the _recv or _recvlist method.

_SEATTAC

indicates that the query failed because the attachment transfer is not complete. If the previous message surfaced by the query had attachments, no subsequent queries will be allowed until _acceptAttachment and the COMPLETE flag are called to signal that attachment transfer is complete. The COMPLETE flag may be specified without an attachment list to signal that no attachments are to be received and attachment acceptance is complete:

attachlist = 0;
call send(obj, "_acceptAttachment", 
          attachlist, rc, "COMPLETE");

_SEHEADR

indicates that an invalid delivery header list was specified. If the header parameter is non-zero, it MUST be an empty SCL list so that it can be updated by the query.

_SEATTEM

indicates that the query failed because a non-empty attachment list was passed in. If attachlist is non-zero, it must be an empty SCL list.

_SEACTRM

indicates that the connection was abnormally terminated. If this return code is surfaced, the queue was abnormally closed. It must be re-opened before any subsequent processing can take place on that queue instance.

If the NOTICE queue attribute is in effect, the delivery_key parameter is required on the query. Set the delivery_key to 0 and call _query 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 (including msgtype, attachlist, and header) is returned. In addition, delivery_key will be updated. This key can be used at a later time to retrieve this message from the queue. To retrieve the actual message, _query should be called again, this time specifying the delivery_key that was returned on the initial query.

If the queue is not operating under NOTICE mode, the delivery_key parameter should not be specified.

Example 1

This example queries on a Queue instance where the queue was opened in FETCH mode and the attribute POLL is set.

header = makelist();
attachlist = makelist();
call send(queueInst, '_query', etype, msgtype,
          header, attachlist, rc);

if (etype = "DELIVERY") then do;
   if (msgtype = 1) then do;
      /* add salary information */
   end;
end;

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

Example 2

This example queries on a Queue instance where the queue was opened by using the NOTICE attribute. In this case, if the message type is 4, the application calls the query again to retrieve the actual message on the queue.

header = makelist();
attachlist = makelist();
key = 0;
call send(queueInst, '_query', etype, msgtype, 
          header, attachlist, rc, key);

if (etype eq "DELIVERY") then do;
   if (msgtype eq 4) then do;
      rc = dellist(header,'Y'); 
      rc = dellist(attachlist,'Y'); 

      header = makelist()
      attachlist = makelist();

         /*******************************/
         /* specify the key value       */
         /* returned by the initial     */
         /* query                       */
         /*******************************/
      call send(queueInst, '_query', etype, msgtype, 
                header, attachlist, rc, key);
   end;
end;

Chapter Contents
Previous
Next
Top of Page