_query

_query

Query on a specific connection.

Syntax
Example

Syntax

CALL SEND(cnctionInst, '_query', etype, msgtype, header, attachlist, rc);

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

etype C type of event received

msgtype N message type of received message

header L delivery header list

attachlist L attachment list

rc N return code

Where...	Is type...	And represents...
etype	C	type of event received
msgtype	N	message type of received message
header	L	delivery header list
attachlist	L	attachment list
rc	N	return code

When _query is invoked on a Cnction instance, only events received on this specific connection are returned. This is different behavior than the _query method that is invoked on a station instance, which listens for events on all connections.

etype will have one of the following values when returned from the query:

DISCONNECT: Disconnect event received on this connection. The cnctionInst must be opened again (_open) before any subsequent sends, receives, or queries will be allowed.
MESSAGE: Message received.
ABORT: Abort event received.

The msgtype parameter is set by the user when the message is sent and 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 when using the _recv or _recvlist methods.

The header parameter is an SCL list that returns delivery information. A header value of 0 indicates that the delivery information should not be surfaced by the QUERY. Otherwise, header must be an empty SCL list. If a message event is returned, header is updated with the delivery information.

The attachlist parameter is a list of attachments that have been included with the message. An attachlist value of 0 indicates 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. If non-zero, attachlist must be an empty SCL list. If a message event is returned, attachlist will be updated only if any attachments were received along with the message. If attachments are surfaced, actions must be taken to receive the attachments and to indicate that the receipt is complete. See Sending Attachments for more information about the receiving of attachments.

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 that are listed are a defined set of warning and 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 the rc is not one of the return codes that are listed here, use SYSMSG() to determine the exact error message.

_SEREL

This return code 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 will be allowed until the previous message is received using the _recv or _recvlist method.

_SEATTAC

This return code 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 the _acceptAttachment method is called by using the COMPLETE flag. This signals that the attachment transfer is complete. The COMPLETE flag may be specified without an attachment list to signal that no attachments are to be received and that attachment acceptance is complete.

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

_SEATTEM

This return code indicates that the query failed because a non-empty attachment list was passed. If non-zero, attachlist must be an empty SCL list.

_SEHEADR

This return code indicates that an invalid delivery header list was specified. If non-zero, header must be an empty SCL list so that it can be updated by the query.

Example

This example queries on the Cnction instance, listening for messages on this specific connection only.

   /* create empty attachment list to */
attachlist = makelist();

   /* create empty header list */
header = makelist();

   /* query on this specific connection */
call send(cnctionInst, '_query', etype, 
         msgtype, header, attachlist, rc);

if (etype = "DISCONNECT") then do;
end;

else if (etype = "MESSAGE") then do;

      /* if message type is one,        */
      /* application realizes that only */
      /* one list needs to be received  */
   if (msgtype eq 1) then do;
      list1 = makelist();
      call send(cnctionInst, '_recvlist', 
                rc, list1);
   end;

      /* if message type is two,        */
      /* application realizes that name */
      /* and age must be received       */
   else if (msgtype eq 2) then do;
      name = ''
      age = 0;
      call send(cnctionInst, '_recv', 
                rc, name, age);
      end;
end;

Chapter Contents
Previous
Next
Top of Page