Overview of Coding Standards

Importance of these Standards

The coding standards described in this manual, together with the user
interface standards described in the Oracle Applications User Interface
Standards for Forms–Based Products, are used by Oracle Corporation
developers to build Oracle Applications. If you want to build custom
application code that integrates with and has the same look and feel as
Oracle Applications, you must follow these standards. If you do not
follow these standards exactly as they are presented, you may not
achieve an acceptable result.
This manual makes no attempt to analyze the consequences of
deviating from the standards in particular cases. The libraries and
procedures that are packaged with Oracle Applications all assume
adherence to these standards. In fact, since the behavior of Oracle
Forms, the Oracle Applications standard libraries, and the standards
are so tightly linked, a deviation from standards that appears to be
minor may in fact have far–reaching and unpredictable results.
Therefore, we recommend that when you develop custom application
code, you follow the standards exactly as they are described in this
manual and in the Oracle Applications User Interface Standards for
Forms–Based Products.

Coding Principles

Oracle Applications coding standards are guided by the following
principles:
• Code must be readable to be maintained
• Tools such as Oracle Forms and PL/SQL are used whenever
possible (avoid complex user exits using other coding languages)
• Fast performance over the World Wide Web (the web) is critical
• Platform–specific code should be avoided except where
absolutely necessary
• Reusable objects should be employed wherever possible

Coding With Handlers

Oracle Applications uses groups of packaged procedures, called
handlers, to organize PL/SQL code in forms so that it is easier to
develop, maintain, and debug.
In Oracle Forms, code is placed in triggers, which execute the code
when that trigger event occurs. Implementing complex logic may
require scattering its code across multiple triggers. Because code in
triggers is not located in one place, it cannot be written or reviewed
comprehensively, making development, maintenance, and debugging
more difficult. To determine what code and events affect a particular
item, a developer must scan many triggers throughout the form. Code
that affects multiple items can be extremely difficult to trace.
To centralize the code so it is easier to develop, maintain, and debug,
place the code in packaged procedures and call those procedures from
the triggers. Pass the name of the trigger as an argument for the
procedure to process. This scheme allows the code for a single
business rule to be associated with multiple trigger points, but to reside
in a single location.
There are different kinds of procedures for the different kinds of code
you write: item handlers, event handlers, table handlers, and business
rules. Code resides in these procedures; do not put any code in the
triggers other than calls to the procedures.
Handlers may reside in program units in the form itself, in form
libraries, or in stored packages in the database as appropriate.

Item Handlers

An item handler is a PL/SQL procedure that encapsulates all of the
code that acts upon an item. Most of the validation, defaulting, and
behavior logic for an item is typically in an item handler.

Event Handlers

An event handler is a PL/SQL procedure that encapsulates all of the
code that acts upon an event. Usually event handlers exist to satisfy
requirements of either Oracle Forms or the Oracle Applications User
Interface Standards for Forms–Based Products, as opposed to particular
business requirements for a product.

Table Handlers

A table handler encapsulates all of the code that manages interactions
between a block and its base table. When an updatable block is based
on a view, you must supply procedures to manage the insert, update,
lock and delete. Referential integrity checks often require additional
procedures. Table handlers may reside on either the forms server or
the database, depending on their size and the amount of interaction
with the database, but they typically reside in the database.

Business Rules

A business rule describes complex data behavior. For example, one
business rule is: ”A discount cannot be greater than 10% if the current
credit rating of the buyer is less than ’Good’.” Another business rule is:
”A Need–By Date is required if a requisition is made for an inventory
item.”
A business rule procedure encapsulates all of the code to implement
one business rule when the business rule is complex or affects more
than one item or event. The business rule procedure is then called by
the item or event handlers that are involved in the business rule. If the
business rule is simple and affects only one item or event, implement
the business rule directly in the item or event handler.

Libraries

Libraries contain reusable client–side code. They support these form
coding standards by allowing the same code to be used by all forms to
enforce specific validation, navigation and cosmetic behaviors and
appearances.
Libraries allow code to be written once and used by multiple forms.
Additionally, because the executables attach at runtime, they facilitate
development and maintenance without being invasive to a form.
Every form requires several standard triggers and procedures to link
the form with a library. Many of these triggers and procedures have a
default behavior that a developer overrides for specific items or blocks.

Application–Specific Libraries

Each application is strongly encouraged to create its own libraries.
Typically, each application creates a central library that governs
behaviors of objects found throughout many of its forms. Additional
libraries should be created for each major transaction form to facilitate
the following:
• Multiple developers can work on a single module, with some
developers coding the actual form and others coding the
supporting libraries.
• Shipment and installation of patches to code is vastly simplified
if the correction is isolated in a library. Libraries do not require
any porting or translation.
All libraries should reside in the $AU_TOP/resource directory (or its
equivalent).

Attaching Libraries

Sometimes library attachments can be lost on platforms that have
case–sensitive filenames. By Oracle Applications standards, library
names must be in all uppercase letters (except for the file extension).
However, for forms developed using Microsoft Windows, the library
filename may be attached using mixed case letters, making the
attachment invalid on case–sensitive platforms such as Unix. If you
attach a library to a form in the Oracle Forms Developer on Microsoft
Windows, you should avoid using the Browse mechanism to locate the
file. Instead, type in just the filename, in uppercase only, with no file
extension (for example, CUSTOM). Oracle Forms will then preserve
the attachment exactly as you typed it. Note that your attachment
should never include a directory path; your FORMS60_PATH should
include the directory that holds all your libraries.

Performance

Performance is a critical issue in any application. Applications must
avoid overloading the network that connects desktop client, server, and
database server computers, since often it is network performance that
most influences users’ perceptions of application performance.
Oracle Applications are designed to minimize network traffic on all
tiers. For example, they try to limit network round trips to one per
user–distinguishable event by employing the following coding
standards:

• Use database stored procedures when extensive SQL is required
• Code all non–SQL logic on the client side where possible
• Cache data on the client side where practical
• Base blocks on views that denormalize foreign key information
where practical


Coding for Web Compatibility

Following Oracle Applications standards carefully will help ensure that
your forms can be deployed on the Web.
You should avoid using the following features in your forms, as they
are not applicable in this architecture:
• ActiveX, VBX, OCX, OLE, DDE (Microsoft Windows–specific
features that would not be available for a browser running on a
Macintosh, for example, and cannot be displayed to users from
within the browser)
• Timers other than one–millisecond timers (one–millisecond
timers are treated as timers that fire immediately)
• WHEN–MOUSE–MOVE, WHEN–MOUSE–ENTER/LEAVE and
WHEN–WINDOW–ACTIVATED/DEACTIVATED triggers
• Open File dialog box
– It would open a file on the applications server, rather than
on the client machine (where the browser is) as a user might
expect
• Combo boxes
– Our standards do not use combo boxes anyhow
• Text_IO and HOST built–in routines
– These would take place on the applications server, rather
than on the client machine (where the browser is) as a user
might expect

The Standard Development Environment

These coding standards assume that you are developing code in the
appropriate Oracle Applications development environment, which
includes compatible versions of several products. You can ensure that
you have all the correct versions of the Oracle Applications and other
Oracle products by installing all products from one set of Oracle
Applications Release 11i CDs.
• Oracle Forms Developer 6i
• Oracle Reports Developer 6i
• Oracle Application Object Library Release 11i
• Oracle8i
• JInitiator
While you can develop forms using the standard Oracle Forms
Developer, you cannot run your Oracle Applications–based forms from
the Oracle Forms Developer. Running such forms requires additional
Oracle Application Object Library user exits referred to by the libraries,
as well as settings and runtime code that can only be seen when
running forms through a browser with JInitiator. Both the libraries and
the user exits also assume a full installation of the Oracle Application
Object Library database schema, as they reference tables, views, and
packages contained therein.

Mandatory Settings for Running Oracle Applications

The html file used to launch Oracle Applications must include several
specific settings for Oracle Applications to function properly. The
following table contains the required parameters and their required
values:
Name Value
colorScheme- blue
lookAndFeel -oracle
separateFrame- true
darkLook -true
readOnlyBackground- automatic
dontTruncateTabs- true
background- no

Additionally, the file OracleApplications.dat must contain the
following lines:
app.ui.requiredFieldVABGColor=255,242,203
app.ui.lovButtons=true
app.ui.requiredFieldVA=true
There are several variables that must be set correctly, either as Unix
environment variables or NT Registry settings, before starting up your
Forms Server for running Oracle Applications. These variables include
NLS_DATE_FORMAT. NLS_DATE_FORMAT must be set to
DD–MON–RR

Mandatory Settings for Form Generation

At form generation time, make sure you designate the character set
designed for your language in the NLS_LANG variable in your
Windows NT registry or environment file (for Unix). You must ensure
that the character set you specify is the character set being used for
your Oracle Applications installation.
You must also set the value of your FORMS60_PATH environment
variable in your environment file (or platform equivalent such as
Windows NT registry) to include any directory that contains forms,
files, or libraries you use to develop and generate your forms.
Specifically, you must include a path to the <$AU_TOP>/forms/US
directory to be able to find all referenced forms, and a path to the
<$AU_TOP>/resource directory to be able to find the Oracle
Applications library files you need (where <$AU_TOP> is the
appropriate directory path, not the variable).

Recommended Setting for Form Development

Oracle Forms Developer allows referenced objects to be overridden in
the local form. Oracle Forms Developer also does not normally
provide any indication that an object is referenced unless you set a
special environment variable (Registry setting for NT). Set the
environment variable (Registry setting) ORACLE_APPLICATIONS to
TRUE before starting Oracle Forms Developer. This setting allows you
to see the reference markers (little flags with an ”R” in them) on
referenced objects so you can avoid changing referenced objects
unintentionally. Any object referenced from the APPSTAND form must
never be changed.

Oracle Application Object Library for Release 11i

Oracle Application Object Library (AOL) for Release 11i includes
(partial list):
• Starting forms
– Template form with standard triggers (TEMPLATE)
– Form containing standard property classes for your runtime
platform (APPSTAND)
• PL/SQL libraries
– Routines for Flexfields, Function security, User Profiles,
Message Dictionary (FNDSQF)
– Standard user interface routines (APPCORE, APPCORE2)
– Routines for Calendar widget (APPDAYPK)
• Development standards
– Oracle Applications User Interface Standards for Forms–Based


Setting Object Characteristics

The characteristics of most form objects, including modules, windows,
canvases, blocks, regions, and items may be set in the following ways:
• Inherited through property classes, which cause certain
properties to be identical in all forms (such as canvas visual
attributes)
• At the discretion of the developer during form design (such as
window sizes)
• At runtime, by calling standard library routines (such as window
positions)

Shared Objects
These standards rely extensively on the object referencing capabilities
of Oracle Forms. These capabilities allow objects to be reused across
multiple forms, with changes to the master instance automatically
inherited by forms that share the object. Additionally, these shared
objects provide flexibility for cross–platform support, allowing Oracle
Applications to adhere to the look and feel conventions of the platform
they run on.
APPSTAND Form
The APPSTAND form contains the master copy of the shared objects.
It contains the following:
• Object group STANDARD_PC_AND_VA, which contains the
Visual Attributes and Property Classes required to implement
much of the user interface described in the Oracle Applications
User Interface Standards for Forms–Based Products. A property
class exists for almost every item and situation needed for
development.
• Object group STANDARD_TOOLBAR, which contains the
windows, canvasses, blocks, and items of the Applications
Toolbar. This group also contains other items which are required
in all forms but are not necessarily part of the Toolbar.
• Object group STANDARD_CALENDAR, which contains the
windows, canvasses, blocks, and items of the Applications
Calendar.
Object group QUERY_FIND, which contains a window, canvas,
block, and items used as a starting point for coding a Find
Window. This object group is copied into each form, rather than
referenced, so that it can be modified.

TEMPLATE Form

The TEMPLATE form is the required starting point for all development
of new forms. It includes references to many APPSTAND objects,
several attached libraries, required triggers, and other objects.
Start developing each new form by copying this file, located in
$AU_TOP/forms/US (or your language and platform equivalent), to a
local directory and renaming it as appropriate. Be sure to rename the
filename, the internal module name, and the name listed in the call to
FND_STANDARD.FORM_INFO found in the form–level PRE–FORM
trigger.

FNDMENU

The Oracle Applications default menu (with menu entries common to
all forms, such as File, Edit, View, Help, and so on) is contained in the
$AU_TOP/resource/US directory (or its equivalent) as the file
FNDMENU. You should never modify this file, nor should you create
your own menu for your forms.

Standard Libraries

Application Object Library contains several libraries that support the
Oracle Applications User Interface Standards for Forms–Based Products:

• FNDSQF contains packages and procedures for Message
Dictionary, flexfields, profiles, and concurrent processing. It also
has various other utilities for navigation, multicurrency, WHO,
etc.

• APPCORE and APPCORE2 contain the packages and procedures
that are required of all forms to support the menu, Toolbar, and
other required standard behaviors. APPCORE2 is a
near–duplicate of APPCORE intended for use with the CUSTOM
library.

• APPDAYPK contains the packages that control the Applications
Calendar.

• APPFLDR contains all of the packages that enable folder blocks.

• VERT, GLOBE, PSAC, PQH_GEN, GHR, JA, JE, and JL exist to
support globalization and vertical markets. These libraries are
for Oracle Applications use only and may not be attached to
custom forms. However, they appear to be attached to most
forms based on the TEMPLATE form because they are attached
to the APPCORE library or other standard libraries.

• CUSTOM contains stub calls that may be modified to provide
custom code for Oracle Applications forms without modifying
the Oracle Applications forms directly.

The TEMPLATE form includes attachments to the FNDSQF, APPCORE
and APPDAYPK libraries. Other standard Oracle Applications libraries
are attached to those libraries and may appear to be attached to the
TEMPLATE form.


Property Classes

Property classes are sets of attributes that can be applied to almost any
Oracle Forms object. The TEMPLATE form automatically contains
property classes, via references to APPSTAND, that enforce standard
cosmetic appearances and behaviors for all widgets and containers as
described in the Oracle Applications User Interface Standards for
Forms–Based Products.

Application–specific Property Classes, Object Groups and Objects
Each application should take advantage of the referencing capabilities
of Oracle Forms to help implement standards for their particular
application in the same manner as APPSTAND.
For example, the General Ledger application might have specified
standard widths and behaviors for ”Total” fields throughout the
application. A GL_TOTAL Property Class, referenced into each form,
could set properties such as width, format mask, etc. A General
Ledger developer, after referencing in this set of property classes, can
then simply apply the GL_TOTAL property class to each item in the
form that is a Total field and it inherits its standard appearance and
behavior automatically. Entire items or blocks can also be reused.
Further, property classes can be based on other property classes, so the
GL_TOTAL class could be based on the standard TEXT_ITEM_
DISPLAY_ONLY class in APPSTAND. Such subclassing allows the
application–specific object to inherit changes made within APPSTAND
automatically.
Most Oracle Applications products also have a ”standard” form
(typically called [Application short name]STAND, such as GLSTAND
or BOMSTAND) in the same directory if you install the development
versions of those products. These files are used for storing
application–specific object groups, property classes, and other objects
that are referenced into Oracle Applications forms.

Visual Attributes

All of the visual attributes described in the Oracle Applications User
Interface Standards for Forms–Based Products are automatically included
in the TEMPLATE form via references to APPSTAND. Each visual
attribute is associated with a property class or is applied at runtime by
APPCORE routines.
For detailed information about the specific color palettes and effects of
the visual attributes, see the Oracle Applications User Interface Standards
for Forms–Based Products.

Overview of Application Development Steps

This is the general process of creating an application that integrates
with Oracle Applications.
1. Register your application.
2. Set up your application directory structures.
3. Modify the appropriate environment files.
4. Register your custom Oracle schema.
5. Include your custom application and Oracle schema in data
groups.
6. Create your application tables and views.
7. Integrate your tables and views with the Oracle Applications APPS
schema.
8. Register your flexfields tables.
9. Build your application libraries and forms.
10. Build your application functions and menus.
11. Build your application responsibilities.
12. Build concurrent programs and reports.
13. Customize Oracle Applications forms if necessary using the
CUSTOM library.

Overview of Form Development Steps

This is the general process of building a form that integrates with
Oracle Applications.
1. Copy the form TEMPLATE and rename it.
2. Attach any necessary libraries to your copy of TEMPLATE.
TEMPLATE comes with several libraries already attached.
3. Create your form blocks, items, LOVs, and other objects and apply
appropriate property classes.
4. Create your window layout in adherence with the Oracle
Applications User Interface Standards for Forms–Based Products.
5. Add table handler logic.
6. Code logic for window and alternative region control.
7. Add Find windows and/or Row–LOVs and enable Query Find.
8. Code logic for item relations such as dependent fields.
9. Code any messages to use Message Dictionary.
10. Add flexfields logic if necessary.
11. Add choices to the Special menu and add logic to modify the
default menu and toolbar behavior if necessary.
12. Code any other appropriate logic.
13. Test your form by itself.
14. Register your form with Oracle Application Object Library.
15. Create a form function for your form and register any subfunctions.
16. Add your form function to a menu, or create a custom menu.
17. Assign your menu to a responsibility and assign your responsibility
to a user.
18. Test your form from within Oracle Applications (especially if it
uses features such as user profiles or function security).