SAS Component Language Dictionary

SETLATTR

Sets the attributes of an SCL list or an item in a list

Category:

List

Syntax
Attribute Values for Lists and List Items
Attribute Values for Lists Only
Attribute Values for List Items Only
Details
Attribute Pairs
Using Passwords to Protect List Attributes from Modification
Example
See Also

Syntax

rc=SETLATTR(list-id,attributes<,index>);

rc

contains the return code for the operation:

0	successful
0	not successful

Type: Character

list-id

is the identifier of the list whose attributes or item attributes are set. An invalid list-id produces an error condition.

Type: Numeric or List

attributes

lists one or more attributes of the list or list item as shown in Attribute Values for Lists and List Items and Attribute Values for Lists Only. Use blanks to separate multiple attributes. Attributes for lists are ignored when you are setting list item attributes, and attributes for list items are ignored when you are setting list attributes. This enables you to create a single attribute string that you can apply both to lists and to list items.

Type: Character

index

is the position of the list item whose attributes are being modified. The position can be specified as a positive or negative number. By default, index is 1 (the first item). If index is a positive number, then the item is at position index from the beginning of the list. If index is a negative number, then the item is at position ABS(index) from the end of the list. If index is zero or omitted, then SETLATTR sets list attributes. An error condition results if the absolute value for index is zero or if it is greater than the number of items in the list.

Type: Numeric

Attribute Values for Lists and List Items

'DEFAULT': combines all the default attributes.
'DELETE': allows the list or item to be deleted. (This is a default.)
'FIXEDTYPE': prevents changes in the type of the item. See also NUMONLY and CHARONLY. For a list, prevents changes in the type of all individual items.
'NODELETE': prevents a list or list item from being deleted. List items that do not have the NODELETE attribute can be deleted from a list with this attribute. A list without this attribute can be deleted even though it contains items that have the NODELETE attribute.
'NOFIXEDTYPE': allows the type of an item to change. For a list, allows the type of each item to change as long as the list does not have the CHARONLY or NUMONLY attribute and the item does not have the FIXEDTYPE attribute. (This is a default.)
'NOUPDATE': prevents updates to the value for a list item. For a list, updates are not allowed to any item, even those with the UPDATE attribute. This enables you to make a list read-only in one step without having to make each individual item read-only.
'UPDATE': allows updates to the value of a list item. For a list, UPDATE allows updates to all items that do not have the NOUPDATE attribute. (This is a default.)

Attribute Values for Lists Only

'ANYNAMES': allows item names to be any character string, although names are always converted to uppercase and trailing blanks are removed. (This is a default.)
'CHARONLY': requires all items to have character values.
'COPY': copies the list during a recursive copy operation if the list is a sublist. (This is a default.)
'DUPNAMES': allows duplicate names in the list. (This is a default.)
'FIXEDLENGTH': prevents the list length from changing.
'HONORCASE': specifies that searches must be case-sensitive and that values for successful searches must match the case of the list item value.
'NOCHARONLY': allows items to have numeric values and list identifier values. (This is a default.)
'NOCOPY': prevents the list from being copied during a recursive copy operation if the list is a sublist. Instead, only the list identifier is copied to the target list. No recursion takes place for the list.
'NODUPNAMES': requires all item names to be unique.
'NOFIXEDLENGTH': allows the list length to change. (This is a default.)
'NOHONORCASE': allows a search of list items to match values, regardless of the case in which they are stored. (This is a default.)
'NONUMONLY': allows the list to contain character values and list identifier values. (This is a default.)
'NUMONLY': requires all items to have numeric values.
'SASNAMES': requires all items in the list to be named, and requires all names to be valid SAS names with no leading or trailing blanks.

Attribute Values for List Items Only

'ACTIVE': makes the item active in a pop-up menu that is opened by the POPMENU function. (This is a default.)
'INACTIVE': prevents the item from being active in a pop-up menu that is opened by the POPMENU function. (Users cannot select it.)
'AUTO': specifies that the item is an automatic instance variable. Refer to the online Help for SAS/AF software for more information about automatic instance variables.
'NOAUTO': specifies that the item is not an automatic instance variable.
'NOWRITE': prevents the item from being written by the SAVELIST function.
'WRITE': allows the item to be written when the list is stored via SAVELIST. (This is a default.)

Details

If index is omitted or zero, the attributes are assigned to the list. Otherwise, the attributes are assigned to the item at the position specified by index. Item attributes are attached to the items in the list, not to the position in the list, so that an item keeps its attributes after the list is rotated or reversed or after other items are inserted or deleted. That is, if you assign the NODELETE attribute to the fourth item in the list and then delete the item at position 2, the item still has the NODELETE attribute even though it is now at position 3.

If a list has the NOCOPY attribute, it is not copied if it is a sublist in a recursive call of COPYLIST. Instead, only the list identifier is copied to the target list, and no recursion takes place on the list. You can still copy a list with NOCOPY if it is the source (top-level) list.

Attribute Pairs

The attributes for lists and list items come in mutually exclusive pairs. For example, NOUPDATE designates that UPDATE is off. Setting one attribute of a mutually exclusive pair automatically turns off the other. The attribute pairs are shown in the following table.

Attribute	Complement Attribute	Applies To
ACTIVE	INACTIVE	Items
ANYNAMES	SASNAMES	Lists
COPY	NOCOPY	Lists
DELETE	NODELETE	Items and Lists
DUPNAMES	NODUPNAMES	Lists
HONORCASE	NOHONORCASE	Lists
NOCHARONLY	CHARONLY	Lists
NOFIXEDLENGTH	FIXEDLENGTH	Lists
NOFIXEDTYPE	FIXEDTYPE	Items and Lists
NONUMONLY	NUMONLY	Lists
UPDATE	NOUPDATE	Items and Lists
WRITE	NOWRITE	Items and Lists

The attributes of a list (such as CHARONLY, NUMONLY, FIXEDTYPE, and NOUPDATE) do not apply to sublists that the list contains. You must assign these attributes to the sublists if you want them to have these attributes.

Both list and item attributes are copied by COPYLIST. However, COPYLIST does not copy passwords.

Most of the list functions that alter lists or their contents are affected in some way by list attributes and item attributes. See the documentation for the individual functions to see how they are affected.

Using Passwords to Protect List Attributes from Modification

You can assign a password to list attributes, which enables you to protect them. The password is stored with the list and must be supplied in subsequent SETLATTR statements in order to modify either list attributes or item attributes. The password is specified as PASSWORD=password in the attribute string. The password may not contain any blanks, but case is significant. For example, the passwords frobble and FROBBLE are different.

The following statements show how to assign a password:

pwd='password=grombaq';
myattr='nodelete noupdate';
rc=setlattr(mylist,myattr||' '||pwd);

If an SCL program attempts to modify the value of one item in MYLIST, the program halts, because the list has the NOUPDATE attribute. If you want to permit updates of the list again, you can execute SETLATTR as follows:

rc=setlattr(mylist,pwd ||'update');

Note: An error condition results if you attempt to alter list attributes without specifying the PASSWORD= option and password. [cautionend]

You can remove the password from a list with NOPASSWORD=. Thereafter, any SCL program can change attributes or set the password. Either of the following statements removes the previously set password from the list identified by MYLIST:

rc=setlattr(mylist,'no'||pwd);

rc=setlattr(mylist,'nopassword=grombaq');

You must supply the correct password in order to remove a password that was previously set.

Example

The NODELETE list attribute means that the list itself cannot be deleted with DELLIST. The NODELETE item attribute indicates that an item cannot be deleted from the list regardless of the item's type. The following statements show this distinction:

a=makelist(3);
b=makelist();
   /*  Set 3rd item in A to B.  */
a=setiteml(a,b,3);
   /* Give list B the NODELETE attribute. */
   /* DELLIST(b) will be an error.            */
rc=setlattr(b,'NODELETE');
   /* Give the 3rd item in A the      */
   /* NODELETE attribute.              */
   /* DELITEM(a, 3) will be an error.  */
rc=setlattr(a,'NODELETE',3);
   /* Move B to the second item in the list */
   /* and set the third item with 0.        */
a=setiteml(a,b,2);
a=setitemn(a,0,3);
   /* Remove B from list A,          */
   /* but B still exists.            */
   /* DELITEM(a,2) will be an error now. */
a=delitem(a,2);

See CLEARLIST and DELLIST for more information about the DELETE and NODELETE attributes.