getform Statement—Transfer Data into Program Variables
This statement transfers data from the form into program variables.
Syntax
Non-dynamic version:
getform [formname]
(variable[:indicator_var] = fieldname
{, variable[:indicator_var] = fieldname})
Dynamic version:
getform [formname]
using [descriptor] descriptor_name
Description
The getform statement transfers data from simple fields on the specified form into program variables. (You can transfer data from table field columns using the getrow and unloadtable statements.) Formname must specify a declared form (see the addform and forminit statements) that has data in its fields. You can specify formname using a quoted or unquoted character string or host string variable.
Getform does not return operators entered into forms in query mode; for example, if the user enters >1000, getform returns 1000. To obtain the operator (>), you must use the getoper statement.
If you do not specify a formname, getform must be syntactically within a display block, and the current form is assumed.
Fieldname must identify a field on the specified form. You can specify fieldname using a quoted or unquoted character string literal or as a program variable. The variable associated with the field must have a data type compatible with the field's data type. (See your host language companion guide for information about compatible data types.)
You must include the indicator variable if the field is nullable. If the retrieved data is null, the indicator variable is set to -1. (If the retrieved data is null and an indicator variable is not present, Ingres returns an error.)
Using an indicator variable also enables your application to detect string truncation. When the retrieved character string is larger than the variable to which it is assigned, the string is truncated. In such instances, if an indicator variable is present, it is set to an integer indicating the full, untruncated length of the character string.
The dynamic version of the getform statement transfers data from the specified form to variables pointed at and described by descriptor_name. Descriptor_name identifies an SQLDA (SQL Descriptor Area), a host language structure allocated at run time. (The actual structure name is not required to be SQLDA and can be differently defined by the program.)
You must describe the form and allocate the variables pointed at by the SQLDA before you can issue a dynamic getform statement. Read the SQL Reference Guide and your host language companion guide for information about the structure, allocation, and use of the SQLDA.
Note: The dynamic version of the getform statement is unavailable in QUEL. For dynamic behavior in QUEL use the param statement. See the QUEL Reference Guide.
Getform validates the fields before retrieving the values. If a field contains invalid data, a runtime error is displayed and the user variable is not updated. However, execution flow is unaffected.
Examples—getform statement:
Example 1:
Place data from the ename and sal fields of form empform into program variables.
exec frs getform empform (:namevar = ename,
:salvar = sal);
Example 2:
Place data from the field specified by the variable fieldvar in the form specified by the variable formvar, into the variable namevar.
exec frs getform :formvar (:namevar = :fieldvar);
Example 3:
Place data from the current form into a database table. Within a display block, the form name need not be specified.
...
exec frs activate menuitem 'Add';
exec frs begin;
exec frs validate;
exec frs getform (:namevar = ename,
:salvar = sal);
exec sql insert into employee (ename, sal)
values (:namevar, :salvar);
exec frs end;
Example 4:
Get values from a nullable field.
exec frs getform empform (:spousevar:indicator_var
= spouse);
Example 5:
Using a dynamic getform statement, retrieve a query operator and a salary value from the sal field, displayed in query mode.
sqlda.sqld = 2;
sqlda.sqlvar(1).sqltype = INT;
sqlda.sqlvar(1).sqllen = 4;
sqlda.sqlvar(1).sqldata = address(op_var);
sqlda.sqlvar(1).sqlind = null;
sqlda.sqlvar(1).sqlname = 'GOP(sal)';
sqlda.sqlvar(2).sqltype = -FLOAT;
sqlda.sqlvar(2).sqllen = 8;
sqlda.sqlvar(2).sqldata = address(sal_var);
sqlda.sqlvar(2).sqlind = address(null_ind);
slqda.sqlvar(2).sqlname = 'sal';
exec frs getform :form_var using descriptor sqlda;