SAS Component Language Dictionary

SAVELIST

Stores SCL list items in a SAS catalog entry or in an external file

Category:

List

Syntax
Type Options
Details
Example
See Also

Syntax

sysrc=SAVELIST(type,target,list-id<,attr-list-id<,description>>;

sysrc

contains the return code for the operation:

0	successful
0	not successful

Type: Numeric

type

specifies the type of file or data source named in source and one or more options to use:

'CATALOG<(options)>': saves text in a SAS catalog entry.
'FILE<(options)>': saves text in an external file that is named in target.
'FILEREF<(options)>': saves text in an external file that is identified by a fileref named in target.

Type: Character

The available options are described in Type Options. Separate multiple options with blanks. For example, when you save a list to a catalog entry, the first character of each item is assumed to be a carriage-control character, because FILLIST puts a carriage control in the first character of each item when it fills a list. If a list was not filled with FILLIST and does not have a carriage-control character as the first character, the first character of text is lost in each item of the list saved with SAVELIST. For lists of this type, use CATALOG(ADDCC) to add a carriage-control character as the first character in each list item.

target

is the name of the catalog entry, external file, or fileref in which the list items are stored. For catalog entries, this must be a four-level name (libref.catalog.entry-name.entry-type).

Type: Character

list-id

contains the identifier of the list that contains the items to be stored in a SAS file or external file. An invalid list-id produces an error condition. For text catalog entries, the first character in each item in the list contains the FORTRAN carriage-control character: 1 means that a new page starts with this line.

Type: Numeric or List

attr-list-id

contains the identifier of the list to fill with text attribute information when type is CATALOG. An error condition results if attr-list-id is not a valid list identifier.

Type: Numeric

description

is the text of a catalog entry description. This argument is ignored if the value for type is FILE or FILEREF. (The description is displayed in the catalog directory.)

Type: Character

Type Options

ADDCC: adds a default carriage-control character. Used with type FILE, FILEREF, and CATALOG and with catalog entry types LOG, OUTPUT, and SOURCE. If you use ADDCC and STRIPCC together, then both options are ignored.
APPEND: attempts to open the external file in APPEND mode and appends text from the list to the external file. Used with type FILE or FILEREF.
PRINT: designates an external file as a PRINT file (uses host carriage-control characters). Used with type FILE or FILEREF.
STRIPCC: removes carriage-control characters. Used with type FILE, FILEREF, and CATALOG and with catalog entry types LOG, OUTPUT, and SOURCE. If you specify STRIPCC, then carriage-control characters are ignored and default carriage control is used. If you use both STRIPCC and ADDCC, then both options are ignored.
TRIM: trims trailing blanks. Used with type FILE, FILEREF, and CATALOG and with catalog entry types LOG, OUTPUT, and SOURCE.

Details

SAVELIST stores the items from an SCL list into a SAS catalog entry or an external file.

When type is CATALOG and you specify LOG, SOURCE, or OUTPUT as the entry-type of target, SAVELIST assumes that the first character of each item is a carriage-control character, because the default behavior of FILLIST for these entry types is to put a carriage-control character in the first item of list items when it creates a list. Therefore, if the items in the list identified by list-id do not have a carriage-control character as the first character, then save the list to a SOURCE entry using the ADDCC option. That will add a default (' ') carriage-control character as the first character in each line of text that is written to the SOURCE entry.

When type is CATALOG and you specify SLIST as the entry-type of target, the list -- including names, list attributes, and item attributes -- can be re-created with the FILLIST function, although the list identifiers will be different. The lists that you save with SAVELIST can persist across SAS sessions if you save them in a permanent catalog.

When a list is stored into any file type other than an SLIST entry, each item in the list identified by list-id must be a character string. Each string is stored as a separate line of text. When type is CATALOG and the entry type of target is LOG, OUTPUT, or SOURCE and a value is specified for attr-list-id, the attribute list items must also contain text. See the description of FILLIST for a description of the text attribute specifications. If the value for attr-list-id is omitted or is 0, then no attributes are stored with the catalog entry. Any value specified for attr-list-id is ignored when a list is stored in an external file or in an SLIST catalog entry.

When SAVELIST writes a list, an item that has the NOWRITE attribute is not written to the file. This is useful for placing temporary run-time values into a list that should not be written to the file because of its transient nature. For example, if you place table identifiers in lists to be saved with SAVELIST and restored with FILLIST in another task or another SAS session, the table identifiers become invalid. Thus, use SETLATTR to set the NOWRITE attribute on that list item.

(Do not confuse text attributes such as color and highlight with list attributes as specified with SETLATTR.) To check the attributes of a list or list item, use HASATTR. To change attributes, use SETLATTR.

Example

Perform operations similar to copying a list recursively with COPYLIST(mylistid,'Y'):

   /* Assume that the catalog WORK.TEMP exists: */
rc=savelist('catalog','work.temp.mylist.slist',
   mylistid);
newlistid=makelist();
rc=fillist('catalog','work.temp.mylist.slist',
   newlistid);
rc=delete('work.temp.mylist.slist','catalog');