The source modules must be saved into the Oracle Forms 4.5 tables although this version allows source forms to be saved either in the file system or database.
If you already have an Oracle Forms 4.0 GUI application, you can easily move your application following the instructions in the section "Using Oracle Forms 4.0 GUI Applications in Oracle Forms 4.5".
If you have a character-mode application, there are four options open to you.
These options are listed in increasing amount of effort needed to upgrade your application. You have to decide how you want your users to run the application and how much time and effort you can spend upgrading the application. The following sections describe these options in more detail.
There is no upgrade per se if you already have an Oracle Forms 4.0 bitmapped application. You only need to re-generate your forms, menus and libraries. This produces the runtime version of your applications.
You can create the upgraded Forms 4.5 module binary files by opening your modules directly in the Forms 4.5 designer and saving them. Before you create the binary files, you should make a backup of your existing modules because the Oracle Forms 4.0 designer cannot read any module saved in Oracle Forms 4.5 format.
Your applications will be functional immediately after re-generation. However, you should still test the application to verify that it works in the same way as before the upgrade. You are encouraged to add any relevant features listed in the "New Features" section.
This section gives you all the steps required to upgrade your character-mode application to the latest version of Oracle Forms to run in a character-mode environment.
There are three things to help you set up the environment and plan your upgrade process.
The source modules must be saved into the Oracle Forms 4.5 tables although this version allows source forms to be saved either in the file system or database.
Upgrading SQL*Forms 2.0, 2.3 or 3.0 character-mode applications to run in a character-mode environment is very straightforward. The following command is used to upgrade your forms:
f45gen <module-name> <username>/<password> upgrade=yes version=<version-number>
You have to substitute f45gen with the appropriate generate command for your platform. When upgrading version 2.0 or 2.3 forms, you also have to include the version parameter with a value of 20 or 23. To convert the box drawing characters in version 2.0, you need to have the original CRT file and use the parameter crt_file=vt220. If you do not have the CRT file, you will have to manually replace any desired box or line drawings using the layout editor after the upgrade.
The following figure shows the file formats and extensions used in Oracle Forms 4.5.
Form, menu and library modules are now stored in binary format by default from the designer. These binary files are portable across platforms. The executable is the runtime version of the module.
The upgrade produces both the binary and executable files. To only create the binary file, use the option generate_on_upgrade=no parameter. You can use the following command to get the corresponding text files (similar to an .INP file) after the upgrade:
f45gen <module-name> <username>/<password> logon=no script=yes
When upgrading either version 2.0 or 2.3 triggers, there is the option of having KEY-UP and KEY-DOWN triggers added which will replicate the functionality of the Previous Record and Next Record operations. This option may be selected by using the add_triggers=yes parameter.
Starting with SQL*Forms 2.3, macros issued in triggers had the ability to fail. When upgrading SQL*Forms 2.0 applications, it is necessary to use the parameter nofail=yes to add in the NOFAIL keyword after the #EXEMACRO predicate in all of the trigger steps to maintain the same behavior as in SQL*Forms 2.0.
There is no facility to upgrade your SQL*Menu 4.0 applications to Oracle Forms 4.5. You will have to upgrade the SQL*Menu 4.0 applications to SQL*Menu 5.0 before upgrading them to Oracle Forms 4.5.
For your SQL*Menu 5.0 modules, use the above commands with the additional parameter module_type=menu. The parameter generate_on_upgrade=no is also available for menu modules. You can use a wild-card character as part of the menu module name to upgrade multiple menu applications stored on the database. For example, the command below upgrades all menu applications that begin with "ap_" in the database and puts the upgraded applications back into the database:
f45gen ap_% system/manager module_type=menu upgrade=yes
SQL*Forms 2.0 and 2.3 applications do not have any menus associated with them. The default menu is added to these upgraded applications. Oracle Forms 4.5 implements menu security using the granted roles stored in the data dictionary. To upgrade menu security roles, a user who has database administrator (DBA) privileges (typically the SYSTEM user) must run the following command:
f45gen userid=system/manager upgrade_roles=yes
If the role already exists in the database, the users will simply be added to the existing role.
To grant a user access to base tables, a user who has DBA privileges must run the SQL script with the username as the first argument:
sqlplus system/manager @frm45grt.sql
You have to substitute sqlplus with the appropriate command for your platform. frm45grt.sql is found in the Forms' SQL directory.
The upgrade only makes the following changes to your applications:
V2-style triggers are still supported, although we do not recommend their use in future applications. You should instead use PL/SQL-style triggers. Oracle Forms does not modify your trigger code in any way.
There is one difference after the upgrade. In SQL*Forms 3.0, the ON-NEW-FIELD-INSTANCE trigger only fires when the user changes the cursor location. Therefore, your ON-NEW-FIELD-INSTANCE trigger can have built-ins that navigate out of the field, do something and then return to the field without the ON-NEW-FIELD-INSTANCE trigger firing in an infinite loop.
Oracle Forms 4.0 and 4.5 fires the WHEN-NEW-ITEM-INSTANCE trigger whenever the cursor changes location (not necessarily due to user navigation) and lands in that item. Appendix B shows some code you need to add to these WHEN-NEW-ITEM-INSTANCE triggers to resolve the problem.
With this change, your application will have exactly the same behavior as your original one in a character-mode environment. However, you should still test the application to verify that it works in the same way as before the upgrade.
In a bitmapped environment, users navigate using the mouse instead of function keys. Hence, any code for validation or block coordination that is based on key triggers will not be executed. However, most applications that run in character-mode environments make use of key triggers extensively. There are two ways to handle the situation - either disabling mouse usage in the form or disabling Forms' default navigation.
Before we get into the details of these two methods, we need to first upgrade the application using the instructions in the "Upgrading Character-mode Applications to Run in Character-mode Environment" section.
Because of the beveling used to produce a three-dimensional effect in a bitmapped environment, the text items may be one character shorter than your item length. You can choose to use a smaller font for your text items or you may want to use the widen_fields=yes parameter to add one more character to all your text items to compensate for this effect. This will however lessen the space that you currently have between text items by one character cell or cause the text items to overlap if they are currently flushed against each other. Our experience is that this is not a problem in most of our customers' applications.
This approach allows your users to run the upgraded application in a bitmapped environment. Your forms will behave in exactly the same way as in a character-mode environment - the users will not be able to click out of an item in the form with a mouse but will be able to use the mouse to select an item from the menu. The following is a list of things that needs to be done with this option.
Notwithstanding the Mouse Navigation Limit setting, the user always has access to the menu using the mouse. You can set the Mouse Navigation Limit to item level to prevent users from navigating out of an item in the form with the mouse. In this way, users will have to use the function keys to navigate in the form as in the existing application but have the option of using the mouse for menu selection.
This technique allows your users to run your applications in a bitmapped environment with minimal re-writing of your code.
This approach allows your users to run the application in a bitmapped environment using the mouse both for navigation and menu selection. This section describes the key issues involved, as well as solutions for this approach.
The first step is to analyze your application. You can print out all blocks and triggers in the application with the Action->Print Doc->Detail menu item in the SQL*Forms 3.0 designer. You will also need screen dumps of the application. With these, you can now create a diagram representing the form by drawing in the triggers on the screen layouts. An example of such a diagram is shown in Figure 4.
Figure 4 Application analysis You will notice that there are two sets of triggers in your application - non-key-triggers and key-triggers. Non-key-triggers and certain key-triggers do not present a problem when migrating from character-mode to bitmapped environment. An example of a key-trigger that does not present a problem after migration is KEY-HELP. There is no event that can be invoked with the mouse which would cause the Help screen to be displayed. This event can only be fired from either the keys, menu or another event.
However, key-triggers initiating navigation will present some problems after migration. An example is the KEY-NXTBLK trigger. This means that the user can click in an item in the next block with the mouse without the KEY-NXTBLK trigger firing.
Since triggers that do not initiate navigation cannot be invoked with a mouse, we do not have to change anything in the application for this set of triggers. However, you may want to create buttons and a toolbar in your application allowing your users easy access to these operations.
As we can see, only triggers that initiate navigation are the ones that will present us with some problems when moving an application from a character-mode to a bitmapped environment. There are eight of these triggers:
Based on this observation, we will suggest ways to replace your triggers. Since each application is unique, our suggestions are by no means exhaustive. However, we hope that they will give you a head start in your upgrade process.
You will need to first upgrade your application using the instructions in the "Upgrading Character-mode Applications to Run in Bitmapped Environment" section.
You may also want to convert the pop-up windows to stacked canvas-views using the instructions in the "Converting Pop-up Windows to Stacked Canvas-views" section to prevent users from moving or iconifying the windows.
The following are a few scenarios that are common in applications:
If that item is display-only, change it to a display item or change the Insert Allowed item property to false in the designer. Otherwise, you can use either of the following built-ins to dynamically disable items that you do not want users to update:
set_item_property ('item-name', ENABLED, PROPERTY_FALSE);
set_item_property ('item-name', INSERT_ALLOWED, PROPERTY_FALSE);
If the item is in a different block, you should put those items in a separate canvas-view, and use the show_view and hide_view built-ins to only display the relevant blocks and items.
This problem can be solved by disabling Forms' default navigation and wrapping some code on top of your application to perform the navigation. Please refer to Appendix A for more information.
If you decide to use the new relation objects and you have customized the generated key-triggers and procedures, Appendix C has a detailed list of the generated code. You will need to transfer your code to the new relation object.
If you have a single-record master block, the decision of using the new relation object is a matter of easing maintenance.
The code framework takes care of the WHEN-NEW-ITEM-INSTANCE trigger infinite loop problem discussed in the section "Upgrading Character-mode Applications to Run in Character-mode Environment" implicitly. Hence, you do not need the code given in Appendix B to resolve the problem.
You can also try to incorporate some new features described in the "New Features" section to improve user productivity. Finally, test the application to verify that it works in the same way as before the upgrade.
This approach requires a lot more effort than the previous one but allows your users to use the mouse to perform all operations in a bitmapped environment.
A content canvas-view is the "base" view and occupies the entire window in which it is displayed. A stacked canvas-view can be displayed in the same window as a content canvas-view and any number of stacked canvas-views. It can be anywhere on a window and usually hides certain portions of the window.
Pop-up pages are converted to content canvas-views in new windows in Oracle Forms 4.5. They behave in the same manner as running SQL*Forms 3.0 in a bitmapped environment. However you may have positioned pop-up pages to overlay certain parts of the screen. Now, these windows can be moved around or even iconified with the mouse which may destroy the effect you want. You can still achieve the same effect by converting these pop-up windows to stacked canvas-views by following the steps below:
Open the upgraded form module in the designer. For each window that you want to convert to a stacked canvas-view, click on the canvas-view in the navigator to change its properties in the property palette. Change the Canvas-view Type property to Stacked. Change the Window property to the window you want to display the stacked canvas-view. Change the Display X Position and Display Y Position properties to put your stacked canvas-view in the correct position after the upgrade. Remove any extraneous windows. It is important that you do not rename the canvases after the upgrade since any %_PAGE(1) in your code refers to a canvas-view named "PAGE_1". If you change the name of the canvas-view, you need to change the corresponding name used in your code.
In order for the application to look like and behave as in SQL*Forms 3.0, change the Displayed property of the canvas-view to FALSE. You can use the following built-in to show the stacked canvas-view:
show_view ('stacked-canvas-view-name');
When the user navigates out of the stacked canvas-view, you can hide it using the hide_view built-in. If all your items in the block are on the same canvas-view, write a POST-BLOCK trigger to hide the stacked canvas-view as follows:
hide_view ('stacked-canvas-view-name');
If your items in the block span multiple canvas-views, this code will be put on events that cause navigation into an item in another canvas-view. For example, you can put the code in a PRE-BLOCK or WHEN-NEW-BLOCK-INSTANCE trigger.
Alternatively, you can use a checkbox and a WHEN-CHECKBOX-CHANGED trigger with the following code to bring up the stacked canvas-view when the checkbox is checked and dismiss it when the checkbox is unchecked.
if :control.check = 'T' then
show_view ('stacked-canvas-view-name');
else
hide_view ('stacked-canvas-view-name');
end if;
After analyzing your application, you may find that the most effective way of upgrading your application and using the new features is a thorough rethinking to get the maximum benefit out of the new capabilities of GUI. This section describes the four major steps to build your GUI application.
This approach enables you to harness the full power of Oracle Forms 4.5 in a bitmapped environment resulting in increased user productivity and ease of maintenance.
Part #: A32362
Copyright © 1996 Oracle Corporation. All Rights Reserved.