Chapter Contents




Message exchange between two bound session instances.



CALL SEND(cnctionInst, '_sendlist', msgtype, header, attachlist, rc <, list1,...,listn>);

Where... Is type... And represents...
msgtype N user-specified message type
header L delivery header list (or 0 if none)
attachlist L attachment list (or 0 if none)
rc N return code
list1...listn L message to send which consists of 0 or more SCL lists

The _sendlist method allows one or more SCL lists to be sent between two bound session instances. Any type of SCL list is supported (that is, named lists, unnamed lists, embedded lists, and recursive lists).

The msgtype parameter is set by the user when the message is sent and will be surfaced on the receiving side upon return from 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 using the _recvlist method.

The delivery header parameter is an SCL list that represents delivery information that is to be included. This information is surfaced on the query so it may be viewed by the receiver. If there is no information to include, header may be set to 0. Otherwise, header should be a valid SCL list, which consists of supported named items used to relay delivery information.

The attachlist parameter is an SCL list that represents a list of attachments to be sent with the message. If there are no attachments to send, a 0 should be specified. Otherwise, a valid attachment list should be identified by attachlist. This attachment list will be surfaced by the query on the receiving side. The receiving side then has the flexibility to decide which (if any) attachments to receive. See Sending Attachments for more details about the specific syntax for attachlist.

If an error or warning condition is encountered during the send, 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 below, use SYSMSG() to determine the exact error message.

This return code indicates that the send failed because the previous message (surfaced by a query) has not been received. When _query returns a message, no sends are allowed on that connection until the previous message is received by using the _recv or _recvlist method.

This return code indicates that the send failed because the attachment transfer is not complete. If the previous message surfaced by the query had attachments, no sends will be allowed on the connection until the _acceptAttachment method is called with the COMPLETE flag. This signals 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 that attachment acceptance is complete:
call send(obj, "_acceptAttachment", 
          0, rc, "COMPLETE");

This return code indicates that the send failed because a DISCONNECT is pending on this connection. If this return code is surfaced, _query should be called for this connection so that the disconnect can be received and the resources cleaned up.

This return code is a WARNING that indicates that the message was sent successfully but one or more errors were encountered during attachment transfer. See Attachment Error Handling for more details.

The list1...listn parameters are the 0 to n SCL lists to send.


This example invokes the _sendlist method on the Cnction instance to send two SCL lists that have no attachments.

   /* first list to send has 4 items    */
rc=setnitemc(namelist, "Mary Gill",  "STUDENT");
rc=setnitemc(namelist, "Jane Smith", "TEACHER");
rc=setnitemc(namelist, "Julie Jones","PRINCIPAL");
rc=setnitemc(namelist, "Bob Thomas", "COACH");

   /* second list to send is a list     */
   /* that contains two embedded lists  */
mainlist = makelist();

rc=setitemc(data1, 'WORK.ABC', 1);
rc=setitemc(data1, 'SASUSER.COMPANY', 2);
rc=setitemc(data1, 'SASUSER.LOCATION',1);

rc=setitemc(data2, 'SASHELP.BASE', 1);
rc=setitemc(data2, 'SASHELP.EIS', 2);

   /* insert the above two lists into   */
   /* mainlist                          */
mainlist=insertl(mainlist, data1);
mainlist=insertl(mainlist, data2);

   /* set message type so that the      */
   /* receiving side knows how many     */
   /* lists are to be received          */
msgtype =22;
header = 0;
attachlist = 0;

call send(cnctionInst, '_sendlist', msgtype, 
          header, attachlist, rc, namelist, 

Chapter Contents



Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.