AppBuilder Open and Save
Beta Draft
Author: (Author's Name)
Date Last Updated: (Date)
Scheduled Release: (Release Number)
Revision History
The following revisions have been made to this document:
Date: (date)
Revision: (rev-no)
Developer: (developer)
Summary of Changes: (summary)
Copyright (C) 2000 by Progress Software Corporation ("PSC"), 14 Oak Park, Bedford, MA 01730, and other contributors as listed below. All Rights Reserved.
The Initial Developer of the Original Code is PSC. The Original Code is Progress IDE code released to open source December 1, 2000.
The contents of this file are subject to the Possenet Public License Version 1.0 (the "License"); you may not use this file except in compliance with the License. A copy of the License is available as of the date of this notice at:
http://www.possenet.org/license.html
Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. You should refer to the License for the specific language governing rights and limitations under the License.
Contributors
Jane Contributor, Joe Contributor
Contents
The AppBuilder, formerly the User Interface Builder (UIB), is a rapid application development (RAD) tool for creating and maintaining PROGRESS 4GL-based graphical user interfaces (GUIs). It provides a palette of widgets that may be dragged and dropped onto a design window, and then further customized and enhanced to meet the application designer's requirements. The widgets on the palette are comprised of native widgets that are inherent in the PROGRESS 4GL, and custom widgets, consisting of native widgets or combinations of native widgets along with additional code, that serve as reusable interface design components.
At the core of the AppBuilder's architecture is the notion of structured application code. The AppBuilder is both a code generator and a code parser. The application modules created with the AppBuilder are saved as ASCII text files on the operating system. These text files are carefully structured into logical blocks of PROGRESS 4GL statements; they are formatted and ordered to support both of these activities:
This document examines the structure of the AppBuilder generated code, and how the code is written to and read from the operating system.
The Open and Save procedures for the AppBuilder are primarily top-down, structured procedures with large "main" blocks and a few internal procedures. The AppBuilder tool is the evolution of the User Interface Builder (UIB), which was originally designed before many of the more powerful PROGRESS 4GL capabilities, such as persistent procedures, dynamic temp-tables and queries, publish/subscribe and user-defined functions, existed. The tool has undergone many changes and enhancements since its inception in 1992, but the file structure, and consequently the open and save routines, are still largely based on the original design philosophy.
All AppBuilder-generated files are comprised of a set of ordered code sections. The number and nature of the sections is dependent on the file type. See section 2.2, "File Types". The remaining information in this section examines the complete set of AppBuilder code sections, and identifies the order in which they occur in a file.
The Header Section is also referred to as the "TopOfFile" section. This is where the AppBuilder generates the main comment block and other comments for identifying the source of the file. This section can contain the following information:
The Definitions Section generates temp-table, buffer, user field and custom definitions.
2.1.3 Standard Preprocessors Section
The Standard Preprocessors section identifies the code section where most of the AppBuilder-maintained preprocessors are generated. The following list identifies some of the possible preprocessor values:
2.1.4 Control Definitions Section
This section contains definitions that are maintained exclusively by the AppBuilder. Some examples include:Note: The text widgets are not defined here, but rather they are defined as literals in the parent frame's definition.
2.1.5 Included Libraries Section
Here is where any included library (e.g., ADM standard include files) references are generated.
2.1.6 Runtime Attributes and Settings Section
This section identifies where various runtime values are assigned, to initialize widget properties such as HIDDEN, SENSITIVE, READ-ONLY, and so forth. Here are some examples of the possible content of this section:
2.1.7 Control Triggers Section
The Control Triggers section generates the default trigger code for the AppBuilder-maintained widgets (for example, triggers to handle the WINDOW-CLOSE, END-ERROR and ENDKEY events for the default window). Also, if an OCX container is included in the window, this section generates the definition for the containing CONTROL-FRAME.
This section generates the main code block. This section is user-maintained, but there may be some default code generated here for certain file types.
The following list identifies examples of the kind of code that might be generated in the Main Block:
2.1.9 Internal Procedures Section
This section generates all the internal procedures in alphabetical order. This can include some AppBuilder-maintained procedures such as adm-create-objects( ), enable-all( ) and disable-all( ).
2.1.10 Internal Functions Section
This section generates all the internal functions in alphabetical order. Note that the corresponding function prototypes are automatically generated above in the Control Definitions section.
The AppBuilder supports a number of different file types. Each file type can have a different composition, but all of the file types share the same overall structure. The three major file categories, designated by the file extension, are:
Most of the variations between different file types in the AppBuilder are in the content; it is the default values that are generated for each section that provide the unique characteristics of the corresponding file type. Some sections may be left out or contain no code in certain files. For example, only SmartObjects have an Included Libraries section; some files do not have any widgets and therefore do not have any code in the Control Definitions and Control Triggers sections (the Control Triggers section may not even be generated).
The Save procedure is essentially a code generator. The main routine is "_gen4gl.p". It is designed to generate code into carefully structured and designated sections, to facilitate the parsing of the code back into the AppBuilder. The Save procedure collects the information stored in the AppBuilder's internal temp-tables that pertains to the specified object, and uses it to generate the appropriate Progress 4GL definitions and logic to a file on disk. Various decisions are made during the Save process to determine the correct composition and placement of information in the file. See section 4 "Primary Algorithms and Processes" later in this document for a high-level diagram of the typical Save process.
The Open procedure is basically a code parser comprised of two main modules:
The Open procedure first runs the input file through a utility called the Analyzer. The Analyzer is a form of compiler that scans the file for specific constructs and generates an output file that contains detailed information about the widgets and code blocks contained in the original input file. The Analyzer generates two output files. The Analyzer output files are then scanned by the AppBuilder and the information is transferred into the AppBuilder's internal temp-table structure to allow the procedure to be visualized and edited with the tool.
The AppBuilder's Open and Save procedures rely heavily on the AppBuilder internal temp-tables. The internal temp-tables provide the majority of the data used to generate a file, including all of the information supplied by the user during the creation and/or modification of the file in the AppBuilder tool. For more information about the AppBuilder internal temp-tables, see the AB Temp-Tables Open Source document. This section further identifies and describes some key variables associated with the Open and Save processes.
The following table identifies and briefly describes some of the key variables associated with the Save process:
Key Variable | Description |
_UIB_VERSION | The version number of the AppBuilder (or User Interface Builder - UIB). |
Loc | Describes the locations of code sections of an AppBuilder file (see pre_proc.i for details). |
p_status | Input parameter to _gen4gl.p. Describes the mode in which the procedure is being used. Possible values are Save, SaveAs, Save:Check, Export, Run, Preview, Debug and Print. |
pre_proc.i | Contains a number of preprocessors that are used by the AppBuilder. For example, section IDs for XFTR use. |
The following table identifies and briefly describes some of the key variables associated with the Open process:
Key Variable | Description |
open_file | File name to suck in. |
web_temp_file | Web temp file to suck in. |
import_mode | Mode of operation; possible values are:
|
from_schema | True if processing schema-picker output. |
_inp_line | Character array used to store lines of text read in from input file. |
cur_sect | Integer that corresponds to the section of the file that is currently being processed; see adeuib\pre_proc.i for possible values. |
4 Primary Algorithms and Processes
This section presents two separate graphics to describe the Save .w File and Open File processes, respectively.
Figure 1 in this section highlights the main steps in the Save process flow, and details how each file section is evaluated to determine if extended features must also be processed before the file is saved. The ADE Event procedure (_adeevnt.p) is initially called to provide notification that the AppBuilder is about to save a file. At this point in the process, the user can customize the processing to occur to this file; specifically, the user can modify the unsaved file using extended feature capabilities. Then, once each of the code sections has been generated, the ADE Event procedure is again notified that the Save process is completed.
4.1.1 A Few Details About Customized Processing
As noted in Figure 1, after each section of the file is generated in the main Save process flow, the AppBuilder's internal storage is checked to determine if an extended feature (XFTR) is designated to be run; this process can be referred to as the iterative Extended Feature processing model. For example, if an extended feature is defined, the XFTR code is executed. If not, the next code section is evaluated and processed identically. After all the code sections are generated in this manner, the ADE Event procedure is notified that the Save process is done.
Figure 1: Save Process - High-level Flow Diagram, including detailed steps of the Iterative Extended Feature Processing Model
Figure 2 highlights the main steps in the Open process flow. As noted in the first three processing boxes in the diagram, the file is first run through the Analyzer, and then the Analyzer output is processed and loaded into the AppBuilder's internal temp-table structure. Then, the information in the temp-tables is used to visualize the procedure and allow its contents to be edited as identified in the fifth processing box in the diagram. Next, the Open process will cause any Extended Features (XFTRs) that are defined in the input file to be initiated before the Open process notifies the ADE Event procedure that it has finished opening the file.
Figure 2: Open Process - High-level Flow Diagram
This section addresses the following advanced topics:
The Analyzer is a form of compiler, or preprocessor, that scans a Progress 4GL procedure file and produces two output files:
The code sections must be identified to the Analyzer by wrapping them in special preprocessor directives, namely &ANALYZE-SUSPEND and &ANALYZE-RESUME.
The AppBuilder generates the appropriate &ANALYZE-SUSPEND/RESUME statements around each of its code sections when it saves a file. When the AppBuilder opens a file, it first runs the file through the Analyzer to produce the output files. The output files are then parsed separately to obtain the widget definitions and code sections needed to realize and maintain the procedure file. The &ANALYZE-SUSPEND statement can also accept parameters that are used to provide more details about the code block that follows.
The AppBuilder, and other ADE tools, call the ADE Event Handler (adecomm\_adeevnt.p) to notify of certain significant points in application processing, such as before a file is opened and after a file has been saved. You can modify the ADE Event Handler to perform various customized tasks upon receiving these events. See the appropriate AppBuilder- or ADE tools-related Online Help in the appropriate Progress product for more details and examples.
Extended features, or XFTRs (pronounced "ex-features"), provide a mechanism to allow you to customize the behavior of the AppBuilder during the opening and saving of files. An XFTR is a special code block that is manually inserted into an AppBuilder-generated file that contains directives for additional processing that is to occur at different points in the file. The AppBuilder's "open file" routine is designed to recognize embedded XFTR code sections and perform the actions that they specify as "inline" customizations. Typically, an XFTR code block will use the AppBuilder's API functions to access the internal representation of the procedure file they are contained in to either modify the internal information or to provide the information to an external program.
For more information about XFTRs, refer to the AppBuilder Developer's Guide, a book in the Progress product documentation set.
The Structured Procedure, Structured Include, and the Method Library files that are generated by the AppBuilder utilize a special mechanism for excluding the internal procedure and function blocks from the file at compile time. This mechanism consists of a wrapper that is placed around each internal entry; it checks for the existence of a special preprocessor having the name EXCLUDE-internalEntryName.
Note: internalEntryName is the name of the internal entry that is being wrapped.
If the corresponding preprocessor has been defined, the code block for the internal entry that follows is "compiled out" of the .r file when it is compiled. This mechanism is intended to provide an easy way to override the default behavior of a file by allowing an internal entry (or "method") with the same name to be defined elsewhere in the file. This is particularly useful when the file is implemented as a Super Procedure.
Here is an example:
&IF DEFINED(EXCLUDE-myIntProc) = 0 &THEN
PROCEDURE myIntProc:5.4.1 Conditions That Govern the Inclusion of Internal Procedure myIntProc
If somewhere in the file there is a definition for the preprocessor EXCLUDE-myIntProc, then the internal procedure myIntProc will not be included in the .r file when the corresponding source file is compiled. However, if this preprocessor EXCLUDE-myIntProc is not defined, then the internal procedure will be included.
The AppBuilder uses the following source files:
Source File Name | Description | ||
Adeshar\_gen4gl.p | Performs "Save" of AppBuilder files; generates structured 4gl code that the AppBuilder can efficiently parse in order to reopen the file. | ||
Adeshar\_gendefs.p | Generates the Definitions section of a file. | ||
Adeuib\_qssuckr.p | Performs "Open" of AppBuilder files; runs source file through Analyzer and parses the resulting output files, loads the widgets and code sections into internal temp-tables; reads in and runs XFTR code blocks | Adeuib\_cdsuckr.p | Performs the actual reading in of code sections and loads them into internal temp-tables to allow them to be maintained by the Section Editor. |
The Open and Save routines are integral parts of the AppBuilder tool. Other ADE tools also use the Save routine (i.e., _gen4gl.p). For example, the Section Editor uses it to check the syntax of its contents.
8 Build Process and Requirements
The Open and Save routines are integral parts of the AppBuilder tool; they cannot be built and run independently.
Select the File->Save menu option in the AppBuilder to invoke the Save routine.
Select the File->Open menu option in the AppBuilder to invoke the Open routine.
10 Test Requirements and Strategies
Not Applicable
Not Applicable
Provide a list of documents that contain additional information about the tool. For example: The following documents provide additional information about the tool: