SAS Component Language Dictionary

DELNITEM

Deletes a named item from an SCL list

Category:

List

Syntax
Details
Example
See Also

Syntax

list-id=DELNITEM(list-id,name,<occurrence
<,start-index<,index<,forceup>>>>);

list-id

is the identifier of the list from which the item is to be deleted. The function returns the list identifier that is passed in. An invalid list-id produces an error condition.

Type: Numeric or List

name

is the name of the item to delete. Item names are converted to uppercase and trailing blanks are ignored when searching the list for a matching name. Thus, the names 'abc' and 'Abc' are converted to 'ABC'.

Type: Character

occurrence

is the number of the occurrence of the named item to delete. The default, 1, specifies the first occurrence of the item.

Type: Numeric

start-index

specifies where in the list to begin searching for the item. By default, start-index is 1 (the first item). If start-index is positive, then the search begins at position start-index items from the beginning of the list. If start-index is negative, then the search begins at the item specified by ABS(start-index) items from the end of the list. An error condition results if the absolute value of start-index is zero or if it is greater than the number of items in the list.

Type: Numeric

index

specifies the variable to contain the position number of the deleted item. Index must be initialized to a nonmissing value; otherwise, errors result.

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

Type: Numeric

forceup

can have one of the following values:

'Y'	specifies a case-insensitive search, which overrides the HONORCASE or NOHONORCASE list attribute.
'N'	specifies a search that uses the HONORCASE or NOHONORCASE list attribute and is the default action for lists when FORCEUP is not specified.
IGNORECASE	IGNORECASE is the alias for NOHONORCASE and is the default for a list. But you can use the SETLATTR function to set a list's attribute to HONORCASE.

Details

DELNITEM searches for a named item and deletes it from the list. Case is ignored only if forceup is 'Y'; otherwise, it searches according to the list attribute HONORCASE and NOHONORCASE.

If a list has the NOHONORCASE attribute, the case is also ignored.

If occurrence and start-index are both positive or both negative, then the search proceeds forward from the start-index item. For forward searches, the search continues only to the end of the list and does not wrap back to the front of the list. If occurrence or start-index is negative, then the search is backwards. For backward searches, the search continues only to the beginning of the list and does not wrap back to the end of the list.

DELNITEM does not make a copy of the list. The delete operation is performed in place on the list. For example, the following statement deletes the first item named app in the list identified by LISTID:

listid=delnitem(listid,'app');

When the item to be deleted is a sublist, DELNITEM deletes the item but not the sublist, because the sublist may be referenced by other SCL variables or lists.

An error condition results if

the item has the NODELETE attribute
the list has the NOUPDATE or FIXEDLENGTH attribute
the named item is not found in the list.

To check the attributes of a list or list item, use HASATTR. To change these attributes, use SETLATTR.

Example

The following code creates a list named A, adds four items to the list, and prints the list. Then it deletes the third item in the list and prints the list again.

a=makelist();
rc=insertc(a,'a',-1,'var1');
rc=insertc(a,'b',-1,'var2');
rc=insertc(a,'c',-1,'var1');
rc=insertc(a,'d',-1,'var2');
call putlist(a,'Before deleting',0);
pos=0;
rc=delnitem(a,'var1',2,1,pos);
put pos=;
call putlist(a,'After deleting',0);

The results of this program are:

Before deleting(VAR1='a'
                VAR2='b'
                VAR1='c'
                VAR2='d'
                )[5]
POS=3
After deleting(VAR1='a'
               VAR2='b'
               VAR2='d'
               )[5]

Note: [5] is the list identifier that was assigned when this example was tested and may be different each time the example is run. [cautionend]