Creating a Parameter List
You can use the following built-in subprograms to create and manipulate a
Parameter list:
Tip: Keep in mind the following when you create Parameter lists:
CREATE_Parameter_LIST is a function whose return value is the ID of the
list being created. You must assign the ID to a variable that you
declared as type PARAMLIST (an Form Builder data type).
A call to CREATE_Parameter_LIST creates a Parameter list that does not
yet contain any Parameters. To add Parameters to the list, execute the
ADD_Parameter procedure.
GET_Parameter_ATTR and SET_Parameter_ATTR can be used to get and set the
type and value of a Parameter that has been added to a Parameter list
with the ADD_Parameter built-in. Do not use these built-ins to get or
set the value of a form Parameter that was defined at design time;
instead, refer to the Parameter using bind variable Syntax or indirect
reference. GET_Parameter_LIST is a function that returns the ParamList
ID of an indicated Parameter list, similar to the FIND-* functions
available for other object types.
The following example creates a Parameter list, adds two Parameters to it, and
then passes the list to a form by way of the CALL_FORM procedure:
/*
** Declare a variable of type ParamList to store
** the Parameter list ID
*/
DECLARE
list_id ParamList;
BEGIN
/*
** Create a Parameter list named "input_params"
*/
list_id := Create_Parameter_List('input_params');
/*
** Add two Parameters to the list to pass values for each
** user-defined Parameters defined in the target form; for each
** Parameter, specify its key, type (text or data), and value
*/
Add_Parameter(list_id, 'CITY',TEXT_Parameter,'BOGOTA');
Add_Parameter(list_id, 'CATEGORY',TEXT_Parameter,'EXPORTS');
/*
** Now call the form, referencing the Parameter list ID
** in the last argument to the CALL_FORM procedure
*/
Open_Form('trade',ACTIVATE,NO_SESSION,list_id);
END;
The Default Parameter List
Each form includes a built-in Parameter list named Default.
The Default Parameter list contains all of the form Parameters that were
defined in the form at design time. For example, if you define Parameters p1,
p2, and p3 in Form A at design time, they are automatically included in the
Default Parameter list for Form A.
The Default Parameter list can be passed to a called form by including it in the
argument list of the OPEN_FORM, CALL_FORM, or NEW_FORM built-in procedures.
DECLARE
the_list PARAMLIST:= Get_Parameter_List('default');
BEGIN
Open_Form('form_B',ACTIVATE, NO_SESSION,'default');
END;
ADD_Parameter
Description
Adds Parameters to a Parameter list. Each Parameter consists of a key, its
type, and an associated value.
Syntax
PROCEDURE ADD_Parameter
(list VARCHAR2,
key VARCHAR2,
paramtype VARCHAR2,
value VARCHAR2);
PROCEDURE ADD_Parameter
(name VARCHAR2,
key VARCHAR2,
paramtype VARCHAR2,
value VARCHAR2);
Built-in Type unrestricted procedure
Enter Query Mode yes
Parameters
list or name Specifies the Parameter list to which the Parameter is assigned.
The actual Parameter can be either a Parameter list ID of type
PARAMLIST, or the VARCHAR2 name of the Parameter list.
key The name of the Parameter. The data type of the key is
VARCHAR2.
paramtype Specifies one of the following two types:
TEXT_Parameter A VARCHAR2 string literal.
DATA_Parameter A VARCHAR2 string specifying the name of a
record group defined in the current form.
When Form Builder passes a data Parameter to
Report Builder or Graphics Builder, the data
in the specified record group can substitute
for a query that Report Builder or Graphics
Builder would ordinarily execute to run the
report or display.
value The actual value you intend to pass to the called module.
If you are passing a text Parameter, the maximum length is 64K
characters. Data type of the value is VARCHAR2.
Seitenanfang
CREATE_Parameter_LIST
Description
Creates a Parameter list with the given name. The Parameter list has no
Parameters when it is created; they must be added using the ADD_Parameter
built-in subprogram. A Parameter list can be passed as an argument to the
CALL_FORM, NEW_FORM, OPEN_FORM, and RUN_PRODUCT built-in subprograms.
Syntax
FUNCTION CREATE_Parameter_LIST
(name VARCHAR2);
Built-in Type unrestricted function
Returns ParamList
Enter Query Mode yes
Parameters
name Specifies the VARCHAR2 name of the Parameter list object.
When Form Builder creates the object, it assigns it a unique ID of type
PARAMLIST. You can call the Parameter list by name or by ID in later calls to
Parameter list-related built-in subprograms.
Seitenanfang
DELETE_Parameter
Description
Deletes the Parameter with the given key from the Parameter list.
Syntax
PROCEDURE DELETE_Parameter
(list VARCHAR2,
key VARCHAR2);
PROCEDURE DELETE_Parameter
(name VARCHAR2,
key VARCHAR2);
Built-in Type unrestricted procedure
Enter Query Mode yes
Parameters
list or name Specifies the Parameter list, either by list ID or name.
The actual Parameter can be either a Parameter list ID of type
PARAMLIST, or the VARCHAR2 name of the Parameter list.
key The name of the Parameter. The data type of the key is
VARCHAR2.
Seitenanfang
DESTROY_Parameter_LIST
Description
Deletes a dynamically created Parameter list and all Parameters it contains.
Syntax
PROCEDURE DESTROY_Parameter_LIST
(list VARCHAR2);
PROCEDURE DESTROY_Parameter_LIST
(name VARCHAR2);
Built-in Type unrestricted procedure
Enter Query Mode yes
Parameters
list or name Specifies the Parameter list, either by list ID or name.
The actual Parameter can be either a Parameter list ID of
type PARAMLIST, or the VARCHAR2 name of the Parameter list.
Usage Notes:
When a Parameter list is destroyed using DESTROY_Parameter_LIST the Parameter
list handle is NOT set to NULL.
Use the GET_Parameter_LIST built-in to return the ID to a variable of the
type PARAMLIST.
Seitenanfang
GET_Parameter_ATTR
Description
Returns the current value and type of an indicated Parameter in
an indicated Parameter list.
Syntax
FUNCTION GET_Parameter_ATTR
(list VARCHAR2,
key VARCHAR2,
paramtype NUMBER,
value VARCHAR2);
FUNCTION GET_Parameter_ATTR
(name VARCHAR2,
key VARCHAR2,
paramtype NUMBER,
value VARCHAR2);
Built-in Type unrestricted procedure that returns two OUT Parameters
Enter Query Mode yes
Parameters
list or name Specifies the Parameter list to which the Parameter is assigned.
The actual Parameter can be either a Parameter list ID of type
PARAMLIST, or the VARCHAR2 name of the Parameter list.
key The VARCHAR2 name of the Parameter.
paramtype An OUT Parameter of type NUMBER. The actual Parameter you
supply must be a variable of type NUMBER, and cannot be an
expression. Executing the Parameter sets the value of the
variable to one of the following numeric constants:
DATA_Parameter Indicates that the Parameter's value is the
name of a record group.
TEXT_Parameter Indicates that the Parameter's value is an
actual data value.
value An OUT Parameter of type VARCHAR2. If the Parameter is a data
type Parameter, the value is the name of a record group.
If the Parameter is a text Parameter, the value is an
actual text Parameter.
For an overview of using OUT Parameters with PL/SQL procedures,
refer to the PL/SQL 2.0 User's Guide and Reference.
Seitenanfang
GET_Parameter_LIST
Description
Searches the list of Parameter lists and returns a Parameter list ID when it
finds a valid Parameter list with the given name.
You must define an variable of type PARAMLIST to accept the return value.
This function is similar to the FIND_ functions available for other objects.
Syntax
FUNCTION GET_Parameter_LIST
(name VARCHAR2);
Built-in Type unrestricted function
Returns ParamList
Enter Query Mode yes
Parameters
name Specifies a valid VARCHAR2 Parameter list name.
Seitenanfang
SET_Parameter_ATTR
Description
Sets the type and value of an indicated Parameter in an indicated
Parameter list.
Syntax
SET_Parameter_ATTR
(list PARAMLIST,
key VARCHAR2,
paramtype NUMBER,
value VARCHAR2);
SET_Parameter_ATTR
(name VARCHAR2,
key VARCHAR2,
paramtype NUMBER,
value VARCHAR2);
Built-in Type unrestricted procedure
Enter Query Mode yes
Parameters
list or name Specifies the Parameter list.
The actual Parameter can be either a Parameter list ID of
type PARAMLIST, or the VARCHAR2 name of the Parameter list.
key The VARCHAR2 name of the Parameter.
paramtype Specifies the type of Parameter you intend to pass:
DATA_Parameter Indicates that the Parameter's value is
the name of a record group.
TEXT_Parameter Indicates that the Parameter's value is an
actual data value.
value The value of the Parameter specified as a VARCHAR2 string.
Seitenanfang