Method Libraries
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

1 Overview
2 Architecture
2.1 ADE Library Manager Object
2.2 Included-Libraries Code Section
2.3 Calling the Library Manager to Open Method Library Files
2.4 How the AppBuilder Uses Method Library Files
2.4.1 Method Library Dialog Box
2.4.2 Creating Local Overrides
2.4.3 Insert Call Dialog Box
3 Primary Data Structures
3.1 Variables
3.2 Temp-Tables
4 Primary Algorithms and Processes
5 Advanced Topics
5.1 ADE Object Manager and ADE Objects
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

A method library or primary include file is a structured Progress include file that is part of the standard set of ADM class files that are used to help define ADM objects and their behavior. This document describes how the AppBuilder opens, manages, and uses method libraries. Using method library files, the AppBuilder can add method libraries to a procedure, create local override procedures and functions for super procedures, and insert procedure and function calls into code sections.

Note: The term "method library" is used synonymous with the term "primary include file" throughout this and other Progress and Open Source documents as well as in the ADE Tools. Please see the Progress ADM 2 Guide for more details on method library or primary include files.

Note: ADM1 relied heavily on the procedures and functions defined in method libraries to provide a SmartObject's functionality. In ADM2, super procedures now contain most of those procedures and functions.

2. Architecture

A method library or primary include file is a structured Progress include file that is part of the standard set of ADM class files that are used to help define ADM objects and their behavior. A method library starts the super procedure for an ADM class, can initialize some properties, references the class property file, is referenced directly in a template or in another class' primary include file, and references the custom primary include file, if relevant.

2.1. ADE Library Manager Object

The AppBuilder uses a persistent ADE object, called the Method Library Manager object, to manage method libraries. It is also referred to as the Library Manager object. For more information on persistent ADE objects, see Section 5.1 “ADE Object Manager and ADE Objects”. The Library Manager object reads and manages method libraries and their code sections and handles requests from AppBuilder for information about them.

AppBuilder starts the Library Manager object during its own startup process with this call in _uibmain.p:

/* Initialize the ADE LIB-MGR Object. */

RUN adecomm/_adeobj.p ("LIB-MGR":U, INPUT-OUTPUT _h_mlmgr).

The Library Manager's ADE object name is "LIB-MGR" and its persistent procedure source file is adeshar/_mlmgr.p (This pairing is specified in the ADE object manager procedure, _adeobj.p). The AppBuilder defines its shared variable, _h_mlmgr, (in sharvars.i) to store the Library Manager's persistent procedure handle. This allows AppBuilder to reference the Library Manager object when making calls to the Library Manager's internal procedures and functions.

You can see the adeshar/_mlmgr.p persistent procedure running during an AB session using the Procedure Object Viewer Protool.

Note: You must turn off the Procedure Viewer's "Hide ADE Procedures" option to see the procedure.

2.2 Included-Libraries Code Section

Method Library file references are contained in the AB-maintained Included-Libraries code section of a structured AppBuilder file. Here is an example of an Included-Libraries code section:

&ANALYZE-SUSPEND _UIB-CODE-BLOCK _CUSTOM _INCLUDED-LIB Include

/* ********************* Included-Libraries ******************** */

  {src/adm2/smart.i}

 

/* _UIB-CODE-BLOCK-END */

&ANALYZE-RESUME

You use the AppBuilder's Method Library dialog box to add, remove, or modify references to method libraries for an AppBuilder procedure file.

2.3 Calling the Library Manager to Open Method Library Files

The Library Manager opens method library files when the AppBuilder performs either of the following actions:

While reading code sections from an AppBuilder procedure file, the AppBuilder checks if it is reading an Included-Libraries section. If it is, the AppBuilder calls the ADE Library Manager object (LIB-MGR, handle _h_mlmgr) to open all the method libraries referenced in that section. (See the Open Source AppBuilder information on "Opening .w Files".)

The AppBuilder calls the adeuib/_cdsuckr.p procedure to read code sections. Here is the call in _cdsuckr.p to open included libraries:

/* Call ADE LIB-MGR to open Included Library files. */

ELSE IF _TRG._tEVENT = "_INCLUDED-LIB":U THEN DO:

  IF VALID-HANDLE( _h_mlmgr ) THEN DO:

    RUN get-inclib-list IN _h_mlmgr ( INPUT  _TRG._tCODE ,

                                      INPUT  {&EOL},

                                      OUTPUT ml_inclibs ).

    RUN open-lib IN _h_mlmgr ( INPUT STRING( _U._WINDOW-HANDLE ) ,

                               INPUT ml_inclibs ).

  END.

END.

The call to the Library Manager get-inclib-list procedure passes in the Included-Libraries code block and a delimiter and receives back a comma-separated list of include file references, without the include braces. For example, in the code example in Section 2.2, Included-Libraries Code Section, the get-inclib-list procedure would return "src/adm2/smart.i" in the ml_inclibs variable.

Once the list of method library files to open is established, the AppBuilder calls the Library Manager procedure open-lib to actually open the specified library files. The AppBuilder uses the procedure file's design window widget handle (_U._WINDOW-HANDLE) to identify the parent object of the method library files to open.

2.4 How the AppBuilder Uses Method Library Files

The AppBuilder uses information in method library files to:

The sections that follow describe the technical and programming aspects of these uses in more detail.

2.4.1 Method Library Dialog Box

The Method Library dialog box is used to add, remove, or modify references to method libraries for an AppBuilder procedure file. It is accessed from the AppBuilder Procedure Setting’s dialog box. The adeuib/_mldlg.w procedure implements the Method Library dialog box. The file is an AB procedure file. Accessed from this dialog box is the Add/Modify Method Library References dialog box, implemented by the adeuib/_mlref.p procedure. It is used to add or modify a specific method library reference in an AppBuilder procedure.

The Method Library dialog box (_mldlg.w) set-init-values internal procedure builds a list of the included library names using this Library Manager call:

RUN get-inclib-names IN h_mlmgr (INPUT  p_Parent_ID ,

                                 OUTPUT p_Include_List ).

The call returns a comma-delimited list of included library names. The set-init-values procedure then adds include braces {} to the names and displays the include references in the dialog’s Method Libraries list.

When the dialog is closed, if any changes have been made, the Method Library dialog box closes and reopens the library owner object representing the procedure object using the following Library Manager calls:

RUN close-parent IN h_mlmgr (INPUT p_Parent_ID ).

RUN open-lib IN h_mlmgr (INPUT p_Parent_ID ,  

                         INPUT p_Include_List ).

By closing and reopening the library owner, the lists of procedures and functions used for local overrides and insert calls is rebuilt and any new super procedures are run, reflecting the latest method library and super procedure information.

2.4.2 Creating Local Overrides

The New Procedure and New Function dialog boxes are used to create local overrides of procedures and functions defined by a procedure object’s super procedures. These dialogs are accessed from the Section Editor’s “New” button. The adeuib/_newproc.w and adeuib/_newfunc.w procedures implement the dialog boxes. Both files are AppBuilder procedure files.

The New Procedure and New Function dialogs are called from the Section Editor’s NewBlock internal procedure. The NewBlock internal procedure calls the Get_Proc_Lists internal procedure to build a list of all procedures and functions that can be overridden. The Get_Proc_Lists procedure in turn calls the Library Manager’s get-saved methods and get-saved-funcs procedures to perform the actual building of the procedure and function name lists.

After accumulating the list of procedure and function names defined in the procedure object itself and all of it’s included method library files, NewBlock builds a list of super procedure handles and a name list of all procedures and functions defined in all super procedures run by the procedure object. The names list is combined with those defined by the object internally to create the complete list of procedures and functions that can be overridden (using either ADM1 “adm-“ to “local-“ prefixes or ADM2 override super procedure entries). The super procedure handles list and accumulated override list become part of the input parameters to _newproc.w. The code example below shows these calls as they occur in NewBlock for calling the New Procedure dialog box.

RUN get-super-procedures IN _h_mlmgr ( INPUT STRING(_SEW._hwin) ,

                                       INPUT-OUTPUT Super_Procs ,

                                       INPUT-OUTPUT Super_Handles).

RUN get-super-procs IN _h_mlmgr (INPUT Super_Handles ,

                                                      INPUT-OUTPUT Smart_List).

RUN adeuib/_newproc.w ( INPUT Super_Handles   ,

                        INPUT new_command     ,

                        INPUT Smart_List      ,

                        INPUT Invalid_List    ,

                        INPUT-OUTPUT new_name ,

                        OUTPUT Type           ,

                        OUTPUT Code_Block     ,

                        OUTPUT a_OK           ).

The _newproc.w call returns the following information:

If the type of procedure to create is a standard procedure, then the code block returned is null and NewBlock calls adeshar/_coddflt.p to generate standard code for the new procedure. Otherwise, the type of procedure to create is an override of a super procedure internal entry and the code block returned is the override code generated by _newproc.w.

NewBlock performs a similar set of calls to the Library Manager object to build lists of super procedure function names and procedure handles that are passed as input parameters to the New Function dialog box’s adeuib/_newfunc.w procedure. Those calls are show here:

RUN get-super-procedures IN _h_mlmgr ( INPUT STRING(_SEW._hwin) ,

                                       INPUT-OUTPUT Super_Procs ,

                                       INPUT-OUTPUT Super_Handles).

RUN get-super-funcs IN _h_mlmgr (INPUT Super_Handles ,

                                 INPUT-OUTPUT Smart_List).

RUN adeuib/_newfunc.w ( INPUT Super_Handles   ,

                        INPUT new_command     ,

                        INPUT Smart_List      ,

                        INPUT Invalid_List    ,

                        INPUT-OUTPUT new_name ,

                        OUTPUT Type           ,

                        OUTPUT Returns_Type   ,

                        OUTPUT Define_As      ,

                        OUTPUT Code_Block     ,

                        OUTPUT a_OK           ).


The _newfunc.w call returns the following information:

Since function code blocks are built by the _newfunc.w procedure, no call to _coddflt.p is necessary.

The returned information is then used by procedure NewBlock to create the appropriate _SEW_TRG record, which ultimately becomes and _TRG code section record.

2.4.3 Insert Call Dialog Box

The Insert Call dialog box is used to insert procedure and function calls into code sections using the Section Editor. The adeuib/_inscall.w procedure implements the Insert Call dialog box.

Note: The adeuib/_inscal8.w procedure implements the Insert Call dialog box for version 8 ADM1 calls. Both files are AppBuilder procedure files.

The Insert Call dialog box is called from the Section Editor’s InsertProcName internal procedure, which calls the Section Editor’s build_proc_list and build_func_list procedures to build separate lists of all procedure and function names defined by the procedure object. InsertProcName also calls the Library Manager’s get-saved methods and get-saved-funcs procedures to add procedure and function names defined in method library files to the name lists.

In addition to accumulating lists of procedure and function names defined in the procedure object itself and all of it’s included method library files, InsertProcName builds a list of super procedure handles and super procedures names run by the procedure object. This is accomplished with a call to the Library Manager’s get-super-procedures procedure. The super procedure handles and names are combined to create a paired objects list. All the lists are then passed to _inscall.w to display the Insert Call dialog box. Here are those calls from InsertProcName:

/* Build a list of the object's Super Procedures and add them to

   the Objects list. */

RUN get-super-procedures IN _h_mlmgr ( INPUT STRING(_SEW._hwin) ,

                                       INPUT-OUTPUT Super_Procs ,

                                       INPUT-OUTPUT Super_Handles).

DO iItem = 1 TO NUM-ENTRIES(Super_Handles):

  ASSIGN hSuper_Proc = WIDGET-HANDLE(ENTRY(iItem, Super_Handles )).

  IF NOT VALID-HANDLE(hSuper_Proc) THEN NEXT.

  ASSIGN Objects = Objects + "," + hSuper_Proc:FILE-NAME + " " + STRING(hSuper_Proc).

END.

RUN adeuib/_inscall.w

    (INPUT  Objects ,

     INPUT  This_Methods ,

     INPUT  This_Funcs   ,

     INPUT  Super_Handles,

     INPUT  Proc_Id,

     OUTPUT Command      ,

     OUTPUT Return_Value ,

     OUTPUT OK           ) .

The InsertProcName procedure uses the return values to create an appropriate code section record.

3. Primary Data Structures

AppBuilder and the Library Manager use a combination of variables and temp-tables as the primary data structures to manager method libraries.

3.1 Variables

The following table lists several important variables used throughout the Library Manager code that are defined by the Library Manager:

Table 1 - Key Variables Defined by Library Manager

Variable Name

Data Type

Description

Tag_*

Character

Tag_* variables are various code tokens or tags found in AB structure files that indicate certain code sections and code blocks. Library Manager uses them during code processing/parsing.

Type_Include_Lib

Character

The string " _INCLUDED-LIB " the Library Manager code uses to parse and search for an Included-Libraries section within a library file. Used for reading and opening nested included library references.

Tag_RunSuper

Character

The string " RUN start-super-proc" the Library Manager code uses to parse and determine if it should run an ADM super procedure.

The following table lists several important shared variables defined by AppBuilder in adeuib/sharvars.i that are used in managing method libraries and the Library Manager.

Table 2 - Key Shared Variables Defined by AppBuilder (sharvars.i) for LIB-MGR

Variable Name

Data Type

Description

_h_mlmgr

Handle

Procedure handle of the Method Library Manager. See OpenSource Method Library Manager Guide for more information.

3.2 Temp-Tables

The temp-table _LIB-OWNER cross-references an owning procedure file (an _P) and all its referenced library files (_LIB). The following table describes the fields in _LIB-OWNER.

Though several procedure object files can be open in the AppBuilder with include references to the same method libraries, only one _LIB record is created for each method library. This reflects the same structure as Progress source files and includes. Each reference represents an owning reference and one _LIB-OWNER record is created for each reference. If the references are to the same method library file, only one _LIB record is used to represent that library file.

Table 3 - Fields of the _LIB-OWNER Temp-Table

Field Name

Data Type

Description

_PARENT-ID

Character

ID of parent object. AB uses design window widget handle (_U._WINDOW-HANDLE).

_ORDER

Integer

Number used in an index to preserve the order in which a library file references are read.

_LIB-FILE-NAME

Character

Full pathname of the library file.

The temp-table _LIB represents all library files currently open in the AppBuilder. Only one _LIB record is created for each method library. The following table describes the fields in _LIB.

Table 4 - Key Fields of the _LIB Temp-Table

Field Name

Data Type

Description

_FILE –NAME

Character

Name of the library file as it is used in source code or as it is opened by the AppBuilder.

_FULL –PATHNAME

Character

Full operating system pathname of the library file.

_SAVED-SMART-METHODS

Character

Comma-delimited list of ADM smart method (event procedure) names defined in a method library file. These procedures are prefixed with “adm-“ and are primarily defined in ADM1 method library files.The Section Editor calls LIB-MGR procedure get-saved-methods to retrieve this list when displaying the Insert Call and New Procedure dialog boxes.

_SAVED-ALL-METHODS

Character

Comma-delimited list of all procedure names defined in a method library file.

_SAVED-ALL-FUNCTIONS

Character

Comma-delimited list of all function names defined in a method library file.

_SAVED-SMART-FUNCTIONS

Character

Comma-delimited list of all ADM smart function names defined in a method library file. These functions are prefixed with “adm-“ and are primarily defined in ADM1 method library files. No smart functions were defined for ADM1 method library files.

_LOCAL-TEMPLATE

Character

Field not used.

_METHOD-TEMPLATE

Character

Field not used.

_SUPER-PROCS

Character

Comma-delimited list of super procedure names the method library runs.The Section Editor calls LIB-MGR procedure get-super-procedures to retrieve this list and a list of the running super procedure handles when displaying the Insert Call and New Procedure dialog boxes.

Temp-table _CODE-SECTION is all the code sections read from all the library files currently open in the AppBuilder. Only the AB-maintained Included-Libraries code sections are actually read. They are the only code sections actually used by ADE code and only reading them increases the speed of opening library files. The following table describes the fields in _CODE-SECTION.

Table 5 - Key Fields of the _CODE-SECTION Temp-Table

Field Name

Data Type

Description

_LIB-RECID

Recid

Recid of the _LIB record that owns the code section.

_ORDER

Integer

Number used in an index to preserve the order in which code sections are read. Ensures Included-Libraries sections are maintained in correct order.

_PARENT-NAME

Character

Name of parent widget for the code block.

_TYPE

Character

Type of AppBuilder code section. Example: _CUSTOM or _CONTROL.

_NAME

Character

AppBuilder widget name owning the code section. Example: btn-OK.

_CODE-BLOCK

Character

Stores a code section’s code.

4 Primary Algorithms and Processes

Not Applicable.

5 Advanced Topics

5.1 ADE Object Manager and ADE Objects

ADE tools can use the adecomm/_adeobj.p procedure (also referred to as ADE object manager) to start and get the handle of a persistent ADE object. A persistent ADE object is a persistently running procedure that the ADE tools start and call to support ADE-related functionality.

The ADE object manager’s _adeobj.p procedure has two parameters:

Parameter

Description

INPUT p_Object_Name

String Identifying the ADE Object to run.

INPUT-OUTPUT p_hObject

Persistent Procedure Handle of the requested object.

Each ADE object processed by _adeobj.p has a string, called its object name, used to uniquely identify it. The _adeobj.p procedure defines a list of object names and the source file references needed to run them. A caller then passes the object name and receives back that ADE object's persistent procedure handle. If caller happens to pass the correct handle for the object, the same handle is passed back. Otherwise, the ADE object manager traces the session's persistent procedure chain looking for a persistent procedure whose file name reference matches that of the ADE object requested. If one is found, that persistent procedure's handle is returned. If no file name match is found, the ADE object manager runs the ADE object's source file persistently and returns its handle.

6 Dependencies

Not Applicable.

7 Source File

There are three source files that implement most of the various aspects of managing method libraries. They are briefly described here:

Source File

Description

Adeshar/_mlmgr.p

ADE Method Library Manager or Library Manager object procedure. This is the Library Manager object used to read and manage method libraries and their code sections and handle requests for information about them. You can see this persistent procedure running using the Procedure Object Viewer protool when the AppBuilder is active.

Note: You must turn off the "Hide ADE Procedures" option to see the procedure.

Adeuib/_mldlg.w

Method Library dialog box procedure. Used to add, remove, or modify references to method libraries for an AppBuilder procedure file. This file is itself an AB procedure file.

Adeuib/_mlref.p

Add/Modify Method Library Reference dialog box. Used to add or modify a specific method library reference in an AppBuilder procedure.

8 Process and Requirements

Not Applicable.

9 Execution Methods

Not Applicable.

10 Requirements and Strategies

Not Applicable.

11 Supplementary Information

Not Applicable.

12 Related Documentation

Anyone working with the Method Libraries should read the following related documents: