GNM_RCS_Oracle_Forms_Standards_TR

• 1. .Introduction

     1. Purpose

This document outlines the standards for all Oracle Forms development for the Rights & Contributor System (RCS).

These standards are to be followed in development wherever possible, unless there is a pressing need to deviate from them.

The standards are based on O3 Team Limited’s own in-house standards.

• 1. Scope

This document covers Oracle Forms standards, but not the PL/SQL written within the Form triggers of program units: a separate set of PLSQL standards deals with PLSQL objects stored on the database (triggers, packages, procedures & functions), and PL/SQL written into Oracle Forms and Oracle Reports.

• 1. .Oracle Forms

     1. Names

        1. Menus

There are two menus Forms:

• • rcs_menu.mmb internally named RCS_MENU

  • rcs_menu_nologon.mmb internally named RCS_MENU_NOLOGON

The first is used in all screens where the user is logged in and the 2nd for screens where the user is not logged in i.e. the login screen.

• 1. PLSQL libraries

There are two library Forms:

• • rcs_library.pll internally named RCS_LIBRARY

  • webutil.pll supplied by Oracle and internally named WEBUTIL

The first of these is attached to all Forms, the 2nd only to those Forms that require interaction with the client operating system files.

• 1. Object libraries

There are two object libraries:

• • rcs_objects.olb internally named RCS_OBJECTS

  • webutil.olb internally named WEBUTIL

The first of these is reference by all Forms for standard groups of objects, such as alerts and Form-level triggers; the 2nd only by those Forms that require interaction with the client operating system files.

• 1. Forms

The modules of type Form are the actual interface the user sees and uses to maintains data, with the exception of one Form that is used as a source of referenced objects:

• • rcs_reference.fmb

All other Forms are named according to these standards:

Report submission screens rcs_reports_999_pc.fmb internally named RCS_REPORTS_999

Other screens rcs_<alias>_999_pc.fmb internally named RCS_<alias>_999

Where <alias> is the four-letter alias used for the main table managed by the screen;

999 is a unique number (usually increments of 10) within each <alias> identifying the screen; and

_pc is a throwback to when there were separate screens for PC and MAC deployment.

Exceptions to the rule include the logon screen (rcs_logon_pc.fmb), the password reset screen (rcs_reset_pc.fmb), and the welcome screen (rcs_splash_pc.fmb).

• 1. Properties

All Oracle Forms should have the subclass FORM. This will set the following properties:

NB Required Enforcement is deferred to enable a When-Validate-Trigger to highlight all mandatory fields in red if they have no value. This is a style requested by GNM at the outset.

Other properties that need to be set are:

No other properties need to be set as the defaults are satisfactory.

The Current Record Visual Attribute Group should NOT be set. The style devised for RCS is that the current record is only highlighted in a different colour if multiple records in a Block are visible and furthermore only text items are highlighted, not checkboxes or radio groups.

• 1. .Triggers

     1. Usage

Triggers that are available only for backward compatibility must not be used. For example, the When-Validate-Item trigger should be used instead of the Post-Change trigger. It is possible such triggers may be deprecated in a future release of Oracle Forms.

No user defined triggers may be written. Program Units must be used instead.

• 1. Standards

Many Form-level triggers perform pre-defined functions throughout the application. Such triggers are therefore inherited into the Oracle Forms via a referenced Object Group.

• 1. Start-up

Start-up processing (Pre-Form and When-New-Form-Instance) occurs once on entry to the Form. The PRE-FORM triggers shall always have this library call:

l_startup.generic_processing;

This does the following:

• • Defines the size of the main window, and displays it; and

  • Assigns this window a title.

The start-up processing usually includes specific code added by the programmer; for this reason these triggers must not be referenced.

• 1. Exit

When exiting a Form, the user should always be prompted as to whether they wish to commit any outstanding changes in that Form.

• 1. Others

A Key-Others trigger shall be used (referenced) to disable other keystrokes that are not going to be provided in the application. This includes Key-F0 to Key-F9.

• 1. Reuse functionality across Forms

Defining common triggers in an Object Group in a reference Form helps provide consistent functionality across all Forms.

The Object Group TRIGGERS_FORM must be referenced into all Forms and any template Forms.

To minimise the impact of changing the functionality of any of these triggers, the triggers in the reference Form should execute code written in the library rcs_library.

• 1. Reuse functionality within a Form

When programmatically executing built-ins that correspond to key triggers, it is almost always better to use do_key(<built-in>) instead. This technique ensures that a Form behaves in a more consistent manner, and avoids the repetition of any Form-specific code on the key trigger.

A good example of this is a When-New-Form-Instance trigger that should execute a query on entry to the Form. It should have the code do_key(‘execute_query’);.

The toolbar buttons that provide key functionality must also use the corresponding built-in.

• 1. Level

Triggers shall be written at the level that they are most appropriate to.

• 1. Execution hierarchy

The Execution hierarchy property can be left as default i.e. Override, unless other behaviour is required.

As described above, most key triggers are referenced at Form-level to ensure standardised behaviour. When duplicating such triggers at a lower level it may be necessary to set the Execution hierarchy property to “Before” or “After” to augment such functionality.

• 1. .Alerts

     1. Usage

Alerts are used for all programmer defined messages that must be sent to the user. The message built-in must not be used as users often don’t notice that are on the status line of the window.

• 1. Standards

Several standard alerts are provided as referenced objects from the reference Form via the Object Group ALERTS. These alerts are listed below, along with a guide to the severity of the conditions appropriate to each alert, and the behaviour of the buttons.

In the right hand column above, those buttons highlighted in bold are the “default” button for that alert.

New alerts may be added to Forms if none of the above is deemed suitable for the message being raised.

• 1. .Attached Libraries

Libraries provide a single source of code that can be used by many Forms and menus. Using libraries improves the modularity of the system, and significantly reduces the overhead of implementing changes, as only the library needs to be changed.

However there is an overhead that when a library is compiled the Forms that have it attached also should be recompiled.

• 1. Usage

PL/SQL code should be written into a library if:

• • It can be used by multiple Forms; and

  • It does not reference the database (this would be better as database PL/SQL)

No direct reference to a Form field or system variable is allowed in library code, as the fields do not exist in the library Form and so it will not compile. Library code can be written, however, to reference system variables and fields in the Form to which the library is attached by using the name_in built-in. Form fields can also be written to using the copy and default_value built-ins, provided the fields can be identified using system variables or have their names passed in. Items in the Forms can also be accessed by declaring IN or IN OUT parameters of datatype ITEM.

• 1. Standards

     1. Remove path

When attaching Libraries to Forms (from the file system) always choose to remove the path.

• 1. Avoid hierarchies

In RCS libraries are only attached to Forms and menus. Libraries can, in theory, be attached to other libraries, and a hierarchy of libraries can be built up, but for the sake of simplicity this should not be done. It is far easier to combine such hierarchical structures into one library.

• 1. .Blocks

     1. Usage

Every Form that has date fields shall have a referenced Object Group CALENDAR, which includes a Block named CALENDAR. Every Form that uses WEBUTIL shall have a Block of that name too.

Those Blocks aside, all other Blocks are defined in the Form as either:

• • Data Blocks (which have an underlying table or view); or

  • Control Blocks (non-base table Blocks).

• 1. Standards

     1. Names

Control Blocks should be named CTRL or a name that succinctly conveys the Block’s intended use within the Form e.g. SEARCH. Such names should be meaningful enough to be clear and unambiguous, yet concise so as to not be cumbersome to reference within code.

Base table Blocks must be named using the 4-letter alias associated with the underlying table. These aliases are described elsewhere in the core technical documentation. For example, Block CURR would query data from table CURRENCIES. If two or more Blocks are based on the same table, then a numeric ordinal shall be suffixed to each common Block name in order to uniquely distinguish them e.g. CURR1 and CURR2.

• 1. Block linking

Use Oracle Forms default Block linking code and Relation objects wherever possible.

• 1. Properties

The Property Class BLOCK_DATABASE should be attached to each Data Block to provide a standard look and feel. Importantly this sets the following properties:

If a Block can be scrolled it should have a scrollbar, which should have Visual Attribute SCROLLBAR.

Navigation Style should be Same Record, unless usability dictates otherwise.

All base table Blocks should have an Alias (of the same name) and an Order By Clause.

• 1. Items

     1. Names

Base table items should be named the same as the underlying columns of the table.

Non-base table fields should be given names that reflect the data being displayed, along with a prefix NBT_ (Non-Base-Table)

For example, if the NAME column from table CONTENT_PROVIDERS (CPRO) is to be displayed in a Block where the base table is COMMISSIONS, then a suitable name for the lookup field would be NBT_CPRO_NAME.

• 1. Main properties

A Property Class must be referenced in the Subclass Information for all visible items, or an item in another Form should be referenced. Amongst other things, Property Classes are used to control the size of fields in Oracle Forms, the font used, and so on. There are also standard triggers on some of the Property Classes (e.g. those for Date, Datetime and Multi-line text fields) which are inherited by the Item.

It is essential that Property Classes be applied to ensure the application is more easily to maintain.

Besides the properties that are inherited from the Property Class, the following are most significant Item properties:

• 1. Other properties

The following Item standards apply:

• • Items must be navigable left to right and top to bottom, to ensure consistent navigation throughout the system;

  • Scrollbars must be applied to multi-line fields;

  • Hints should be entered with Auto Hint turned on;

  • Hints and Tooltips should have the same values;

  • Display Items should be used for display-only fields;

  • Check Boxes should only be used for Boolean or mandatory yes/no input;

  • Date Items must have a Format mask of ”DD/MM/YYYY”;

  • Datetime Items must have a Format mask of ”DD/MM/YYYY HH24:MI:SS”;

  • Button items must always have a label and a short-cut letter; and

  • Multi-line fields should have the property Wrap Style set to Word.

• 1. .Canvases

     1. Usage

All Forms have standard Canvases inherited from the Object Group CANVASES.

Other Canvases may be added to individual Forms as needed.

• 1. Standards

Where possible the Subclass Information for new canvases should refer to another Canvas of the same type in this or another Form:

Properties

• • The Popup menu CANVAS should be used;

  • The Visual Attribute should be FONT; and

  • The Background Color should be WHITE.

NB If the Canvas is to the have coloured background then a Visual Attribute such as WEB_BACKGROUND_COLOUR should be used

If the Canvas Type is Tab then each Tab Page must have a Label and usually a Visual Attribute of FONT.

• 1. .Editors

Oracle Forms allows the user to use an editor when the operator has navigated to a text item. This allows the operator a larger window to edit text in, along with some basic editing features.

When an editor is displayed at runtime, Oracle Forms is in Edit mode, and no triggers fire until the operator returns to Normal mode by dismissing the editor.

• 1. Usage

The default editor is to be available on double-click in multi-line text items.

A standard menu option in the main menu allows the user to open the editor:

Tools → Edit → Edit

Invoking the editor should be at the discretion of the operator. In special circumstances the editor can be invoked programmatically by executing the edit_textitem built-in procedure when the cursor is in a text item.

• 1. Standards

Do not define user-named editors. It is very unlikely they will work on both the PCs and Macs that the system is deployed on.

• 1. .LOVs

     1. Usage

Oracle Forms LOVs should be used instead of bespoke screens to implement list of values functionality.

LOVs should be provided for all foreign key/descriptor items in base table Blocks.

• 1. Standards

     1. Names

Prefixes and suffixes of “LOV” must not be used in LOV names.

Usually an LOV is given the same name as the Record Group whose data it displays.

For example, the LOV CPRO would display the data returned by the Record Group CPRO (Content Providers data).

Where multiple LOVs are based on the same record group, a distinguishing suffix should be used. For example, the LOVs CPRO_PAYEE and CPRO_CONTRIBUTOR would both be based on the Record Group CPRO, but would have different usages in a Form.

• 1. Properties

All LOVs must have a Property Class attached. At the time of writing, the following are made available from the reference Form for this purpose:

• • LOV

  • LOV_BIG

  • LOV_SMALL

LOVs must always be given a Title.

ID columns must never be displayed, where they have no inherent business meaning.

All other LOV columns shall be given user-friendly Titles.

Date columns must be given a width that is sufficient for the standard Format “DD/MM/YYYY”.

The height and width of the LOV should reflect the amount of data to be displayed.

• 1. Invoking LOVs

When an LOV is invoked it can restrict the data retrieved by the value in the field that is the input focus. In general this facility is not implemented.

As a general rule, the list_values built-in shall be used to implement List of Values functionality. The show_lov built-in Boolean function is only used in circumstances where the result of the operation is needed i.e. was a value chosen or not (TRUE/FALSE).

LOVs should not be automatically invoked on entry to an item, unless this improves the user experience.

The ‘Validate From List’ item property is used where no other values are allowed.

• 1. .Object Groups

Object Groups are used to bundle together related objects. Used properly they are very valuable as they can significantly enhance consistency across the application and reduce maintenance overheads.

• 1. Usage

Object Groups should only be defined for the purpose of referencing them from one Form to another, as they achieve little when defined in isolation. A core set of universally used Object Groups exists in the reference Form rcs_reference.fmb. These tend to deal with look and feel objects such as alerts, property classes and Visual Attributes.

Other Object Groups are defined in the main Forms to ensure specific features can be defined once and replicated across many Forms e.g. a Contributor pop-up Object Group that contains a Window, a Canvas, a Block, Record Groups and corresponding LOVs, and Program Units.

When new objects are added to an Object Group in the reference Form, the new objects will be inherited in all Forms that reference the Object Group the next time those Forms are loaded into Forms Designer, or compiled on the server.

The following Object Groups are available in the RCS_REFERENCE reference Form.

ALERTS

CALENDAR

CANVASES

POPUP_MENUS

PROPERTY_CLASSES

TRIGGERS_FORM

VISUAL_ATTRIBUTES

WINDOWS

• 1. Standards

     1. Placement

In general existing Object Groups must be added to, instead of adding new Object Groups.

However, if a group of objects is required in a small number of Forms then a new Object Group may be created within one of those Forms and referenced in the others.

A new Object Group is created in the lowest numbered Form, and inherited in the others e.g. an Object Group in rcs_comm_010_pc.fmb might be inherited in rcs_comm_020_pc.fmb, rcs_comm_040_pc.fmb, and rcs_comm_041_pc.fmb.

• 1. Names

Object groups that contain standard objects of a particular type should be named after that object type e.g. ALERTS, CANVASES and POPUP_MENUS.

Object groups that provide a self-contained area of functionality should be given a meaningful name e.g. CALENDAR, CONTRIBUTOR_POPUP and RIGHTS_PALETTE.

• 1. .Parameters

This section covers Form parameters. It does not deal with procedure, function or cursor parameters. Standards relating to these are documented in the PL/SQL Standards and Guidelines.

• 1. Usage

Parameters must be used to pass data values to called Forms. Global variables should not be used for this purpose.

If data needs to be passed back from a called Form to its calling Form two options are available:

• 1. Global variables can be used; or

  2. programme data can be defined in a library or database package.

  3. Standards

Parameters can be added as needed in accordance with the standards below:

• 1. Names

If the data being passed is the context of the calling Form then the parameter name should reflect that data context e.g. FRMT_CODE would be used to receive a content Format code.

Parameters should not be prefixed with P_ or any other such indication: they will always be referenced in the Form as :parameter.<name> so P_, for example, would be superfluous.

If the parameter is used to convey an instruction rather than pass a data context, its name is usually MODE. This parameter is used to determine how a Form should behave, where the same Form can be run in different ways for different purposes when called from another Form or from the Menu.

• 1. Datatype and defaults

Char is used for varchar2 data, Number for all numeric data, and Date for date values.

As a rule default values are left blank on all parameters.

• 1. .Popup menus

There are 2 standard Popup menus that are inherited by all Forms via the POPUP_MENUS Object Group. They are:

• • FIELD

  • CANVAS

These Popup menus should be attached to all text items and all Canvases respectively.

They both include menu options to Exit the Form, Show Keys, and Show Help. The FIELD Popup menu also has Copy and Paste menu options.

• 1. .Program Units

     1. Usage

Program Units should contain all the significant processing that is needed by the triggers in the Form, especially where it is used more than once, or where it needs to be referenced by another Form.

Most code that is written should be packaged. Packages must conform to the PL/SQL Standards.

Three types of package tend to be used:

• • Object style packages e.g. F_WINDOW or F_FORM

  • A packages for each Block, with procedures and functions specific to that Block e.g. F_CPRO

  • A subset of the Block packages enabling a smaller number of procedures & functions to be inherited in another Form e.g. F_CPRO_TELEPHONE

• 1. Standards

     1. Names

Package names should be prefixed F_ in Forms, and L_ in libraries, as this helps a developer identify where the called code exists.

• 1. Structure and layout

All package bodies should define private procedures and functions before the public procedures and functions, and clearly mark the point where the public declarations start.

The PL/SQL Standards must be adhered to. All code must be in lower case, including any references to Form items.

• 1. Declarations

Use %type in variable declarations whenever possible.

Use %rowtype in record declarations whenever possible.

Always use varchar2 instead of varchar or char.

Schema names and database link names must NOT be coded into Forms code (or any code for that matter).

• 1. SQL and DML

All SQL and DML statements should be moved from the Form to an appropriate package on the database. This is done to:

• • Reduce network traffic;

  • Improve usage of shared SQL in the System Global Area on the database; and

  • Improve modularity of the code.

• 1. Libraries

If a program unit is reusable across modules, and does not access the database, it should be considered a candidate for inclusion in a library, or if not used in many Forms it can referenced into those other Forms.

• 1. Global variables

Forms Global variables should only be used to return data from a called Form.

• 1. Navigation built-Ins

Oracle Forms navigation built-ins should not be used directly to implement any inter-Form navigation or calls to Oracle Reports: instead a wrapper package called l_execute is provided in rcs_library.pll

• 1. Reading and writing object properties

Always use the find_ built-in function to identify Form objects before referencing them programmatically, and always use the resultant “id” as a means of later identifying the object in set_ or get_ built-ins.

Avoid using the set_ or get_ built-ins with the object name as this requires Forms to implicitly find the object’s id itself, every time, which is less efficient.

Use the id_null(<object_id>) built-in function in conjunction with the appropriate find_ built-in to check the existence of dynamically (programmatically) defined objects. This helps avoid runtime errors when code incorrectly assumes that an object exists when it doesn’t. This technique is also useful where find_ is being used on objects created at design time.

Be aware of the subtle difference between the get_ and set_ built-ins. “Set” built-ins often take numeric constants as arguments, whereas the corresponding “get” built-ins return a character string identical to the name of the constant being requested. Note also that the name of the constant is not case sensitive, whereas the value of the character string is.

For example:

set_window_property(Forms_mdi_window, window_state, maximize)

and

set_window_property(Forms_mdi_window, window_state, MAXIMIZE)

are identical (the first being compliant with this set of standards);

whereas:

get_window_property(Forms_mdi_window, window_state) = ‘maximize’

and

get_window_property(Forms_mdi_window, window_state) = maximize

will never be true, but this can be:

get_window_property(Forms_mdi_window, window_state) = ‘MAXIMIZE’

• 1. .Property Classes

     1. Usage

Property Classes are widely used to control the look and feel of the application, in part by incorporating a Visual attribute.

Ideally everything that is visible in the user interface should have a Property Class, and therefore a Visual Attribute.

• 1. Standards

All Property Classes must be defined in the reference Form, and incorporated into the appropriate Object Group.

Values inherited from Property Classes should only be overridden in rare circumstances.

Property Class names must indicate how or where they should be used. For example:

DATETIME is used on all datetime fields;

RADIO_GROUP is used on all Radio Groups; and

RADIO_BUTTON is used on all Radio Group Buttons.

• 1. .Record Groups

     1. Usage

Record Groups should be used for the following purposes:

• • To define queries used by LOVs; and

  • To store arrays of data (unusually).

• 1. Standards

     1. Names

For Record Groups that are based upon a query, the name of the record group must always be, or start with, the 4-leter alias of the “main” table that is used in the query.

Where a record group is static and not based upon a query, then a concise and logical name that represents the contents of the data within shall be assigned.

• 1. Reuse

Record Groups with queries that do not reference any Oracle Forms items (i.e. queries that do not need parameters) are candidates for reuse across multiple Forms. These may be saved to the reference Form or referenced directly from one Form to another.

• 1. Queries

All queries must have an order by clause.

The query must only return data that passes the item validation in the Form.

In general queries should be set to refresh, unless there is a pressing performance implication of doing so.

• 1. Populating drop-down list items

Record Groups can be used to populate list items, although this is being phased out in RCS. These Record Groups are generally created & populated programmatically by procedures and functions in the F_GROUP package within a Form.

• 1. .Visual Attributes

Visual Attributes are used to maintain a consistent look across the application. They primarily deal with sizes, fonts and colours.

• 1. Usage

Visual Attributes should be applied to all visible user interface objects (usually as part of the Property Class definition) such as Alerts, fields, checkboxes, radio groups, Canvases, LOVs and Windows.

• 1. Standards

All Visual Attributes must be defined in the reference Form, and incorporated into the appropriate Object Group.

Visual Attribute names must indicate the appearance they provide.

• 1. .Windows

The parent Window of an MDI application is called an application Window. All other Windows must be either document windows or dialog windows. The Windows OS uses MDI windows, but the Mac does not.

• 1. Usage

Document windows always remain within the confines of the application window.

Dialog windows are free floating, and (if defined as movable) can be moved outside the application window.

A root Window is always a Document window.

• 1. Standards

Every Form must have a Window named WINDOW_PRIMARY, inherited from the reference Form.

• 1. Names and titles

Besides WINDOW_PRIMARY, windows added by the programmer should have a name that reflects their contents e.g. ORDERS, or CONTRIBUTOR_POPUP.

Each Window should have a Title that reflects the contents e.g. Order details, or Contributor details.

Each window that can be minimized should have a Minimize Title e.g. Order, or Contrib.

• 1. Other properties

Windows should be defined as Modal if they must be closed before another operation is performed; otherwise they can be left floating while data in another Window is the focus.

If quick access to additional windows is needed, then Minimize should be allowed.

Windows should not be Resizable as the data within in them will not flex accordingly.

• 1. Closing windows

Every Window should have a Close or Exit button which closes the window. This button should be placed in the bottom right and corner of the Canvas displayed in the Window.

A WHEN-WINDOW-CLOSED trigger should be coded in all screens that have closable Windows to ensure that if the Window is closed via the “Close” control in the corner of the Window the focus will move to the appropriate Block and field.

End of Document