SAS Component Language Dictionary

FILLIST

Fills an SCL list with text and data

Category:

List

Syntax
Type Options
Details
	External Files
	SLIST Catalog Entries
	LIST Catalog Entries
	SOURCE, OUTPUT, and LOG Catalog Entries
Examples
	Example 1: Reading Text and Attributes Into a List
	Example 2: Performing a Recursive List Copy
	Example 3: Reading and Printing Out Data and Attributes from LIST Entries
See Also

Syntax

sysrc=FILLIST(type,source,list-id<,attr-list-id<,desc-var-name>>);

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)>': specifies that source names a catalog entry.
'FILE<(options)>': specifies that source names an external file.
'FILEREF<(options)>': specifies that source names a fileref that has been assigned to an external file.
'SASICONS<(numbers)>': specifies the numbers for icons that are provided with SAS software. (When you specify SASICONS, source is ignored. Specify a null argument '' for source.)
'SEARCH': specifies catalog names in the current search path (source is ignored). Use the SEARCH function to define the search path, or specify '' for source.

The available options are described inType Options. Separate multiple options with blanks. For example, to fill a list from an external print file and to strip carriage-control characters, specify FILE(PRINT STRIPCC) for type.

Type: Character

source

is a catalog entry (specified as libref.catalog.entry.type), an external file, or a fileref.

Type: Character

list-id

contains the identifier of the list to fill. An invalid list-id produces an error condition.

Type: Numeric or List

attr-list-id

contains the identifier of the list to fill with text attribute source information when type is CATALOG and the entry type is LOG, OUTPUT, or SOURCE. An invalid attr-list-id produces an error condition.

Type: Numeric

desc-var-name

is the name of the variable in which you want to store the text of the catalog entry description. This argument is ignored if type is FILE or FILEREF.

Note: This parameter is an update parameter. See Input, Output, and Update Parameters for more information. [cautionend]

Type: Character

Type Options

ADDCC: adds default host carriage-control characters. Used with type FILE, FILEREF, and CATALOG and with catalog entry types LOG, OUTPUT, and SOURCE.
PRINT: designates an external file as a PRINT file (uses the host carriage-control characters). Used with type FILE and FILEREF.
STRIPCC: removes carriage-control characters. Used with type FILE, FILEREF, and CATALOG and with catalog entry types LOG, OUTPUT, and SOURCE.
TRIM: trims trailing blanks. Used with type FILE, FILEREF and CATALOG and with catalog entry types LOG, OUTPUT, and SOURCE. TRIM is used if you want to use FILLIST to fill a list with items that contain trailing blanks and then remove the blanks so that they will not be displayed in a pop-up menu that is produced by POPMENU.

Details

Each line of text in the source file is placed in a separate character item of the list identified by list-id. The number of items in the filled list is determined by the number of lines of text. All SCL lists must be created with MAKELIST before you call FILLIST. FILLIST automatically clears the lists before it fills the lists.

Data from the external file or catalog entry cannot exceed the maximum length of a character value in an SCL list item, which is 32,766 characters.

External Files

If type is FILE, then source is the name of an external file. If type is FILEREF, then source is a SAS fileref. FILLIST reads each record of the file into a separate character item.

SLIST Catalog Entries

If type is CATALOG and the catalog entry type in source is SLIST, then the types of the items in the filled list are determined by the saved list, and they may be character strings, numbers, or other lists. All item attributes and names are duplicated, as are the list attributes. However, the list identifier numbers are different.

LIST Catalog Entries

If type is CATALOG and the catalog entry type in source is LIST, FILLIST reads the contents of a SAS/AF LIST entry into list-id. The list contains either all numeric or all character items, depending on the contents of the LIST entry. The attribute list contains the following named values, which are all character type:

INFORMAT: is the SAS informat that was specified in the LIST entry.
FORMAT: is the SAS format that was specified in the LIST entry.
MESSAGE: is the error message that was specified in the LIST entry.
CAPS: reports whether the LIST entry has the CAPS attribute. Y or N.
SORTED: reports whether the LIST entry has the SORT attribute. Y or N.
NOHONORCASE: reports whether the LIST entry has the CASE-INSENSITIVE attribute. Y or N.
TYPE: is the TYPE attribute that was specified in the LIST entry. N for numeric, C for character.
JUST: is the JUST attribute that was specified in the LIST entry. L, R, C, or N for left, right, center, or none.

SOURCE, OUTPUT, and LOG Catalog Entries

If type is CATALOG and the entry type is OUTPUT, LOG, or SOURCE, the first character in each list item contains a FORTRAN carriage-control character: 1 means that a new page starts with this line. See STRIPCC above. ADDCC converts all carriage-control characters to ' ' (blank).

If type is CATALOG and the entry type is OUTPUT, LOG, or SOURCE, then any text attributes (such as color and display attributes), are read one element per line into attr-list-id, if it is specified. These attributes consist of a character item for each line of text. Each character item contains one character for each character in the line, plus a prefix descriptor character. The prefix character is T for a title line, H for a header line, or D for a data line. The other characters represent the text display attributes and color, as described in the tables below.

Do not confuse text attributes (color, display, and so on) with list attributes that are specified with SETLATTR.

The attribute list that is filled by FILLIST contains one item for each line of text from the SAS catalog entry. The attribute string for each line has one character for each character of text. Each attribute character represents the SAS windowing environment color and display attribute. Not all display devices support all colors.

Color attributes are represented as follows:

Color	Value	Color	Value
BLUE	'10'x	WHITE	'70'x
RED	'20'x	ORANGE	'80'x
PINK	'30'x	BLACK	'90'x
GREEN	'40'x	MAGENTA	'A0'x
CYAN	'50'x	GRAY	'B0'x
YELLOW	'60'x	BROWN	'C0'x

Display attributes are represented as follows:

Attribute	Value
NONE	'00'x
HIGHLIGHT	'01'x
UNDERLINE	'02'x
BLINK	'04'x
REVERSE	'08'x

You combine the color and display attributes by adding them together. For example, you can specify GREEN UNDERLINE by adding '40'x to '02'x to yield '42'x. To assign GREEN UNDERLINE to the first 4 characters of a string, you could use a statement like:

str = '42424242'x;

See also STRATTR, which creates attribute strings.

You can use GETITEMC or POPC to retrieve an item from this list.

An error condition is produced if

either list has the NOUPDATE, NUMONLY, or FIXEDLENGTH attribute
any item in either list cannot be removed because it has the NODELETE attribute.

Examples

Example 1: Reading Text and Attributes Into a List

Suppose you have an OUTPUT entry named FINANCE.REPORTS.MONTHLY.OUTPUT that contains the text "Net:($45,034)" on line 45. The text Net: is white with no highlight attributes, whereas the text ($45,034) is red reverse. The following statements read the text and attributes and print line 45.

INIT:
   text_list=makelist();
   attr_list=makelist();
   rc=fillist('CATALOG',
      'FINANCE.REPORTS.MONTHLY.OUTPUT',
      text_list,attr_list);
   text=substr(getitemc(text_list,45),2);
   attr=substr(getitemc(attr_list,45),2);
   len=compress(put(2*length(text), 4.));
   attrhex=putc(attr,'$HEX'||len||'.');
   put attr;
   put text;
   put attrhex;
return;

Note: SUBSTR removes the carriage-control characters. [cautionend]

This example produces the following output:

ppppp(((((((((
Net: ($45,034)
7070707070282828282828282828

The line of text consists of five white characters with no attributes, represented by the attribute value '70'x, followed by nine red reverse characters, represented by '28'x.

Example 2: Performing a Recursive List Copy

The following statements perform an operation similar to a recursive list copy:

rc=savelist('CATALOG','WORK.TEMP.MYLIST.SLIST',
   mylist);
new_list=makelist();
rc=fillist('CATALOG','WORK.TEMP.MYLIST.SLIST',
   new_list);
rc=delete('WORK.TEMP.TEMP.SLIST','CATALOG');

Lists that are saved in a permanent catalog with SAVELIST can persist across SAS sessions.

Example 3: Reading and Printing Out Data and Attributes from LIST Entries

Consider two LIST entries: SASUSER.DATA.A.LIST, which contains some character data, and SASUSER.DATA.DATES.LIST, which contains formatted numeric data. The following program reads the data and attributes from these entries and uses PUTLIST to print the results.

INIT:
items=makelist();
attrs=makelist();
rc=fillist('catalog','sasuser.data.a.list',
   items,attrs);
call putlist(items,'A.LIST contents:',0);
call putlist(attrs,'A.LIST attributes:',0);
rc=fillist('catalog','sasuser.data.dates.list',
   items,attrs);
call putlist(items,'DATES.LIST contents:',0);
call putlist(attrs,'DATES.LIST attributes:',0);
rc=dellist(items);
rc=dellist(attrs);
return;

The output for these entries may look like this:

A.LIST contents:('THIS     '
                 'IS       '
                 'A        '
                 'LIST     '
                 'ENTRY    '
                 'WITH     '
                 'EIGHT    '
                 'ITEMS    '
                 )[5]
A.LIST attributes:(INFORMAT=''
                   FORMAT=''
                   MESSAGE=''
                   CAPS='Y'
                   SORTED='N'
                   NOHONORCASE='Y'
                   TYPE='C'
                   JUST='L'
                   )[7]
DATES.LIST contents:(1765
                     11162
                     11813
                     12072
                     )[5]
DATES.LIST attributes:(INFORMAT='DATE.'
                       FORMAT='DATE.'
                       MESSAGE=''
                       CAPS='Y'
                       SORTED='Y'
                       NOHONORCASE='N'
                       TYPE='N'
                       JUST='L'
                       )[7]

Note: [5] and [7] are the list identifiers that were assigned when this example was run and may be different each time the example is run. [cautionend]