|SAS Component Language: Reference|
SCL supports a feature called named lists, which enable you to assign a name to each item in a list, or only to some list items. The name can be any SCL character string, not just character strings that are valid SAS column names, unless the list has the SASNAMES attribute. As with SAS names, list item names can contain mixed-case characters--for example, EmployeeLocation.
If you search a list for which the HONORCASE attribute has not been set, then SCL will uppercase the item names for the search operation only. The item names are not permanently changed to uppercase.
You can use the GETNITEMC, GETNITEMN, GETNITEML, and GETNITEMO functions to access named list items by their name rather than by their position. This feature enables you to vary the contents of the list according to your application needs without having to keep track of where a particular item is located in a list. To assign or replace values that are associated with a name, use the SETNITEMC, SETNITEMN, SETNITEML, or SETNITEMO function. To delete an item by its name, use the DELNITEM function.
Item names in a list do not have to be unique unless the NODUPNAMES attribute has been assigned to the list. Item names are stored as they are entered. If the list has the HONORCASE attribute (the default), then 'abc' and 'Abc' are two different item names. Otherwise, if the list has the IGNORECASE attribute, these names are duplicate names.
To search for an item by its name, you use the NAMEDITEM function. If the list has the HONORCASE attribute, this function searches for item names that match the case specified for the search unless you use the FORCE-UP attribute for NAMEDITEM. This attribute overrides the HONORCASE attribute and converts the item name to upper case for the search. However, the case of the item name is converted only for the search; the name continues to be stored as you entered it. The function ignores trailing blanks when searching for a matching name. If a list contains duplicate names, the search function finds the first occurrence of the name unless you have specified a different occurrence of the item for the search. By inserting a new item at the beginning of the list, you can ``hide'' a previous value because a named search will find your new item first by default. To restore the previous value, simply delete the new item from the list.
You can freely mix named items with unnamed items in a list. You can also use both kinds of indexing (by name or by index) in any list, regardless of how the list was created or whether all, some, or no items have names.
|Indexing a Named Item by its Position|
To find the index of a named item in a list, use the NAMEDITEM function. This enables you to access an item later by its index in the list, which is a faster search. However, searching by index is not safe if the index of the item might change between the time you find the index and the time you use the index.
The following statement replaces the value associated
with the first occurrence of the item named
ACME in the list NUMBERS
with the value
(201) 555-2263. These statements do not modify the
list if the name
ACME is not found:
i=nameditem(numbers,'Acme'); if i>0 then rc=setitemc(numbers,'(201) 555-2263',i);
|Determining or Replacing an Item's Name|
To replace the name of an item, use the NAMEITEM function. You can also use NAMEITEM when you want to find out the name of an item but you do not want to change the item's name.
|Finding an Occurrence of a Name|
In general, the
functions that enable you to access a list item
by its name operate on the first occurrence of the name by default. However,
you can combine the optional arguments occurrence, start-index, and ignore-case
to refer to items other than the first occurrence. Occurrence enables you to specify the number of the occurrence of a named
item that you want to find. For example, a value of three references the
third occurrence, and a value of ten references the tenth occurrence. The
following example demonstrates how to find the indexes of the first and third
/* default occurrence is 1 */ first=nameditem(listid,'SCL'); /* Find the third occurrence */ third=nameditem(listid,'SCL',3);
|Specifying Where the Search for an Item Starts|
start-index argument specifies
the position in the list in which to begin the search for a named item. The
default is 1, which starts the search at the first item in the list. If the
value for start-index is negative, then the search
starts at position ABS(start-index) from the
end of the list and searches toward the front of the list. For example, a start-index of -1 references the list's last item, whereas
a start-index of -2 references the list's
second-to-last item. Thus, to change the value of the last occurrence of
a list item named
X to the value y, you
can use a statement like the following:
Top of Page
Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.