putform Statement—Transfer Data to the Form

The putform statement transfers data into simple fields on a form. The dynamic version allows you to do this using values determined at run time.

Formname must identify a declared form (see the addform or forminit statement descriptions). You can specify formname using a quoted or unquoted character string literal or program variable. If you use putform in a display block, omit formname: the current form is assumed.

In the non-dynamic version, the list of fieldnames identifies the fields into which values are placed. The fields must be simple fields which are not derived fields. (Use the loadtable, insertrow, and putrow statements to transfer data into table field columns.) You can specify express fieldname using a quoted or unquoted character string or a program variable. Similarly, value can be either a literal or a variable. A field and the value assigned to it must have compatible data types. (See your host language companion guide for information about compatible data types.)

There are two ways to assign a null value to a field: (1) specify the field's associated value as the key word null, or (2) use an indicator variable. Using an indicator variable enables the user or program to decide at run time whether to place a null in the field. See your query language reference guide for descriptions of Indicator variables.

When you execute a dynamic putform, the field names and values found in the specified descriptor_name are used. The descriptor_name identifies an SQL Descriptor Area (SQLDA), a host language structure allocated at run time. See your query language reference guide and your host language companion guide for information about the SQLDA. (The dynamic usage of putform is not available with QUEL.)

Each field that receives new values has its change variable set to 0.

A validation check is not automatically performed when a value is assigned to a field. To check that the value assigned is valid according to the current specification for the form, use validate Statement—Validate Fields.

Place data from a constant and a program variable into the form empform.

Place data from the database into the current form.

...
exec frs activate menuitem 'GetNext';
exec frs begin;
    exec sql fetch cursor1 into :namevar, :salvar;
    exec frs putform (ename = :namevar,
                      sal = :salvar);
exec frs end;

Place a null into a field using the null constant.

exec frs activate menuitem 'NewOrder';
exec frs begin;
     . . .
     exec frs putform (description = null);
     . . .
exec frs end;

Use an indicator variable to provide the run time potential to put a null into a field.

exec frs activate menuitem 'Invoice';
exec frs begin;
    . . .

    /* Display salesperson for invoice if any */
    exec frs putform (salesperson =
                               :name:indicator_var);
    . . .
exec frs end;

Using dynamic statements, retrieve data from a database and display it on a form for the user to browse. (The cursor and the putform statement use the same SQLDA.)

exec frs describe form :form_var into sqlda;
...
exec sql declare csr cursor for stmt;
exec sql open csr for readonly;
loop until no more rows
    exec sql fetch csr using descriptor sqlda;
    exec frs putform :form_var using
        descriptor sqlda;
    exec frs sleep 4;
end loop;
exec sql close csr;