_query

_query

Generic query on any connection.

Syntax
Example

Syntax

CALL SEND(stationInst, '_query', etype, msgtype, header, attachlist, cnctionInst, 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

cnctionInst N Cnction instance on which the event was received

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
cnctionInst	N	Cnction instance on which the event was received
rc	N	return code

Used for direct messaging, the _query listens on a station instance for incoming events on any connection.

The event type etype is returned with one of the following values:

CONNECT: connect event received
DISCONNECT: disconnect event received
MESSAGE: message received
ABORT: abort event received.

The msgtype parameter can be set by the user when the message is sent and is surfaced on the query. This value is user-specified, and when surfaced by the query, the user can use the message type to determine how many and what type of parameters should be used in receiving the actual message when using the _recv and _recvlist methods.

The header parameter is an SCL list 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 must be passed into the _query as 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. 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. If the value is not 0, attachlist must be an empty SCL list. If a message event is returned, attachlist is updated only if 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.

The cnctionInst parameter is set upon return. This indicates the Cnction instance on which the event was received.

If a CONNECT event is received, a successfully opened instance of the Cnction class is returned in cnctionInst. This Cnction instance can now be used to send, receive or query on the connection.
If a MESSAGE event is received, cnctionInst will be the Cnction instance on which the message was received.
If a DISCONNECT or ABORT event is received, cnctionInst will be the Cnction instance on which the disconnect or abort was received.

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

If the parameter rc is not one of the parameters that are listed below, 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 that is surfaced by the query had attachments, no subsequent queries will be allowed until the _acceptAttachment method is called 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(cnctionInst, "_acceptAttachment", 
          0, rc, "COMPLETE");

_SEATTEM

This return code indicates that the query failed because a non-empty attachment list was passed in. 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, the header must be an empty SCL list so that it can be updated by the query.

Example

This example queries on the station instance by listening for messages on any connections.

   /*************************************/
   /* create empty attachment list to   */
   /* pass into query                   */
   /*************************************/
attachlist = makelist();
call send(stationInst, '_query', etype, 
          msgtype, attachlist, cnctionInst, rc);

if (etype = "CONNECT") then do;
      /**********************************/
      /* send message back on new       */
      /* connection instance            */
      /**********************************/
   msgtype = 5;
   call send(cnctionInst, '_send', 
             msgtype, 0, 0, rc, "Return string");
end;

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

else if (etype = "MESSAGE") then do;
      /**********************************/
      /* will have meaning to some user */
      /**********************************/
   if (msgtype = 1) then 
      ...more data lines... 
end;

Chapter Contents
Previous
Next
Top of Page