SCL Lists

Assigning Names to SCL List Items

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. The maximum length of an SCL list item name is 255 characters. 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 item named SCL :

   /* 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

The 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:

listid=setnitemn(listid,y,'X',1,-1);

Top of Page