Converting from Dictionary-IV

OPENworkshop classes are based on Dictionary-IV structures. OPENworkshop methods can be written in either Script-IV or Thoroughbred Basic. Developers with applications that use Dictionary-IV are in a great position to move them to OPENworkshop.

Some changes will be required. This section outlines a recommended approach to moving an application to OPENworkshop, and details the necessary changes. The focus of this document is on code developed based on the Solution-IV source code models and development standards.

First, the benefits and advantages of the OPENworkshop development environment over Dictionary-IV are reviewed. Next, the process of moving your application code to OPENworkshop is detailed.

Differences between Dictionary-IV and OPENworkshop

A paradigm shift occurs when a developer moves from a 3GL/4GL based development environment to an object-oriented environment. This shift occurs in moving the developer’s focus from the programs to the actual data itself. Rather than designing a program, which performs a series of procedures and functions on data files, the focus moves to the data, files themselves and interactions between these files. Many programs in OPENworkshop are tied directly to the individual data element itself at the format level.

Moving to OPENworkshop

The following subsections describe changes that must be made to existing specifications and code when moving to OPENworkshop. For more information on how to change existing features, please refer to the following sections.

Formats: No changes are required to any format definition you have already developed. You will probably wish to take advantage of the additional facilities available, particularly to add pre-processing and post-processing functions.
Links: No changes are required to any link definition you have already developed. You will probably wish to take advantage of the additional facilities available, particularly to add pre-processing and post-processing functions.
Menus: OPENworkshop allows you to use pop-up menus. You will probably wish to convert many of your menus to OPENworkshop pop-up menus. RUN”OO” and select the Utilities option. For more information see the OPENworkshop Main menu.
Views: Existing Dictionary-IV views are automatically converted to OPENworkshop Views. You will probably decide to modify your existing views to take advantage of the greater flexibility of OPENworkshop views.
Screens: No changes are required to any screen definition you have already developed. Screen definitions that are not already windowed must be converted to windowed screens. For more information see the Dictionary-IV Administrator Guide (Dictionary-IV Supplemental Utilities).
Reports: No change is required for existing reports.
Queries: No change is required for existing queries.
Help: No changes are required to any help definition you have already developed. Help definitions that are not already windowed must be converted to windowed help. For more information see the Dictionary-IV Administrator Guide (Dictionary-IV Supplemental Utilities).
Scripts: These will need to be changed to reflect OPENworkshop requirements, as described in the following sections.
Thoroughbred: These will need to be changed to reflect OPENworkshop requirements, as
Basic programs: described in the following sections.

The process of moving to OPENworkshop basically involves cleaning up certain types of undisciplined code. This requires removing the following types of code:

Code that performs manual window manipulation.
PRINT @ commands
INPUT commands that do not use the dictionary
WINDOW commands
RUN statements

The process of changing this type of code is explained in detail below and has been divided into two phases, Phase I and Phase II. For more information, please refer to the following two sections.

Phase I Changes

The following changes are performed in Phase I and are required when moving to OPENworkshop:

Creating OPENworkshop Menus

OPENworkshop gives you the capability of using pop-up menus rather than the full screen menus as in Dictionary-IV. The OO program can be run using the command:

RUN”OO”

To convert your Dictionary-IV menus to OPENworkshop list box menus select Utilities then select Build List Box Menus. Enter the 2-character Library name or names (separated by commas) or enter the 2- character Library name and menu name or names (separated by commas).

[SH:][L1,L2,Ln]

[SH:][LLM1,LLM2,LLMn]

Where:

SH is the sub-heading
Ln is a specific library name
LLMn is a specific library and menu name.

These menus are converted while honoring any existing VIP menu headings thus creating a different List Box menu for each menu heading

The system creates help modules matching the screen menu name and overwrites help modules with like names. It creates multiple help names for screen menus containing sub-headings. A menu help module will be created containing the sub-headings and another one containing the selections that are subordinate to each sub-heading. The help module names will be:

LL    LLMM, LLMM0, LLMM1, LLMMn
LLM1 LLM1, LLM10, LLM11, LLMMn

Windowed Screens

Two types of screens exist in Dictionary-IV – standard (non-windowed) screens and windowed screens. When running under OPENworkshop it is necessary to convert any standard screens to windowed screens first. One reason is that when running under the OPENworkshop environment, you are never actually in the main window (WINDOW 0). Also, each method cleans up all windows created by the method and all files opened by the method. It does this by saving the window list and data file channel list when the method is initiated and deleting all windows and closing all files not on these lists when the method terminates.

As an added benefit, windowed character-based screens may be defined which use custom colors as well as a variety of graphic characters.

All screens in your application can be converted to windowed screens using the Window Conversion Utilities found on the Dictionary-IV UTMENU11 menu Dictionary-IV Supplemental Utilities menu), then selecting Convert Screens Into Window Format. For more information see the Dictionary-IV Administrator Guide.

Windowed Help

Because of the issues mentioned above regarding windowed screens, all help should be converted to windowed help as well. Use the Dictionary-IV UTMENU11 menu (Dictionary-IV Supplemental Utilities menu), and then select Convert Help Text Into Window Format. For more information see the Dictionary-IV Administrator Guide.

Programs

Programs in OPENworkshop are called methods. It is important to understand that all methods in OPENworkshop are actually public programs. The following paragraphs outline the differences between Dictionary-IV scripts and OPENworkshop methods.

Script methods (type S) are similar to primary scripts (type 1) in Dictionary-IV. Most menu options initiate type S methods. These are the most common methods used in OPENworkshop development.

Thoroughbred Basic methods (type M) are similar to Thoroughbred Basic programs in Dictionary-IV. See the next section for converting Thoroughbred Basic programs to type M methods.

Continuation scripts (type 2) differ in OPENworkshop only in that they are now called as public programs. When the OPENworkshop compiler encounters a RUN program-name command that specifies a type 2 script, it will automatically generate a CALL to the script followed by an exit to the OPENworkshop menu system. This works fine as long as your continuation script always returns to the menu.

However, if your continuation script re-runs your primary script, you can quickly run out of memory because of recursive calls. To fix this problem, see the section on Changing RUNs below.

Overlay scripts (type 3), continuation scripts (type 2), and public scripts (type 6) work in the same way as under Dictionary-IV.

BEGINs, Thoroughbred Basic Public Programs, Hard-Coded Channels

Although not a problem for script developers, any Thoroughbred Basic program that does a BEGIN must be changed. These Thoroughbred Basic programs should be converted to type M methods. The process for doing this is as follows:

First, change the script type from B (Thoroughbred Basic) to an M type method.

Second, change the beginning of the method to read as follows:

METHOD A$,B$,C$ (or whatever variables are on ENTER list)
(documentation can go here without the need for an
 exclamation (!) point.)
.... (signifies the start of the actual program code)

Third, remove any general SET ESC and SET ERR logic at the beginning of the program. All methods generate their own escape and error logic automatically. Finally, to exit the method, change your exit to the following:
```
GO TO CUEXIT
```
CUEXIT is a standard routine, which will close all channels opened by the program, delete any windows, which were created, and set the precision back.
Fourth, remove any hard-coded channels that are used. Instead of opening the file on a hard-coded channel, use the UNT function as follows:
```
C3=UNT;
OPEN (C3) "<file-name>"
```
Last, recompile all methods using the OPENworkshop Source-IV compiler.

Note: Any formats you use can be included with an FN declaration immediately following the word

METHOD. This will include the format with the OPT=“NONE” option.

Changing RUNs

Because there is no main program in OPENworkshop, every method may be thought of as a self-contained public program, it is illegal to perform a RUN program-name command from anywhere in your application. At first, this sounds like an arbitrary restriction, but looking closer, we see that these RUN commands can be easily replaced. This is shown in several different examples.

First, consider the example of a period end update process. Here, you have a primary script (type 1) that chains to subsequent continuation (type 2) scripts by using a RUN directive. In most cases, these will not have to be changed at all, other than changing the type 1 script to a type S method.

The OPENworkshop script compiler actually translates these RUNs into a CALL to an ENTER-less public program automatically. An ENTER-less public is a public program with no ENTER statement. When you call a public in this way, all 4GL and 3GL variables are passed by reference into the public program. In addition, any channels you have open are kept open. Essentially, the entire environment is made available to the called program. When the called program terminates, the calling program automatically exits. This all works perfectly as long as you don’t chain through more programs than you have available memory to load all of these programs simultaneously.

Next, consider the same example, only the script we are chaining to has a different environment area and is a type 1 or type U script. There are two different approaches, which can be taken with these situations.

First, the scripts you are chaining through can each be changed into a type 6 public script with an ENTER statement containing no variables. Then, the calling program simply calls each of these publics in succession.
Alternately, you can change the scripts you are chaining through to type S methods. Each RUN would then be replaced with the following code:
```
CLOSE ALL (this closes all open channels)
CONNECT METHOD "chain to prog name"
```

Next, consider a typical data entry program. Here a primary (type 1) script RUNs a series of continuation (type 2) scripts depending on what the user selects. Typically, the header portion is handled by one script, the lines by one script and the summary screen by another script. Remember that the script compiler translates each of these RUNs into a CALL. Obviously, these must be changed or you will run out of memory after entering only a few transactions.

Again, the change here is relatively simple. Each of the RUNs in the continuation scripts is changed to set a flag and do a TERMINATE instead of a run as follows:

LET #TAFINST1.INST-LINE-CONTROL = "1"
(1 for header, 2 for lines, 3 for summary)
TERMINATE

Then, in the lead script a routine is used to control which program should be called as follows:

LET #TAFINST1.INST-LINE-CONTROL = "1"
LET STATUS = ""
DO LOOP UNTIL #TAFINST1.INST-LINE-CONTROL = " "
LET P$ = "ARPIDAT" + #TAFINST1.INST-LINE-CONTROL
CALL P$
ENDLOOP

The reason the above code contains a CALL P$ instead of the original RUN P$ is that the script compiler will automatically TERMINATE after a RUN. Thus, our loop variable would never be checked, and it would automatically exit as soon as one transaction was entered.

One function that comes in handy is TCB(13). This function will return the public program level at which you are currently running. For example:

IF TCB(13) THEN
   TERMINATE
ELSE
   RUN "ARPCUST0"
ENDIF

Changing RUN “ID” to TERMINATE

Our next example of a RUN is where we are returning to the menu. Doing a TERMINATE in OPENworkshop will return you to the calling program if you are in a script or method that was called by another script. Once you are back to the original method initiated from the OPENworkshop menu, a TERMINATE will return you to the menu just as it does in Dictionary-IV. All RUN “ID” statements should be changed to TERMINATE.

Changing RUN “IRPCA0” to CONNECT REPORT

This code was used in Dictionary-IV to chain from a script to a Report-IV report. Again, the RUN is not allowed. All RUN “IRPCA0” statements should be changed to use the CONNECT REPORT directive as follows:

CONNECT REPORT "report name"

In addition, often a program was RUN in the T lines at the conclusion of a report. These termination lines should be removed and the script that drives the report should simply CONNECT REPORT to each report in the sequence of reports to print. At the end of the CONNECT REPORT sequence, the update program can be initiated using a CONNECT METHOD.

Saving Format Changes in Report-IV

In order to make Report-IV extensible, Report-IV will attempt to put back all formats to their initial value when the report was started. This may cause problems if you actually want to change a global format data element. If you want to change a format, after setting the format value, you must assign the bracket variable to the format. For example, to change a variable in #TAFINST1, do the following:

LET #TAFINST1.INST-PRINTER-ID = "LP"
LET ]TAFINST1$ = #TAFINST1

This sample code will save the data in format #TAFINST1 that you have changed.

Changing RUN “IDVIEW” to CONNECT VIEW

IDVIEW is used in Dictionary-IV to chain from a script to a multi-record maintenance view. Since RUNs are not allowed in OPENworkshop, these statements should be changed to use the CONNECT VIEW directive as follows:

CONNECT VIEW "view name"

Removing WINDOW DELETEs

A WINDOW DELETE directive was often required in Dictionary-IV to clear a windowed screen. Under OPENworkshop, because of the way the environment cleans up when exiting a method, these WINDOW DELETEs are simply not needed. Further, because of the recursive nature of OPENworkshop, you could actually run Invoice Entry from Invoice Entry. In the second instance of Invoice Entry, the window names are not the same as the screen names and a WINDOW DELETE directive will cause serious problems.

WINDOW DELETE ALL and PRINT ‘WC’

As mentioned before, since you are never in the main window (window 0) while running an
OPENworkshop application, both of these directives should be avoided.

WINDOW SELECT and WINDOW SELECT (NOUPDATE)

As mentioned previously, an OPENworkshop method cleans up all windows created when the method terminates. Any WINDOW SELECT (NOUPDATE) directives you are using should be removed. Otherwise, when the method exits, the environment will not be aware of anything displayed in a window with the NOUPDATE option, and thus will not be able to clean it up. You will experience display problems when you return to the menu.

Also, WINDOW SELECT (“window name”), even without the NOUPDATE option, should be avoided for the same reason as WINDOW DELETE above. That is, the window name will no longer be the same as the screen name beyond the first instance of the program.

PRINT @ (C,L)

Although the PRINT @ command is still supported by OPENworkshop, this code is not supported when using GUI screens. This is because there is no one-to-one correspondence between a Thoroughbred Basic @ position and the pixel locations on a GUI screen. The data you are printing should be put into a screen formula and the PRINT @ should be replaced with:

PRINT SCREEN screen-name FORMULAS

INPUT @ (C,L)

As with PRINT @, the INPUT @ should be replaced with

INPUT SCREEN screen-name DATA-NAME LIST

PRINT ‘CE’

The ‘CE’ mnemonic that clears from the cursor position to the end of the screen can cause problems in two areas.

A GUI screen has no way of dealing with this mnemonic or any other mnemonic, which prints data or manipulates the screen presentation.
The screen color attributes will be lost for the area of the screen, which is cleared if running in character mode.

Instead, you should use the PRINT SCREEN DATA and PRINT SCREEN DATA CLEAR directives to display and clear screen information.

Phase II Changes

Phase II changes are aimed at helping you reduce the amount of procedural code required to perform various functions in your application.

CONNECT VIEW versus PRINT VIEW

Changing your PRINT VIEWs to CONNECT VIEWs provides a significant increase in flexibility to your application. A CONNECT VIEW can be made to look like a PRINT VIEW with the added benefit that the user can change the view on the fly without changing the underlying code or recompiling any programs. In addition to changing the columns defined in the view, the location and size of the view may also be changed.

CONNECT SCREEN versus INPUT SCREEN

As mentioned previously, OPENworkshop provides several major classes that can reduce the amount of procedural code in your application substantially. By restructuring your data entry programs so they are built around CONNECT SCREEN instead of INPUT SCREEN, you can eliminate a lot of duplicate code. The reason is that this code is tied to the format data element name to which it applies instead of existing in many different programs that operate on this particular data file.

CONNECT VIEW versus INPUT SCREEN LINE OFFSET

In the same way as CONNECT SCREEN, CONNECT VIEW can eliminate a great deal of complex code that was built for header/line entry using INPUT SCREEN LINE OFFSET. All of the flow control code for line item entry is built into the CONNECT VIEW class and can be eliminated from your application. In addition, the I/O triggers contain the code to update the individual files and the INSERT METHOD command handles the line insert logic. This greatly simplifies the line entry process.

Inquiry Programs

Inquiry programs can be re-implemented eliminating virtually all of the program code while at the same time adding functionality. Again, this is due to the power of CONNECT. The inquiry can begin with a masterfile view such as a customer view, which allows selection of a particular customer. From here a pop-up menu can be displayed which shows various inquiry options. From each inquiry option, a CONNECT VIEW can be displayed with further access options for each of these records.

Using the Graphical User Interface

Much of what you need to do to use the graphical user interface is covered in the previous sections on converting to OPENworkshop. The following list summarizes the rules that must be followed when verifying that your application will run with the GUI:

Verify that you are not doing any direct Thoroughbred Basic PRINT @’s or INPUT @’s in your code.
Avoid WINDOW DELETE, WINDOW CREATE, and WINDOW SELECT directives.
Convert all screens and help text to windowed format if using standard format.
Make sure OPEN SCREENs and all PRINT SCREENs are at the same public program level.

From the OPENworkshop Reference, version 8.9.1. Open this page in the PDF