SAS/CONNECT User's Guide

Sending Attachments

To include attachments with the sending of a message, an attachment list must be built to indicate what attachments to include. Both the _send and _sendlist methods (for the Cnction and the Queue classes) use an attachlist parameter.

The attachlist parameter is an SCL list that contains other SCL lists and must contain a separate list for each attachment to include with the message. The syntax for building the attachment list is the same, whether using direct or indirect (queued) messaging.

The supported attachment types are:

Data Set
External File
Catalog
MDDB
DMDB
FDB
SQL Views

Data Set Attachments

When data set attachments are transferred, all data set attributes are cloned by default. These include label, type, passwords, encryption, index, and sort order information.

To specify a data set attachment, the following named items are required:

TYPE: The value of this named item must be "DATASET" to indicate that this is a data set attachment.
MEMNAME: The value of this named item should be the data set's member name.
LIBNAME: The value of this named item should be the data set's library name.

Additionally, there are optional named items that may be specified for data set attachments. These optional settings not only provide a means to subset the data before transfer, but they also provide a way to surface descriptive information to the receiving side. The optional named items that are supported include:

DESCRIPTION: The value of this named item is user-specified, descriptive text to accompany the attachment. This information is surfaced to the user on the receiving side and allows the user to provide specific information about this attachment.
WHERE: The value of this named item is a WHERE statement to apply to the data set. This provides a way to subset the data before transfer.
DATASET_OPTIONS: The value of this named item can be any valid data set options string. This too provides a way to subset the data before transfer.
ATTACH_VERSION: The value of this named item is a character string and the only supported value in Version 7 or Version 8 is VERSION_612. This parameter only applies to indirect messaging and only applies when sending catalog or data set attachments. If a Version 7 or Version 8 application sends a data set or a catalog attachment to a queue, a Version 6 application cannot accept them; it will fail. However, the Version 7 or Version 8 application can specify this option to indicate that the catalog or data set should be sent to the queue in Version 6 format. This way, both Version 6 and Version 7 or Version 8 applications can accept the attachment.
MAJOR_VERSION: The value of this named item is a numeric, user-specified version that will be presented to the receiver.
MINOR_VERSION: The value of this named item is a numeric, user-specified version that will be presented to the receiver.
INDEX: The value of this named item must be either N or NO. By default, the data set's index is re-created on the output data set. This named item allows the default to be overridden so that indexes are not created on the output file.

Example 1

This example specifies two data set attachments to be included with the message. The data sets are SASUSER.DATAX and WORK.ABC.

For data set SASUSER.DATAX, the required named items would be defined as:

named item TYPE has a value of DATASET
named item LIBNAME has a value of SASUSER
named item MEMNAME has a value of DATAX.

For data set WORK.ABC, the required named items would be defined as:

named item TYPE has a value of DATASET
named item LIBNAME has a value of WORK
named item MEMNAME has a value of ABC.

For both data sets, DESCRIPTION was optionally set so that more descriptive information will be surfaced to the receiver.

   /***************************************/
   /* list1 contains attachment one,      */
   /* sasuser.datax                       */
   /***************************************/
list1 = makelist();
rc = setnitemc(list1, "DATASET", "TYPE");
rc = setnitemc(list1, "DATAX", "MEMNAME");
rc = setnitemc(list1, "SASUSER", "LIBNAME");
rc = setnitemc(list1, "Tasklist dataset for 
               client application.", 
               "DESCRIPTION");

   /***************************************/
   /* list2 contains attachment two,      */
   /* work.abc                            */
   /***************************************/
list2 = makelist();
rc = setnitemc(list2, "ABC", "MEMNAME");
rc = setnitemc(list2, "WORK", "LIBNAME");
rc = setnitemc(list2, "DATASET", "TYPE");
rc = setnitemc(list2, "Playpen data.", 
               "DESCRIPTION");

   /***************************************/
   /* attachlist is the main attachment   */
   /* list. It must contain a separate    */
   /* SCL list for each attachment        */
   /***************************************/
attachlist = makelist();
attachlist = insertl(attachlist, list1, -1);
attachlist = insertl(attachlist, list2, -1);

msgtype = 25;
hdr = 0;
call send(obj, '_sendlist', msgtype, hdr,
          attachlist, rc, sendlist);

             /***  or  ***/

call send(obj, '_send', msgtype, hdr, 
          attachlist, rc, string1);

Example 2

This example illustrates the use of WHERE and DATASET_OPTIONS to subset the data before transfer.

   /***************************************/
   /* list 1 contains attachment one,     */
   /* sasuser.xx                          */
   /***************************************/
list1 = makelist();
rc = setnitemc(list1, "DATASET", "TYPE");
rc = setnitemc(list1, "XX", "MEMNAME");
rc = setnitemc(list1, "SASUSER", "LIBNAME");
rc = setnitemc(list1, "(X>10) AND (Y < 100)",
               "WHERE");
rc = setnitemc(list1, "DROP=NAMES READ=X", 
               "DATASET_OPTIONS");

attachlist = makelist();
attachlist = insertl(attachlist, list1, -1);

msgtype  = 2;
hdr = 0;

call send(cobs, '_send', msgtype, hdr, 
          attachlist, rc, Numeric1);

Catalog Attachments

SAS catalogs are another type of attachment that may be included with messages. To specify a catalog attachment, the following named items are required:

TYPE: The value of this named item must be CATALOG to indicate that this is a catalog attachment.
MEMNAME: The value of this named item should be the catalog's member name.
LIBNAME: The value of this named item should be the catalog's library name.

Additionally, there are optional named items that may be specified for catalog attachments. These optional settings provide a way to subset the catalog before transfer and to surface descriptive information to the receiving side. The optional named items that are supported include:

DESCRIPTION: The value of this named item is user-specified, descriptive text to accompany the attachment. This information is surfaced to the user on the receiving side and allows the user to provide specific information about this attachment.
SELECT: The value of this named item is a SELECT statement to apply to the catalog. This provides a way to select specific entries to include without sending the entire catalog. The value of this named item should take the form of ENTRY1.ENTRYTYPE ENTRY2.ENTRYTYPE..., for each entry to select. The select and exclude items are mutually exclusive so you cannot specify both SELECT and EXCLUDE for a given catalog attachment.
EXCLUDE: The value of this named item is an EXCLUDE statement to apply to the catalog. This provides a way to exclude specific entries so that unnecessary entries are not transferred. The value of this named item should take the form of ENTRY1.ENTRYTYPE ENTRY2.ENTRYTYPE..., for each entry to exclude. The select and exclude items are mutually exclusive so you cannot specify both SELECT and EXCLUDE for a given catalog attachment.
MAJOR_VERSION: The value of this named item is a numeric, user-specified version that will be presented to the receiver.
MINOR_VERSION: The value of this named item is a numeric, user-specified version that will be presented to the receiver.

Example

This example specifies one catalog attachment to be included with the message. The catalog is SASHELP.BASE. The required named items are

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

Optionally, DESCRIPTION is specified to provide descriptive information to the receiving side, and SELECT is specified to select specific entries to include.

   /***************************************/
   /* main attachment list                */
   /***************************************/
attachlist = makelist();

   /***************************************/
   /* build attachment one with the       */
   /* SELECT statement                    */
   /***************************************/
list1 = makelist();
rc = setnitemc(list1, "CATALOG", "TYPE");
rc = setnitemc(list1, "BASE", "MEMNAME");
rc = setnitemc(list1, "SASHELP", "LIBNAME");
rc = setnitemc(list1, "RLIST.LIST XYZ.SCL
               MAIN.FRAME", 
               "SELECT");
rc = setnitemc(list1, "A few entries 
               from base catalog.", 
               "DESCRIPTION");

   /***************************************/
   /* insert attachment one into main list*/
   /***************************************/
attachlist = insertl(attachlist, list1, -1);

msgtype = 2;
hdr = 0;
call send(cobs, '_send', msgtype, hdr, 
          attachlist, rc, "string1");

External File Attachments

External files may also be sent as attachments. To specify an external file attachment, the following named items are required:

TYPE: The value of this named item must be either EXTERNAL_TEXT or EXTERNAL_BIN. If the attachment is a text file, specify EXTERNAL_TEXT so that the appropriate translation will occur. If including a binary file as an attachment, specify EXTERNAL_BIN.
FILENAME or FILEREF: If the external file is to be referenced by a fileref, specify the named item FILEREF; its value will be the fileref that defines this file. If the external file is to be referenced by its physical filename, specify the named item FILENAME; its value will be the physical name of the file.

Additionally, there are optional named items that may be specified. These optional settings include:

DESCRIPTION: The value of this named item is user-specified, descriptive text to accompany the attachment. This information is surfaced to the user on the receiving side and allows the user to provide specific information about this attachment.
MAJOR_VERSION: The value of this named item is a numeric, user-specified version that will be presented to the receiver.
MINOR_VERSION: The value of this named item is a numeric, user-specified version that will be presented to the receiver.

Example

This example defines three external file attachments to send with the message. The first attachment is an external text file, /tmp/text.file. The required named items for this attachment are

named item TYPE has a value of EXTERNAL_TEXT
named item FILENAME has a value of /tmp/text.file

The second attachment is an external text file defined by the fileref RLINK. The required named items for this attachment are

named item TYPE has a value of EXTERNAL_TEXT
named item FILEREF has a value of RLINK.

Finally, the last attachment is an external binary file, /tmp/binary.file. The required named items for this attachment are

named item TYPE has a value of EXTERNAL_BIN
named item FILENAME has a value of /tmp/binary.file.

The optional named items that may be specified for external file attachments, which are used in this example, include DESCRIPTION and MAJOR_VERSION.

   /***************************************/
   /* LIST1 contains attachment one       */
   /***************************************/
list1 = makelist();
rc = setnitemc(list1, "EXTERNAL_TEXT", "TYPE");
rc = setnitemc(list1, "/tmp/text.file", "FILENAME");
rc = setnitemc(list1, "modified script file for unix",
            "DESCRIPTION");
rc = setnitemc(list1, 11, "MAJOR_VERSION");

   /***************************************/
   /* LIST2 contains attachment two       */
   /***************************************/
list2 = makelist();
rc = setnitemc(list2, "EXTERNAL_TEXT", "TYPE");
rc = setnitemc(list2, "RLINK", "FILEREF");

   /***************************************/
   /* LIST3 contains attachment three     */
   /***************************************/
list3 = makelist();
rc = setnitemc(list3, "EXTERNAL_BIN", "TYPE");
rc = setnitemc(list3, "/tmp/binary.file", "FILENAME");

   /***************************************/
   /* ATTACHLIST is the main attachment   */
   /* list; insert each attachment into   */
   /* main attachment list.               */
   /***************************************/
attachlist = makelist();
attachlist = insertl(attachlist, list1, -1);
attachlist = insertl(attachlist, list2, -1);
attachlist = insertl(attachlist, list3, -1);

msgtype = 22;
hdr = 0; 
call send(cobs, '_send', msgtype, hdr, 
          attachlist, rc, string1);

Utility Attachments

Utility files that are supported include files of the following types: MDDB, DMDB, FDB, and SQL Views.

To specify a utility file attachment, the following named items are required:

TYPE: The value of this named item must be either MDDB, DMDB, VIEW, or FDB to indicate the type of attachment.
MEMNAME: The value of this named item should be the member name.
LIBNAME: The value of this named item should be the library name.

Additionally, there are optional named items that may be specified for utility file attachments. These optional settings provide a way to surface descriptive information to the receiving side. The optional named items that are supported include:

DESCRIPTION: The value of this named item is user-specified, descriptive text to accompany the attachment. This information is surfaced to the user on the receiving side and allows the user to provide specific information about this attachment.
MAJOR_VERSION: The value of this named item is a numeric, user-specified version that will be presented to the receiver.
MINOR_VERSION: The value of this named item is a numeric, user-specified version that will be presented to the receiver.

Example

This example specifies two utility file attachments and one data set to be included with the message. The files are SASUSER.TESTDATA (a SAS data set), WORK.FMDDB (an MDDB file), and SASUSER.TESTVIEW (an SQL View).

The required named items for the data set SASUSER.TESTDATA are

named item TYPE has a value of DATASET
named item LIBNAME has a value of SASUSER
named item MEMNAME has a value of TESTDATA.

The required named items for the data set WORK.FMDDB are

named item TYPE has a value of MDDB
named item LIBNAME has a value of WORK
named item MEMNAME has a value of FMDDB.

The required named items for the data set SASUSER.TESTVIEW are

named item TYPE has a value of VIEW
named item LIBNAME has a value of SASUSER
named item MEMNAME has a value of TESTVIEW.

For the three data sets, DESCRIPTION was optionally set so that more descriptive information will be surfaced to the receiver.

list1 = makelist();
rc = setnitemc(list1, "DATASET", "TYPE");
rc = setnitemc(list1, "TESTDATA","MEMNAME");
rc = setnitemc(list1, "SASUSER", "LIBNAME");
rc = setnitemc(list1, 
           "Testdata in sasuser directory.",
           "DESCRIPTION");

list2 = makelist();
rc = setnitemc(list2, "FMDDB", "MEMNAME");
rc = setnitemc(list2, "WORK", "LIBNAME");
rc = setnitemc(list2, "MDDB", "TYPE");
rc = setnitemc(list2, "Playpen mddb", 
               "DESCRIPTION");

list3 = makelist();
rc = setnitemc(list3, "TESTVIEW","MEMNAME");
rc = setnitemc(list3, "SASUSER", "LIBNAME");
rc = setnitemc(list3, "VIEW", "TYPE");
rc = setnitemc(list3, "SQL view file", 
               "DESCRIPTION");

   /***************************************/
   /* ATTACHLIST is the main attachment   */
   /* list. It must contain a separate    */
   /* SCL list for each attachment        */
   /***************************************/
attachlist = makelist();
attachlist = insertl(attachlist, list1, -1);
attachlist = insertl(attachlist, list2, -1);
attachlist = insertl(attachlist, list3, -1);

msgtype = 25;
hdr = 0;
call send(obj, '_sendlist', msgtype, hdr, 
          attachlist rc, sendlist);

                 /***  or  ***/

call send(obj, '_send', msgtype, hdr, 
          attachlist rc, string1);

Chapter Contents
Previous
Next
Top of Page