describe Statement—Retrieve Descriptive Information
This statement retrieves descriptive information about a form or table field.
Syntax
For retrieving form information:
describe form formname [mode]
into descriptor_name
For retrieving table field information:
describe table formname tablename [mode]
into descriptor_name
Description
The forms describe statement is used in dynamic applications to return the data type, length, and name information about the simple fields on a form or the columns of a table field. This information, which is stored in the SQLDA, is used by dynamic forms input and output statements to set and retrieve form data.
You can issue the describe statement at any time after the form is initialized. (The forminit or addform statement initializes a form.) It is not necessary to initialize a table field to describe it, although the form which contains the table field must have been initialized.
Note: The describe statement is not available in QUEL. For dynamic behavior in QUEL use the param statement. See the QUEL Reference Guide.
Describe statements can be issued from inside a display loop even if the form described is the form being displayed.
Formname identifies the form being described and can be a quoted or unquoted string or program string variable.
Tablename identifies the table field being described and must be a table field associated with formname. Tablename can be a string, quoted or unquoted, or a program string variable.
Mode determines what subset of fields or columns is described. You can specify mode with a quoted or unquoted string or program string variable. Its value can be any of the following:
update
Specifies that the FRS returns the description of all updatable fields in a form or columns in a table field. Descriptions of derived, display-only, and query-only fields are not returned. This mode corresponds to a form or table field displayed in update or fill mode.
query
Specifies that the FRS returns the description of updatable and query-only fields in a form or columns in a table field. This mode corresponds to a form or table field displayed in query mode.
all
Specifies that the FRS returns a description of all fields in the form or columns in the table field, including those that are display-only or query-only. You can use this mode to map complete database table descriptions (such as those returned by describing the prepared statement 'select * from emp') to a form or table field.
If no mode is specified, then the mode defaults to all.
Descriptor_name is the name of an SQL Descriptor Area (SQLDA). An SQLDA is a host language structure allocated at run time whose name, if not SQLDA, is defined by the program. Part of the structure of an SQLDA is an array of sqlvar elements. After a form or table field is described, each sqlvar element contains the data type, length, and name of one of the fields in the form or columns in the table field corresponding to the specified mode. The FRS does not return hidden column names nor the internal row variables _state and _record in a table. If you want to use these variables in an application, the application must allocate a sqlvar element for each individually.
If the returned data type code indicates a table field when describing a form, the program must issue a describe table statement to collect the column information about the table field. You can issue this statement at the end of the processing or immediately with a different SQLDA.
Each host language has different considerations for the SQLDA structure; in some languages it is not defined. See the SQL Reference Guide for a complete description of the structure of an SQLDA and its use in a dynamic forms application. Your host language companion guide has information about allocating an SQLDA and the variables associated with it.
Example—describe statement:
This program fragment generates a report from a form. The form has both simple fields and a table field.
...
exec frs describe form :form_var into :form_desc;
/* Confirm that form descriptor is large enough */
if (form_desc.sqld > form_desc.sqln) then
free form_desc;
allocate a descriptor with SQLD
or more SQLVAR elements;
exec frs describe form :form_var into :form_desc;
end if;
/* Generate report for form */
call report_form(form_var, form_desc);
/* Find all table fields (type 52), describe them
** and generate a report */
for index = 1 to form_desc.sqld loop
if (form_desc.sqlvar(index).sqltype = 52) then
table_var = form_desc.sqlvar(index).sqlname;
exec frs describe table :form_var :table_var
into :table_desc;
/* Confirm that table field descriptor
** is large enough */
if (table_desc.sqld > table_desc.sqln)
then
free table_desc;
allocate a descriptor with SQLD
or more SQLVAR elements;
exec frs describe table :form_var
:table_var into :table_desc;
end if;
call report_table(table_var, table_desc);
end if;
end loop;
...