23/23 FORMS - Parameter List

Introduction

With the previous versions of Forms, the way to pass values between different forms was using Global variables. This technique you should have already known by previous topics in this book. Now there is a flexible way to pass values between forms. You can create your own parameter list programmatically and pass it as an argument in a CALL_FORM or OPEN_FORM.

You should use the following built-ins functions and procedures to manipulate parameter lists:

CREATE_PARAMETER_LIST: creates an empty parameter list.

ADD_PARAMETER: adds a parameter to an existing parameter list.

GET_PARAMETER_LIST: determines if there is already a parameter list with the same name as the one you are trying to create.

DESTROY_PARAMETER_LIST: destroys a parameter list.

DELETE_PARAMETER: deletes a parameter in the parameter list.

Hands-on

Let’s illustrate the use of these built-ins functions and procedures. Suppose that you need to pass the customer ID from one form (CUSTOMERS) to another form (PORTFOLIO); you use the CUSTOMER ID to query all customers’ stocks portfolio in the portfolio table in the called form. You can execute the following code from a “WHEN-BUTTON-PRESSED” trigger or even from a menu item:

DECLARE

param_list_id ParamList; -- Define an object of type paramlist

BEGIN

param_list_id := GET_PARAMETER_LIST(‘my_parameter');

-- Test if the parameter list already exists.

IF NOT ID_NULL(param_list_id) THEN

DESTROY_PARAMETER_LIST(param_list_id);

END IF;

param_list_id := CREATE_PARAMETER_LIST('my_parameter');

ADD_PARAMETER(param_list_id, 'p_customer_id', TEXT_PARAMETER, :ID);

CALL_FORM('c:', NO_HIDE, DO_REPLACE, NO_QUERY_ONLY, param_list_id);

END;

It is important to remember that you must declare an object of type ParamList. Also, all parameters that you define in the Object Navigator belong to the default parameter list. You can also pass the default parameter list to another form if you need. For example:

WHEN-BUTTON-PRESSED

BEGIN

CALL_FORM('employee', NO_HIDE, DO_REPLACE, NO_QUERY_ONLY, 'default');

END;

When passing the default parameter list as well as any other parameter list, make sure that every parameter exists with the same name in the called form.

Now let us see how we can access the value of parameter in a called form? To access the value of a parameter in a called form, you must create the following triggers in the employee form: WHEN-NEW-FORM-INSTANCE at the form level

In addition, create a parameter with the same name as the parameter that you are passing in the parameter list. If you fail to do this, the application returns an error message that the parameter does not exist.

The following is an example of a trigger needed to do a query based on the

value passed in the parameter list when the form 'portfolio’ is called:

WHEN-NEW-FORM-INSTANCE

BEGIN

-- Obtain the name of the calling form

form_name := GET_APPLICATION_PROPERTY(CALLING_FORM);

IF form_name IS NOT NULL THEN

-- Execute a query if the form is a called form

EXECUTE_QUERY;

ELSE

:parameter.p_customer_id := 10;

END IF;

END;

Also you can create a parameter by executing the following steps:

1) In the Object Navigator, select the Parameters node and choose

NAVIGATOR->CREATE.

2) Bring up the properties of the parameter and set the properties as needed.

For example, Set the Datatype, Default Value, and Name of the parameter.

3) To access the value of the parameter, add the reserved word PARAMETER as a prefix to the parameter name. If you need to assign a value to a parameter, use a regular assignment statement such as:

temp_test := :parameter.test; -- assigns the value of the parameter to test

:parameter.test := 'value'; -- assigns a value to the parameter test

Questions:

Q: How do you pass a parameter from one form to another?

Q: Describe the following build-in procedures and functions:

CREATE_PARAMETER_LIST

ADD_PARAMETER

GET_PARAMETER_LIST

DESTROY_PARAMETER_LIST

DELETE_PARAMETER