SAS/CONNECT User's Guide

Accepting Attachments

When a _query surfaces a message that includes attachments, the attachlist parameter will be non-empty, and it will mirror the attachment list specified on the sending side, with a few changes. First, the receiving application is not made aware of any options that may have been used to subset the data (for example, KEEP, EXCLUDE, WHERE, and data set options). Also, each attachment will have the additional named item ATTACH_ID that is used to identify which attachments are to be accepted or received.

When the _query surfaces the message and its attachment list, the attachments have not yet been transferred.

Note: The receiver is responsible for deciding which attachments to receive by invoking the _acceptAttachment method that has a valid value for the attachlist parameter. This method initiates the transfer of the specified attachments. If no attachments are to be accepted, set attachlist to 0 when calling the _acceptAttachment method. [cautionend]

The accept method supports the COMPLETE flag, which indicates that attachment acceptance is complete. This is an optional flag that does not have to be set on every call to _acceptAttachment. However, whenever a query surfaces a non-empty attachment list, _acceptAttachment with the COMPLETE flag must be called at some point to signal the completion of attachment receipt. No subsequent queries and/or sends will be allowed until the COMPLETE flag is set on the accept method.

When building the attachment list on the sending side, the main attachment list parameter contained a separate list for each attachment. The same is required by _acceptAttachment. The attachlist parameter is required to be an SCL list that contains other SCL lists; one for each attachment to accept.

Data Set Attachments

A list to accept a SAS data set must include the following required named items:

OUTLIB: The value of this named item should be the output library name.
OUT: The value of this named item should be the output member name.
ATTACH_ID: The value of this named item should be a numeric identifier that indicates which attachment to receive. This is the attachment id that is surfaced by the query in the attachlist parameter.

Example

When the query returns with a message and its attachment list, the attachlist parameter contains three attachments.

List one, first item in attachlist:

named item TYPE has a value of DATASET
named item MEMNAME has a value of NAMES
named item LIBNAME has a value of SASUSER
named item ATTACH_ID has a value of 1.

List two, second item in attachlist:

named item TYPE has a value of CATALOG
named item MEMNAME has a value of CONNECT
named item LIBNAME has a value of SASHELP
named item ATTACH_ID has a value of 2.

List three, third item in attachlist:

named item TYPE has a value of DATASET
named item MEMNAME has a value of EMPLOYEES
named item LIBNAME has a value of WORK
named item ATTACH_ID has a value of 3.

This example accepts two of the three attachments by making two separate calls to the accept method. First, the contents of the third attachment in attachlist (which is actually the first item) is received by specifying ATTACH_ID equal to 3. This transfers the input data set WORK.EMPLOYEES into the output data set WORK.ABC. The second attachment to be received is identified by specifying ATTACH_ID equal to 1. This transfers the input data set SASUSER.NAMES into the output data set SASUSER.NAMES.

alist = makelist();
att1  = makelist();
rc = setnitemn(att1, 3, "ATTACH_ID");
rc = setnitemn(att1, "WORK", "OUTLIB");
rc = setnitemn(att1,"ABC", "OUT");
alist = insertl(alist, att1, -1);

   /***************************************/
   /* Accept this attachment but do not   */
   /* set the COMPLETE flag as there are  */
   /* additional ones to accept.          */
   /***************************************/
call send(Obj, '_acceptAttachment', 
          alist, rc);

rc = dellist(alist, 'Y');
alist = makelist();
att2 = makelist();
rc = setnitemn(att2, 1, "ATTACH_ID");
rc = setnitemn(att2, "SASUSER", "OUTLIB");
rc = setnitemn(att2,"NAMES", "OUT");
alist = insertl(alist, att2, -1);

   /***************************************/
   /* The COMPLETE flag is set to         */
   /* indicate attachment acceptance is   */
   /* complete after the second attachment */
   /* is transferred.                     */
   /***************************************/
call send(Obj, '_acceptAttachment', alist,
          rc, "COMPLETE");

Catalog Attachments

To receive catalog attachments, the following named items are required:

OUTLIB: The value of this named item should be the output library name.
OUT: The value of this named item should be the output member name.
ATTACH_ID: The value of this named item should be a numeric identifier that indicates which attachment to receive. This is the attachment id that is surfaced by the query in the attachlist parameter.

Example

When the query returns with a message and its attachment list, the attachlist parameter contains the following three attachments:

List one, first item in attachlist:

named item TYPE has a value of CATALOG
named item MEMNAME has a value of BASE
named item LIBNAME has a value of SASHELP
named item ATTACH_ID has a value of 1.

List two, second item in attachlist:

named item TYPE has a value of DATASET
named item MEMNAME has a value of WORK
named item LIBNAME has a value of TEMP
named item ATTACH_ID has a value of 2.

List three, third item in attachlist:

named item TYPE has a value of CATALOG
named item MEMNAME has a value of INFOCAT
named item LIBNAME has a value of WORK
named item ATTACH_ID has a value of 3.

This example accepts two of the three attachments by making one call to the accept method. The first attachment to receive is identified by setting ATTACH_ID equal to 3. This transfers catalog WORK.INFOCAT to the output catalog, SASUSER.INFOCAT. The second attachment to receive is identified by setting ATTACH_ID equal to 1. This transfers catalog SASHELP.BASE to the output catalog LOCAL.TASKC.

alist = makelist();
att1 = makelist();
rc = setnitemn(att1, 3, "ATTACH_ID");
rc = setnitemn(att1, "SASUSER", "OUTLIB");
rc = setnitemn(att1,"INFOCAT", "OUT");

att2 = makelist();
rc = setnitemn(att2, 1, "ATTACH_ID");
rc = setnitemn(att2, "LOCAL", "OUTLIB");
rc = setnitemn(att2,"TASKC", "OUT");

   /***************************************/
   /* Insert the attachment lists into    */
   /* the main attachment list, alist.    */
   /***************************************/
alist = insertl(alist, att1, -1);
alist = insertl(alist, att2, -1);

   /***************************************/
   /* The COMPLETE flag is set to         */
   /* indicate attachment acceptance is   */
   /* complete.                           */
   /***************************************/
call send(Obj, '_acceptAttachment', 
          alist, rc, "COMPLETE");

External File Attachments

To accept external file attachments, the following named items are required:

OUTFILE or OUTFILEREF: The value of the named item OUTFILE should be the physical filename of the output file. The value of the named item OUTFILEREF should be the output fileref. Only one of these should be specified.
ATTACH_ID: The value of this named item should be a numeric identifier that indicates which attachment to receive. This is the attachment id that is surfaced by the query in the attachlist parameter.

Example

When the query returns with a message and its attachment list, the attachlist parameter contains the following four attachments:

List one, first item in attachlist:

named item TYPE has a value of DATASET
named item MEMNAME has a value of NAMES
named item LIBNAME has a value of SASUSER
named item ATTACH_ID has a value of 1.

List two, second item in attachlist:

named item TYPE has a value of EXTERNAL_TEXT
named item MEMNAME has a value of /tmp/notes.txt
named item ATTACH_ID has a value of 2.

List three, third item in attachlist:

named item TYPE has a value of EXTERNAL_BIN
named item MEMNAME has a value of BINREF
named item ATTACH_ID has a value of 3.

List four, fourth item in attachlist:

named item TYPE has a value of EXTERNAL_TEXT
named item MEMNAME has a value of RLINK
named item ATTACH_ID has a value of 4.

This example accepts three of the four attachments by making one call to the accept method. The first attachment to be received is identified by specifying ATTACH_ID equal to 2. This transfers the input file /tmp/notes.txt to the output file defined by the fileref AFILE. The second attachment to be received is identified by specifying ATTACH_ID equal to 3. This transfers the input file defined by the fileref BINREF, to the output file defined by the fileref BFILE. The third attachment to be received is identified by specifying ATTACH_ID equal to 4. This transfers the input file defined by the fileref RLINK, to the output file /tmp/rlink.scr data set SASUSER.NAMES.

alist = makelist();
att1 = makelist();
rc = setnitemn(att1, 2, "ATTACH_ID");
rc = setnitemn(att1, "afile", "OUTFILEREF");
alist = insertl(alist, att1, -1);

att2 = makelist();
rc = setnitemn(att2, 3, "ATTACH_ID");
rc = setnitemn(att2, "bfile", "OUTFILEREF");
alist = insertl(alist, att2, -1);

att3 = makelist();
rc = setnitemn(att3, 4, "ATTACH_ID");
rc = setnitemn(att3, "/tmp/rlink.scr", 
               "OUTFILE");
alist = insertl(alist, att3, -1);

   /***************************************/
   /* accept attachments                  */
   /***************************************/
call send(Obj, '_acceptAttachment', alist,
          rc);


   /***************************************/
   /* acceptance complete                 */
   /***************************************/
call send(Obj, '_acceptAttachment', 0,
          rc, "COMPLETE");

Chapter Contents
Previous
Next
Top of Page