The first step in the construction of a frame is the creation of its FrameSource object, which contains the source definition of a frame. The attributes of the FrameSource object represent the initial settings of the frame when it is first called or opened. The example application creates the FrameSource with the following code:

The Create method creates a new instance of an object of the specified class. In this case, it returns a new instance of a FrameSource object to the test_frame reference variable.

The fieldtop variable designates the starting position of the top of each field on the form. It is incremented by the size of each field and some predetermined amount (identifying the amount of space between fields) in each iteration of the select loop. The example frame sets this variable at this point so that if the user selects the Go menu item more than once, to create more than one frame, the top field on each new frame starts in the correct position.

After the starting frame's Go operation creates the FrameSource object, it sets the following frame attributes:

The sample application assigns the following values to these attributes:

Some frame attributes, such as StartMenu, are set later in the program (after the code creates the objects contained by the attributes). Other frame attributes are left at their default values. For an example of creating the StartMenu object, see How You Can Create the Frame Menu Items.

The first step in creating the frame's form is creating a FrameForm object, which is a subform that contains the fields on a form. The only step involved in creating a FrameForm object is invoking the Create method of the FrameForm system class and assigning the result to the generated frame's TopForm attribute. There are no FrameForm attributes to set.

The following statement from the example application creates a FrameForm object and assigns it to the TopForm attribute of the FrameSource object represented by test_frame:

In the DynamicFrame frame, all of the steps involved in constructing the form's fields occur inside a select loop. A select statement retrieves the column names of the chosen table. As each is returned, the statements in the select loop generate its corresponding field, including the field's title and data type, and attach it to the form.

Moreover, because the script of the generated frame in the DynamicFrame application contains SQL statements (the select statement and cursor statements) that include the column names, the select loop also contains code that builds these SQL statements.

The following code includes the select statement that retrieves the column names:

The preceding select statement retrieves the name, data type, and length of each column in the table selected by the user into variables.

The DynamicFrame frame uses a select loop to process the values returned by the select statement. The following code adds the column names to the SQL statement strings that are part of the generated frame's script:

This code uses the SQL trim string function to remove trailing blanks from the text of the column's name and data type.

The variable numcolumns, initialized to zero before the select, controls the execution of this code. If numcolumns is non-positive, the columnname variable represents the first row returned by the select statement and the Go operation executes the code that builds the initial portions of the SQL statements. The numcolumns variable is incremented with each pass through the loop so that subsequent values of the columnname variable are added to an existing string.

The variables that hold the character strings representing the SQL statements are of the data type varchar(2000). The system constants HC_NEWLINE and HC_TAB represent newline and tab characters, respectively. If your statement strings are longer than 2000 characters, it is preferable to use StringObject variables instead of varchar variables.

After adding the column name to the statement strings, the Go operation constructs the field title and the field itself (all of which are entry fields in the example). The following code creates the field title and attaches it to the form:

Each field's title is an object of the class FreeTrim, which is used only for textual trim on forms. The previous code defines the trim's position on the form (XLeft and YTop), its actual text value (TextValue), and the appearance of the text (IsBold, TypeSize, Width, and Height).

The code also uses SQL string functions (uppercase and lowercase) to ensure that the title appears with initial capitalization.

Specifying a ParentField attribute for an object identifies which composite field contains that object. Therefore, assigning the form object in test_frame.TopForm to the ParentField attribute of the FreeTrim object attaches the trim to the form by identifying the form as the composite field that contains the trim.

After the title is constructed and attached to the form, the following code constructs its corresponding entry field:

The Create method returns an object of type EntryField to the reference variable, field_ptr. The previous code sample assigns a name to the field_ptr variable and specifies its nullability and its top left-hand starting position.

The Go operation then constructs the data type for the field:

If the data type is integer, float, date, or money, the preceding code ignores the column length returned by the select statement and assigns a length explicitly. Column length is set explicitly for non-character columns because the column length returned by the select statement identifies the number of bytes used by Ingres to store the data internally. Because the DynamicFrame frame requires the column length to define the width of the field on the form, it explicitly assigns column length values to these data types. (Alternatively, the CharsPerLine attribute of EntryField objects can be used to define the width of the field.)

In addition to assigning the column length for each non-character data type, the Go operation assigns the appropriate values for the DataType, FormatString, and IsMultiLine attributes of the EntryField objects.

If the value in the columndatatype variable indicates that the column has a character data type (char, varchar, c, or text), the preceding code sets the field's data type to varchar. The SQL ascii function converts the integer value in the columnlength variable to a character string.

In addition, character columns that are longer than 50 characters are formatted as multiline fields, and a maximum field height and length is enforced. Scroll bars are enabled for columns that require more than four 50-character lines to display.

After the Go operation constructs each field, it sets relevant attributes and attaches the field to the form. The example code sets each entry field's width equal to the value of the columnlength variable multiplied by the width of one character. The height of each entry field is set to the height of one character times the fieldheight variable. The outline width of each field is set using the LW_VERYTHIN constant.

The following code from the example frame sets each entry field's attributes and attaches it to the form:

After attaching the field to the form, the previous code assigns a new value to the fieldtop variable, which determines the position of the next field. The value in the fieldtop variable was assigned to the YTop attribute when the entry field was constructed. For discussions on setting the fieldtop variable, see How You Can Create the FrameSource Object.

The statement in the previous code that sets the fieldtop variable takes the current value of fieldtop and adds to it the height of the field just constructed and a predetermined amount of vertical space. The resulting figure is the value of fieldtop for the next iteration of the loop and places the next field on the form below the field just constructed. The amount of space between them is equal to the amount specified by the vertspace variable.

The select loop is repeated once for each column name returned by the select statement. When it is finished, all fields have been constructed and placed on the form. In addition, portions of the SQL statements used in the generated frame's script are also constructed.

After all the fields have been constructed, you can set the dimensions of the window displaying the frame by setting the WindowHeight and WindowWidth attributes of the FrameSource object. The following code from the Go operation of the DynamicFrame frame sets these dimensions:

To prevent the window's height from exceeding a predetermined amount, the example code contains an if statement that checks the height. If it exceeds the limit (the value of the maxformheight variable), the WindowHeight attribute is set to the value of the maxformheight variable and scroll bars are added to the window, allowing the user to scroll to hidden fields. If the window's height does not exceed the limit, the scroll bars are not added.

The Go operation finishes creating the text of the SQL statements begun in the select loop. Adding formatting characters and the final clause completes the selectstring variable. Adding the terminating semicolon completes the selectupdatestring and fetchstring variables. The following code from the DynamicFrame frame completes the text for the variables used in the SQL statements:

The completed strings are used later when the frame script for the generated frame is constructed.

The generated frame created by the DynamicFrame frame contains a menu bar that has two selections, File and Edit. If the user selects File, two new choices appear, Commit and Close, and Rollback and Close. If the user selects Edit, three new choices appear: Delete and Next, Update and Next, and Next.

The bar across the top of the generated frame's window, which displays the initial menu choices, is an instance of the MenuBar class. Each initial menu option and the submenu options accessed through the initial option is an instance of the MenuGroup class. In the generated frame, each of the submenu choices is an instance of the MenuButton class.

In the FrameSource object, which contains the frame's definition, the menu bar is contained in the StartMenu attribute. Therefore, to construct a menu for a frame, first create the MenuBar object and assign it to the StartMenu attribute. Then name the menu. The following code creates the named menu bar and attaches it to the generated frame:

The following discussion steps through the construction of the File menu group.

For more information about the various types of menu objects, see the Language Reference Guide.

Part of the source code for the generated frame was written in the select loop that constructed the fields. The next section of the DynamicFrame frame script creates the generated frame's source code from the strings constructed in the select loop.

The starting frame uses the following steps to create the generated frame's source code:

After the frame has been fully defined, it must be attached to the application by setting the ParentApplication attribute of the new frame's FrameSource object to the same value that is in the ParentApplication attribute of the currently executing frame. (The currently executing frame is the starting frame of the dynamic application.)

The following code from the example application sets the ParentApplication attribute of the generated frame:

This statement assigns the contents of the ParentApplication attribute of the current frame's FrameSource object to the corresponding attribute of the generated frame's FrameSource object. For a more detailed explanation of the preceding syntax, see How You Can Attach the Frame to the Application.

The DynamicFrame frame performs the additional step of adding the frame to a list of already generated frames. Because the sample application lets a user return to the initial frame, select another table, and select the Go menu item again, a global array variable is used to keep track of which frames have already been generated.

Because the Generated_Frame_List global variable stores the names of generated frames, an existing frame can be executed without requiring regeneration if the user selects a table for which a frame already exists.

The following code from the example application adds the newly generated frame to the list in the global array variable:

The global array variable, Generated_Frame_List, has three attributes: table_name, frame_name, and frame_source. The previous code uses the LastRow attribute (defined for the ArrayObject class) to determine the row sequence number of the last row in the array. The current value of the LastRow attribute is incremented by one to create a new index into the array.

The reference to a previously non-existent row automatically appends a new, empty row to the end of the array. After the row has been added, each of its attributes is assigned the appropriate value for the newly generated frame. The process used to add a new row in the example code is called adding a row by first reference. For more information about adding rows to an array, see Creating a Frame at Runtime.

The following code from the DynamicFrame frame assigns a name to the newly generated frame and executes it:

The callframe statement compiles and runs the new frame. When OpenROAD automatically compiles a dynamically created frame or procedure on first call, it places the text of any compilation errors into Proc4GLSource's Compile_Errors attribute. Check whether the Compile_Errors attribute is null after the first call to detect whether compilation errors occurred.

The following code from the example frame checks the Compile_Errors attribute and writes any errors to a file to facilitate debugging:

If the frame does not compile correctly, its name is removed from the list in the global array variable, Generated_Frame_List.