Oracle9i Designer Migration Guide Part 4. Migrating generated Forms applications to Oracle9i Designer |
Contents

# Chapter 1 Introduction

This migration guide provides the information necessary for upgrading Forms Applications that were designed and generated using earlier releases of Designer to Oracle9i Designer.

The document discusses migration from the following earlier releases:

- 1.3.2
- 2.1.2
- 6.0

This document assumes that you have already installed Oracle9i Designer and migrated your repository. (See the instructions in Part 2 of this Migration Guide.) The document then explains steps that you have to take so that you can:

- Generate your application from Oracle9i Designer and achieve the same generated results you had from earlier releases, and
- Take advantage of new features that have been added to Designer since your previous release.

Throughout the document, special mention is made of any migration issues known at the time of publication of this document.

There are a number of migration scenarios that are possible in bringing your Designer generated applications forward into Oracle9i Designer.

## Scenario 1. Migrate, Regenerate All, No Redesign

In this scenario, you will regenerate your entire application from Oracle9i Designer, including all forms, libraries, menus and reports. However, you will continue to use your existing template forms and object libraries.

The goal of this scenario is to be able to generate your application out of Oracle9i Designer and achieve the same results you got when generating out of your previous Designer release. No attempt is made to redesign your existing application to make use of new features available in Oracle9i Designer.

This scenario has the following characteristics:

- It is fast and requires minimal changes in the application definition in the Oracle Designer repository
- It uses your existing templates and libraries, upgraded to Forms 9i. Any customizations made to the templates and libraries are preserved.
- It does not take advantage of any new features in Oracle9i Designer. It is merely a 'technical' upgrade.

This scenario is appropriate when:

- Your application is already in production.
- Your application is stable, no major functional modifications are expected.
- Maintenance is limited to simple bug fixing.
- Your application is 100% generated, or post-generation modifications are minor.

## Scenario 2. Migrate, Regenerate All, With Redesign

In this scenario, you will regenerate your entire application from Oracle9i Designer, including all forms, libraries, menus and reports. As you regenerate each module, you will make use of new features as appropriate.

The goal of this scenario is to take advantage of the new features available in Oracle9i Designer. As with Scenario 1, you want to be able to generate your application and get the same user interface you got from your previous release of Designer. However, many new features have been added to Designer to make achieving the desired result easier. Many features that were difficult or impossible to generate with earlier releases of Designer are now supported. Thus, in one pass, you can eliminate post generation modifications and difficult constructs that were used only to work around limitations of earlier releases of Designer.

This scenario has the following characteristics:

- Any customizations made to the templates need to be applied to the Oracle9i Designer versions.
- It requires modifications in many module definitions, and is therefore more time-consuming
- It fully leverages the new features in Oracle9i Designer.

This scenario is appropriate when:

- Your application is still in development.
- Your application is in production, but major functional modifications are to be made, or are expected.
- Your application requires modifications that can only be implemented using the new functionality in Designer.
- Your application has been heavily modified post-generation, but the majority of the modifications are no longer needed due to the new functionality in Designer.

## Scenario 3. Migrate, Regenerate Incrementally

This is the most complex scenario. In this scenario, you will migrate your application a little at a time, rather than all at once. You will begin by upgrading all of your forms, libraries, menus and reports to Forms 9i. You will then make the changes required to run forms generated from your previous release of Designer alongside forms generated from Oracle9i Designer. Finally, over some arbitrarily long period of time, you will regenerate all of your modules out of Oracle9i Designer.

The goal of this scenario is to allow you to regenerate your whole application, taking into account new features, but in such a way that you do not have to migrate your entire application in one go. This means you will be able to move the deployed application to the new tool stack before you have completely migrated every form. Thus, you can continue with bug fixes and new development in parallel with the continuing migration effort.

This scenario has the following characteristics:

- It requires you to do work to allow old and new generated forms to run side by side. This is extra work that is not required for Scenarios 1 and 2, and that will eventually be discarded. Thus, the total effort required is greater.
- It allows you to perform a phased migration. You can take advantage of the new Designer features right away, without the need to regenerate all your forms at once.

This scenario is appropriate when:

- Your application is in production, but major functional modifications are to be made, or are expected.
- Your application requires modifications which can only be implemented using new functionality in Designer
- Your application is too large to migrate in one ‘big bang'.

## Scenario 4. Forms Migration Only

The first three scenarios all eventually require you to regenerate your application. Any post-generation modifications will be lost. If you heavily modified your application post-generation, and the characteristics of Scenario 1 apply to your situation, you might consider only upgrading the runtime environment to Forms 9i, and not upgrading to Oracle9i Designer. This implies that all future maintenance has to be done manually in Developer.

This part of the migration guide does not cover a 'Forms only' migration. For information on migrating Forms to 9i, see the Oracle Technology Network at http://otn.oracle.com/products/forms and select ‘Migration’ under ‘Oracle Forms Technical Information’.

Note that, even though you may choose not to use Oracle9i Designer for continued form generation, you may still use Oracle9i Designer to maintain your database definitions. You may also choose to use the Software Configuration Management features of Oracle9i Designer to manage your application source code (.fmb, .mmb, .pll and .rdf files).

For information on Software Configuration Management with Oracle9i Designer, see the Oracle Technology Network at http://otn.oracle.com/products/repository .

## Scenario 5. Design Capture

If you heavily modified your application post-generation, and the characteristics of Scenario 2 apply, you may want to consider using the Design Capture features of Oracle9i Designer.

This part of the migration guide does not cover Design Capture. For information on Design Capture, see the Oracle Designer online help.

# Chapter 2 Oracle9i Designer New Features

Depending on which Designer release you are coming from, many features of Oracle9i Designer may be new to you.

This chapter presents a brief overview of new features that are of particular interest when migrating a generated forms application. It is by no means an exhaustive list of all new features, and it does not try to explain each new feature in detail. Rather, it introduces the relevant features and points you to where you can find more information in the Oracle9i Designer online help.

This chapter is organized by Designer release. You should begin reading at the section for your "from" Designer release, and then continue reading the sections for any later releases. For example, if you are migrating from Designer 1.3.2, you need to read all the sections below. If you are migrating from Designer 2.1.2, you may skip the section on Designer 1.3.2 and read the sections for Designer 2.1.2 and 6.0.

## Migrating from Designer 1.3.2

This section describes new features added in release 2.1.2. If you are already at release 2.1.2 or higher, skip this section.

### Design Editor

The functionality provided by individual Release 1 design level tools is now incorporated into a single tool called the Design Editor. Each of the Release 1 tools maps onto a Design Editor component. It is essential that you understand how to use the Design Editor before beginning your migration.

Release 1.x tool | Release 2.x Design Editor components
RON | Design Editor Navigator The Design Editor Navigator is a key component within the Design Editor. It is similar to the RON, but contains only objects specific to the design phase. You can use drag and drop, instead of clicking on menu options or toolbar buttons, to perform a wide range of tasks. For example, you can create a module diagram from a module definition by dragging the module from the Design Editor Navigator component onto the worksurface. You can also drag existing Repository definitions from the Navigator onto the diagrams. Most of the tasks that can be performed using other Design Editor components can also be performed from the Design Editor Navigator.
RON Property Palette | Design Editor Property Palettes and Property Dialog boxes When you create and edit repository definitions in the Design Editor, you can use either Property Dialog boxes (new for Release 2) or Property Palettes. Property Dialog boxes are wizard-style elements that walk you through complex tasks. They are especially useful when creating whole new modules or module components as they walk you through all of the required tasks in order. They are also useful as a tool for learning Designer. Property Palettes provide you with a direct way of entering/editing information for all of the properties that exist for an object. Property palettes are the quickest way of setting properties for existing objects, because all properties are displayed in a single palette.
Module Diagrammer | Module Diagrams Module Diagrams are created by dragging a module from the Design Editor Navigator to the worksurface.
Preferences Navigator | Preferences Palette Preference values are set using the Preference Palette within the Design Editor. Some behaviors that used to be governed by preferences (for example Item Group Orientation) are now properties in the associated object’s property palette. Many new preferences have been added.
Module Logic Navigator | Logic Editor In previous releases you could define server-side procedural logic by recording PL/SQL functions, packages and procedures. In this release you can also record 'application logic’ which corresponds to Form Level, Block Level and Item Level Triggers in Forms.
Module Structure Diagrammer | Module Network/ PL/SQL Composition viewer A module network viewer enables you to display module networks horizontally in the Design Editor Navigator. This allows you to clearly see the relationships between the modules in a network.

### Module Components

The structure of a module changed after Designer 1.3.2. Modules are now broken down into module components. Each module component consists of one base table usage and zero or more lookup table usages.

Module components can also contain so-called unbound items that are items that are not part of the base or lookup tables. This eliminates the need for secondary column usages.

Module components can also be designated as ‘re-usable’. This means that a single module component can be included in multiple modules.

### Form Logic in Designer

One of the most important changes in Designer is the ability to record form level, block level and item level triggers in Designer. Each module, module component and item has a node for adding application logic. This can consist of one or more pl/sql code segments. Designer lets you intersperse your custom code segments before, between, after and instead of code segments that Designer itself will generate.

### Preferences and the Object Library

Form Builder has introduced the new concept of the object library. An object library is the collection of forms objects into a file that uses the .olb suffix. Objects from the object library can be subclassed into forms. Thus, the object is a sort of super template. Designer allows you to use the object library for subclassing into generated forms. Designer comes with a pre-defined object library that contains a number of objects recognized and used by Form Generator. You can also extend this object library to add your own objects.

Designer still uses (and provides) a template form, but this template form now works very closely with the object library.

Designer also provides a utility for building an object library from a maintenance form. This form has a name like [designer home]\bin\fm2libxx.exe where xx is the major Designer release number. There is also a .txt document that explains how to use the utility.

See the Form Builder online help for information about how to use the object library.

The object library can now govern many of the settings and behaviors that used to be governed by preferences. Thus, many of the old preferences are now obsolete. See the Design Editor online help about preferences for information on which preferences are now obsolete.

### TAPI (some logic can go in the server instead of in the form)

Designer now allows you to generate a table API that acts as a server-side wrapper for your tables to enforce business logic. Essentially, this boils down to one pl/sql package per table. The PL/SQL package is stored in the database. Each table has database triggers that invoke the TAPI.

Logic that used to be placed in your form can now be placed in the TAPI. For example:

- Populating a primary key from a sequence
- Populating audit columns
- Populating default values
- Validating dynamic domains
- Simple business rule validation

Generated forms use the new ‘Returning’ clause to refresh data generated by the TAPI into the form record buffer.

See the Designer online documentation for more details about the TAPI.

### PL/SQL Libraries in Designer

Library generation is a major new feature in this release. Features of the new Library Generator are:

- Generation of library modules (.pll files) from repository library module definitions (either as a separate operation or during generation of a module to which it is attached).
- Design capture of existing library modules into the repository.

### Reports

The module component, a new Repository object, provides a container for the tables, columns, and derived items that Report Generator uses to generate a query. A module component contains one base table usage. It also may contain one or more lookup table usages and two new types of table usages:

- subquery table usages
- single-row SQL aggregate table usages.

In this release, groups are generated from the Item Groups that are defined in the module component. In addition, some of the properties that control group generation are now item group properties. For example, you can define a layout style for each break item group.

In this release, Report Generator provides a simpler interface for defining break groups in Group Left (Break) reports. To define the "break" column or columns, create a new break item group and add the break columns to it.

To define the column values that you want to display in a generated report, you define a new type of repository object, a bound item.

You can now add Oracle Developer Report Builder report triggers and named routines directly to Oracle Designer repository objects.

This release includes a new type of repository object for defining navigation between report modules or between a report module and another type of module: the Navigation Action Item.

You can now generate a matrix report from a single module component. In previous releases, you could only generate a matrix report from three base table usages (module components): one for each of the matrix groups.

There is now a distinction between two types of summaries:

- Computed summaries, which are calculated on the client
- SQL Aggregate summaries, which are calculated on the server

There is now a distinction between three types of derived items:

- SQL Expressions, which are evaluated on the server
- Client Side Functions, which are evaluated on the client
- Server Side Functions, which are evaluated on the server

#### Reports on the Web

In the previous release of Report Generator, you generated a report for Web output by attaching the CGWEBP.RDF (PDF) or CGWEBH.RDF (HTML) template to the report module. This release of Report Generator includes a new preference, DSPFMT, for specifying the type of report output.

In this release, you can generate HTMLCSS output to support cascading style sheets.

In the previous release of Report Generator, the CGWEB.pll library contained PL/SQL code for generating Web functionality such as hypertext links and tags. The library was attached to the default template report. In this release, Report Generator generates calls to Report Builder SRW built-in procedures instead of calls to procedures in the CGWEB.pll library. The CGWEB.pll library is no longer necessary and is therefore no longer attached to the default template report. However, CGWEB.pll is still supplied with this release of Report Generator to support generation of report modules that have been upgraded from the previous release. To attach CGWEB.pll to reports generated using this release of Report Generator either set MODLIB to CGWEB.pll or use Report Builder to attach CGWEB.pll to the template report.

#### Report Queries

In this release, Report Generator does not automatically generate a parameter that specifies the START WITH clause for treewalk links. To specify the START WITH clause and other treewalk link properties, use the table usage repository properties.

This release includes a new type of table usage: the subquery table usage. The subquery table usage enables you to explicitly define a subquery. In previous releases, you created subqueries by defining a table usage and hiding all the items (detailed column usages) in that table usage. In this release, you simply select the parent table usage and define a new table usage, specifying "Subquery" as the type. Use the WHERE clause property of the subquery table usage to define the restriction that you want the subquery to apply. This release also provides a more direct way of adding the NOT operator to reverse the logic of the query. Instead of setting a preference (ANNOTR), reverse the logic by setting the 'Not Exist?' Repository table usage property.

The new preference DETLNK controls how Report Generator creates the link between master and detail rows and enables you to use correlated subqueries to increase network efficiency.

You can now retrieve all rows from two or more tables by defining a SQL query set. When you define a SQL query set, Report Generator adds the UNION operator to the generated query to return all rows from all SELECT statements.

In this release, Report Generator adds all bound items to the generated SELECT list. In previous releases, if you specified that a detailed column usage should not be displayed on the generated report, Report Generator removed the column from the SELECT list. You do not need to define bound items for foreign key columns unless you want to generate a field for the foreign key column. Report Generator adds the foreign key column to the SELECT list when needed to join module components or table usages.

#### Report Parameter Forms

If you create parameters in the report module definition, the parameter form is created whenever you run the generated report. Report Generator no longer supports parameter form generation, parameter form templates, or parameter form layout preferences.

Domain validation of parameters is now controlled on the server. For more information, refer to 'About reference code tables' in the Server Generator on-line help.

#### Template Definition Files

This release of Report Generator supports template definition files (TDFs), which are new in Oracle Developer Report Builder 3.0. If you upgrade report modules from previous releases of Oracle Designer, Report Generator automatically converts RDF templates to TDF format.

The close integration between Report Generator and Report Builder templates also means that some of the customization via preference settings and post-generation modifications is now consolidated. For example, spacing between labels, fields, and groups can now be set using Template properties.

In the previous release of Report Generator you were able to add default boilerplate object keywords to your layout model template and apply formatting styles to these objects. This was to allow generated objects in the report to inherit the format that you applied to the boilerplate object. In this release, the font and visual attributes can be specified in the template definition file.

Removed boilerplate object keywords | How to customize in Release 2
CG$M1 and CG$M2 | Combined into one object CG$MT
CG$BUTTON | Use the repository item properties width and height
CG$SIZING | Use the Report Builder with the Layout Model open
CG$DCU_GRP_FRM | Use the Template properties in the Oracle Designer Item Group Style/Title sections
CG$HEADER | Use the Template properties in the Frames section of the Layout Model Body
CG$PARAMETER | This functionality is not supported in this release
CG$PROMPT | Use the Template properties in the Field/Labels Headings section of the Layout Model Body
CG$FIELD | Use the Template properties in the Fields section of the Layout Model Body
CG$US | Use the Report Builder Layout Editor to create a field in the Report Builder template, and set the source to be a column that is of datatype char (e.g., DESNAME). Add the following Report built-in function call to the Format Trigger: srw.set_field_char (0, user)

## Migrating from Designer 2.1.2

This section describes new features added for release 6.0. If you are already at release 6.0 or higher, skip this section.

The biggest change for Form Generation in moving from Designer 2.1.2 to Designer 6.0 was the change from Forms 5 to Forms 6. There were a few minor changes in addition to this:

- generation of bean area items containing Java Beans
- generation of custom (java) user interface components (which includes support for the Oracle Look and Feel)
- full screen menu generation no longer supported.

## Migrating from Designer 6.0

This section describes new features added for release 6i.

### LOV components

The new repository LOV element simplifies the process of LOV generation by decoupling LOVs from lookup table usages. This not only makes it easier to define LOVs, it also enables you to:

- define multiple LOVs for the same block
- reuse the same LOV in multiple blocks and multiple forms
- define LOVs for unbound items.

### New Layout Features

This release includes a number of new layout features. Some of these new features can cause changes to the layout of your migrated applications.

There are a number of new layout styles available:

- support for the splitting of blocks across multiple canvases by generating multi-region blocks, and also the design capture of multi-region blocks
- support for the placing of blocks beside each other on the same canvas
- generation of navigator style forms (to provide a user interface similar to that of the Design Editor) and navigator style items.

You can now generate spreadtables onto tab canvases.

This release introduced relative tab stops (as distinct from absolute tab stops in previous releases) as a means to position and align items and item groups. Your migrated applications will continue to use the old absolute tab stops unless you specifically change them to use the new relative tab stops.

Enhancements have been added to layout functionality, including:

- Specification of real units when setting the decoration preferences.
- Extra line above decoration options for the preferences BLKDEC, CONDEC, GRPDEC, OFADEC, RADDEC, STBDEC.
- Using BLKSBP, you can position a block scrollbar to the right or left of the multi-record area within a block instead of to the right or left edge of the block itself.
- In multi-record blocks in which the lines do not wrap, Form Generator now positions a summary item below the item it summarizes (instead of repeating the summary item for each displayed row).
- If a module component's Width property was not explicitly set, Form Generator reduces the width of the generated block to optimize side-by-side block layout by removing any unused space to the right of the rightmost item.
- The new LAYFRA preference gives you the option to generate frames instead of graphic objects/text as decoration.
- Increased coverage for the preferences ITMPPE and ITMMPW to allow expansion of other types of generated text as well as item prompts.
- You can now display values from a lookup table in a combo box, as well as in a text list or a poplist.

### Support for New Oracle Forms Features

Enhancements have been added to support native Oracle Forms features, including:

- Native Oracle Forms tooltip support for generated items using ITMTIP.
- Generation of Oracle Forms display items is now supported, along with a corresponding new standard source object called CGSO$DISPLAY_ITEM.
- Generation of Oracle Forms hierarchical tree items is now supported, along with a corresponding new standard source object called CGSO$HTREE.
- Generation of mirror items from unbound items.
- Placing all generated code into a generated module library attached to the generated form rather than into the generated form itself using the new PGULIB preference.

### Support for New Oracle8 Features

Enhancements have been added to support new Oracle8 features available in Oracle Forms, including:

- Use of the Oracle8 RETURNING clause when inserting or updating records, enabling the form to populate a base table item with the value returned from a derived column without having to requery the database.

# Chapter 3 General Migration Issues

There are a number of actions you must take regardless of which migration scenario you choose.

This chapter is organized by Designer release. You should begin reading at the section for your "from" Designer release, and then continue reading the sections for any later releases. For example, if you are migrating from Designer 1.3.2, you need to read all sections below. If you are migrating from Designer 2.1.2, you may skip the section on Designer 1.3.2 and read the sections for Designer 2.1.2 and 6.0.

## Migrating from 1.3.2

This section covers general migration issues when migrating from Designer 1.3.2. If you are migrating from a later release, you may skip this section.

### Add System Folder to Oracle9i Designer Workarea

If your migrated modules have '*******' in the Language property, it means that they are referencing the language from another folder, usually the System Folder. If this happens, modify your workarea to include the System Folder.

### Generating Context-Sensitive HTML Help

When application systems are upgraded to Oracle9i Designer, the Help Context Id Prefix is nullified for all Repository objects. The ID's are cleared because Oracle9i Designer uses a different format for the help IDs (see bug 656392).

If you have context-sensitive online help, you must generate the Help file(s) before you start generating the forms! By generating the Help file(s), new Context IDs are generated.

### Module Implementation Name

In earlier releases, Form Generator derived the name of generated source and executable files from the module's Short Name property and ignored a module's Implementation Name property. MS Help Generator did use the module's Implementation Name property and required that its value was six characters or less.

It is therefore quite likely that a module developed using Oracle Designer 1.3.2 has its Short Name property and Implementation Name property set to two different values.

In Oracle9i Designer, Form Generator uses a module's Implementation Name property to derive the name of generated source and executable files. The (HTML) Help Generator continues to use a module's Implementation Name property, but the six-character limit has been removed.

This may be an issue where:

- You have added code in one module to call another module (i.e. if user code or template code in a generated form calls another generated executable).
- The called module's Implementation Name and Short Name properties are different.

If you generate the called module in Oracle9i Designer, the call will fail because the called executable will have a different name to that expected in the code.

- Change the Implementation Name property of every form and menu module to the value of the module's Short Name property.

### Where/Validation Condition on Lookup Table Usages

In version 1.3, the where/validation condition on Lookup Table Usages could be used to restrict the allowable foreign key values. The where validation condition entered was applied in three places:

- in the LOV record group query to restrict the records displayed in the LOV
- in the WHEN-VALIDATE-ITEM trigger on the foreign key column(s), to make sure the restriction was also applied when the value was entered manually without using the LOV
- in the POST-QUERY (or POST-CHANGE in case of a hidden FK column) trigger to apply the restriction to existing rows

However, using the same where clause for the POST-QUERY places a limitation on the use of foreign keys. With this schema, you cannot create a relationship where all lookup rows are valid on existing records, but only some subset of the lookups can be used when creating a new record.

To address this issue, many developers specified sophisticated conditions in the WHERE/Validation Condition property.

In Oracle9i Designer, the WHERE/Validation condition property has been replaced with two properties to handle the two different operations:

- The Lookup validation WHERE Clause property is used to restrict the value in the LOV and validate values entered directly into a field.
- The Where Clause of Query property is used to restrict the existing records returned by querying the block.

On upgrade, both the 'Lookup validation Where Clause' property and the 'Where Clause of Query' property are populated with the value of the Designer 1.3.2 'Where/Validation Condition' property. If you have included sophisticated conditions in the Where/Validation Condition property of lookup table usages to avoid inappropriate constraint violation messages, these are unlikely to be suitable for the new Where Clause of Query property.

You will probably need to clear the ‘Where Clause of Query’ property on lookup table usages after upgrading. You may also need to clear it on base table usages, though only if it is related to the old LOV (i.e. the base table usage may also have its own valid where clause that you don't want to delete).

In addition to splitting the 'Where/Validation Clause', the implementation of the 'Where Clause of Query' no longer uses the POST-QUERY or POST-CHANGE trigger. The 'Where Clause of Query' on the lookup table usage is now added as a sub-select to the 'Where Clause' of the base table block in the generated form. This is a much better implementation, as you no longer get an error message when querying an existing record that violates the restriction. A side effect of the implementation is that if you have used system variables in the old 'Where Clause' and you fail to clear the 'Where Clause of Query' property, your form will fail to compile as references to System variables are not allowed in the block 'Where Clause'.

### Titling of First Block

Preference PAGTFB governs the titling of the first block on a page. This preference did not work when set to Yes in version 1.3. In version 9i the preference works fine, which means that if the value is set to Yes, and you generate the form again with version 9i, the layout will be different from the 1.3 generation as the block title will appear now.

### Names of Lookup Items Changed

In Designer 1.3.2, the user could not control the name assigned to lookup items in the generated form. The generator typically determined the item name by prefixing the column name with DSP_. In Oracle9i Designer, the user is able to explicitly set the name of lookup items, and the default is set to L_<column name>. But, the migration from Designer 1.3.2 to Oracle9i Designer sets the lookup item names to the new style names, rather than the old style names. Thus, if you have any PL/SQL code in your libraries that refers to lookup items, the code will now be incorrect.

You will need to either:

- update the lookup names (where necessary) in Oracle9i Designer to the old names, or
- update the PL/SQL code to use the new names.

### Display in LOV Property Lost

In migrating from Designer 1.3.2 to Designer 6.0, the Display in LOV property is lost for all items except the FK item. Since this is lost in 6.0, it is also not present in 9i.

You can either:

- Correct the lookup column usages in Designer 6.0 before migrating to Oracle9i Designer, or
- Correct the LOV components in Oracle9i Designer.

### Long Item Names Truncated to 28 characters

If a column usage name was longer than 28 characters in Designer 1.3.2, it will be truncated in Oracle9i Designer. If you have written pl/sql code in your modules that uses the long column name, it will no longer compile.

You will need to either:

- update the column names (where necessary) in Oracle9i Designer to the old names, or
- update the PL/SQL code to use the new names.

### LOV Tile lost during upgrade

The LOV title is lost during the upgrade from Designer 1.3.2 to Designer 6.0. Since this is lost in 6.0, it is also not present in 9i.

You will have to manually add the title back to each LOV.

### Space Added below Spreadtable Horizontal Scrollbar

In Designer 1.3.2, if you set SPRSBH=1, there was no vertical space below the horizontal scrollbar for a spreadtable. In this release, there is always at least one line of vertical space below the scrollbar. There is no workaround. This has been logged as bug #1781417.

### Review the setting of USEPKR

In earlier releases, if the AUTOQY preference was set to Yes:

- Form Generator generated a POST-FORM trigger to save the primary key of the current row into a global variable upon exit from a form.
- If the first block of a generated form is not insertable, Form Generator generated a WHEN-NEW-FORM-INSTANCE trigger that uses the value of the global variable to query the base table of the block.

In Designer 9i, the USEPKR preference replaces AUTOQY and the requirements for the first block have changed. If you set USEPKR to Query, the first block in the generated form must be query only (i.e. it must not be insertable or updatable). If you set USEPKR to All, the first block can be insertable and/or updatable.

So Form Generator will no longer generate auto-queried forms where the first block must not be insertable but can be updatable.

- If it is acceptable for the first block to be query-only (i.e. Not insertable or updatable), set USEPKR to Query.
- If the first block must be updatable, set USEPKR to All. Be aware that blocks that previously did not meet the conditions for AUTOQY (i.e. blocks that are insertable) will also be autoqueried.

### Menu Separators

You generate menu separators by defining a module with the Language set to null. During the upgrade process, the module language is defaulted to ‘Developer/2000 Forms’. Therefore, you must clear the Language property again for the menu separator modules before you generate the menu.

### Name Resolution in Forms 9i

Strange behavior may occur whenever you have a routine in one .pll library that calls a routine in another .pll library. It does not occur when the routine in the .pll library is called directly from the form.

This is actually a Forms migration issue, rather than a Designer issue. However, since Designer 1.3.2 required extensive use of pl/sql libraries for application code, you are likely to run into this issue, so we will discuss it here.

With Forms 4.5, you could define a program unit in one library, and then override it by creating a program unit of the same name in a second library and adding the second library before the first library in the list of attached libraries.

For example, suppose you created a library, general_form_handler.pll with a procedure initialize_form. This procedure calls a number of standard routines that are stored in core_routines.pll.

You attach core_routines.pll to general_form_handler.pll, and you attach general_form_handler.pll to your generater template form so that it is automatically attached to all generated forms.

Now, suppose in myform4, you want to customize the procedure init_block from core_routines.pll. With Forms 4.5, you could simply do the following.

When you called initialize_form from myform1, 2 or 3, it would call init_block from core_routines.pll. When you called initialize_form from myform4, it would call init_block from form4.pll.

This worked because form4.pll is placed ‘on top of’ core_routines.pll in myform4’s list of attached libraries. Internally, this happens because, in Forms 4.5, every time a call is made to a procedure, a new ‘search’ for a procedure with that name is executed, finding the one closest to the form. This process is called 'Name Resolution'.

In Forms 9i (and all forms versions 5.0 and higher), the algorithm for name resolution has changed to improve performance. When a library procedure calls another library procedure for the first time, name resolution is performed, and the program unit that is called is cached in memory. The next time the same call is made, it uses the cached routine.

In our example, this results in seemingly strange behavior at runtime. If the user runs the application and opens myform4 first, and then later opens myform1, 2 or 3, then all of the forms will use the version of init_block from form4.pll. On the other hand, if the user opens myform1, 2 or 3 first, and then opens myform4, all of the forms will use the version of init_block from core_routines.pll. The behavior of all forms depends on which version of init_block was opened first.

There are two workarounds for this problem.

- Copy the chain of calling program unit(s) to the module specific library, even if you do not want to customize these program units.

Since name resolution is always performed for routines that are called directly from a form, myform1, 2 and 3 will call initialize_form from general_form_handler.pll and myform4 will call initialize_form from form4.pll. Then, since these two versions of initialize_form are not the same 'calling' routine, name resolution will be performed again, and each version of initialize_form will call its own init_block. Thus, each form will correctly call its own version of both initialize_form and init_block.

This is the preferred workaround, but not always feasible if the program unit being customized is called from various places.

- Copy the calling program unit (initialize_form) to the module specific library. Copy and rename the program unit you want to customize. Modify the calling program unit to call the renamed version of this program unit.

For migration scenarios 1 and 3, where the original libraries continue to be used in the migrated application, you are more likely to run into this behavior.

### Generating Reports

The report generation process has changed dramatically. Report Generator now leverages the powerful new features in Reports 9i, including the new concept of a report template file (.tdf extension).

Report templates allow you to define standard layout settings, like font, font size, margins between frames, labels and fields, etc. Refer to the Report Builder online help for more information.

With the introduction of report templates, many layout preferences have become obsolete. These preferences have been removed from Report Generator. Refer to the Report Generator online help for a complete list of new, modified and removed report generator preferences.

As a consequence, you cannot use the old report generator template, since it contains a number of boilerplate objects that are no longer supported, and relies on a number of layout preferences that have been removed. You should create new report templates from scratch, or use the ones supplied with Oracle9i Designer.

#### Reports with Item Groups

The Layout Format of an item group used to be inherited from the module component in which it was contained. Now, the module component and item group can each have a Layout Format. This means that for all item groups that have the Layout Format set to 'Standard', you should change the item group's Layout Format to match the value of the Layout Style of its module component.

#### Money Items

The display datatype Money is no longer supported. You will have to set the Format Mask property to get the money format you like.

#### Reports with Across Style Layout

If the module component layout style is set to 'Across', and you have defined an item group within the module component, you should make the following changes to the definition of the item group.

- Set the item group's Layout Style to Across
- Set the item group's Break Style to Across

#### Review the setting of PARNME

This preference is used when naming parameters for generated reports. Set it to Null to ensure that generated parameter names are the same as the names defined in the repository.

## Migrating from 1.3.2, 2.1.2 or 6.0

This section covers general migration issues when migrating from Designer 2.1.2 or Designer 6.0. These issues can also affect migrations from Designer 1.3.2. The upgrade from these two releases is the same.

### Copy Where Clause of Lookup to LOV

The Designer migration fails to copy the where clause on the lookup table usage to the list of values. You will have to copy this manually wherever you have used such a where clause.

### Where Clause of LOV

If you have a where clause in an LOV, and that where clause references more than one column, the generated record group query will be generated incorrectly. The first column references the LOV's table usage alias while subsequent columns reference the item in the form.

Example: the where clause… REL_TYPE='S' and NAME like 'F%'

This is generated into:

    SELECT REL1.ID            ID,

           REL1.NAME          NAME,

           REL1.DEL_STREET    DEL_STREET,

           REL1.DEL_CITY      DEL_CITY,

           REL1.REL_TYPE      REL_TYPE

      FROM CLR_RELATIONS      REL1

     WHERE /*    CG$LOVI_WC_START REL 10 */

           (REL1.REL_TYPE='S'    and :REL.NAME like 'F%')

           /*    CG$LOVI_WC_END REL 10 */

Workaround: You must explicitly enter the table alias in front of the column names. In the example above, this would be :

    REL1.REL_TYPE='S' and REL1.NAME like 'F%'

This has been recorded as bug #1422339.

### Display Properties of LOV items

The Designer migration fails to copy the display properties from the lookup table usage to the list of values column usages. You will have to copy these manually.

Further, the migration includes the primary key column in the LOV column usages, and sets the Display Property = Yes. Unless you want the primary key visible as the first item in the LOV, you must change this display property to No.

### LOVs using Filter Before Query

The old Forms bug which causes a runtime error when using aliases in the select clause of an LOV that has Filter Before Query set to Yes has returned in Forms 6i. This has been logged as Forms bug #1347776.

You must repair all LOVs that have Filter Before Display? = Yes.

- Determine which field will be the first displayed field in the generated LOV.
- In the LOV component in Oracle9i Designer, change the Name property of the column usage to match exactly its associated column name. (Usually, remove the L_<alias>_ from the beginning of the Name.)

### New Possibility for LOV Buttons

Designer now lets you define a runtime webforms paramater in your registry.dat file which causes a field with an LOV to display a '…' in the field body when the user places the cursor in the field. Thus, you are no longer required to generate LOV buttons to give the users a visual clue that an LOV exists.

If you want to take advantage of this, you will need to change preference LOVBUT to No. In the registry.dat file, set parameter: app.ui.lovButtons=true

### Data Source Type = Query

There is a problem using Datasource Type = Query with a module component which includes a Lookup. When you use this Datasource Type, Designer generates a post-query trigger to retrieve the lookup data. The problem shows up at runtime when you query more records than will display on the screen, go to the last record displayed on the screen, and then attempt to go to the next record.

At this point, running through the web-browser, the form locks. Running client server, the form closes.

When the post-query trigger is fired, Forms also fires the on-lock trigger to lock the record. It does this because, with this datasource type, it thinks that the lookup field is a base table field. For some reason, on all records that did not show on the first screenful of records, Forms is unable to obtain a lock on the record and returns FRM-40654. At this point, the form hangs or exits.

With this datasource type, it is not necessary to generate a post-query trigger. The lookup information is already being retrieved as part of the base table query.

Solution: Either do not use this datasource type or you will have to do a post-generation change to remove the post-query trigger generated by Designer.

This has been recorded as bug #1351904.

### Updateable Views

Form Generator has changed how it handles views. Forms based on views can now retrieve server-generated values from the database without any extra coding. In order to support this, Form Generator now requires that if a view usage is updateable, the associated view must have a primary key defined in Designer.

To avoid this problem, add a primary key to all your views.

### Views or Tables with No Primary Key

If you have a module component based on a view or table that does not have a primary key, you must set the NXTKEY preference to No. If you don't, you will get a compile error on the form. Alternatively, you can add a dummy primary key to the table or view.

### Views with Derived Columns

You can create a column on a view from an expression (such as the concatenation of two columns). However, the view column will be generated with a default width of 4000 on the database. If you then use this column in an LOV, the generated record group will not compile. A column in a record group is limited to a width of 2000.

### Check the width of generated buttons

In earlier releases, Form Generator used two different sizing algorithms when determining the dimensions of generated items and buttons.

In Oracle9i Designer, Form Generator uses the same algorithm to size both items and buttons. As a result, buttons are generated with slightly smaller dimensions.

The change in dimensions will be particularly noticable where the generated application contains large buttons, and the button label occupies the entire button face.

If changed button dimensions are unacceptable, increase the Width property of the repository item from which the button was generated.

### Variety of Layout Differences

This issue cannot be assessed until after you have followed your chosen migration scenario and begun generating forms. However, it is included in the ‘General Migration Issues’ chapter since the same issues apply regardless of which migration path you choose.

Once you start generating your forms from Oracle9i Designer you will notice a variety of problems with layout. Depending on your forms, the following issues may or may not cause problems for you.

- Due to the addition of Relative Tab Stops and Side by Side canvases, Designer has changed its algorithm for determining the width and height of a generated canvas and the blocks it contains. In previous releases, if the Module Component's height and width were set to null, Form Generator set the width to the value in preference PAGCWD, and set the height just large enough to contain all the data (up to a maximum set in preference PAGCHT). Now, the algorithm is much more complex. (See the Designer online help for all the details.) If you leave the height and width null, you will not get the same layout you got from earlier releases. Chances are, the generated canvases and blocks will be larger. So, where we used to advise that you always leave the module component Height and Width properties blank, it is better now to fill them in. Designer no longer just uses the values you key in. It now calculates a good fit height and width from these values.
- In previous releases, if you had a module component that was narrower than the canvas and you set the block justification preference to CENTER, the data in the module component would be centered in the module component and the module component itself would be centered on the content canvas. In this release, Form Generator centers the data in the module component, but unfortunately it left-justifies the module component on the canvas. If you want a block centered, you will have to explicitly set the block width to the same value as the canvas width in order to get the block contents centered on the canvas.
- Designer has changed how it handles multi-line text display. If the field width is too large for the canvas, it used to expand the canvas. Now it shrinks the multi-line text item. You will have to adjust your item sizes accordingly.
- Tab handling has changed considerably with the introduction of relative tabs and changing the Horizontal vs. Vertical item group property from a preference to a property. You may find you have to revisit your tab definitions.
- A multi-record block with an overflow right may need to have the number of rows reduced so that the multi-row section is not taller than the overflow section.
- Oracle9i Designer has changed its functionality regarding the handling of scrollbars on a multi-record block whose data is placed on tabbed item groups. In the previous release, there was no scrollbar on these screens. Designer now displays a scrollbar on the context canvas next to the tabbed canvases.
- Designer has changed its algorithm for calculating item widths. In general, the widths of items being generated are slightly different.
- Designer has changed how it determines the width of action items. Be aware that action item button width may not generate correctly.

# Chapter 4 Scenario 1: Migrate, Regenerate All, No Redesign

In this scenario, you will regenerate your entire application from Oracle9i Designer, including all forms, libraries, menus and reports. However, you will use your existing template form(s) and object libraries (if applicable).

The goal of this scenario is to be able to generate your application out of Oracle9i Designer and achieve the same results you got when generating out of your previous Designer release. No attempt is made to redesign your existing application to make use of new features available in Oracle9i Designer.

This chapter assumes that you have performed all the actions described in Chapter 3, General Migration Issues.

## Migrating from 1.3.2

This section covers migrating from Designer 1.3.2. If you are migrating from a later release, you may skip this section.

### Upgrading existing Forms 4.5 template forms

A number of changes to template forms created with Developer/2000 (Forms 4.5) are necessary before Form Generator 6i can use them:

- If a template visual attribute's Background Color property is set to Arrows, it must be set to None.
- Add comment CGAP$TES_SEQUENCE_BEFORE to each template trigger. This comment is needed because it is now possible to sequence template trigger code either before or after the code that will be generated into the trigger by Forms Generator.
- Add comment CGAP$TNR to each template program unit.
- The template form must be upgraded from Forms 4.5 to Forms 6i.

Oracle Designer supplies a utility to perform these changes.

- Read the PFRMxx.txt file in <oracle_home>\cgenfxx or <oracle_home>\bin.
- Run the PFRMxx utility to upgrade Forms 4.5 templates for use with Form Generator in Oracle9i Designer.

You must run this utility for all template forms as well as referenced forms. You can do this in batch by creating a .bat file containing the following line of code once for each form to be upgraded.

pfrmxx -i <input>.fmb -o <output>.fmb ChVisAt(arrows%none) AddTrg(CGAP$TES_SEQUENCE_BEFORE)

Review the Designer online help topics ‘…Release 1.x style…’ to determine any changes you may need to make to your template form before generating.

### Upgrade existing Forms 4.5 template menus

You cannot use the PFRMxx utility to upgrade template menus.

- Open and save each template menu module using Form Builder 6i

### Upgrade Forms 4.5 Libraries

Upgrading the libraries is straightforward. To upgrade manually, you open the library in Form Builder 9i (or Report Builder 9i). Form Builder will automatically start converting PL/SQL version to PL/SQL version 2. During this PL/SQL conversion you will be asked to confirm certain conversion operations. You can safely press the 'Convert All' button if you are prompted for such a conversion operation.

You can also create a .bat file to perform this upgrade in batch mode. Include the following line of code once for each library to be upgraded.

ifcmpxx module=<library>.pll userid=<user>/<pass>@<connect> module_type=LIBRARY Logon=YES Batch=Yes upgrade=YES version=45 build=No window_state=Minimize

### Attached OFG Libraries

Designer release 1.3.2 attached a number of OFG libraries to generated forms. You may also have attached some of those libraries to your custom PL/SQL libraries.

The Form Generator does not use these libraries anymore. Form Generator now uses a new, renamed version for each of these libraries.

Designer 1.3.2 Library | Oracle9i Designer Library
OFG4BSL | OFGBSL
OFG4CALL | OFGCALL
OFG4HPL | OFGHPL
OFG4MES | OFGMES
OFG4MNL | OFGMNL
OFG4TEL | OFGTEL

You must ensure the program units in the new libraries (which still have the same names as the old version) are used at runtime instead of the old versions.

When you regenerate your forms from Oracle9i Designer, they will automatically get the new libraries attached.

However, if you attached the OFG4… libraries to your pl/sql libraries you will have to correct each library manually.

- De-attach the obsolete OFG4… libraries from all libraries
- Attach the new OFG… libraries

### Review use of the obsolete preferences and the setting of OLBOLD

This preference enables you to specify that Form Generator is to continue to use preferences made obsolete by the support for object libraries.

The obsolete preferences are:

Preference | Equivalent object library object property
AUTOHP | Display Hint Automatically
BLKVSB | Show Vertical Scroll Bar
COLSEC | Enforce Column Security
IMGBEV | Image Item – Bevel
IMGCMP | Image Item - Compression Quality
IMGDHT | Image Item – Height
IMGDWD | Image Item – Width
IMGHSB | Image Item - Show Horizontal Scroll Bar
IMGQLT | Image Item - Display Quality
IMGSZS | Image Item - Sizing Style
IMGVSB | Image Item - Show Vertical Scroll Bar
LOVNAV | Push Button - Keyboard Navigable
TXTBEV | Text Item – Bevel
WINCLO | Window - Close Allowed
WINDLG | Window - Window Style
WINFHT | Window - Height
WINFIX | Window – Resize Allowed
WINFWD | Window – Width
WINFXP | Window – X Position
WINFYP | Window – Y Position
WINHSB | Window – Show Horizontal Scrollbar
WINICN | Window - Icon Filename
WINICO | Window - Minimize Allowed
WINICT | Window - Minimized Title
WINMOV | Window - Move Allowed
WINVSB | Window - Show Vertical Scrollbar
WINZOO | Window - Maximize Allowed

Note that the default setting of OLBOLD is No, so you will have to change this preference if you want to continue using the obsolete preferences. Also note that the OLBOLD preference is provided for backwards compatibility only. This preference and the obsolete preferences will be removed in future releases of Form Generator.

### Review Template Window Properties

Check if your old templates have windows which have 'Primary Canvas', 'Horizontal Toolbar' or 'Vertical Toolbar' properties set explicitly to Null instead of inheriting null from the factory settings. (A small green box is displayed to the left of the property name.) If so, re-inherit these properties. (The small green box will change to a bullet.)

### Review the setting of STOOLB

This preference enables you to specify the name and extension (in the fomat myobjlib.olb) of a default object library. The value of STOOLB is used as the default in the Object Library Name field on the Generate Form dialog box.

Since you have decided not to use an object library (by choosing this migration scenario), you must set STOOLB to null.

### Review use of color palettes

When generating a form, Form Generator determines which color palette to give the generated form as follows:

- If a template form is being used, Form Generator gives the generated form the template form's color palette.
- If a template form is not being used, Form Generator gives the generated form the default Form Builder color palette.

In earlier releases, the template forms supplied with Form Generator did not use the default Form Builder template. Instead, they used a color palette similar to that used in Oracle Applications forms.

In this release, the shipped template forms supplied with Form Generator have been given the default Form Builder color palette. If you compare a form generated using the old templates and a form generated using the new templates you will notice significant color differences.

However, the earlier template forms are still supplied (as .fmb files with names beginning with OFG4) to enable you to continue using the non-default color palette.

If you have used one of the template forms supplied with Form Generator to generate forms, continue to use the same template form.

Note: If you intend to use an object library as well as the template form you used in earlier versions, be aware that the objects in the shipped object libraries supplied in this release were created in forms that had the default Form Builder color palette. To generate forms using both an object library and a template form, make sure objects in the object library were originally created in a form with the same color palette as the template form. For more information, refer to the online help topic 'Notes on color palettes and Form Generator'.

### Review use of coordinate systems

Form Generator applies the coordinate system and the default character cell specified for the template form to the generated form.

Note: If you intend to use an object library during generation as well as the template form you used in an earlier version, there is an issue you must be aware of:

- If the object library contains objects that are subclassed or copied into the generated form, the generated objects might be sized incorrectly. This situation occurs where objects in the object library were originally created in forms with a different co-ordinate system to that of the template form.
- To ensure generated objects are sized correctly, make sure any object library objects that will be copied or subclassed into the generated form (e.g CGSO$LOVBUT) are created in a form with the same coordinate system as the template form you are using.

### Review the setting of MSGSFT

In earlier releases, you could use MSGSFT to specify a form-level procedure for displaying soft-coded messages for use instead of the standard Forms message handling procedures.

In Oracle9i Designer, MSGSFT specifies the name of a package. Form Generator is supplied with a suitable message-handling package called CG$FORM_ERRORS in the ofgtel.pll library. If you specify a package other than CG$FORM_ERRORS, the package you specify must contain the following three program units:

- a procedure called PUSH
- a function called MSGGETTEXT
- a procedure called RAISE_FAILURE.

There are also other naming conventions and parameter requirements you must follow if you decide to specify a package other than CG$FORM_ERRORS. For these reasons, we recommend you copy CG$FORM_ERRORS and then modify the copy. For more information, refer to the help topic 'About customizing the CG$FORM_ERRORS package'.

Refer to the help system to find out more about the requirements for a suitable message-handling package.

### Review the setting of CANNTC

In earlier releases, you could use Form Generator to generate stacked item groups onto different stacked canvases displayed in the same area on a form. Only one of the stacked canvases is visible at any one time. Users of the generated form select which stacked canvas to display using a control poplist. This was an effective alternative implementation to Form Builder's native implementation of tab canvases.

In Oracle9i Designer, Form Generator enables you to generate a native Form Builder tab canvas with a number of tab pages. Each tab page contains a stacked item group.

Form Generator continues to support the alternative implementation (using stacked canvases and an item group), and uses the CANNTC preference to determine whether to generate native Form Builder tab canvases or the alternative implementation. However, the default setting of CANNTC (Yes) indicates that Form Generator is to generate native tab canvases.

Note that native tab canvases require more vertical space. If the increased vertical space required by tab canavases is not available, set CANNTC to No.

### Regenerating the Application System

In the Preferences Editor, at the application level, change the preferences STFFMB and STMMMB to the names of your (upgraded) form and menu templates.

Use the Batch Generation option under the Tools menu in the Design Editor to generate your application.

You must generate the following object types.

- Libraries (if you have Design Captured them)
- Menus
- Forms
- Reports

## Migrating from 2.1.2

This section covers general migration issues when migrating from Designer 2.1.2. If you are migrating from a later release, you may skip this section.

First perform all the steps described in the section 'Migrating from 2.1.2 or 6.0' in the Chapter 3 "General Migration Issues", earlier in this part.

### Upgrade Forms 5.0 Libraries

Upgrading the libraries is straightforward. To upgrade manually, perform the following steps.

- Open the library in Form Builder 9i (or Report Builder 9i)
- Choose Program -> Compile -> All
- Save

You can also create a .bat file to perform this upgrade by including the following line of code once for each library.

ifcmpxx module=<library>.pll userid=<user>/<pass>@<connect> module_type=LIBRARY Logon=YES Batch=Yes build=No window_state=Minimize

### Regenerating the Application System

In the Preferences Editor, at the application level, change the preferences STFFMB and STMMMB to the names of your old form and menu templates.

Use the Batch Generation option under the Tools menu in the Design Editor to generate your application.

You must generate the following object types.

- Libraries (if you have design captured them)
- Menus
- Forms
- Reports.

## Migrating from 6.0

This section covers general migration issues when migrating from Designer Release 6.0. If you are migrating from a later release, you may skip this section.

First perform all the steps described in the section 'Migrating from 2.1.2 or 6.0' in Chapter 3 "General Migration Issues", earlier in this document.

### Regenerating the Application System

In the Preferences Editor, at the application level, change the preferences STFFMB and STMMMB to the names of your old form and menu templates.

Use the Batch Generation option under the Tools menu in the Design Editor to generate your application.

You must generate the following object types:

- Libraries
- Menus
- Forms
- Reports.

# Chapter 5 Scenario 2: Migrate, Regenerate All, with Redesign

In this scenario, you will regenerate your entire application from Oracle9i Designer, including all forms, libraries, menus and reports. You will use the new templates and object library provided by Oracle9i Designer. As you regenerate each module, you will make use of new features as appropriate.

The goal of this scenario is to take advantage of the new features available in Oracle9i Designer. As with Scenario 1, you want to be able to generate your application and get the same user interface you got from your previous release of Designer. However, many new features have been added to Designer to make achieving the desired result easier. Many features that were difficult or impossible to generate with earlier releases of Designer are now supported. Thus, in one pass, you can eliminate post generation modifications and difficult constructs that were used only to work around limitations of earlier releases of Designer.

This chapter is organized by Designer release. You should begin reading at the section for your "from" Designer release, and then continue reading the sections for any later releases. For example, if you are migrating from Designer 1.3.2, you need to read all the sections below. If you are migrating from Designer 2.1.2, you may skip the section on Designer 1.3.2 and read the sections for Designer 2.1.2 and 6.0.

## Migrating from 1.3.2

This section covers migration from Designer 1.3.2. If you are migrating from a later release, you may skip this section.

### Object libraries

To take full advantage of the the new features of Oracle9i Designer, you must use an Object Library. You can use the default object library provided with Designer, create an object library from your old reference form, or use a combination of the two.

#### Benefits

Object libraries are a new feature in Oracle Developer and are used by Form Generator in Oracle Designer. In earlier versions of Form Generator, much of the functionality provided by object libraries was available using preferences and objects defined in templates.

Since Oracle Designer Release 2, Form Generator has been able to use source objects in the object library to set the properties of generated objects. This method is more flexible since you can change object properties in the object library and propagate those changes to subclassed objects in generated forms simply by recompiling the forms (i.e. you do not have to generate the forms again). We strongly recommend you make use of the flexibility offered by object libraries to set and maintain standards in the applications you generate.

#### About object libraries

An Oracle Developer object library is a container for reusable objects. Object libraries enable you to:

- reuse an object in many forms
- apply standards to existing objects.

You can copy both objects and subclass objects from object libraries.

Object libraries are the recommended method for subclassing objects. Changes made to a source object in an object library can be propagated to any objects subclassed from that object by recompiling the appropriate forms.

#### About subclassed objects

A subclassed object is similar to a copied object, except that a subclassed object maintains a link to its source object.

Subclassing objects is an efficient way to reuse objects and enforce standards. A subclassed object automatically inherits any changes that have been made to the source object when you recompile a module containing it.

Object libraries are the recommended method for subclassing objects, since it is convenient to keep the source of subclassed objects separately. Changes made to properties of a source object in an object library can be propagated to any objects subclassed from that object by subsequently recompiling the appropriate forms.

Note: If you make changes to a subclassed object property that has been inherited from a source object, subsequently recompiling the form will not modify the changed property. Changing the subclassed property removes the link between that property and the source object. However, the link between unchanged subclassed properties and the source object remains in force.

##### Form Generator and object libraries

When you generate forms using Form Generator, you can specify that Form Generator creates generated objects by either copying or subclassing from properties of source objects in an object library specified by the STOOLB preference.

You will typically want generated objects to inherit their properties from source objects, although you can direct Form Generator to use preference settings or repository information instead. But because source objects have all the properties of generated objects, using source objects enables you to set generated object properties that cannot be set using preferences or repository information.

Object libraries used by Form Generator can contain two types of source object:

- standard source objects
- implementation source objects.

##### Standard source objects

A standard source object is an object in the object library that Form Generator is programmed to recognize and use when creating a particular type of generated object. Form Generator uses the names of standard source objects to determine which to use during generation. Standard source objects have names prefixed with CGSO$. The rest of the object's name indicates the generated objects for which it can be the source. For example, the CGSO$CHECK_BOX standard source object is the source object for generated check boxes. You can find a complete list of standard source objects in the Designer online help as well as in the default object library shipped with Designer.

##### Implementation source objects

An implementation source object is an object that can be used to override a standard source object. You can explicitly direct the Form Generator to use an implementation source object (instead of a standard source object) when generating a particular object. You use the repository object definition's Template/Library Object property to specify the implementation source object that Form Generator is to use.

You can specify two types of implementation source object:

- user-defined implementation source objects, which you have created and named yourself
- shipped implementation source objects, which provide default Oracle Developer functionality and which have names prefixed with CGAI$.

##### User-defined implementation source objects

You can add your own implementation source objects for any type of object. When creating a user-defined implementation source object, we recommend you do not give it a name that begins with CGSO$ or CGAI$.

If Form Generator copies or subclasses properties of a generated block from an object library block, any items belonging to the object library block are also included in the generated form. If such an item has a name that begins CGAI$, Form Generator places the item below other items in the generated block and beside buttons generated from action items defined for the module component. For more information, refer to the help topic 'Items copied or subclassed from items in object library blocks'.

##### Shipped implementation source objects

The shipped object library ofgstnd1.olb contains a number of implementation source objects that provide default Oracle Developer functionality. The names of these implementation source objects begin with CGAI$. You can specify one of these implementation source objects for the object Form Generator to use when generating:

- an action item
- an unbound item with a Display Type of Button.

Note: This same functionality was provided in earlier versions of Form Generator by CG$ button items in the template. Although the CG$ button item method continues to be supported in this release, we recommend you use CGAI$ implementation source objects instead.

For a list of the shipped implementation source objects and the equivalent CG$ template button items, refer to the help topic 'Alphabetical list of shipped implementation source objects'.

#### Creating an object library using the FM2LIBxx utility

##### Creating an Object Library the Hard Way

To create an object library using only Form Builder, you would have to perform the following steps:

- Create an empty object library (.olb file).
- Create a dummy form (.fmb file).
- Add objects to the dummy form.
- Drag and drop the objects into the object library.
- Discard the dummy form.

To maintain the object library, you would have to perform the following steps:

- Open the object library.
- Create a dummy form.
- Drag and drop the object you wish to modify from the object library to the dummy form.
- Make the desired changes.
- Drag and drop the object back to the object library.
- Discard the dummy form.

This method has a number of disadvantages. First, the process itself is cumbersome and error prone. Much worse though is the fact that if you have objects that are subclassed amongst themselves, then when you drag them out and back into the object library for maintenance, all the subclassing is lost.

##### Creating an Object Library the Easy Way

Designer supplies a utility called FM2LIBxx (where xx is the Designer version number) that will automatically create an object library from a form.

This utility enables you to create and maintain source objects in forms. Essentially, you create an 'object library maintenance' form which includes everything you want to have in your object library. This form is not discarded, but kept as part of your template set. Whenever you need to modify your object library, you make the changes in this maintenance form.

You use the FM2LIBxx utility to generate the object library .olb file from the maintenance form.

There are several advantages to this approach, including:

- Ease of maintenance - you do not have to drag objects into a form module for editing and then drag them back into the object library.
- Subclassing information is retained when editing objects - subclassing information is lost when you drag objects into an object library from a form module for editing.

For more information about using the FM2LIBxx utility, refer to the file fm2libxx.txt in the <ORACLE_HOME>\CGENFxx directory.

#### Object libraries and earlier versions of Form Generator

##### Object libraries, obsolete preferences, and OLBOLD

In previous versions, Form Generator used a number of preferences to set object properties. For example, you might have set the IMGBEV preference to determine the style of the border surrounding images.

The support for object libraries has resulted in a number of preferences becoming obsolete. For a full list of obsolete preferences, refer to the online help topic 'Alphabetical list of obsolete preferences and the equivalent object library properties'.

We strongly recommend you do not use the obsolete preferences. However, to ensure backwards-compatability, you can set the OLBOLD preference to specify that Form Generator continues to use these preferences instead of properties in the object library.

Note: The OLBOLD preference and the obsolete preferences will be removed in future releases of Form Generator.

##### Object libraries and CG$ template objects

In previous versions, Form Generator used a number of objects from the template form to control properties of generated objects.

In Oracle Designer Release 2, Form Generator continues to use CG$ template objects as in previous releases - with one exception. When creating an LOV indicator button, Form Generator first searches the object library for a standard source object called CGSO$LOV_BUT and uses that instead of a CG$LB template object if one has been defined.

Note: It is likely that CG$ template objects will be replaced by object library functionality in future releases of Form Generator.

##### Object libraries and CG$ template button items

In previous versions, Form Generator used a number of CG$ template button items from the template form to provide default Form Builder functionality.

In this release, Form Generator continues to use CG$ template button items. However, equivalent functionality is also available through the use of shipped implementation source objects (prefixed CGAI$) in the object library. For a list of the shipped implementation source objects and the equivalent CG$ template button items, refer to the help topic 'Alphabetical list of shipped implementation source objects'.

Note that the behavior of Form Generator with regard to shipped implementation source objects and CG$ template button items is slightly different. If a template contains CG$ template buttons, every form generated with that template contains those CG$ template buttons. To include the same functionality in every generated form using CGAI$ objects, either explicitly specify implementation source objects for individual unbound items in every module (potentially difficult to maintain and not recommended), or follow the instructions below to generate a common control block:

- Create a reusable module component.
- Create an unbound item for each generated item you want in the control block.
- Set the Template/Library Object property for each unbound item to the appropriate CGAI$ implementation source object.
- Include the reusable module component as the first or last component in every module.

##### Object libraries and Generator named visual attributes

In previous versions, Form Generator applied a number of Generator named visual attributes (NVAs) from the template form to generated objects.

In this release, Form Generator can use the properties of standard source objects in the object library to set the properties of generated objects in much the same way as using Generator NVAs. This method is more flexible since you can change object properties in the object library and propagate those changes to subclassed objects in generated forms simply by recompiling the forms. We strongly recommend you make use of the flexibility offered by object libraries to set and maintain standards in the applications you generate.

However, to ensure backwards-compatability, Form Generator continues to use Generator NVAs on objects that have not been subclassed or copied from an object library as follows:

- If an implementation object in the object library has been specified for an object, use this if it exists.
- If an implementation object has been specified and it does not exist, or if no implementation object has been specified, use an appropriate standard source object from the object library.
- If no appropriate standard source object exists in the object library, apply the appropriate visual attribute from the template form.

Note: Generator NVAs will be removed in future releases of Form Generator.

##### Object libraries and generated items' widths, lengths, and formats

In previous versions, if information about an item's width, length, and format were not recorded in the repository (either against the column definition or the item definition), Form Generator obtained this information from a number of preferences (prefixed TXT).

In this release, if information about an item's width, length, and format are not recorded in the repository, Form Generator obtains this information from source objects in the object library. Form Generator uses the corresponding TXT preferences only if no appropriate source object exists in the object library, or if an appropriate source object exists but the relevent property has not been set.

#### Standard source objects and object libraries

During generation, Form Generator analyzes each object it creates to determine which standard source object it expects to use in the object library. Form Generator can use a standard source object from an object library during generation providing the standard source object:

- has one of the recognized names
- is of the correct object type.

Form Generator uses the names of standard source objects to determine which to use during generation. Standard source objects have names prefixed with CGSO$. The rest of the object's name indicates the generated objects for which it can be the source. For example, the CGSO$CHECK_BOX standard source object is the source object for generated check boxes. For a list of the recognized names of standard source objects, refer to the online help topic 'Alphabetical list of standard source objects and object types'.

The standard source objects are arranged in a predefined hierarchy. If Form Generator does not find the expected standard source object, it searches the object library for the parent of the standard source object and uses that instead. For a graphical representation of the standard source object hierarchy, refer to the online help topic 'Hierarchy of standard source objects'.

##### Standard source object suffixes

In some cases, you can further refine the standard source objects from which Form Generator obtains properties for generated objects by adding the suffixes below to the standard source object name:

Order | Suffix | Use if generated object will be a...
1 | _MR | ...multi-record block, or an item in a multi-record block
2 | _CT | ...control block (i.e. the module component contains only unbound items)
3 | _DO | ...display only item
4 | _MD | ...mandatory item

You can use the above suffixes individually or in combination. Form Generator will use the most appropriate standard source item, according to the order of precedence indicated.

Form Generator first searches the object library for a standard source object name containing all of the applicable suffixes. If no such standard source object exists, Form Generator searches the object library for the standard source object name that contains the greatest number of appropriate suffixes. If two or more standard source objects contain the same number of appropriate source objects, Form Generator uses the one containing the suffixes highest in the order of precedence (see table above).

Note that Form Generator ignores a standard source object if any of the suffixes are not applicable.

##### Examples

Example 1: Form Generator is going to create a display-only check box in a multi-record block.

Form Generator searches the object library for each of the following objects, in the order shown:

    CGSO$CHECK_BOX_MR_DO

    CGSO$CHECK_BOX_MR

    CGSO$CHECK_BOX_DO

    CGSO$CHECK_BOX

    CGSO$DEFAULT_ITEM_MR_DO

    CGSO$DEFAULT_ITEM_MR

    CGSO$DEFAULT_ITEM_DO

    CGSO$DEFAULT_ITEM

As soon as Form Generator finds one of these objects, it subclasses or copies the object into the generated form and abandons the search. If Form Generator fails to find any of these standard source objects, it creates a check box item using default item properties.

Example 2: The object library contains the following objects:

    CGSO$CHAR_MD_DO

    CGSO$CHAR_MR

    CGSO$CHAR_DO

    CGSO$CHAR

Form Generator is generating a form from a module that contains a display-only character item in a multi-record block. Form Generator subclasses or copies the CGSO$CHAR_MR standard source object into the generated form because:

- the _MD suffix in CGSO$CHAR_MD_DO is inappropriate
- the _DO suffix in CGSO$CHAR_DO is lower in the suffix order of precedence than _MR.

Example 3: The object library contains the following objects:

    CGSO$DATE_MR

    CGSO$CHAR_MR_MD

    CGSO$CHAR_DO

    CGSO$DEFAULT_ITEM

Form Generator is generating a form from a module that contains a mandatory data item in a single record block. Form Generator subclasses or copies the CGSO$DEFAULT_ITEM standard source object into the generated form because:

- the _MR suffix in CGSO$DATE_MR is inappropriate
- the only occurrences of CGSO$CHAR (i.e. the parent of CGSO$DATE) have inappropriate suffixes (_MR_MD and _DO).

If the object library had contained a standard source object called CGSO$CHAR, or failing that an object called CGSO$DEFAULT_ITEM_MD, Form Generator would have used these objects instead.

#### Current Record Indicator and the Object Library

If you want to use the Current Record Indicator in your forms, you must create a Visual Attribute called CG$CURRENT_RECORD in your object library. This is not included in the Designer default object library, so you will need to add it.

### Application logic

#### Benefits

The ability to record client-side code or 'application logic' in the repository is a new feature in Oracle Designer since release 1.3.2.

In earlier releases, you could include your own code in generated applications only by entering code for template objects or in attached libraries. This method was cumbersome and prone to error.

In this release, not only can you enter the code in the repository but you can also:

- specify which events in the generated application cause the code to execute
- specify whether your code executes before, after, or instead of code created by Form Generator.

Storing the code within the repository also enables you to make use of Oracle Designer's dependency analysis features to assess the impact of proposed changes.

#### About application logic

'Application logic' is the name given both to code created by the Form Generator and to code you enter by hand. Application logic comprises event code (code that executes in response to particular events) and named routines (code that is called by event code).

There are different types of application logic:

- Generated application logic - event code and named routines created by Form Generator.
- User-modified generated application logic - event code and named routines created by Form Generator and subsequently modified by the user (and optionally captured into the repository).
- User application logic - event code and named routines defined by the user in the repository.
- Object library (OL) application logic - event code and named routines for particular objects that are copied into the generated application from a specified object library during generation.
- Template application logic - form-level event code and named routines that are copied into the generated application from a template during generation.

You can record application logic at the module level, the module component level and the item level.

In Form Builder, event code is implemented as trigger code. Event code segments are individual pieces of trigger code. A named routine becomes a program unit held at module level or in an attached library, or on the server.

#### Where to enter application logic

The answer to this question depends on the complexity of the code involved. If the code is very simple (a few lines of code), then you can enter the code directly in the event logic in the form module. However, if the code is complex, we recommend you include as little code in the generated form as possible. In practice, this means including event code in the form that simply calls procedures on the server or in an attached library. This strategy offers several advantages:

- Maintaining generated applications is easier because code on the server or in a library can be modified without recompiling generated forms.
- In the case of server-side procedures, network traffic is minimized and performance improved.
- It promotes reusability, since the same code can be used by different forms.
- It reduces the size of .fmx.

The recommended scenario is shown in the diagram below.

We recommend that named routines that require database access (where the code includes SQL commands) be placed in stored procedures on the server and not in an attached library.

##### Where to enter event code

If the event code (or calls to code stored on the server or in an attached library) is to be included in every form:

- Enter block level and item level event code in an object library.
- Enter form level event code in the template form.

If event code is to be included in a single form or in some but not all forms, enter the event code in the repository against the required modules, module components and items.

##### Where to enter named routines

In a typical client server environment, we recommend you create named routines (e.g. procedures) either on the server or in a library attached to the generated form. These named routines are then called by the event code incorporated in the generated form from the repository, an object library or the template.

If the named routines are to be held on the server:

- Enter the named routine in the Oracle Designer repository using the Logic Editor, and then run the Server Generator to create the named routines on the server.
- Enter the named routines manually in a text file, and then run the text file using SQL*Plus.

If the named routines are to be held in an attached library:

- Enter the named routines in a library manually using Form Builder and attach the library to the template form.
- Enter the named routines as application logic in a repository module of type Library, link the repository module to one or more modules of language Oracle Developer Forms (or Oracle Developer Reports) in a module network, and use Library Generator to generate the library module.

#### Capturing application logic from Form Builder applications

You can capture (or 'reverse engineer') application logic into the repository from:

- Forms you did not generate using Form Generator
- Forms you did generate using Form Generator and subsequently modified using Form Builder
- PLL modules (which can now be stored in Designer).

During design capture, any user application logic or user modified generated application logic is captured into the repository. However, Form Generator uses comments in the code to identify and ignore:

- generated application logic
- template application logic
- object library application logic.

Where a trigger is captured, the execution style property of the corresponding event is set to the same value.

Note that BEGIN and END; statements must appear on separate lines.

#### About generated application logic

##### What is generated application logic?

Generated application logic is the code generated by Form Generator each time a form is generated. Generated application logic is not held in the repository.

If the form has already been generated, any existing generated application logic is overwritten.

Generated application logic comprises:

- generated code groups
- generated named routines.

Although generated application logic is not stored in the repository, generated code groups are represented in the Design Navigator window. This enables you to sequence user code groups and user-modified generated code groups before and after generated code groups.

Note that generated named routines are not represented in the Design Navigator window.

##### What are generated code groups?

Generated code groups are the standard sections of trigger code (and any called program units) generated by Form Generator.

Generated code groups are identified by a unique comment (e.g. /*CGRI$CHECK_ON_DELETE*/). If the generated form is captured into the repository, these comments will enable Form Generator to identify the code as generated application logic. Generated application logic is not captured into the repository during design capture.

For a list of generated code groups, refer to the following help topics:

- "Form Generator code groups (grouped alphabetically)"
- "Form Generator code groups (grouped by functionality)".

##### What are generated named routines?

Generated named routines are the standard program units created at module level by Form Generator.

#### About user-modified generated application logic

Using Form Builder, you can modify the application logic that Form Generator has generated.

To prevent user-modified generated application logic from being overwritten if the form is generated again, you must capture the application logic into the repository.

Capturing the user-modified generated application logic into the repository enables you to generate the form again, incorporating the changes you have made in Form Builder.

#### About user application logic

User application logic is both:

- code you enter into the repository using the Design Editor and the Logic Editor
- code you enter using Form Builder and then capture into the repository.

When you enter user application logic, you specify it as being one of the following:

- A named routine, which is generated as a Form Builder program unit and called from triggers or other program units
- An event code segment, which is generated as Form Builder trigger code

#### About OLB application logic

Object Library (OLB) application logic is code (event code and named routines) associated with objects in the object library that is added to blocks and items created during form generation.

When Form Generator includes an object from the object library in a generated form, any code associated with that object is also included in the generated form.

#### About template application logic

Template application logic is the name given to named routines or event code (program units or form level triggers) that you create in the template form. You might create template application logic to perform a common function that you want in all the forms you generate.

Form Generator copies program units from the template form straight into the generated form.

Form Generator copies form level trigger code from the template into the generated form. Form Generator uses comments in the template trigger code to determine whether to sequence it before or after generated code and user code for the same trigger.

Form Generator also copies form-level sub-classed triggers into the generated form. In this case, note that Form Generator is unable to modify the sub-classed trigger code. Therefore, any functionality Form Generator would have added to the trigger had it been non-sub-classed is not included in the generated form.

### Unbound Items

In Designer 1.3.2, if you wanted to create a non-base table item you used a concept called Secondary Column Usages. This release of Designer allows you to create Unbound Items, a much more flexible implementation of non-base table items.

Unbound items are items that exist within a module component, but are not associated with any table usage. You can define the type, placement and display, as well as application logic, for unbound items. You can also define an LOV against an unbound item.

Your Secondary Column Usages will be automatically migrated to unbound items. However, they will retain the old (ugly) names from 1.3.2. Consider renaming the unbound items to more descriptive names. Be aware however, that any code referencing the old names will need to be updated to use the new names.

### Action Items

Action items are a shortcut method of creating buttons in your application. There are two types of action items:

- Navigation Action Items – used to navigate to other blocks in the same form or to navigate to other forms
- Custom Action Items – used to generate all other button items.

Navigation action items are quick and easy to create and the code for the WHEN-BUTTON-PRESSED trigger is automatically generated.

However, action items are always displayed on the bottom of the current window. Designer does not provide a mechanism for specifying where you want the action item placed on the screen. If you want to control where the buttons are placed, you can:

- Write a PRE-FORM trigger that explicitly sets the x and y coordinates of the generated buttons.
- Use an Unbound Item with display type Button instead (and write your own WHEN-BUTTON-PRESSED trigger).

You should replace all buttons that were generated as secondary column usages with either unbound items or action items.

Again, you can rename the action items to more descriptive names. You will need to update any code that references the old names.

### Reusable module components

#### Benefits

In previous releases, the only way to copy part of one module to a new module was to copy the complete module, delete those elements that you did not want, and then use the remainder as the basis for the new module.

In this release, you can simply specify that a module component be made reusable. Making a module component reusable encapsulates the properties, preferences and event code. You can then include this reusable component in any number of modules.

Reusing module components in this way increases developer productivity and encourages consistency. The modules that use the reusable component automatically inherit all changes that you make to the reusable component, its application logic, and its associated preferences.

Reusable module components are an ideal way of defining control blocks to help give generated forms a common look and feel. For example, placing standard Form Builder functionality in a common control block at the top of every form presents users with a consistent interface.

### Native Form Builder tab canvases

#### Benefits

Screen real estate on which to lay out the items that comprise an application is often severely limited, either by the physical size of the screen or by the number of fields that have to be displayed. Users frequently have to navigate through many screens to enter information.

In previous releases, a number of strategies were available to increase the virtual size of the screen:

- Multiple content canvases
- Multiple stacked canvases
- Spread tables
- Different stacked canvases displayed in the same area on a form and accessed via a poplist.

In this release, Form Generator can generate native Form Builder tab canvases, each containing two or more tab pages.

Native Form Builder tab canvases have standard Windows look-and-feel and an intuitive behavior. They can form an integral part of your screen layout strategy.

#### About tab canvases and tab pages

##### What is a tab canvas?

A tab canvas enables you to group and display a large amount of related information on a single, dynamic canvas object. Like stacked canvases, tab canvases are displayed on top of a content canvas, partly obscuring it.

A tab canvas is made up of one or more tab pages. Tab pages each display a subset of the information displayed on the entire tab canvas.

##### What are tab pages?

A tab canvas can have many tab pages, and must have at least one. Think of tab pages as the folders in a filing system. Each individual tab page (folder) has a labeled tab that developers and end users click to access the page. You click the labeled tab to display the page at the front of the tab canvas, thereby obscuring any other page(s).

Each tab page occupies an equal amount of space on the tab canvas, roughly equal to the size of the canvas itself. This layering of related canvas sections enables you to display more information on a single canvas.

Tab pages are sub-objects of a tab canvas. Like the canvas to which it is attached, each tab page has properties.

#### About generated tab canvases and tab pages

##### What are generated native Form Builder tab canvases?

Form Generator generates a native Form Builder tab canvas and tab pages on which to place:

- Generated blocks, if two or more repository module components have their Placement properties set to New tab canvas page
- Generated stacked item groups, if two or more repository item groups in a module component have their Stacked property set to Yes.

If the above conditions are met and CANNTC is set to Yes, Form Generator places each block generated from a module component and each stacked item group onto different tab pages.

On selection of a tab label, the corresponding tab page is displayed and the cursor navigates to the first enterable item on that tab page. When users navigate to an item on a tab page that is not currently displayed (by pressing the [Next Item] key), the appropriate tab page is displayed.

##### An alternative implementation in earlier releases

In earlier releases, Form Generator enabled you to generate similar functionality using stacked item groups placed onto different stacked canvases displayed in the same area on a form. The different stacked canvases could be accessed via a poplist.

You might have existing module designs that include this alternative implementation. The CANNTC preference enables you either to make use of the new Form Generator functionality to place the stacked item groups on the native Form Builder tab canvases, or to continue to place the groups on stacked canvases.

#### Notes on the use of tab canvases for displaying blocks

Note the following when generating tab canvases to display blocks:

- A tab canvas (and its tab pages) generated from module components will appear at the position of the first module component that has its Placement property set to New Tab Canvas Page. It is your responsibility to make sure that blocks in the resulting form do not appear to users to be out of sequence.
- A content canvas can contain only one tab canvas generated from module components.
- If a generated form contains multiple content canvases, each content canvas can contain one tab canvas generated from module components.
- All block layout preferences apply to blocks generated onto tab pages.
- If the block you are generating onto a tab canvas page contains stacked item groups that are themselves to be generated onto a native Form Builder tab canvas, the first item in the block must not be in one of the stacked item groups. The first item must be placed on the underlying tab canvas page.
- The label for a tab canvas page is derived from the title given to the first block displayed on that tab canvas page. If you do not want both the label and the block title to appear on the tab canvas page, set POPTFB to No to prevent the block title being displayed (if the first block on a tab canvas page is the first block on the content canvas, use PAGTFB).
- If you set the X Position and Y Position properties of the first module component to be placed on the first tab canvas page, Form Generator will use those properties to position the generated tab canvas on the underlying content canvas.
- If the first block in a content canvas is generated onto a tab canvas and you set the Width and Height properties of the module component from which that block was generated, Form Generator will use the dimensions you specified as dimensions for the underlying content canvas.

By default, Form Generator determines the dimensions of a generated tab canvas as follows:

- Form Generator determines the width of a generated tab canvas from the width of the underlying content canvas.
- Form Generator determines the height of a generated tab canvas from the height of the highest block placed on a tab canvas page.

However, you can override the default dimensions of a generated tab canvas using module component Width and Height properties. If you do use the Width and Height properties, Form Generator determines the dimensions of a generated tab canvas as follows:

- Form Generator determines the width of a generated tab canvas either from the largest Width property specified for any module component placed on a tab canvas page or from the width of the widest block to be displayed on a tab canvas page, whichever is the greater.
- Form Generator determines the height of a generated tab canvas either from the largest Height property specified for any module component placed on a tab canvas page or from the height of the highest block to be displayed on a tab canvas page, whichever is the greater.

#### Notes on the use of tab canvases for displaying stacked item groups

Note the following when generating tab canvases to display stacked item groups:

- A block cannot contain more than one tab canvas displaying stacked item groups.
- Tab canvases displaying stacked item groups can be laid out within blocks that are themselves displayed on tab canvases (for more information, refer to "Examples of blocks generated onto tab canvases/tab pages" in the Designer online help).
- Tab canvases displaying stacked item groups cannot appear on other stacked canvases (including spreadtables and overflow context areas).
- A tab canvas displaying stacked item groups cannot contain items from more than one block.
- To ensure items in stacked item groups on a tab canvas in a detail block are synchronized with a master block (on a different canvas), set the BSCSCP preference to Window or Form.
- If all the items in a detail block are in stacked item groups on tab pages on a tab canvas, Form Generator creates a block context area above the tab canvas for any context items from the master block (for more information, refer to "Block context area and block context item generation" in the Designer online help).

### Server API

In this release, you can base a generated block on a procedure stored on the server and pass a PL/SQL table of records between the block and the procedure. It is the procedure that queries and performs DML on the base table. Basing a generated block containing lookup items on stored procedures is significantly more efficient in terms of network traffic than the other options outlined above. An Oracle Designer utility enables you to create suitable server-side procedures on which to base blocks by generating the Server API from table and module component definitions in the repository.

#### What is the Server API?

The Server API provides a powerful and easy-to-use PL/SQL interface that generated client applications can call to perform queries and DML operations on base tables in the Oracle Server.

The Oracle Designer Server Generator is the tool to use to generate the Server API.

The Server API is made up of:

- the Module Component API (comprising procedures to perform queries on the tables used by a generated application, and calls to Table API procedures to perform DML operations on those tables).
- the Table API (comprising procedures to perform inserts, updates, deletions and locks on the tables used by a generated application).

If you specify Procedure as the query datasource for a generated block, the block is populated by a procedure in the Module Component API (this procedure is referred to as a 'module handler') that passes a PL/SQL table of records to the generated form.

Similarly, if you specify Procedure as the DML datasource for a generated block, a table of records is passed from the block back to the module handler on the server, which in turn calls a procedure in the Table API (this procedure is referred to as a 'table handler') to update the base table.

If you intend to base a generated block on a server-side procedure generated as part of the Server API, you must generate the API before you attempt to run the generated form.

### Library generation

A new addition to the Oracle Designer toolset is the Library Generator. Using Library Generator, you can:

- generate Oracle Developer library modules from module definitions recorded in the Oracle Designer repository
- capture existing Oracle Developer library modules into the Oracle Designer repository.

When generating library modules, you can run Library Generator in one of two ways:

- To generate specific library modules, you can run Library Generator standalone.
- When using Form Generator or Report Generator to generate an Oracle Developer module, you can run Library Generator automatically to generate any attached library modules.

All Oracle Developer modules can use a generated library module, unless the generated library includes calls to language-specific built-ins. If the generated library does include calls to such built-ins, Library Generator uses the appropriate Oracle Developer compiler to compile the library.

Note that it is the repository module's Language property that Library Generator uses to determine which Oracle Developer compiler to use. It is your responsibility to ensure that:

- the repository module's Language property is appropriate for the built-ins called in the module
- built-ins from different languages are not called by the same library module
- the compiler from the appropriate Oracle Developer component is available (for generating and capturing repository modules of Language Oracle Developer Common Library, both the Oracle Developer Form Builder and the Oracle Developer Report Builder compilers are suitable)

#### Module Specific Libraries

You will need to re-evaluate all of your module specific libraries that you created for forms generated from Designer 1.3.2. In many cases, the logic will no longer be necessary at all because of new features that have been added to Designer. In other cases, the logic may be so simple that you choose to record it as application logic in the form module itself, rather than having a separate library.

Where you do still require a separate library, you should capture the library into Designer. You can attach the library module to its related form module using the module network link, or you can continue to use the MODLIB preference if you like.

### Templates cut down to size

In earlier releases, template forms were often the only mechanism for:

- controlling properties of generated objects
- including generator objects and user code in generated forms.

In this release, application logic and object libraries provide powerful alternatives to the existing template technology. In many cases, these alternatives are more efficient since:

- Using object library objects enables you to change the properties of objects in a generated form simply by changing the properties of source objects and recompiling the form. It is not necessary to generate the form again.
- Recording application logic in the repository enables you to specify when code is to execute, and to make use of Oracle Designer's dependency analysis features to assess the impact of proposed changes.

As you take advantage of other new features in Oracle Designer, you should also consider how those new features enable you to move functionality from the template and into object libraries and application logic.

However, continue to use template forms for:

- functionality requiring control blocks (e.g. toolbars, calendar widgets)
- form level code and objects (e.g. alerts, object groups, popup menus) that you want in multiple forms
- setting the character cell size and the coordinate system of generated forms
- defining the color palette used in generated forms
- attaching libraries to multiple generated forms (note that although this method is quicker than using repository module networks, you will not have access to Oracle Designer's impact analysis features)
- defining current record visual attributes
- property classes.

## Migrating from 2.1.2 or 6.0

This section covers general migration issues when migrating from Designer 6.0.

### Lookup Usages

In Designer 1.3.2, you used a lookup table usage to create both lookup items on the main canvas as well as to generate a Forms LOV. In this release of Designer, the concepts of lookup usages and LOVs have been separated.

The lookup table usage now has only one purpose - to display values from a lookup table on the canvas. These lookup items can be enterable, queriable and sortable.

You can attach a List of Values to base table column usage, a lookup column usage, or an unbound item. The only requirement is that the item must be explicitly defined as Insertable and/or Updateable.

See the next section for information on creating a list of values.

#### LOV generation

The new repository LOV element simplifies the process of LOV generation by decoupling LOVs from lookup table usages. This not only makes it easier to define LOVs, it also enables you to:

- define multiple LOVs for the same block
- reuse the same LOV in multiple blocks and multiple forms
- define LOVs for unbound items.

#### Native Oracle Forms LOVs

Using Form Generator you can generate Oracle Forms LOVs to populate two kinds of generated text items:

- Items generated from repository bound or unbound item definitions that are explicitly associated with repository LOV definitions.

> In this case, the generated LOV is always based on a query. The generated LOV will be available for those items explicitly associated with the repository LOV definition. You can specify which values are returned from the LOV to the form and which items in the form are populated with the returned values. In addition, you can specify different LOVs to use for querying information and for entering information.

> You can associate LOV definitions with both foreign key bound items and non-foreign key bound items. If you associate an LOV definition with a foreign key item in a base table usage, the lookup table at the other end of the foreign key might be the same as the LOV base table usage. If this is the case, note that:

- You do not have to define a module component lookup table usage of the lookup table as well.
- If you do define a module component lookup table usage of the lookup table as well, the module component lookup table usage's 'Where Clause of Query' property and 'Validation Where Clause' property will be used to restrict the values in the LOV when querying data and entering data respectively.

> The repository LOV definitions you create can be either specific to a single module or reusable by multiple modules.

- Items generated from repository bound or unbound item definitions for which allowable values have been recorded.

> In this case, the generated LOV can either be based on a static record group hard coded into the generated form or on a query record group populated dynamically by a query on a reference code table. For more information about reference code tables, refer to "Reference code table generation" in the Designer online help.

#### Lists of Values forms

By default, Form Generator generates native Oracle Forms LOV objects. However, you can also create a list of values form. This is a separate form that behaves like a list of values. It is called whenever the user presses the list of values button. It can return data to the calling form. The advantage of a list of values form is that the user can perform complex queries to find the requested records. It is also much better when a large number of records needs to be displayed.

To create a list of values form, you create a form module in Designer and set its Layout Format property to LOV, using the FKLOVT preference.

To call a list of values form, specify the form you want to call using the DVLOVF and DVHLVF preferences in the calling form.

#### Poplists

You can use repository LOV definitions to generate poplist, text list and combo box items by associating a repository LOV definition with an item that has its Display Type property set to Poplist, Text list or Combo box.

### Reusable LOV Components

Oracle9i Designer also allows you to create reusable LOV components that can then be included in any form module.

### Multi Region Blocks

Most blocks you generate will be single region blocks. Single region blocks are based on a single table and comprise one rectangular layout region that cannot be split across different canvases or windows. You generate a single region block from a single module component.

In some cases, you will want to generate multi-region blocks. As with single region blocks, a multi-region block is based on a single table. However, a multi-region block comprises a number of different rectangular layout regions. The layout regions in a multi-region block can be placed on:

- different places on the same canvas
- different canvases in the same window
- different canvases in different windows.

You generate a multi-region block by defining:

- a primary module component with one base table usage and (optionally) one or more lookup table usages
- one or more module sub-components, each with a usage of the same base table as the primary module component, and (optionally) each with one or more lookup table usages.

Form Generator creates a rectangular layout region for the primary module component and for each module sub-component. Although they contain items based on columns from the same table, the different layout regions can display different numbers of rows. The data in different regions in a multi-region block is always synchronized (i.e. the regions all display data for the same current record).

You can create bound items based on the same columns as bound items in the primary module component (or any other module sub-component). Note that Form Generator will generate second and subsequent items as mirror items. Also note the standard source objects for these mirror items will be the same as for the first bound item (i.e. not CGSO$CONTEXT, which is the usual standard source object for mirror items).

### Side By Side Blocks

By default, Form Generator places the second and subsequent blocks on the same canvas below the previous blocks on that canvas. Use a module component's Placement property and Right of Component property to place a block beside a previous block instead of below it.

When you create a new module component, it is automatically placed in a new window and on a different canvas. To generate two blocks side-by-side on the same canvas, you must first include the corresponding module components in the same window and on the same canvas.

To place a block beside a previous block on the same canvas:

- Set the module component's Placement property to Right of.
- Set the module component's Right of Component property to the name of a previous module component.

### Navigator Style Forms

A navigator style form enables users to quickly navigate through hierarchical data to locate a particular record and comprises:

- a hierarchical tree item in a navigator window
- one or more detail windows in which record details can be viewed and edited.

The look and feel of the expanding and collapsing tree is similar to the tree in the Design Editor's navigator window.

You can use Form Generator to generate a navigator style form by setting a module's Layout Format property to Navigator.

Form Generator generates the first block in the form on a new content canvas into a new window (the navigator window) and creates an item in the block of type Hierarchical Tree (note that the window, canvas, block and item are not modeled in the repository).

All blocks and records in the generated form are represented as nodes in the hierarchical tree item. When the form is opened, the navigator window displays all master blocks in the form as unexpanded 'block nodes'. If the user expands one of the block nodes, the records in the block appear as 'record nodes'. If the master block is linked to one or more detail blocks, each record node can be expanded to display a block node for the detail block(s). If the user expands the detail block node, the records in the detail block appear as record nodes.

At any point, the user can select a record node and view or edit that record in the corresponding block in a separate detail window.

You can also include buttons on vertical and horizontal toolbars in the navigator window to provide extra functionality. For example, you might want to include buttons to expand all nodes and collapse all nodes.

See the Oracle Designer online help for more information about generator Navigator Style Forms.

### Relative Tab Stops

Form Generator enables you to specify the points at which Form Generator is to position the starts and ends of items and their prompts. These points are referred to as tab stops.

In this release of Designer, there are now two kinds of tab stop:

- Absolute tab stops (old style - tab stop positions are specified in character cells and items are placed at those positions)
- Relative tab stops (new style - items sharing the same tab stop are positioned relative to each other).

Note that the use of absolute tab stops and relative tab stops are mutually exclusive.

Relative tab stops are numeric values that enable you to position and align items and item groups relative to each other (i.e. next to each other or below each other). Using relative tab stops also enables you to explicitly specify that you want a particular item or item group to appear on a new line.

You set relative tab stops for both items and item groups using either or both of the following relative tab stop properties:

- Start Tab Stop property
- End Tab Stop property

If you specify relative tab stops, during generation Form Generator horizontally positions items/item groups so that any items/item groups with the same relative tab values are vertically aligned below one another. The Start Tab Stop property and the End Tab Stop property determine whether it is the left hand edge, the right hand edge, or both edges of the item/item group that are aligned.

In addition, an item's Align Prompt property enables you to vertically align the starts of prompts of items that are vertically aligned (note that Form Generator might ignore this property to optimize the use of space).

When using relative tab stops, you can set the Tab Stop Scope property of a container object (i.e. an item group or module component) to align:

- items within an item group with items outside the item group
- items within one module component with items in another module component.

For detailed illustrations of how to use relative tab stops, refer to the online help topic 'Examples of the use of relative tab stops'.

#### Notes on the use of relative tab stops

Note the following when using relative tab stops:

- In general, Form Generator uses relative tab stops only if relative tab stops have been defined and the Tab Stop Scope property of an item group or module component is set to Self or Parent. Form Generator also uses relative tab stops to position items in an item group with its Tab Stop Scope property set to None if the object that contains the item group (i.e. a module component or another item group) has its Tab Stop Scope property set to Self or Parent. In this case, Form Generator positions items as if the item group's Tab Stop Scope property was set to Self.
- Items are always sequenced (for navigation purposes) according to the value of their Usage Sequence property. Relative tab stops are sequenced in their numeric order. If the relative tab setting of the next item in the usage sequence is lower than the relative tab setting of the previous item, Form Generator places the next item on a new line and aligns it appropriately.
- The interaction between relative tab stops and the BLKVFL preference is complex. For more information, refer to "Notes on relative tab stops and BLKVFL" in the Designer online help.
- We recommend you increase the numbers for relative tab stops in increments to allow for the subsequent insertion of new tab stops between existing ones.
- Post prompts cannot be aligned using relative tab stops.
- If you have specified relative tab stops, Form Generator increases the width of the canvas sufficiently to display all the items and item groups. In other words, block overflow does not occur.

# Chapter 6 Scenario 3: Migrate, Regenerate Incrementally

This is the most complex scenario. In this scenario, you will migrate your application a little at a time, rather than all at once.

- You will begin by upgrading all of your forms, libraries, menus and reports to Forms 9i.
- You will then make the changes required to run forms generated from your previous release of Designer alongside forms generated from Oracle9i Designer.
- Finally, over some arbitrarily long period of time, you will regenerate all of your modules out of Oracle9i Designer.

The goal of this scenario is to allow you to regenerate your whole application, taking into account new features, but in such a way that you do not have to migrate your entire application in one go. This means you will be able to move the deployed application to the new tool stack before you have completely migrated every form. Thus, you can continue with bug fixes and new development in parallel with the continuing migration effort.

## Migrating from 1.3.2

This section covers general migration issues when migrating from Designer Release 1.3.2. If you are migrating from a later release, you may skip this section.

### Review use of color palettes

When generating a form, Form Generator determines which color palette to give the generated form as follows:

- If a template form is being used, Form Generator gives the generated form the template form's color palette.
- If a template form is not being used, Form Generator gives the generated form the default Form Builder color palette.

In earlier releases, the template forms supplied with Form Generator did not use the default Form Builder template. Instead, they used a color palette similar to that used in Oracle Applications forms.

In this release, the shipped template forms supplied with Form Generator have been given the default Form Builder color palette.

The color palette consists of a grid, 38 colors wide by 6 colors high. The primary problems are caused in the first 14 columns of the grid. The remainder of the grid is very slightly different, but only noticable to the most discerning eye.

Designer 1.3.2, Custom Color Palette, first 14 columns

Black | White | r0g0b0 | r40g0b0 | r55g0b0 | r70g0b0 | r85g0b0 | r100g0b0 | r0g0b40 | r40g0b40 | r55g0b40 | r70g0b40 | r85g0b40 | r100g0b40
Control | Blue | r0g40b0 | r40g40b0 | r55g40b0 | r70g40b0 | r85g40b0 | r100g40b0 | r0g40b40 | r40g40b40 | r55g40b40 | r70g40b40 | r85g40b40 | r100g40b40
Button | Magenta | r0g55b0 | r40g55b0 | r55g55b0 | r70g55b0 | r85g55b0 | r100g55b0 | r0g55b40 | r40g55b40 | r55g55b40 | r70g55b40 | r85g55b40 | r100g55b40
Canvas | Red | r0g70b0 | r40g70b0 | r55g70b0 | r70g70b0 | r85g70b0 | r100g70b0 | r0g70b40 | r40g70b40 | r55g70b40 | r70g70b40 | r85g70b40 | r100g70b40
Gray | Cyan | r0g85b0 | r40g85b0 | r55g85b0 | r70g85b0 | r85g85b0 | r100g85b0 | r0g85b40 | r40g85b40 | r55g85b40 | r70g85b40 | r85g85b40 | r100g85b40
Yellow | Green | r0g100b0 | r40g100b0 | r55g100b0 | r70g100b0 | r85g100b0 | r100g100b0 | r0g100b40 | r40g100b40 | r55g100b40 | r70g100b40 | r85g100b40 | r100g100b40

Oracle9i Designer, Default Forms Color Palette, first 14 columns

Black | White | Green | Darkgreen | Gray96 | Gray92 | Gray88 | Gray84 | r0g0b0 | r25g0b0 | r50g0b0 | r75g0b0 | r88g0b0 | r100g0b0
Gray | Darkgray | Cyan | Darkcyan | Gray80 | Gray76 | Gray72 | Gray68 | r0g25b0 | r25g25b0 | r50g25b0 | r75g25b0 | r88g25b0 | r100g25b0
Red | Darkred | Blue | Darkblue | Gray64 | Gray60 | Gray56 | Gray52 | r0g50b0 | r25g50b0 | r50g50b0 | r75g50b0 | r88g50b0 | r100g50b0
Yellow | Darkyellow | Magenta | Darkmagenta | Gray48 | Gray44 | Gray40 | Gray36 | r0g75b0 | r25g75b0 | r50g75b0 | r75g75b0 | r88g75b0 | r100g75b0
Custom1 | Custom2 | Custom3 | Custom4 | Gray32 | Gray28 | Gray24 | Gray20 | r0g88b0 | r25g88b0 | r50g88b0 | r75g88b0 | r88g88b0 | r100g88b0
Custom5 | Custom6 | Custom7 | Custom8 | Gray16 | Gray12 | Gray8 | Gray4 | r0g100b0 | r25g100b0 | r50g100b0 | r75g100b0 | r88g100b0 | r100g100b0

Using both color palettes in the same application causes problems, because the color palette is loaded with the first form and then not reloaded. So, since your start form will be re-generated with the new color palette, all of your forms will use the new color palette.

Unfortunately, the colors are mapped by their position in the color palette, not by the actual color name. Thus, when one of your old forms uses a color, it is actually just using whichever color is in that position in the color palette.

So, given the two color palettes above:

If the old form asks for… | It actually gets…
Black | Black
White | White
Control | Gray
Button | Red
Red | Darkyellow
Cyan | Custom2

To further complicate matters, with Webforms, you don't have to specify colors in your forms at all. You can set all of your colors to 'undefined' or to the keyword 'automatic' in your object library. Then, you can pass a runtime parameter to the Forms60 Server that specifies the Look and Feel (Oracle or Generic) and the desired colorscheme. (There are 8 pre-defined color schemes.) At runtime, all items whose color is 'undefined' or 'automatic' will automatically be rendered with the proper colors for the selected colorscheme.

Unfortunately, the item prompts in the old forms that were generated by Designer 1.3.2 are generated as boilerplate and not using the prompt property. This means they will not be automatically changed at runtime.

#### Changing the Color Palette

You basically have two options to solve this problem:

- Modify the old forms to use the new color palette.
- Modify the new template form to use the old custom color palette.

To be able to change the color palette of an .fmb, Form Builder needs to be opened in a special ‘mode’. To do this, launch Form Builder, navigate to Tools > Preferences, and set ‘Color Mode’ to ‘editable’. Now close Form Builder, and open it again (this step is necessary).

Export the color palette you want to use to a file:

- Open a form which has the color palette that you want to use.
- Open the layout editor by double-clicking on a canvas (it doesn't matter which one)
- Choose File > Export > Color Palette. (If this option is grayed out, you have not successfully changed the “Color Mode” of Forms Builder.) Save the color palette to your file system. The file should have the extension '.pal'.

Import the color palette into the form(s) you want to change:

- Open the form whose color palette you want to change.
- Open the layout editor by double-clicking on a canvas (it doesn’t matter which one).
- Navigate to File > Import > Color Palette. (If this option is grayed out, you have not successfully changed the “Color Mode” of Forms Builder.)
- Choose “File” as Data Source, and click “Browse” to locate the color palette you exported.
- Click OK.

With your old forms, you will have to import the color palette into each form individually even if you used a reference form, because the color palette is not inherited from a reference form.

Unfortunately, we still have one more problem to overcome.

You have successfully installed the new color palette. If you look at the "Foreground Color" and "Background Color" properties for any given item, they appear to have the right values because the color names are correct. But, internally they are STILL pointing to the old position of that color in the color palette.

Even trickier is the fact that if you click on the LOV button next to the color value, the correct color in the color palette is highlighted, but internally it is STILL pointing to the wrong color.

The only way to correct this inconsistent state is to go to the property palette of the visual attribute used on the item, go to the "Background Color" and "Foreground Color" properties, first select any other color, and then change the color back to its original value. Now, not only the color name but also the underlying index value will point to the "true" color in the new color palette.

- The bad news is that you need to do this for ALL explicit color references. If you used a reference form to define visual attributes, and then used these visual attributes in your old template form, you only have to do this for each visual attribute in the reference form. However, if the visual attributes were directly in the template form, or if you set the colors directly in the template form, then you will have to open each form and 'fix' every color reference.
- Two exceptions are the colors "white" and "black". It is not necessary to 'fix' these colors, because they were not relocated between the two palettes.
- Another exception is the color "canvas". Since this color doesn't exist in the new color palette, all occurrences of "canvas" must be replaced with the color "gray".

What this all boils down to is this:

- Unless your old application is very small and you don't mind a lot of tedious work, you are going to have to continue to use the old custom color palette in your newly generated forms
- You probably won't be able to use the automatic color schemes with the new Oracle Look and Feel

### Toolbar vs. Smartbar

The Oracle9i Designer menu template makes use of the Smartbar feature of Forms. The toolbar is now defined declaratively in the menu rather than in every form.

In your old forms, you will now see both the Smartbar and the old toolbar canvas.

You have two options:

- Remove the toolbar block and canvas from your old forms.

> If you used a reference form with Designer 1.3.2, you can easily remove the toolbar block and canvas from all your forms by removing it from the reference form and then recompiling new .fmx files.

> If your toolbar block and canvas were directly in the 1.3.2 template form, then you would have to open each generated form and remove them.

- Remove the Smartbar from the new menu template and add a toolbar block and canvas to the new form template (subclassed from the object library of course).

To remove the Smartbar from the new menu template, you simply change the 'Visible in Horizontal Menu' property to 'No' for each item where it currently is set to 'Yes'.

You can copy your old toolbar block and canvas to your new template form.

### Dummy LOV Objects

For modules that call an LOV module (not a native Forms LOV), the Generator creates a dummy LOV object named CGxx$DUMMY_LOV and a corresponding Record Group object with the same name.

In Forms generated from Designer 1.3.2, the record group will have a Column Specification with one dummy column, also named CGxx$DUMMY_LOV, of type character, length = 1, with a default value of (again) CGxx$DUMMY_LOV.

Notice that the default value is longer than the length of the column. This now causes a compile error in forms. To resolve this, you must either clear the default value in the Column Specification of the record group or increase its length to 14.

Unfortunately, this has to be done manually.

### Upgrading forms to Forms 9i

You must upgrade all your existing forms to Forms 9i. You can use the Forms compiler to perform this upgrade.

ifcmpxx module= myform userid= scott/tiger upgrade=YES Logon=YES Batch=YES build=Yes Window_state=Minimize

You can run this in batch by creating a .bat file containing the above line of code once for each form to be upgraded.

### Regenerate Your Menu and Start Form

You will need to re-generate your menu(s) and start form. This ensures that all your forms run in the context of your new application.

### Upgrade Libraries to Forms or Reports 9i

Upgrading the libraries is straightforward. To upgrade manually, you open the library in Form Builder 9i (or Report Builder 9i). Form Builder will automatically start converting PL/SQL version to PL/SQL version 2. During this PL/SQL conversion it will ask you to confirm certain conversion operations. You can safely press the 'Convert All' button if you are prompted for such a conversion operation.

You can also create a .bat file to perform this upgrade in batch. Include the following line of code once for each library to be upgraded.

ifcmpxx module=<library>.pll userid=<user>/<pass>@<connect> module_type=LIBRARY Logon=YES Batch=Yes upgrade=YES version=45 build=No window_state=Minimize

### Attached OFG Libraries

Designer release 1.3.2 attached a number of OFG libraries to generated forms. You may also have attached some of those libraries to your custom PL/SQL libraries.

Form Generator does not use these libraries anymore. Form Generator now uses a new, renamed version for each of these libraries.

Designer 1.3.2 Library | Oracle9i Designer Library
OFG4BSL | OFGBSL
OFG4CALL | OFGCALL
OFG4HPL | OFGHPL
OFG4MES | OFGMES
OFG4MNL | OFGMNL
OFG4TEL | OFGTEL
| OFGNAVL
| OFGTAB
| OFGTREEN

You must make both sets of libraries available in your runtime environment. The old forms will continue to run with the old libraries until they have been upgraded.

When you regenerate your forms from Oracle9i Designer, they will automatically get the new libraries attached.

However, if you attached the OFG4… libraries to your pl/sql libraries you will have to upgrade each library manually.

- De-attach the obsolete OFG4… libraries from all libraries
- Attach the new OFG… libraries

### Name Resolution in 9i

Carefully read the section 'Name Resolution in 9i' in the Chapter 3 "General Migration Issues". It is highly likely you will run into these issues described there if your application has generic library routines that are overridden in module specific libraries.

### Replace Designer 1.3.2 forms with Oracle9i Designer forms

This step can be performed on a form-by-form basis. The actions required depend on the type of module. Refer to the chapters on 'General Migration Issues' and 'Scenario 2' for detailed information on regenerating your forms.

If you have a form that calls another form, you should replace both forms at the same time.

Once all forms have been replaced, you can remove the old OFG4… libraries from your runtime environment as well as any other old libraries, reference forms, and templates.

## Migrating from 2.1.2

This section covers general migration issues when migrating from Designer Release 2.1.2. If you are migrating from a later release, you may skip this section.

### Toolbar vs. Smartbar

The Oracle9i Designer menu template makes use of the Smartbar feature of Forms. The toolbar is now defined declaratively in the menu rather than in every form.

In your old forms, you will now see both the Smartbar and the old toolbar canvas.

You have two options:

- Remove the toolbar block and canvas from your old forms.

> If you used an object library with Designer 2.1.2, you can easily remove the toolbar block and canvas from all your forms by removing it from the object library and then recompiling new .fmx files.

> If your toolbar block and canvas were directly in the 2.1.2 template form, then you would have to open each generated form and remove it.

- Remove the Smartbar from the new menu template and add a toolbar block and canvas to the new form template (subclassed from the object library of course).

To remove the Smartbar from the new menu template, you simply change the 'Visible in Horizontal Menu' property to 'No' for each item where it currently is set to 'Yes'.

You can copy your old toolbar block and canvas to your new template form.

### Upgrading forms to Forms 9i

You must upgrade all your existing 5.0 forms to Forms 9i. You can use the Forms compiler to perform this upgrade.

ifcmpxx module= myform userid= scott/tiger upgrade=YES Logon=YES Batch=YES build=Yes Window_state=Minimize

You can run this in batch by creating a .bat file containing the above line of code once for each form to be upgraded.

### Regenerate Your Menu and Start Form

You will need to re-generate your menu(s) and start form. This ensures that all your forms run in the context of your new application.

### Upgrade Libraries to Forms or Reports 9i

Upgrading the libraries is straightforward. To upgrade manually, you open the library in Form Builder 9i (or Report Builder 9i). Form Builder will automatically start converting PL/SQL version to PL/SQL version 2. During this PL/SQL conversion it will ask you to confirm certain conversion operations. You can safely press the 'Convert All' button if you are prompted for such a conversion operation.

You can also create a .bat file to perform this upgrade in batch. Include the following line of code once for each library to be upgraded.

ifcmpxx module=<library>.pll userid=<user>/<pass>@<connect> module_type=LIBRARY Logon=YES Batch=Yes upgrade=YES version=50 build=No window_state=Minimize

### Replace Designer 2.1.2 forms with Oracle9i Designer forms

This step can be performed on a form-by-form basis. The actions required depend on the type of module. Refer to the chapters on 'General Migration Issues' and 'Scenario 2' for detailed information on regenerating your forms.

If you have a form that calls another form, you should replace both forms at the same time.

Once all forms have been replaced, you can remove the old OFG4… libraries from your runtime environment as well as any other old libraries, reference forms, and templates.

## Migrating from 6.0

This section covers general migration issues when migrating from Designer Release 6.0.

### Toolbar vs. Smartbar

The Oracle9i Designer menu template makes use of the Smartbar feature of Forms. The toolbar is now defined declaratively in the menu rather than in every form.

In your old forms, you will now see both the Smartbar and the old toolbar canvas.

You have two options:

- Remove the toolbar block and canvas from your old forms.

> If you used an object library with Designer 6.0, you can easily remove the toolbar block and canvas from all your forms by removing it from the object library and then recompiling new .fmx files.

> If your toolbar block and canvas were directly in the 6.0 template form, then you would have to open each generated form and remove it.

- Remove the Smartbar from the new menu template and add a toolbar block and canvas to the new form template (subclassed from the object library of course).

To remove the Smartbar from the new menu template, you simply change the 'Visible in Horizontal Menu' property to 'No' for each item where it currently is set to 'Yes'.

You can copy your old toolbar block and canvas to your new template form.

### Regenerate Your Menu and Start Form

You will need to regenerate your menu(s) and start form. This ensures that all your forms run in the context of your new application.

### Replace Designer 6.0 forms with Oracle9i Designer forms

This step can be performed on a form-by-form basis. The actions required depend on the type of module. Refer to the chapters on 'General Migration Issues' and 'Scenario 2' for detailed information on regenerating your forms.

If you have a form that calls another form, you should replace both forms at the same time.

Once all forms have been replaced, you can remove the old OFG4… libraries from your runtime environment as well as any other old libraries, reference forms, and templates.

Prev | Next
| Copyright © 2002, Oracle Corporation. All Rights Reserved. |
Contents