CLEARLIST

CLEARLIST

Clears the items from an SCL list without deleting the list and optionally clears all sublist items

Category: List

Syntax
Details
Example
See Also

Syntax

rc=CLEARLIST(list-id<,recursively>);

rc

indicates whether the operation is successful:

0	successful
0	not successful

Type: Numeric

list-id

is the identifier of the list that contains the items to clear. An invalid list-id produces an error condition.

Type: Numeric or List

recursively

indicates whether to recursively clear all the list's sublists as well as all sublists of its sublists.

`'N'`	Sublists are not cleared. (This is the default.)
`'Y'`	All sublists are cleared.

Type: Character

Details

CLEARLIST clears all the items from the SCL list identified by list-id. The list is not deleted, but its length is reduced to 0. If recursively is 'Y', then all the list's sublists, including sublists of sublists, are also cleared.

CAUTION:: Before you clear a list recursively, make sure it is not needed by other parts of the SCL program. The recursively option clears all of a list's sublists, even if they are referenced in other SCL lists or by other SCL variables.

An error condition results if

the list has the NOUPDATE or FIXEDLENGTH attribute.
any item in the list (or in its sublists, if recursively is 'Y') has the NODELETE attribute.
recursively is 'Y', and any sublist has the NOUPDATE or FIXEDLENGTH attribute.
list-id is a component or class identifier.

If an error condition results, no further items or sublists are cleared.

Example

Clear all sublists from an existing list identified by MYLIST without deleting items that are not sublists:

   /* Copy the list.  */
cp=copylist(mylist);
  /* Clear the entire list, including sublists  */
  /* that also appear in CP.                    */
rc=clearlist(mylist,'Y');

   /* Copy the old list data.  */
   /* Sublists have been cleared.  */
mylist=copylist(cp,'N',mylist);

   /* Delete the copied list. */
rc=dellist(cp);

See Also

Chapter Contents
Previous
Next
Top of Page