PRO*Tools
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
3 Primary Data Structures
4 Primary Algorithms and Processes
4.1 ADM1 PRO*Spy (protools/_prospy.w)
4.2 ADM1.0 -> ADM1.1 Upgrade Utility (protools/_smoupg.p)
4.3 AppServer Session Information (protools/_asinfo.w)
4.4 Color Changer (protools/_colorch.w)
4.5 COM Object Viewer (protools/_proobjv.p)
4.6 Configuration Information (protools/_procfg.w)
4.7 Control Hierarchy (protools/_walker.w)
4.8 Database Connections (protools/_dblist.w)
4.9 Editor (protools/_pwedit.p)
4.10 OS Prompt (protools/_osprmt.p)
4.11 PRO*Spy (protools/_prospy9.w)
4.12 Procedure Object Viewer (protools/_ppmgr.w)
4.13 PROPATH Editor (protools/_propath.w)
4.14 Prototype Generator (protools/_protgen.w)
4.15 ProwcApp Editor (protools/_prowcapped.w)
4.16 Run Procedure (protools/_runfile.w)
4.17 Screen Capture (protools/_scrcap.w)
4.18 Screen Scaling Utility (protools/_ppuscl.p)
4.19 Service Parameter Maintenance (protools/_waspartn.w)
4.20 Session Attributes (protools/_session.w)
4.21 Set Font 2 (protools/_edfont.p)
4.22 SmartObject Upgrade Utility (protools/_v89conv.w)
4.23 Window Viewer (protools/_winmgr.w)
4.24 Windows Information (protools/_wabout.p)
4.25 XML Schema Mapping (protools/_xmlview.w)
5 Advanced Topics
6 Dependencies
6.1 Temporary Tables
6.2 AppBuilder
6.3 Common Routines
6.4 Executables
7 Source Files
8 Build Process and Requirements
9 Execution Methods
10 Test Requirements and Strategies
11 Supplementary Information
12 Related Documentation


1. Overview
PRO*Tools are a collection of applets available for Progress developers that provide functionality such as information about the current Progress session, debugging aides, and deployment tools. It is possible to add applets to the PRO*Tools and customize how the existing applets display in the PRO*Tools palette and how they are run with the PRO*Tools Customization option.

2. Architecture
PRO*Tools are a collection of applets available for Progress developers that provide functionality such as information about the current Progress session, debugging aides, and deployment tools. It is possible to add applets to the PRO*Tools and customize how the existing applets display in the PRO*Tools palette and how they are run with the PRO*Tools Customization option.

A startup file is used at initialization of the PRO*Tools palette to determine which applets to display on the palette and which images to use and what to run for each applet and how to run the applet.

The startup file, protools/protools.dat stores the function definitions for the PRO*Tool applets. It contains the following data:

A default protools.dat file exits in DLC/gui/protools. PRO*Tools Customization allows for a different startup file to be used. Customizing PRO*Tools writes the following key values to the ProTools section of the current environment (registry or initialization file):

3. Primary Data Structures
Function definitions in the startup file (protools/protools.dat) are input from the file into pt-function temp-table records. These temp-table records are then used to create the palette and determine how to run the applets from the palette.

4. Primary Data Structures
The primary processes of PRO*Tools include the supported applets described in this section.

4.1 ADM1 PRO*Spy (protools/_prospy.w)
The ADM1 PRO*Spy is available as a debugging tool for ADM1 (Version 8) SmartObject applications. It is not included in the startup file (protools/protools.dat) for Version 9 and can be added to the startup file through PRO*Tools customization.

4.2 ADM1.0 -> ADM1.1Upgrade Utility (protools/_smoupg.p)
The Version 8 SmartObject Upgrade Utility is available for converting ADM1.0 (Version 8.0x) SmartObjects into ADM1.1 (Version 8.1x) SmartObjects. The protools/_smoupg.p procedure is a stub procedure that determines whether the AppBuilder is running before running the upgrade utility, adeuib/_smoupg.w.

4.3 AppServer Session Information (protools/_asinfo.w)
The AppServer Session Information applet is a dialog box that displays connection and execution information for an AppServer. It gathers the displayed information for an AppServer by invoking adecomm/_asread.p on the AppServer.

4.4 Color Changer (protools/_colorch.w)
The Color Changer applet is a window that allows Progress system colors 0 through 15 to be changed using the SYSTEM-DIALOG COLOR statement. The changed colors can also be saved to the current environment (registry or initialization file) with a PUT-KEY-VALUE COLOR ALL statement.

4.5 COM Object Viewer (protools/_proobjv.p)
The COM Object Viewer applet starts the COM Object Viewer executable, bin\proobjvw.exe, which displays the contents of Type Libraries for Automation Servers and ActiveX Controls.

4.6 Configuration Information (protools/_procfg.w)
The Configuration Information applet is a window that displays product configuration information for the install that it retrieves from SHOWCFG utility output.  The browse that displays the product names and serial numbers uses a temp-table called cfg that is not defined in adettdb/TEMP-DB.df. Refer to section 8. Additional Information for details regarding temp-table use in PRO*Tool procedures.

4.7 Control Hierarchy (protools/_walker.w)
The Control Hierarchy applet is a window that displays objects in the Progress session by walking the widget tree for each window in the Progress session.

4.8 Database Connections (protools/_dblist.w)
The Database Connections applet is a window that allows connections to and disconnections from databases and displays schema information for connected databases. A database alias called tinydict is created for the currently selected database before procedures that access the database schema information are invoked. The procedures that access the database schema information use tinydict to do so.

4.9 Editor (protools/_pwedit.p)
The Editor applet invokes the Procedure Window main procedure, adecomm/_pwmain.p.

4.10 OS Prompt (protools/_osprmt.p)
The OS Prompt applet invokes the MS-DOS command prompt with an appropriate command for the version of Windows being used.

4.11 PRO*Spy (protools/_prospy9.w)
The PRO*Spy applet is a SmartObject debugging tool that runs a SmartObject application and displays execution path information logged for the session by turning the EXECUTION-LOG session attribute on while the application is run.

4.12 Procedure Object Viewer (protools/_ppmgr.w)
The Procedure Object Viewer applet is a window that displays the running persistent procedures in the Progress session. The following are also displayed for the currently selected procedure:

4.13 PROPATH Editor (protools/_propath.w)
The PROPATH Editor is a dialog box that displays and allows modifications to the first 999 items in the Progress PROPATH and allows the user to save the PROPATH in the current environment (registry or initialization file).

4.14 Prototype Generator (protools/_protgen.w)
The Prototype Generator applet is a window that generates prototype include files for a super procedures by running the super procedure with adecomm/_runcode.p and then getting the signatures of its internal entries.

4.15 ProwcApp Editor (protools/_prowcapped.w)
The ProwcApp Editor applet starts the Progress Web Client Application Editor executable, bin\prowcappeditor.exe.

4.16 Run Procedure (protools/_runfile.w)
The Run Procedure applet is a window that runs a procedure with adecomm/_runcode.p.

4.17 Screen Capture (protools/_scrcap.w)
The Screen Capture applet allows screen images of Progress windows to be captured.

4.18 Screen Scaling Utility (protools/_ppuscl.p)
The Screen Scaling Utility assists in scaling the size and position of objects in procedures. The protools/_ppuscl.p procedure is a stub procedure that determines whether the AppBuilder is running before running the scaling utility, adeuib/_ppuscal.w.

4.19 Service Parameter Maintenance (protools/_waspartn.w)
The Service Parameter Maintenance applet is a window that allows creation of application partitions for use by AppBuilder procedures. It uses SmartObjects based on a temp-table called ttAppSrv-TT defined in adettdb/temp-db.df to maintain the partitions. And it uses the AppServer Utilities (adecomm/as-utils.w) to write the partition data to the deployment file (appsrvtt.d). There are two types of partitions that can be created by this applet:

4.20 Session Attributes (protools/_session.w)
The Session Attributes applet displays attributes of the SESSION handle and allows the attribute values to be printed.

4.21 Session Attributes (protools/_session.w)
The Set Font 2 applet invokes the SYSTEM-DIALOG FONT dialog for font 2. Font 2 is the font used for the ADE source code editors.

4.22 SmartObject Upgrade Utility (protools/_v89conv.w)
The SmartObject Upgrade Utility assists in converting Version 8 SmartObjects to Version 9 SmartObjects. The conversions are data-driven based on the v89names.dat file.

4.23 Window Viewer (protools/_winmgr.w)
The Window Viewer applet displays open windows for the Progress session and can hide a window or view a hidden window and can pop a window to the top.

4.24 Windows Information (protools/_wabout.p)
The Windows Information applet displays windows operation system information with a call to ShellAbout.

4.25 XML Schema Mapping (protools/_xmlview.w)
The XML Schema Mapping Tool allows creation and editing of schema-based XML mapping files.

5. Advanced Topics
Not Applicable

6. Dependencies
The PRO*Tools have a number of dependencies, depending on the tool.

6.1 Temporary Tables
The SmartObjects that make up the Service Parameter Maintenance applet use definitions from adettdb/temp-db.df. In order to load these files into the AppBuilder and modify them, connection to a TEMP-DB database that includes the definitions in adettdb/temp-db.df is required.

There are several other PRO*Tool procedures that include temp-table definitions but these definitions are not included in adettdb/temp-db.df. This is currently logged as bug 20000907-009 and will be fixed to include these temp-table definitions in adettdb/temp-db.df and to update the procedures accordingly to use these temp-table definitions. Until this bug is fixed, any of these affected files will give errors when loaded into the AppBuilder and saving these files in the AppBuilder may remove their temp-table definitions. Until this bug is fixed, care should be taken when modifying any of these procedures. The procedures affected are indicated with an * in the source file listing.

6.2 AppBuilder
The following applets require that the AppBuilder be running in order to run them:

6.3 Common Routines
Most of the applets depend on various adecomm and adeshar routines, including:

The Database Connections applet depends on additional adecomm routines for database connecting/disconnecting, including:

The AppServer Information and Service Parameter Maintenance applets depend on additional adecomm routines for AppServer connections, including:

The SmartObject Upgrade Utility applet depends on additional adecomm and adeshar routines for directory searches and for use of an editable drop-down combo-box activex control, including:

The PROPATH Editor Search option depends on adecomm/fileinfo.i to use the fileinfo.dll to get file information.

6.4 Executables
The COM Object Viewer requires bin/proobjvw.exe to be available.

The ProwcApp Editor requires bin/prowcappeditor.exe to be available.

7. Source Files
This tool uses the following source files:

Note: Files flagged with an asterisk (*) identify procedures that cannot be loaded into the AppBuilder because required temp-table definitions that have not been included in adettdb/TEMP-DB.df.

Source File Description
protools/_protool.p Sets up features for the palette defined in the ProTools Function Definitions.
protools/_protool.i Contains temp-table definition that holds function definitions.
adecomm/palette.w Creates a palette in a window, run by protools/_protool.p
protools/_runonce.i Onlyallows one copy of an applet that includes this file to be run.
*protools/_custmiz.w Customizationdialog box.
*protools/_custmi2.w Add/Updatedialog box for PRO*Tools customizations.
protools/_colorch.w Color Changer applet window.
*protools/_procfg.w Configuration Information applet window.
protools/_walker.w Control Hierarchy applet window.
protools/_dblist.w Database Connections applet window.
protools/_schlist.w Database Connections Schema detail window.
protools/_schdef.i Define temp tables to hold table, field and index information to be displayed by the Database Connections applet.
protools/_tbllist.p Returns a list of table names for a database, used by the Database Connections Schema detail window.
protools/_fldlist.p Returns a list of field names for a table in a database, used by the Database Connections Schema detail window.
protools/_idxlist.p Returns a list of index names for a table in a database, used by the Database Connections Schema detail window.
protools/_gettbl.p Stores table information into a temp-table record for use by the Database Connections Table detail window.
protools/_storarea.p Returns the storage area to protools/_gettbl.p.
protools/_getfld.p Stores field information into a temp-table record for use by the Database Connections Field detail window.
protools/_getidx.p Stores index and index information into temp-table records for use by the Database Connections Index detail window.
protools/_tblavbl.p Accepts a database name and field name and returns a logical value that indicates whether the table still exists in the database, used by the Database Connections applet.
protools/_fldavbl.p Accepts a database name, table name, and field name and returns a logical value that indicates whether the field still exists in the table, used by the Database Connections applet.
protools/_idxavbl.p Accepts a database name, table name and index name and returns a logical value that indicates whether the index still exists for the table, used by the Database Connections applet.
protools/_tbldetl.w Database Connections Table detail window.
protools/_flddetl.w Database Connections Field detail window.
protools/_idxdetl.w Database Connections Index detail window.
protools/_db_gw.p Used by the Database Connections applet to determine whether a database is a schema holder and if so, it returns comma-delimited lists of the foreign db names and their db types.
protools/_osprmt.p OS Prompt applet.
protools/_edfont.p Set Font 2 applet.
protools/_pwedit.p Editor applet.
protools/_ppmgr.w ProcedureObject Viewer applet window.
protools/_propath.w PROPATH Editor applet dialog box.
protools/_search.w PROPATH Editor File Search dialog box.
protools/_runfile.w Run Procedure applet window.
protools/_session.w Session Attributes applet dialog box.
protoools/_winmgr.w Window Viewer applet dialog box.
protools/_wabout.p Call to Windows ShellAbout.
protools/_scrcap.w Screen Capture applet window.
protools/_scrprtd.w Screen Capture printing options dialog box.
*protools/_v89conv.w SmartObject Upgrade Utility applet window.
protools/_v89conv.wrx WRX file for the editable combo-box in _v89conv.w.
protools/sort-dia.w SmartObject Upgrade Utility Sort Options dialog box.
protools/v89names.dat Data file used by the SmartObject Upgrade Utility to determine how code is converted.
protools/_convt89.p SmartObjectUpgrade Utility conversion procedure.
protools/makeflds.w SmartObject Upgrade Utility conversion procedure called by _convt89.p that generates a space-delimited list of fields from a comma delimited list of tables.
protools/_ppuscl.p Stub procedure of the Screen Scaling Utility.
adeuib/_ppuscal.w Screen Scaling Utility applet window.
protools/_proobjv.p Starts COM Object Viewer executable, bin\proobjvw.exe.
protools/waspartn.w Service Parameter Maintenance applet SmartWindow.
protools/dappsrv.w Service Parameter Maintenance SmartDataObject.
protools/vappsrv.w Service Parameter Maintenance SmartDataViewer for updating AppServer Partitions.
protools/vjmssrv.w Service Parameter Maintenance SmartDataViewer for updating JMS Partitions.
protools/_protgen.w Prototype Generator applet window.
protools/_asinfo.w AppServer Session Information applet dialog box.
*protools/_prospy9.w PRO*Spy applet window.
protools/_prowcapped.p Starts Progress Web Client Application Editor executable, bin\prowcappeditor.exe.
adexml/_xmlview.w XML Schema Mapping applet window.
protools/_prospy.w ADM1 PRO*Spy
protools/_msgcnt.w ADM1 PRO*Spy Number of Messages dialog box.
protools/_break.w ADM1 PRO*Spy Breakpoints dialog box.

8. Build Process and Requirements
Not Applicable

9. Execution Methods
PRO*Tools can be invoked by the ADE Standard Tools menu (adecomm/toolmenu.i and adecomm/toolrun.i) available from most ADE Tools.

10. Test Requirements and Strategies
Not Applicable

11. Supplementary Information
Not Applicable

11. Related Documentation
The following documents also provide additional information about the tool: