Procedure Windows
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 © 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

1. Overview
2. Architecture
2.1 Program Architecture
2.2 Starting Procedure Windows
2.3 Startup Processing
2.4 Closing Procedure Windows
2.5 Dynamically Created User Interface
2.5.1 Procedure Window
2.5.2 Editor Frame
2.5.3 Editor Buffer
2.5.4 Menubar and Popup Menu
2.5.5 Procedure Window Widget Pool
2.6 Event Processing
2.7 Persistent Attribute Data
2.7.1 Attribute Data Preprocessor Strings
2.7.2 How Attribute Data Values are Stored
2.7.3 Accessing Attribute Data Values
3. Primary Data Structures
4. Primary Algorithms and Processes
4.1 Menus
4.1.1 File Menu
4.1.2 Edit Menu
4.1.3 Format Selection Submenu
4.1.4 Search Menu
4.1.5 Compile Menu
4.1.6 Help Menu
5. Advanced Topics
6. Dependencies
7. Source Files
8. Build Process and Requirements
9. Execution Methods
10. Test Requirements and Strategies
11. Supplementary Information
12. Related Documentation

1. Overview

Procedure Windows are used to create, edit, save, compile, and run Progress procedure files. The files created and edited with a Procedure Window are free-form source files. This means the files do not follow a specific structure, unlike files created using the AppBuilder which do have a specific source code structure. A Procedure Window’s functionality is accessed using menu options, mouse operations, and keyboard commands. A user can easily edit and view multiple source procedure files, as well as copy and paste between them. While any number of Procedure Windows can be open simultaneously, only a single procedure file can be edited in a Procedure Window.

2. Architecture

2.1 Program Architecture

A Procedure Window is not a persistently running procedure and it does not have any wait-for or other input blocking statements. Procedure Windows don't block for input with a wait-for or update to allow other ADE Tools to be accessible while any number of Procedure Windows are open and available to edit files. Instead, Procedure Windows and their interface widgets are dynamically created with appropriately attached persistent triggers to handle event processing and execute Procedure Window functionality.

2.2 Starting Procedure Windows

The adecomm/_pwmain.p procedure is the main program for creating Procedure Windows. It can be called as often as required to open Procedure Windows. You can open multiple Procedure Windows at one time by passing this procedure a list of files to open. If you do not pass a list of files to open, this procedure creates one untitled Procedure Window.

The following code example shows the call syntax for running _pwmain.p to create Procedure Windows:

RUN adecomm/_pwmain.p (INPUT p_Parent_ID /* PW Parent ID */ ,

INPUT File_List /* Files to open */ ,

INPUT p_Edit_Command /* PW Command */ ).

The following table describes the parameters for _pwmain.p:

Parameter

Data Type

Description

INPUT p_Parent_ID

Character

String value indicating "Parent" of Procedure Window. Pass Null ("") if no parent. The p_Parent_ID parameter should be the name of the calling tool. When the tool exits, it calls adecomm/_pwexit.p and passes p_Parent_ID again. This procedure uses p_Parent_ID to close only those Procedure Windows created by the calling parent. It’s best to pass the application or tool startup procedure name. For example, the Procedure Editor passes a parent value of “_edit.p”. This allows adecomm/_pwexit.p to determine if the caller is the client session startup routine (-p). If it is, then all Procedure Windows are closed (not just those owned by the caller). This takes care of those Procedure Windows created by the PRO*Tools Editor applet. Otherwise, their contents would be lost when the session ends. When the caller is not the session startup procedure, then only those Procedure Windows created by the exiting parent are closed. Procedure Windows that are opened from other Procedure Windows inherit the Parent ID from the Procedure Window that opened them.

INPUT p_FileList

Character

Comma-delimited list of files to open in Procedure Windows. A null value (“”) opens a Procedure Window with an Untitled procedure. Each file is opened in its own Procedure Window. If a file cannot be found, a warning message is displayed in an alert box. If the file to open exists on a remote WebSpeed agent, the OS file name will contain three CHR(3)-delimited parts; file name, local temp file name, and Broker URL to use to save the file.

INPUT p_Edit_Command

Character

Either Null ("") for no special processing other than to open a Procedure Window or "UNTITLED" to force a template file to be opened Untitled.

2.3 Startup Processing

The _pwmain.p procedure calls a series of other _pw*.p procedures to construct a Procedure Window during its startup processing. The following process describes the steps _pwmain.p performs to create a Procedure Window:

1. Initializes the Procedure Window persistent widget pool named “"_ADE_Procedure_Window”.

2. Dynamically creates the main menubar, which is later added to the window widget. All appropriate persistent triggers are attached to the menu items as needed. This is accomplished with the following call:

RUN adecomm/_pwmbar.p ( INPUT NO /* p_Popup */,

OUTPUT h_menu /* PW Menubar Handle */ ).

3. Dynamically creates the window, frame, and editor widgets to represent the Procedure Window user interface. The window handle of the created window widget is returned. This is accomplished with the following call:

RUN adecomm/_pwcreat.p ( INPUT p_Parent_ID /* Parent ID */ ,

INPUT . (other input parameters),

INPUT h_menu /* Menubar */ ,

OUTPUT h_win /* Window H */ ).

4. Creates and attaches the editor widget's popup menu. This is accomplished with a call to the same procedure used to create the main menubar, except “YES” is passed for the input parameter to indicate _pwmbar.p should create and return a popup menu handle instead of a menubar handle. Procedure _pwmbar.p creates a popup menu very similar to the Procedure Editor popup menu with minor variations tailored to the Procedure Window. All appropriate persistent triggers are attached to the menu items when they are created.

5. If processing a specified file name (not Untitled), try to read that file. This is accomplished with the following call:

RUN adecomm/_pwrdfl.p (INPUT h_ed,

INPUT (Proc_Name + .),

OUTPUT Read_OK).

6. If the file is read successfully, or an Untitled Procedure Window is created, enter the window for editing. This is accomplished with an apply entry to the dynamically created editor widget.

7. If no Procedure Window is opened as a result of the previous processing steps, open an Untitled Procedure Window using the parent id passed to _pwmain.p. This is accomplished in the following call:

IF PW_Opened = FALSE THEN

RUN adecomm/_pwmain.p (INPUT p_Parent_ID /* PW Parent ID */ ,

INPUT "" /* Files to open */ ,

INPUT "" /* PW Command */ ).

8. Continue processing the files to open list until there are no more files to process.

This startup process results in opening either a single untitled Procedure Window or several Procedure Windows. In either case, each Procedure Window contains a file for editing.

2.4 Closing Procedure Windows

A Procedure Window closes itself when the File>Close Window option is chosen. However, a tool or application object that created additional Procedure Windows is responsible for closing any open Procedure Windows when it exits or closes.

When an application object (such as an ADE tool) starts a Procedure Window, it passes a Parent ID to the Procedure Window. The Parent ID should uniquely identify the Procedure Window as belonging to that application object. See section 2.2 "Starting Procedure Windows" for a description of Parent ID.

When an application object is exiting or closing, it can close all its currently open Procedure Windows using the following call to adecomm/_pwexit.p:

RUN adecomm/_pwexit.p (INPUT Object-Name /* PW Parent ID */,

OUTPUT OK_Close /* All PW closed */).

The _pwexit.p procedure searches through all of the windows in the current session for Procedure Windows belonging to the parent specified by Object-Name (the p_Parent_Id parameter), and closes all Procedure Windows for the specified parent. If all of the parent object's Procedure Windows close successfully, output parameter p_OK_Close is returned as TRUE. Otherwise, it's returned as FALSE or Unknown.

Note: If the specified parent window that is closing is also the session startup procedure, then the Progress session is ending and _pwexit.p closes all Procedure Windows.

2.5 Dynamically Created User Interface

All user interface elements of a Procedure Window are created dynamically. The adecomm/_pwcreat.p procedure creates all Procedure Window interface widgets, except for the menubar and popup menu. The menus are created by the adecomm/_pwmbar.p procedure.

2.5.1 Procedure Window

A Procedure Window is displayed in a dynamically created window widget. A Procedure Window stores two important pieces of information in the following window widget attributes:

Private-data attribute — Stores the Procedure Window's Parent ID, if there is one, or the question mark string ("?") if the Parent ID is unknown.

Name attribute — Stores the Procedure Window tool name, which is the string "Procedure Window", as specified by the PW_Name preprocessor defined in adecomm/_pwglob.i.

2.5.2 Editor Frame

Except for the menubar and popup menu, all Procedure Window widgets are contained in a dynamically created frame widget called the editor frame. No Procedure Window information is stored in editor frame attributes. However, in addition to the editor buffer where code is typed, the editor frame holds hidden fields that store Procedure Window persistent attribute data. See section 2.7 "Persistent Attribute Data" for details.

2.5.3 Editor Buffer

When you type code in a Procedure Window, you are typing into an editor buffer that is a dynamically created editor widget. The editor buffer's Private-Data attribute stores several persistent Procedure Window attribute data values. See section 2.7 "Persistent Attribute Data" for details.

2.5.4 Menubar and Popup Menu

Procedure Window menubar and popup menus are created dynamically. No Procedure Window information is stored in the attributes of these menus.

The adecomm/_pwmbar.p procedure creates both the menubar and popup menu for a Procedure Window. When input parameter p_Popup is true, _pwmbar.p creates a popup menu. When p_Popup is false, _pwmbar.p creates a menubar menu. The p_Hmenubar output parameter returns the handle to whichever menu is created.

Several menubar and popup menu options are enabled or disabled depending on such factors as whether or not text is selected and whether or not the editor buffer is read-only. The enabling of menu items is accomplished using a MENU-DROP trigger defined for the menubar and popup menu that runs the adecomm/_pwemdrp.p procedure. The adecomm/_pwemdrp.p procedure performs the enabling and disabling of menu items. The items to enable and disable are specified in _pwemdrp.p. The procedure dynamically walks the menubar or popup menu to set the sensitive state of the appropriate menu items. Each item is identified by a menu item label (except the ampersand (&) notation for programming menu short cuts). Because items are identified by menu item labels, the _pwemdrp.p procedure must have its labels match the menu labels defined in adecomm/_pwmbar.p.

2.5.5 Procedure Window Widget Pool

The dynamically created Procedure Window interface widgets are created in a persistent widget pool named "_ADE_Procedure_Window," defined in the _pwglob.i include file by the preprocessor definition PW_Pool and created in the adecomm/_pwmain.p Procedure Window program. The dynamic widgets are created in a widget pool to prevent them from being created in some other tool's widget pool. That could lead to the unwanted deletion of Procedure Windows when the other tool is closed and its widget pool is deleted.

2.6 Event Processing

A Procedure Window attaches persistent triggers to its dynamically created user interface during Procedure Window startup. These persistent triggers handle Procedure Window event processing. The persistent triggers call external Procedure Window files (adecomm/_pw*.p) to execute Procedure Window functionality. Except for editing features such as typing, paging, and mouse operations, most of this functionality is invoked using menubar and popup menu options. The adecomm/_pwmbar.p procedure creates the Procedure Window menubar and popup menu and attaches the triggers that invoke Procedure Window functionality.

2.7 Persistent Attribute Data

Procedure Windows must keep certain pieces of data persistent. For example, a Procedure Window's Find dialog box displays the same Find Text, Match Case, Direction, and other information as the last time it was invoked. Because Procedure Windows are not persistently running procedures and do not block for input, they cannot store their persistent data items in variables or temp-tables. Instead, Procedure Windows store their persistent data items using what is called Procedure Window attribute data items.

Attribute data items have two important features to understand: preprocessor defined strings that identify and describe the data items, and the mechanism by which the data items are stored and accessed. The following sections describe these features.

Note: For more help with understanding Procedure Window attribute data items and values, read the comments and code in the following source files: adecomm/_pwattr.i, adecomm/_pwcreat.p, and adecomm/_pwsrch.p.

2.7.1 Attribute Data Preprocessor Strings

Attribute data items have preprocessor defined strings that identify and describe the persistent data Procedure Windows store and use. Following is the format of the preprocessor defined strings:

PW_Attribute "LABEL,DATA-TYPE,INITIAL-VALUE"

LABEL — Uniquely identifies an attribute data item. For example, the Find Text attribute is identified with a label value of "Find_Text". Some attribute data items are stored in fill-in fields in a Procedure Window's frame. For those data items, the LABEL value specifies the fill-in's label. It is used to identify an attribute to save and retrieve data.

DATA-TYPE — For data items stored in fill-in fields in the Procedure Window frame, the DATA-TYPE value identifies the fill-in's data-type.

INITIAL-VALUE — Specifies an attribute's initial value.

The following preprocessor defined strings for the Procedure Window attribute data items are defined in the adecomm/_pwattr.i include file:

&GLOBAL-DEFINE PW_Find_Text "Find_Text,CHARACTER,"

&GLOBAL-DEFINE PW_Replace_Text "Replace_Text,CHARACTER,"

&GLOBAL-DEFINE PW_Find_Direction "Find_Direction,CHARACTER,DOWN"

&GLOBAL-DEFINE PW_Find_Case "Find_Case,LOGICAL,NO"

&GLOBAL-DEFINE PW_Find_Wrap "Find_Wrap,LOGICAL,YES"

&GLOBAL-DEFINE PW_Replace_Case "Replace_Case,LOGICAL,NO"

&GLOBAL-DEFINE PW_Replace_Wrap "Replace_Wrap,LOGICAL,YES"

&GLOBAL-DEFINE PW_Schema_Prefix "Schema_Prefix,INTEGER,1"

Procedure Window code uses the information in these preprocessor defined strings to store and access attribute data item values.

2.7.2 How Attribute Data Values are Stored

The data value of an attribute data item is stored in one of two ways:

· As an individual value in the Private-Data property of a dynamically created fill-in widget that is hidden in the Procedure Window's editor frame.

· As an entry in a comma-delimited list of values in the Private-Data property of the Procedure Window's editor buffer.

Two attribute data items have their values stored in the Private-Data field of a fill-in field: the Find Text and Replace Text fields used in the Find and Replace dialog boxes. These attributes are stored in their own fill-in fields because their values can be multi-line text of any kind. It would be problematic to determine an appropriate delimiter to use for accessing them if they were stored along with the list of attribute values in the editor buffer's Private-Data property. All other attribute data item values are stored in a comma-delimited list in the Private-Data property of the Procedure Window's editor buffer.

The attribute data items are first created and have their initial values stored when the editor frame is created in adecomm/_pwcreat.p during startup processing, as shown in the following code taken from _pwcreat.p:

/* Use the Editor Frame to hold these PW's Search Attributes. We placed these in FILL-IN widgets of their own because they can be multi-line text strings. Because of the EOL characters, this could be tricky to store properly in a delimited-list. */

RUN CreateFrameAttr ( INPUT h_frame , {&PW_Find_Text} ).

RUN CreateFrameAttr ( INPUT h_frame , {&PW_Replace_Text} ).

/* Additional PW Attributes are stored in comma-list in ED:PRIVATE-DATA. */

RUN InitAttr ( INPUT h_ed ).

The CreateFrameAttr and InitAttr procedures are defined in the adecomm/_pwattr.i include file.

If the Procedure Window is open to edit a remote WebSpeed file, the WebSpeed attributes for the name of the local temporary web file and the remote broker URL are also added to the editor buffer's Private-Data property in code run directly in _pwcreat.p.

2.7.3 AccessingAttribute Data Values

The Find and Replace dialog attribute data item values are accessed using the GetSrchAttr and PutSrchAttr procedures defined in adecomm/_pwsrch.p. Attribute values stored in the editor buffer's Private-Data property are accessed using ENTRY function calls.

To access attribute values stored in the Private-Data property of the fill-in fields in the editor frame, _pwsrch.p first gets the handle of the required fill-in widget using a call to the GetFrameAttr procedure (defined in adecomm/_pwattr.i) and then accesses the data item value directly using the Private-Data property.

3. Primary Data Structures

Not applicable.

4. Primary Algorithms and Processes

4.1 Menus

This section presents the Procedure Window menus with their associated menu items and underlying procedures.

4.1.1 File Menu

Menu Item

Procedure

New

RUN adecomm/_pwfile.p ("NEW").

Open

RUN adecomm/_pwfile.p ("OPEN").

New Procedure Window

RUN adecomm/_pwfile.p ("NEW-PWIN").

Save

RUN adecomm/_pwfile.p ("SAVE").

Save As

RUN adecomm/_pwfile.p ("SAVE-AS").

Print

RUN adecomm/_pwfile.p ("PRINT").

Close Window

RUN adecomm/_pwfile.p ("CLOSE").

4.1.2 Edit Menu

Menu Item

Procedure

Undo

RUN adecomm/_pwedit.p ("UNDO").

Cut

RUN adecomm/_pwedit.p ("CUT").

Copy

RUN adecomm/_pwedit.p ("COPY").

Paste

RUN adecomm/_pwedit.p ("PASTE").

Insert File

RUN adecomm/_pwedit.p ("INSERT-FILE").

Insert Fields

RUN adecomm/_pwedit.p ("INSERT-FIELDS").

Format Selection

Submenu

4.1.3 Format Selection Submenu

Menu Item

Procedure

Indent

RUN adecomm/_pwedit.p ("INDENT-SELECTION").

Unindent

RUN adecomm/_pwedit.p ("UNINDENT-SELECTION").

Comment

RUN adecomm/_pwedit.p ("COMMENT-SELECTION").

Uncomment

RUN adecomm/_pwedit.p ("UNCOMMENT-SELECTION").

4.1.4 Search Menu

Menu Item

Procedure

Find

RUN adecomm/_pwsrch.p ("FIND").

Find Next

RUN adecomm/_pwsrch.p ("FIND-NEXT").

Find Previous

RUN adecomm/_pwsrch.p ("FIND-PREV").

Replace

RUN adecomm/_pwsrch.p ("REPLACE").

Goto Line

RUN adecomm/_pwsrch.p ("GOTO-LINE").

4.1.5 Compile Menu

Menu Item

Procedure

Run

RUN adecomm/_pwcomp.p ("RUN").

Check Syntax

RUN adecomm/_pwcomp.p ("CHECK-SYNTAX").

4.1.6 Help Menu

Menu Item

Procedure

Press F1 in Edit Area

RUN adecomm/_pwhelp.p ( INPUT "KEYWORD" ).

Help Topics

RUN adecomm/_pwhelp.p ("TOPICS").

Messages

RUN adecomm/_pwhelp.p ("MESSAGES").

Recent Messages

RUN adecomm/_pwhelp.p ("RECENT-MESSAGES").

5. Advanced Topics

Not applicable.

6. Dependencies

Not applicable.

7. Source Files

All Procedure Window source files are located in the SRC directory adecomm and begin with the prefix “_pw”. The following table lists and describes the source files that comprise Procedure Windows:

Source File

Description

_pwattr.i

Preprocessor defines and internal procedures used to manage Procedure Window attributes that contain persistent Procedure Window data.

_pwchfnt.p

Changes the font of all Procedure Windows with a specified font to a new specified font.

_pwclose.p

Executes the Procedure Window File>Close command.

_pwclosf.p

Low-level routine to close a Procedure Window file.

_pwcmpfl.p

Compiles the contents of a Procedure Window editor widget or the contents of a disk file to check its syntax.

_pwcomp.p

Executes Procedure Window Compile menu commands.

_pwcreat.p

Creates the Persistent Procedure Window with Menubar, frame, and editor widget, and additional attributes used to hold persistent data. This also attaches default persistent triggers for WINDOW-CLOSE, WINDOW-RESIZE, HELP, and DROP-FILE-NOTIFY.

_pwdelpw.p

Deletes the Procedure Window widget and all its child widgets.

_pwedit.p

Executes the Procedure Window Edit menu commands and handles various other events when they occur in the editor widget, such as TAB, BACK-TAB, and END-ERROR.

_pweditor.i

Procedure Window support procedures. (Encrypted)

_pwemdrp.p

On the MENU-DROP event for a Procedure Window Edit menu or Popup Menu, set the sensitive state of the menu items.

_pwexit.p

Attempt to close all open Procedure Windows for a specified parent.

_pwfchg.p

Executes the File Changed Dialog, which asks the user to save changes made to a modified file before continuing some operation.

_pwfile.p

Executes the Procedure Window File menu commands.

_pwfmod.p

Returns TRUE if the Procedure Window has been modified; FALSE if it has not.

_pwgeteh.p

Returns the handle for any Procedure Window editor widget.

_pwgetfh.p

Returns the handle of the Procedure Window Editor Frame given a Procedure Window handle.

_pwgetun.p

Returns a Procedure Window Untitled procedure name.

_pwgetwh.p

Returns the Window handle for any widget. (File was necessary before WINDOW handle attribute was added to all widgets.)

_pwglob.i

Global defines for Procedure Windows. Currently defines only preprocessor values such as the “Procedure Window” name displayed in the title bar and the Procedure Window widget pool.

_pwhelp.p

Executes the Procedure Window Help menu commands.

_pwin.p

Intended to be a start-up routine called from Progress –p startup procedure to run Procedure Windows. For example, to open a list of files in Procedure Windows based on SESSION:PARAMETER. This procedure is not currently used by any ADE code.

_pwmain.p

The main program to call to open one or more Procedure Windows for editing procedure or include files, or for opening an Untitled procedure in a Procedure Window.

_pwmbar.p

Creates a Procedure Window menu and returns its handle. The menu can be a menubar or popup menu.

_pwnew.p

Executes the Procedure Window File>New command.

_pwnewpw.p

Executes the Procedure Window File>New Procedure Window command.

_pwopen.p

Executes the Procedure Window File>Open. command.

_pwprint.p

Executes the Procedure Window File>Print command.

_pwrdfl.p

Reads a specified file into a Procedure Window editor widget and updates the window’s title bar.

_pwresz.p

Resizes the frame and editor widget for a Procedure Window after the Procedure Window has been resized.

_pwrun.p

Executes the Procedure Window Compile>Run and Compile>Check commands.

_pwsavas.p

Executes the Procedure Window File>Save As command.

_pwsave.p

Executes the Procedure Window File>Save command.

_pwsavef.p

Low-level routine to save editor contents to an operating system file. If saving to a remote WebSpeed agent, this program will save the editor contents to a local temp file only. See the file for details.

_pwsrch.p

Executes the Procedure Window Search menu commands.

_pwwinst.p

Sets the window state of all Procedure Windows that are children of a specified Procedure Window parent. For example, if the Procedure Editor “Minimize Before Run” setting is enabled, then all Procedure Windows opened from the Procedure Editor are minimized. Procedure Windows not opened from the Procedure Editor do not have their window state changed.

8. Build Process and Requirements

When making changes to Procedure Window include files, you must recompile adecomm/_pw*.p files which include the changes files.

9. Execution Methods

Not applicable.

10. Test Requirements and Strategies

If you follow the suggestions for building, and your working directory appears first in your PROPATH, then testing is rather straightforward.

11. Supplementary Information

Not applicable.

12. Related Documentation

It is strongly recommended that anyone wanting to modify Procedure Windows code read the following Progress user documents and POSSE documents:

· Progress Procedure Window Online Help

· WS WebSpeed Workshop (for information about how procedure windows handle remote file management)