This statement allows your user exit to "get" values from fields on a form and assign them to host variables. The user exit can then use the values in calculations, data manipulations, updates, and so on. The syntax of the GET statement follows:

EXEC IAF GET field_name1, field_name2, ...
 INTO :host_variable1, :host_variable2, ...;

where field_name can be any of the following SQL*Forms variables:

• field

• block.field

• system variable

• global variable

• host variable (prefixed with a colon) containing the value of a field, block.field, system variable, or global variable

If field_name is not qualified, it must be unique.

The following example shows how a user exit GETs a field value and assigns it to a host variable:

EXEC IAF GET employee.job INTO :new_job;

All field values are character strings. If it can, GET converts a field value to the datatype of the corresponding host variable. If an illegal or unsupported datatype conversion is attempted, an error is generated.

In the last example, a constant is used to specify block.field. You can also use a host string to specify block and field names, as follows:

set blkfld = 'employee.job';
EXEC IAF GET :blkfld INTO :new_job;

Unless the field is unique, the host string must contain the full block.field reference with intervening period. For example, the following usage is invalid:

set blk = 'employee';
set fld = 'job';
EXEC IAF GET :blk.:fld INTO :new_job;

You can mix explicit and stored field names in a GET statement field list, but not in a single field reference. For example, the following usage is invalid:

set fld = 'job';
EXEC IAF GET employee.:fld INTO :new_job;

This statement allows your user exit to put the values of constants and host variables into fields on a form. Thus, the user exit can display on the SQL*Forms screen any value or message you like. The syntax of the PUT statement follows:

EXEC IAF PUT field_name1, field_name2, ...
 VALUES (:host_variable1, :host_variable2, ...);

where field_name can be any of the following SQL*Forms variables:

• field

• block.field

• system variable

• global variable

• host variable (prefixed with a colon) containing the value of a field, block.field, system variable, or global variable

The following example shows how a user exit PUTs the values of a numeric constant, string constant, and host variable into fields on a form:

EXEC IAF PUT employee.number, employee.name, employee.job
 VALUES (7934, 'MILLER', :new_job);

Like GET, PUT lets you use a host string to specify block and field names, as follows:

set blkfld = 'employee.job';
EXEC IAF PUT :blkfld VALUES (:new_job);

On character-mode terminals, a value PUT into a field is displayed when the user exit returns, rather than when the assignment is made, provided the field is on the current display page. On block-mode terminals, the value is displayed the next time a field is read from the device.

If a user exit changes the value of a field several times, only the last change takes effect.

By calling the function SQLIEM, your user exit can specify an error message that SQL*Forms will display on the message line if the trigger step fails or on the Display Error screen if the step causes an irrecoverable error. The specified message replaces any message defined for the step.

The syntax of the SQLIEM function call is

SQLIEM (error_message, message_length);

where error_message and message_length are character and integer variables, respectively. The Oracle Precompilers generate the appropriate external function declaration for you. You pass both parameters by reference; that is, you pass their addresses, not their values. SQLIEM is a SQL*Forms function; it cannot be called from other Oracle tools.

You can use the WHENEVER statement in an exit to detect invalid datatype conversions (SQLERROR), truncated values PUT into form fields (SQLWARNING), and queries that return no rows (NOT FOUND).

The EXEC TOOLS SET statement passes values from your user exit to Oracle Forms. Specifically, it assigns the values of host variables and constants to Oracle Forms variables and items. The values are displayed after the user exit returns control to the form.

To code the EXEC TOOLS SET statement, you use the syntax

EXEC TOOLS SET form_variable[, ...]
 VALUES ({:host_variable[:indicator] | constant}[, ...]);

where form_variable is an Oracle Forms field, parameter, system variable, or global variable, or a host variable (prefixed with a colon) containing the name of one of the foregoing items.

In the following Pro*C example, your user exit passes an employee name (with optional indicator) to Oracle Forms:

EXEC SQL BEGIN DECLARE SECTION;
 ...
 char ename[20];
 short ename_ind;
EXEC SQL END DECLARE SECTION;
...
strcpy(ename, "MILLER");
ename_ind = 0;
EXEC TOOLS SET emp.ename VALUES (:ename:ename_ind);

In this example, emp.ename is an Oracle Forms block.field.

The EXEC TOOLS GET statement passes values from Oracle Forms to your user exit. Specifically, it assigns the values of Oracle Forms variables and items to host variables. As soon as the values are passed, the user exit can use them for any purpose.

To code the EXEC TOOLS GET statement, you use the syntax

EXEC TOOLS GET form_variable[, ...]
 INTO :host_variable[:indicator][, ...];

where form_variable is an Oracle Forms field, parameter, system variable, or global variable, or a host variable containing the name of one of the foregoing items.

In the following example, Oracle Forms passes an employee name from the block.field emp.ename to your user exit:

EXEC SQL BEGIN DECLARE SECTION;
 ...
 char ename[20];
EXEC SQL END DECLARE SECTION;
...
EXEC TOOLS GET emp.ename INTO :ename;

The EXEC TOOLS SET CONTEXT statement lets you save context information from one user exit call to another. SET CONTEXT names a host-language pointer variable that you can reference later in an EXEC TOOLS GET CONTEXT statement. The pointer variable points to the block of memory in which the context information is stored. With the SET CONTEXT statement, you need not declare a global variable to hold the information.

To code the EXEC TOOLS SET CONTEXT statement, use the syntax

EXEC TOOLS SET CONTEXT :host_pointer_variable
 [IDENTIFIED] BY context_name;

where the optional keyword IDENTIFIED can be used to improve readability and context_name is an undeclared identifier or a character host variable that names the context area.

In the following example, your user exit saves context information for later use:

EXEC SQL BEGIN DECLARE SECTION;
 ...
 char context1[30];
EXEC SQL END DECLARE SECTION;
...
strcpy(context1, "This is context1");
EXEC TOOLS SET CONTEXT :context1 BY my_app1;

In this example, the context name my_app1 is an undeclared identifier. Note that in C, when a char array is used as an argument, the array name is synonymous with a pointer to that array.

The EXEC TOOLS GET CONTEXT statement retrieves the value of a host-language pointer variable into your user exit. The pointer variable points to a block of memory in which context information is stored.

To code the EXEC TOOLS GET CONTEXT statement, use the syntax

EXEC TOOLS GET CONTEXT context_name INTO :host_pointer_variable;

where context_name is an undeclared identifier or a character host variable that names the context area.

In the following Pro*C example, your user exit retrieves a pointer to context information saved earlier:

EXEC SQL BEGIN DECLARE SECTION;
 ...
 char *ctx_ptr;
EXEC SQL END DECLARE SECTION;
...
EXEC TOOLS GET CONTEXT my_app1 INTO :ctx_ptr;

In this example, the context name my_app1 is an undeclared identifier.

The EXEC TOOLS MESSAGE statement passes a message from your user exit to Oracle Forms. The message is displayed on the Oracle Forms message line after the user exit returns control to the form.

To code the EXEC TOOLS MESSAGE statement, you use the syntax

EXEC TOOLS MESSAGE message_text [severity_code];

where message_text is a quoted string or a character host variable, and the optional severity_code is an integer constant or host variable. The MESSAGE statement does not accept indicator variables.

In the following Pro*C example, your user exit passes an error message and severity code to Oracle Forms:

EXEC TOOLS MESSAGE 'Bad field name! Please reenter.' 15;