inquire_frs Statement—Retrieve FRS Runtime Information
This statement provides runtime information concerning the FRS.
Syntax
inquire_frs object_type {parent_name} [row_number]
(variable = frs_constant[(object_name)]
{, variable = frs_constant[(object_name)]})
Description
The inquire_frs statement retrieves a wide range of information about a variety of form objects or the FRS itself. For example, you can determine the type of terminal in use, the display mode of a form, the validation string associated with a column in a table field, or the screen coordinates of a field, a pop-up form, or the cursor. This statement is particularly useful because FRS status and error information is not reflected in the SQLCA and, consequently, you cannot use the embedded SQL whenever statement to handle forms program errors. The inquire_frs statement is essential for determining the effect of forms statements.
To obtain information about all of a form's fields in sequence or all of the columns in a table field, you can use the inquire_frs statement in conjunction with the formdata or tabledata statements, respectively. See the statement descriptions for those statements for more information.
The syntactical elements have the following meanings:
• object_type is the type of object about which you are requesting information. Specify this as a string, with or without quotes. The following table lists valid object types.
• parent_name identifies the form and, when necessary, the table field which contains the specified object_name. Specify the parent_name as a quoted or unquoted string literal or as a program variable. If parent_name is a quoted blank or empty string, the current parent is used. You cannot refer to more than one parent_name in a single inquire_frs statement. Use the following list for reference, keeping in mind that object_name must be of the type specified by object_type:
• row_number identifies a specific row in a table field display and is only accepted when the object_type is row. You can use an integer literal or integer variable to represent row_number. If the specified table field is linked to a data set, then the row number must refer to a row in the display that contains data. For example, if the table field was defined, in VIFRED, to display four rows but only the first two rows have data in them, specify only the values 1 or 2 for row_number. If the table field has not been initialized, specify the values 1 through 4, inclusive, for row_number. If you do not include a row number, then the current row is assumed, that is, the row on which the cursor rests.
• variable is the name of a program variable into which the information is to be retrieved. The data type of each variable must be appropriate to the type of information which it receives.
• frs_constant represents a key word that indicates what type of information is wanted. Each type of object has a variety of frs_constants that provide a variety of information about the specified object. See the detailed descriptions that follow for each object type.
• object_name is the name of the specific object about which you are inquiring. You can express this as a quoted or unquoted string literal or, if the object_type is form, as a program variable. A single inquire_frs statement can contain references to more than one object, however, all of the objects referenced must have the same parents. For example, if the parent_name is form1, object_name can refer to any field on form1, but you cannot refer to fields that appear on form2 or form3, and so forth. Similarly, if the parent_names identify a table field, then the object names must be names of columns in that table field. You cannot reference columns in other table fields or other simple fields on the form.
If you do not include an object name, assumes the current object is assumed, that is, the object on which the cursor rests. However, when the FRS itself is the object_type, not all of its frs_constants require an object name.
The object names for the various object types are listed in the following table:
The following sections describe the use of the inquire_frs statement for each of the object types described above.