Integrating Code Back into Your Program

The final step in the conversion process is integrating your new graphical screens back into your program. This step typically takes the most time and may require some program changes. In some cases, the changes can be extensive. The amount of work you have to do depends on the original state of your program. The process is made somewhat easier because the new screen refers to your program's variables and embedded procedures where applicable.

There is no single correct way to do this step, and no procedure that works for every case. Instead, you have to evaluate your program to see how it can best interact with the updated screen. In the simplest case, the integration process consists of putting the new code in place and commenting out the old code.

When you're integrating the new code, you should analyze your application's:

Data Characteristics

Even though the concept of the Character-to-GUI Wizard is display oriented, you must understand the relationship between the screen and the data. For instance, you should verify that the fields on your new screen are matched with the fields in the FD or working-storage. You should also verify that embedded procedures are associated with your screens and its fields correctly.

In addition, if you've done things like create data sets, then you have to be aware of the fact that you generated code that opens files on initialization. If you don't need those files open, you should deselect OPEN in the definition of the data set.

Keyboard Characteristics

When integrating your new screen code, you must also be aware of your program's keyboard characteristics. If your application instructs users to press a function key and you want to implement this functionality with a push button, you have to know what exception value that key produces and you have to match the same exception values to your screen's new push buttons.

If you printed your cblconfig file or the section of code that contains environment settings before conversion, you should be able to easily locate the KEYSTROKE settings.

Display Characteristics

The most important element of the conversion is your application's display characteristics. In general, the conversion process results in a set of new DISPLAY statements that you must use in place of your old DISPLAY statements. There are several methods you can use to locate your old DISPLAY statements.

Once you know which DISPLAY statements correspond to which screen, you can begin replacing old code with new.

Where screens are displayed initially, you should comment out the old DISPLAY statement and replace it with a PERFORM statement that uses the following syntax:

     PERFORM Acu-[screen-name]-Scrn

For example:

    * display myscreen
     PERFORM Acu-myscreen-Scrn

This paragraph contains code to create a window, display the screen and its main menu on the window, and initialize any complex controls that have been included.

Where elements of screens are displayed (for example, with field-level DISPLAY statements), you should comment out the old DISPLAY statement and replace it with a MODIFY statement. For example:

    * display id-no-field
     MODIFY ID-NO-FIELD value Techhelp-ID

This is made easier because the wizard preserves the name of the Screen section element.

If your original program uses Screen section DISPLAYs and you have duplicated the name of the screen in the Screen Designer, then you may have very little work to do. However, you should replace the initial display window ERASE statement with the workbench-generated DISPLAY STANDARD WINDOW code in the .prd file.

Be sure to comment out non-Screen section DISPLAY statements if your program uses a combination of Screen section and field-level DISPLAY statements. DISPLAY LINE and DISPLAY BOX statements fall into this category. Comment them out.

ACCEPT Handling

Even though the generated code contains ACCEPT statements as well as DISPLAY statements, we recommend that you leave your application's ACCEPTs intact whenever possible. Where your application ACCEPTs screens, no conversion is necessary. (The screen name is already established by the wizard.)

However, where your application ACCEPTs variables, you should comment out the old syntax and replace it with an ACCEPT screen. You should then add an entry field to the screen whose value is the variable you were previously ACCEPTing. For example:

    * accept new-status

In this example, the screen, NEW-STATUS-SCREEN, contains an entry field whose value is new-status. The old ACCEPT is commented out and the new ACCEPT screen is added.

As a rule, you should examine your ACCEPT statements to determine whether they are ACCEPTing screens or variables, and therefore, whether or not you must perform any conversion.

Other Display Considerations

After you have made an initial pass through your application's ACCEPT and DISPLAY statements, you should consider how and whether your screens may be used differently in a graphical world than they were in a character-based world. For instance, it is a common practice in many character-based applications to use DISPLAY statements to redisplay a main screen whenever a field is updated. In the graphical world, it is impractical and unnecessary to recreate a window and redisplay an entire screen just to update a field. Therefore, you may want to use a MODIFY statement to update the field rather than the PERFORM screen.

In addition, in character-based applications, DISPLAYs are often made over existing DISPLAYs, in effect replacing the old DISPLAY with the new one. In graphical applications, controls must be explicitly destroyed or made invisible before other controls are put in the same space.

The way that a screen closes in a character application is also different from the way a screen or window is closed in a graphical application. For this reason, when you are replacing your DISPLAY statements, you should track where the screen closes or is blanked (a less obvious display event) and convert the close as needed. For example, you may replace a DISPLAY statement with a MODIFY statement in the following case:

    * display grow-scrn-1.

However, if you are using a pop-up window, your close event may specify close window handle-1. In this case, when you import the screen, all you need to do is give it a handle of handle-1 and no other conversion is necessary.

Another important difference between character and graphical applications is that character-based applications often dynamically build a screen one line at a time, but it is impractical to display elements line-by-line in the graphical world. Therefore, if your application DISPLAYs a variable in column 10, line 10, and then again in column 10, line 11, and so on, in the graphical world, this may be better accomplished through the use of a list box.

Finally, with a graphical application, you have the opportunity to display message boxes, combo boxes, and other graphical elements that you didn't have access to before. You can use the Screen Designer to add these elements whenever you're ready.

Initialization Sequence

When you generate code for a screen, a statement called perform acu-initial-routine is generated. The acu-initial-routine paragraph performs several functions, some of which you may want and some of which you may not. It performs an ACCEPT System-Information FROM System-Info and an ACCEPT Terminal-Abilities FROM Terminal-Info. In addition, it initializes fonts, bitmaps, and ActiveX resource files; creates menus; and opens files described in data sets. Your character application may already be performing some of these functions, but it isn't likely to perform all of them, and some, like initializing fonts, are critical in the graphical world.

As you are adjusting your original application for the new screen code, you need to make some decisions about what you want your application to do upon initialization. If you want all of the stated initialization routines to take place, you can leave the new perform statement in place, but you may need to remove old redundant code. If you want to perform some of the initialization routines but not others, rather than performing acu-initial-routine, you may prefer to call individual routines, like initialize fonts. In this case, delete the new perform statement and add the desired calls to your own sequence.