skip to main content
OpenEdge Development: ADM and SmartObjects
ADM1 to ADM2 Conversion Utility : Using the ADM1 to ADM2 conversion utility
 
Using the ADM1 to ADM2 conversion utility
Keep the following points in mind as you review this section:
*How you employ the conversion utility depends on your conversion strategy; for example, whether you attempt to convert all files at a single time, or choose to attempt only one directory and its related subdirectories at a time.
*Converting a file means the file is processed by the conversion utility and an attempt is made to convert the file to the ADM2 format; however, the utility cannot convert all files successfully. You will need to examine your conversion attempts and results, and manually perform additional changes to complete the conversion process. How little or how much manual clean‑up work is required for a given conversion attempt varies; to determine this adequately, you must examine the results and perform test routines. For information about manual conversions, see the “Errors and the conversion utility log file” section and the “Customizing the conversion utility” section.
This section discusses the following topics:
*Accessing the conversion utility
*Defining conversion options
*Building the list of files to process
*Performing the conversion
(including the conversion process and errors and the conversion utility log file)
*Reviewing conversion results
*Customizing the conversion utility
Note: Progress Software Corporation strongly advises you back up all files before performing any of the procedures described in this section.
Accessing the conversion utility
You access the conversion utility from the PRO*Tools Palette, by clicking on the SmartObject conversion utility icon, as shown in Figure B–1.
Figure B–1: SmartObject conversion utility icon
This opens the ADM1 to ADM2 SmartObject Conversion Utility window, as shown in Figure B–2.
Figure B–2: ADM1 to ADM2 SmartObject Conversion Utility window
This window has two main sections: an upper portion that defines directory and conversion options and a lower portion that displays specific file information relative to the conversion process.
Defining conversion options
In the upper portion of the Conversion Utility window, you specify file directory information, file filter specifications, and conversion options:
Table B–1 lists and describes the objects you use to set conversion options.
 
Table B–1: Setting up file conversion options
Object
Default value
User‑definable options
Directory fill‑in field
Current working directory
Any directory to which the user has read/write access.
Filter combo box
.w files
Any filter used to limit the files used. Other choices include *.w, *.*, or type in a set of filters.
Include Subdirectories check box
All files in all subdirectories (recursively) of the selected directory
Remove the checkmark to turn off this feature and enable only the files from the selected directory.
Compile after Conversion check box
Recompile all files after each conversion
Remove the checkmark to turn off this feature.
The upper portion of this dialog box also contains a Build File List button. This button is not used to set conversion options and is therefore discussed in the “Building the list of files to process” section instead.
To set up a converstion option:
1. In the Directory fill‑in field, specify the directory of the application to be converted.
The directory you choose to specify depends on your conversion strategy. For example, you might decide to convert an entire application, and therefore specify the root directory of the application. Alternatively, your strategy might be to specify only one directory at a time to convert.
Note: Any directory you intend to convert should be either part of the PROPATH or a subdirectory of a PROPATH directory.
2. Using the Include Subdirectories check box, indicate whether to convert files in the subdirectories (or any subdirectories at any lower levels) of the directory identified in
Step 1.
3. Using the Compile after Conversion check box, indicate whether to compile each file after the conversion attempt.
4. In the Filter combo box, specify the types of files to process.
Typically, you convert only .w files. This is because you are converting Version 8 SmartObjects, which normally have the .w extension.
Building the list of files to process
In addition to the objects noted in the previous section, the upper portion of the ADM1 to ADM2 SmartObject Conversion Utility window contains the Press the Build File List button. This button populates the browser located in the lower portion of the window according to the directory, filter, and conversion specifications you set, as described in the previous section. For example:
After pressing this button, be sure to review the files that display before you begin the actual conversion. The Files to Convert browser contains two display‑only fields:
*Status — Identifies the current status of a file. Status labels are described later in this section. The Not Conv status means the file was not processed since it was entered into the list.
*Name — Identifies the name of the file to be converted.
The amount of time required for the build process varies according to the number of files being prepared. If the build process takes several minutes (a likely situation when loading thousands of files), the browse query is opened to display the first screen full of files, and an overlay frame appears to identify the current directory that is being loaded and the current number of files being loaded.
Table B–2 summarizes the various activities that you can perform based on the file information in the Files to Convert browser.
 
Table B–2: Files in the browser
Status
Course of action
No further file changes are required.
Continue with the information in this section and bypass the information in the “Refining the file selections” section.
You need to modify (add or delete) files in the browser.
Go to the “Refining the file selections” section and return to this section when the changes are complete.
You do not want to continue building the list of files to process for the options defined.
Modify the conversion options in the upper portion of the window and press the Rebuild File List button. This action implements the new options, discarding the browser’s current file contents and repopulating it according to the new options.
You do not want to continue with the current list.
Press the Exit button.
Note: Once you press the Build File button, its text label changes from Build File List to Rebuild File List.
Refining the file selections
Before converting, you can refine your file selection using any of the three additional options that are available by using the three buttons to the right of the browser. Table B–3 identifies these options and the functionality they support.
 
Table B–3: Refining file selection actions 
Button
Description
Sort...
Changes the displayed sort order of the files in the browser from the Sort Options dialog box. The sort options are Status, Name, and Extension. The sort order also determines the order in which the files are processed.
Add a File...
Adds individual files, one at a time, to the browser from the System File dialog box. (This is the only way to add files once the list of files to process has been built.)
Remove
Removes one or more files from the browser. You select the files and then press the Remove button.
Performing the conversion
Progress Software Corporation strongly recommends that before you attempt a conversion as described in this section, you make a backup copy of all source files. This backup copy should be separate from and in addition to the original source files that are saved into the V8-ADM directory structure as described Step 1 below.
Press the Start Conversions button to initiate file conversion according to the sort sequence that you have established. You can convert only files whose status is shown as Not Conv.
Note: The conversion utility does not require the AppBuilder to be running because the utility converts by parsing the code; the files are not loaded into the AppBuilder. However, the application databases should be connected.
The Conversion Process
The conversion utility performs the following steps:
1. The utility moves the files from their current directory structure to a similar structure with a root name V8-ADM. V8-ADM is a subdirectory of the root directory originally defined in the Directory fill‑in field in the upper portion of the utility window. This structure always is created; if it already exists, it is overwritten.
Note: As previously noted, it is essential that you make a backup copy of all source files before attempting a conversion.
2. As each file is converted, the utility changes its status from Not Conv to ..., and concludes with ###-changes.
3. If an error occurs during the conversion process, the utility displays an error alert box that identifies the problem and prompts you to either stop the process (that is, do not attempt to perform any more file conversions) or continue with more files. Regardless of your choice, the utility attempts to convert the file that caused the error and marks its code with an &MESSAGE statement. The statement indicates that a problem occurred during the conversion of the file and notes that the file must be adjusted manually. (Most files require some manual intervention after conversion.) This message displays each time you compile the file, flagging it as untrustworthy until you correct the problem manually.
4. Once the conversion is complete, the utility replaces each original file that was copied to the V8-ADM directory structure with the corresponding converted file.
Note: To abort conversion processing, press the Abort Conversions button. The conversion utility finishes processing only the current file, stopping before the next scheduled file.
Figure B–3 shows how the Conversion Utility window might look once the conversion process is complete.
Figure B–3: Conversion Utility window after a conversion
Table B–4 identifies and describes possible status labels in this window.
 
Table B–4: Conversion status labels displayed in the browser 
Status
Description
No‑change
The file was converted, but no changes were made.
...
The conversion process is taking place.
###‑changes
The file was converted and some number of changes were made. (### represents a numeric value that identifies how many conversion‑related changes were made to a given file.)
Comp.Err.
After the conversion attempt, the compiler found some errors.
Version 9
The conversion utility determined that the file was either previously converted or was built as a Version 9 file, and therefore no conversion attempt was made.
Errors and the conversion utility log file
The conversion utility cannot handle all coding styles and possible code constructs. These situations require manual intervention. To facilitate this, the utility generates a log file named V89conv.log in your working directory. This log identifies what procedures were converted, approximately how many changes were made to the file, whether the file was compiled, and if the compiler encountered errors. Also, if the conversion utility determines it had difficulty converting a procedure, this log tries to capture that information and report where the problem occurred. For information on modifying the conversion utility, see the “Customizing the conversion utility” section.
Reviewing conversion results
This section describes the specific changes that occur when converting ADM1 SmartObjects to ADM2 SmartObjects. The changes it describes include ADM1-to-ADM2 SmartObject conversions, specific ADM file‑conversion changes, and additional conversion changes.
Table B–5 lists the ADM1-to-ADM2 9 SmartObject file conversions the conversion utility tries to perform.
 
Table B–5: ADM1 to ADM2 SmartObject conversions 
ADM1 SmartObject
Corresponding ADM2 SmartObject
ADM1 SmartWindow
ADM2 SmartWindow
ADM1 SmartDialog
ADM2 SmartDialog
ADM1 SmartFrame
ADM2 SmartFrame
ADM1 SmartBrowser
ADM2 SmartDataBrowser
ADM1 SmartQuery
ADM2 SmartDataObject
ADM1 SmartViewer
ADM2 SmartDataViewer
Table B–6 identifies specific ADM1-to-ADM2 file conversion changes.
 
Table B–6: Specific file conversion changes 
For this element . . .
All . . .
Are . . .
RUN DISPATCH
RUN dispatch [ IN hdl ]
  ( [ INPUT ]proc’ ).
Converted to:
RUN proc [ IN hdl ]
Or, if it is a local copy of itself:
RUN SUPER
RUN NOTIFY
RUN notify [ IN hdl ]
  ( [ INPUT ]proc’ ).
Converted to:
PUBLISH ’proc’ [ FROM hdl ]
GET-ATTRIBUTE
RUN get-attribute
  [ IN hdl ]
  ( [ INPUT ] )
attr’).
var=RETURN-VALUE.
Converted to:
var=[hdl:]getpropname ( ).
SET-ATTRIBUTE-LIST
RUN set-attribute-list
  ( [ INPUT ]
attr1=val1,
   attr2=val2, ... ’ ).
Replaced by:
{setpropname1  val1}
{setpropname2  val2}
A variable that contains a list is not converted. You must write your own get and set property functions for any customized attributes.
Some common ADM1 attribute names automatically are converted to the corresponding ADM2 property names (for example, Current-Page to Current Page), based on entries in the file protools/v89names.dat. You can extend this list as described in the “Customizing the conversion utility” section.
This list identifies operations that the conversion utility performs for all converted files:
*Removes the following prefixes from procedures and procedure dispatches:
*adm-.
*local-.
*broker-.
*Any custom prefix defined in protools/convt89.p variable cCustomPrefix.
*Replaces all strings found in the ++ Old Name column of protools/v89names.dat file with the corresponding string in the ++ New Name column.
*Removes all procedures and attribute references found in the protools/v89names.dat file ++ Remove List.
*Replaces local-exit procedures with exitObject procedures.
*Edits the ADM-SUPPORTED-LINKS preprocessor to reflect the Version 9 link types.
*When TABLES-IN-QUERY-... and ENABLED-TABLE-IN-QUERY... have more than one table, generates SECOND-TABLE-IN-QUERY-..., SECOND-ENABLED-TABLE-IN-QUERY-... preprocessors up to the TENTH-TABLE... .
*When converting a SmartViewer or SmartBrowser, generates an include file with a reasonably appropriate set of field definitions for the ADM2 SmartDataObject RowObject temp-table and flagged with an &MESSAGE statement to indicate that it should be replaced with an include file from an appropriate SmartDataObject.
*Removes external table definitions.
*If a procedure is dispatched inside of an instance of itself (for example, dispatching abc inside local-abc), converts this to RUN SUPER syntax.
*Converts Init-Object procedures to constructObject procedures. This includes the conversions of variable attributes to their ADM2 names. For example, Layout becomes ObjectLayout, Edge-Pixels becomes EdgePixels, SmartPanelType becomes PanelType, Right-to-Left becomes RightToLeft, and so on.
*Converts the procedure settings to the ADM2 format. These new formats are required by the AppBuilder to re‑establish the correct state when reading the .w file.
*Creates appropriate field definitions in the Runtime Attribute Settings when converting a Version 8 SmartQuery to an ADM2 SmartDataObject.
*Converts states based on the values of the cStateVals and cStateProps variables in the _convt89.p procedure.
*Removes the entire Method Library section and replaces it with the appropriate Version 9 include files based on the type of object to which it is being converted. The utility determines this by reading the ADM1 template type found in the Definitions section, as shown below:
 
Description:  from VIEWER.W - Template for SmartViewer Objects
If the utility does not find this line, the SmartObject cannot be properly converted. Be sure to restore the line in the Definitions section before attempting the conversion.
If a SmartObject has ADM1 custom method libraries you need to retain, you need to re‑insert them after the conversion. Generally, you have to convert these custom method libraries, as they might not work with ADM2.
Customizing the conversion utility
This section identifies the conversion utility source code and describes why you might want to access it to make modifications.
The source code for the conversion utility is shipped with the tool. This code was written in the AppBuilder and should be maintained in the AppBuilder. The procedure protools/convt89.p performs the majority of the conversion tasks; it has no user interface. This procedure is called by the protools/v89conv.w dialog, which contains most of the conversion utility user interface. Much of the conversion process is table driven from the protools/v89names.dat file.
Caution: Carefully review the contents of the protools/v89names.dat file to ensure that you know how the conversion utility will change your code. You can edit this file to ensure your customized code is not removed. For example, if you customized the state-changed internal procedure and do not want this procedure to be removed during the conversion, make the appropriate edit in the protools/v89names.dat file.
Generally, the conversion utility can fulfill most of the user’s conversion needs. If you need to perform a few one‑for‑one substitutions, however, you can do this by creating more entries in the ++ Old Name ++New Name section of the protools/v89names.dat file.
Note: Use caution when performing these one‑for‑one substitutions. The conversion utility checks each line of code in each of the files to be converted for each of these entries. Consequently, if you convert 1000 files and each file contains an average of 600 lines of code, each entry in this section causes 600,000 lookups.
The ++ Remove List section of the protools/v89names.dat file lists several attributes and procedures that are used in Version 8 but are obsolete in later versions. You can add to this list to remove occurrences of attributes and procedures that must be removed from the source files.
If you want to add or modify features in the conversion utility, you should study the code in protools/convt89.p and perform the changes. An easy change to make is to use custom prefixes (that is, prefixes other than adm‑ and local‑) for your ADM1.1 methods. You should edit protools/convt89.p and initialize the variable cCustomPrefix with your own prefix. For example, if your prefix is ajax‑, then you must give cCustomPrefix the initial value of ajax‑ (including the hyphen).
The ++ Method List section contains four columns:
1. The first column contains the ADM1 method name.
2. The second column contains the name of the ADM2 equivalent.
3. The third column starts with P if the method remains a procedure or FL if it is converted to a function that returns a logical data type.
4. The fourth column contains parameter information for the method. It is a quoted string containing comma‑delimited triplets, each of which includes the following components:
a. The first component is the parameter name.
b. The second component is the data type.
c. The third component, which identifies the parameter type, is either I for INPUT, O for OUTPUT, or I-O for INPUT-OUTPUT.
The triplets themselves are delimited by the vertical bar (|) character.