POPULATE_LIST Built-in
Description
Removes the contents of the current list and populates the list with the values
from a record group. The record group must be created at runtime and it must
have the following two column (VARCHAR2) structure:
Column 1: Column 2:
the list label the list value
Syntax
PROCEDURE POPULATE_LIST
(list_id ITEM,
recgrp_id RecordGroup);
PROCEDURE POPULATE_LIST
(list_id ITEM,
recgrp_name VARCHAR2);
PROCEDURE POPULATE_LIST
(list_name VARCHAR2,
recgrp_id RecordGroup);
PROCEDURE POPULATE_LIST
(list_name VARCHAR2,
recgrp_name VARCHAR2);
Built-in Type unrestricted procedure
Enter Query Mode yes
Parameters
- list_id
-
- Specifies the unique ID that Oracle Forms 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.
-
- recgrp_id
-
- Specifies the unique ID that Oracle Forms assigns when it creates the
record group. The data type of the ID is RecordGroup.
-
- recgrp_name
-
- The VARCHAR2 name you gave to the record group when you created it.
Usage Notes
- Do not use the POPULATE_LIST Built-in if the Mapping of Other Values property
is defined and there are queried records in the block. Doing so may cause
Oracle Forms 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
populate the list using POPULATE_LIST, an error will occur because Oracle Forms
will attempt to display the previously fetched values (A, B, and C), but will
be unable to because these values were removed from the list and replaced
with new values.
- Before populating a list, close any open queries. Use the ABORT_QUERY Built-in
to close an open query.
POPULATE_LIST Restrictions
POPULATE_LIST returns error FRM-41337: Cannot populate the list from the record
group if:
- the record group does not contain either the default value element or the
other values element and the list does not meet the criteria specified for
deleting these elements with DELETE_LIST_ELEMENT. Refer to the restrictions
on DELETE_LIST_ELEMENT for more information.
- the record group contains an other value element but the list does not meet
the criteria specified for adding an other value element with ADD_LIST_ELEMENT.
Refer to the restrictions on ADD_LIST_ELEMENT for more information.
POPULATE_LIST Example
/*
** Built-in: POPULATE_LIST
** Example: Retrieves the values from the current list item
** into record group one, clears the list, and
** populates the list with values from record group
** two when a button is pressed.
** Trigger: When-Button-Pressed
*/
BEGIN
RETRIEVE_LIST(list_id, 'RECGRP_ONE');
CLEAR_LIST(list_id);
POPULATE_LIST(list_id, 'RECGRP_TWO');
END;