Oracle Forms Developer – Form Builder Reference, Volume 1

CLEAR_LIST built-in
Description
Clears all elements from a list item. After Form Builder clears the list, the list will contain only one
element (the null element), regardless of the item’s Required property.
Syntax
PROCEDURE CLEAR_LIST
(list_id ITEM);
PROCEDURE CLEAR_LIST
(list_name VARCHAR2);
Built-in Type unrestricted procedure
Enter Query Mode yes
Parameters
list_id Specifies the unique ID that Form Builder assigns when it creates the list
item. Use the FIND_ITEM built-in to return the ID to an appropriately
typed variable. The data type of the ID is ITEM.
list_name The name you gave to the list item when you created it. The data type of
the name is VARCHAR2.
Usage Notes
• Do not use the CLEAR_LIST built-in if the Mapping of Other Values property is defined and there
are queried records in the block. Doing so may cause Form Builder to be unable to display records
that have already been fetched.
For example, assume that a list item contains the values A, B, and C and the Mapping of Other Values
property is defined. Assume also that these values have been fetched from the database (a query is
open). At this point, if you clear the list with CLEAR_LIST, an error will occur because Form Builder
will attempt to display the previously fetched values (A, B, and C), but will be unable to because the
list was cleared.
Before clearing a list, close any open queries. Use the ABORT_QUERY built-in to close an open
query.
Note: The block status is QUERY when a block contains queried records. The block status is
CHANGED when a block contains records that have been either inserted or updated (queried records
have been modified).
CLEAR_LIST restrictions
• For a Poplist or T-list-style list item, CLEAR_LIST will not clear the default value element or the
other values element from the list if they do not meet the criteria specified for deleting these
elements with DELETE_LIST_ELEMENT.
41