Eadstart Racle Esigner: User Guide

HEADSTART
ORACLE DESIGNER 6.5
User Guide
Version 6.5.3.0
November, 2002
Headstart Oracle Designer 6.5, User Guide
November, 2002
Copyright © 2000-2002 Oracle Corporation.

All rights reserved.
Authors: Lauri Boyd, Sandra Muller
Contributing Authors: Frank Brink, Jacques Coppien
This document is Oracle Corporation property. It contains proprietary information of Oracle
Corporation; it is provided under a license agreement containing restrictions on use and
disclosure and is also protected by copyright law. The reproduction of this material, in whole
or in part, without the express written consent of Oracle Corporation is prohibited.
The information contained in this document is subject to change without notice. If you find
any problems in the documentation please report them to us in writing. Oracle Corporation
does not warrant that this documentation is error free.
This document is provided “as is” and Oracle Corporation shall have no liability in
connection with or arising out of the use of this document.
ORACLE and SQL*Plus are registered trademarks of Oracle Corporation.
ORACLE8i, Oracle Designer, Oracle Repository, Oracle Forms, Oracle Reports, Oracle Form
Generator, PL/SQL, Oracle Report Generator, and Oracle Applications are trademarks of
Oracle Corporation. Custom Development Method is a Service Mark of Oracle Corporation.
Microsoft is a registered trademark and Windows a trademark of Microsoft Corporation.
All other product or company names are used for identification purposes only, and may be
trademarks of their respective owners.
2 Table of Contents Headstart Oracle Designer 6.5 - User Guide

Table of Contents
CHAPTER 1 Introduction ...................................................................................................................1-1

CDM Standards and Guidelines library ..................................................................................1-2
Part I Overview and Setup 3
CHAPTER 2 Headstart Template Package Components .................................................................2-1

Templates, Libraries and Preferences for Developer Generation....................................2-2
Headstart Required Application Forms ...........................................................................2-3
Headstart Foundation Application...................................................................................2-4
Headstart Interface Layer ................................................................................................2-5
Headstart Demo Application ...........................................................................................2-6
CHAPTER 3 Headstart Utilities Components ...................................................................................3-1

Headstart Utilities Components.......................................................................................3-2
Productivity Boosters .............................................................................................................3-2
Quality Checks .......................................................................................................................3-2
Run Utility Form ....................................................................................................................3-2
Administration Application ....................................................................................................3-2
CHAPTER 4 Development Team Access to Headstart .....................................................................4-1

Headstart Utilities............................................................................................................4-2
Maintaining User Groups .......................................................................................................4-2
Creating and Reconciling Users .............................................................................................4-2
Headstart generated applications.....................................................................................4-4
CHAPTER 5 Running the Headstart Utilities ...................................................................................5-1

Important Terms ..............................................................................................................5-2
Context Workarea...................................................................................................................5-2
Context Container...................................................................................................................5-2
Application Code....................................................................................................................5-3
Run Utility Form .............................................................................................................5-4
Navigator ................................................................................................................................5-4
Parameter Window .................................................................................................................5-5
User Preferences..............................................................................................................5-7
QA Details Creation ...............................................................................................................5-7
QA Run Results ......................................................................................................................5-8
Logging ..................................................................................................................................5-9
Process the Following Objects................................................................................................5-9
Folders and Application Systems....................................................................................5-9
Headstart Oracle Designer 6.5 - User Guide Table of Contents i

Primary Objects ............................................................................................................ 5-10
Check In........................................................................................................................ 5-10
CHAPTER 6 Running the Headstart Foundation Application ........................................................6-1

Messages .........................................................................................................................6-2
Module and Parameters ...................................................................................................6-3
Standard Report Parameters ............................................................................................6-7
Part II Roadmap to Application Development 9
CHAPTER 7 Headstart Application Development Approach .........................................................7-1

Benefits of Three Layer Approach ..................................................................................7-2
Logical versus Physical Partitioning ...............................................................................7-3
Headstart Application Development Approach...............................................................7-5
CHAPTER 8 Development Process Roadmaps by Phase .................................................................8-1

Analysis Phase Roadmap ................................................................................................8-2
Business Process Modeling ....................................................................................................8-2
Data Layer - Entity Relationship Modeling............................................................................8-3
Business Logic Layer - Business Rule Modeling ...................................................................8-3
Presentation Layer - Function Modeling ................................................................................8-4
Design and Implementation Phase Roadmap ..................................................................8-5
Technical Application Architecture..........................................................................................8-5
Data Layer...............................................................................................................................8-6
Business Logic Layer ..............................................................................................................8-7
Presentation Layer ..................................................................................................................8-8
Part III Data Layer
CHAPTER 9 Implementing the Data Layer ......................................................................................9-1

Data Layer Roadmap.......................................................................................................9-2
Analysis Phase........................................................................................................................9-2
Design and Implementation Phase ...........................................................................................9-2
Implementing the Data Layer ..........................................................................................9-5
Apply Naming Conventions ...................................................................................................9-5
Define Auto-generated Primary Keys.....................................................................................9-5
Implement Data Structures for Auditing.................................................................................9-5
Enforce Ordering Standards....................................................................................................9-6
Define Views ..........................................................................................................................9-7
Data Security ..........................................................................................................................9-8
Physical Database Design.......................................................................................................9-8
Headstart Quality Checks .......................................................................................................9-9
Part IV Business Logic Layer
CHAPTER 10 CDM RuleFrame..........................................................................................................10-1

Business Rule Roadmap ................................................................................................10-2
Business Rule Analysis......................................................................................................... 10-2
Business Rule Design ........................................................................................................... 10-3
Business Rule Generation..................................................................................................... 10-4
ii Table of Contents Headstart Oracle Designer 6.5 - User Guide

CHAPTER 11 Implementing the Rule Layer .....................................................................................11-1
Business Rule Analysis .................................................................................................11-2
1. Create process events for entities..................................................................................... 11-2
2. Record your business rules using the Business Rule Function object.............................. 11-3
Recording a Business Rule as a Function ..................................................................... 11-3
What to Record ............................................................................................................. 11-3
Business Rule Classification Scheme ........................................................................... 11-5
Static Data Constraint Rules ......................................................................................... 11-6
Dynamic Data Constraint Rules.................................................................................. 11-10
Change Event Rules with DML.................................................................................. 11-13
Change Event Rules without DML (CEW) ................................................................ 11-14
Authorization Rules (AUT) ........................................................................................ 11-14
3. Associate Triggered By events with your business rules............................................... 11-15
4. Record Business Rule - Data Usage .............................................................................. 11-16
5. Clean up redundant events............................................................................................. 11-17
Business Rule Design..................................................................................................11-18
1. Run Business Rule Design Transformer Utility.............................................................. 11-18
2. Run other Business Rule Utilities ................................................................................... 11-19
3. Create additional rules using Business Rule Design Definition Utility .......................... 11-19
4. Check the triggering events for each business rule......................................................... 11-19
5. Code your rule in the related PL/SQL Definition ........................................................... 11-23
Using Standard CAPI Services ................................................................................... 11-25
Creating and Using Custom CAPI Service Definitions .............................................. 11-29
6. Check arguments of PL/SQL Definition......................................................................... 11-33
Business Rule Generation ...........................................................................................11-34
1. Create Custom API Definition........................................................................................ 11-34
CAPI Structure............................................................................................................ 11-35
2. Generate Custom API's using Server Generator ............................................................. 11-36
3. Generate Table API using Table API Generator............................................................. 11-36
4. Recompile invalid PL/SQL packages ............................................................................. 11-36
CHAPTER 12 Accessing the Rule Layer ............................................................................................12-1

Using the VAPI .............................................................................................................12-2
Runtime Environment ...................................................................................................12-4
Opening and Closing a Transaction ..............................................................................12-5
Business Rule Enforcement in the Front End ....................................................................... 12-5
Oracle Forms Applications............................................................................................12-7
Business Rule Enforcement in the Form............................................................................... 12-8
Testing CDM RuleFrame in SQL*Plus.........................................................................12-9
Batch Processing with CDM RuleFrame.....................................................................12-11
Accessing CDM RuleFrame from PL/SQL ........................................................................ 12-11
Standard CAPI Services for Batch Programs.............................................................. 12-12
Performance Issues ............................................................................................................. 12-14
WebDB Applications ..................................................................................................12-18
WebServer Generated Applications ............................................................................12-19
JDeveloper/BC4J Applications ...................................................................................12-20
Other Front Ends .........................................................................................................12-21
Part V Presentation Layer
CHAPTER 13 Getting Started.............................................................................................................13-1

Template Package Architecture.....................................................................................13-3
Template Package Structure ................................................................................................. 13-3
OFG*65.PLL Libraries......................................................................................................... 13-4
Advantages ........................................................................................................................... 13-5
Headstart Oracle Designer 6.5 - User Guide Table of Contents iii

Prepare Your Application for Generation .....................................................................13-7
Reference the Application Level Named Preference Sets .................................................... 13-7
Blank out Language Specific Command Lines..................................................................... 13-7
Create Shortcuts to Headstart Objects (optional).................................................................. 13-8
Set Generator Options........................................................................................................... 13-9
Create and Attach the Application Library........................................................................... 13-9
Create and Attach the Application Menu................................................................................. 11
Create a Start Form for your Application ........................................................................... 13-11
Create an HTML Launch Document for your Application................................................. 13-12
Iterative Development Tasks.......................................................................................13-13
Create Key Constraint Error Messages............................................................................... 13-13
Generate Change History Columns .................................................................................... 13-13
Generate Context Sensitive HTML Help ID’s.................................................................... 13-13
Create Module Revision Parameter .................................................................................... 13-13
Generate Report Module Parameters .................................................................................. 13-14
Module Libraries .........................................................................................................13-15
Attaching Module Libraries................................................................................................ 13-16
Case Sensitivity of File Names....................................................................................13-17
Generating a Case-Sensitive Application ................................................................... 13-17
Making an Application Case-Sensitive....................................................................... 13-17
CHAPTER 14 User Interface Generation...........................................................................................14-1

Menu Template..............................................................................................................14-2
Smartbar ........................................................................................................................14-4
Menu and Smartbar in Your Application ......................................................................14-5
Required Preference Settings................................................................................................ 14-5
Form-Menu Attachment ....................................................................................................... 14-5
Menu Call Method................................................................................................................ 14-6
Sharing of Library Data ........................................................................................................ 14-7
Passing Parameters to Forms ................................................................................................ 14-7
Calling the Same Form with Different Parameter Values..................................................... 14-9
Changing Menu Items at Runtime ........................................................................................ 14-9
Item Popup Menu ............................................................................................................... 14-10
Preventing Recurrent Load of Smartbar Gif Files .............................................................. 14-11
Preventing Recurrent Load of the Menu............................................................................. 14-11
Calendar ......................................................................................................................14-13
Advanced Calendar Options ............................................................................................... 14-13
Calendar Examples ............................................................................................................. 14-14
Visual Attributes..........................................................................................................14-16
Block and Item Group Titles .............................................................................................. 14-16
List of Values ..................................................................................................................... 14-17
Setting Font Typeface, Size and Weight ............................................................................ 14-17
Assigning Special Visual Attributes ................................................................................... 14-17
Layout Generation.......................................................................................................14-18
Blocks on Tabs ................................................................................................................... 14-18
Wizard Layout .................................................................................................................... 14-19
Building a Wizard....................................................................................................... 14-19
Wizard Page Images ................................................................................................... 14-20
Wizard Page Instructions ............................................................................................ 14-21
Splitting a Table over Multiple Pages......................................................................... 14-22
Wizard Control Buttons .............................................................................................. 14-23
Wizard Size and Button Positioning ........................................................................... 14-24
Summary of Building Steps ........................................................................................ 14-25
Side By Side Blocks ........................................................................................................... 14-26
Resizable Spread Tables ..................................................................................................... 14-26
Control Block Generation ...........................................................................................14-28
Item Generation...........................................................................................................14-29
Image Path .......................................................................................................................... 14-29
iv Table of Contents Headstart Oracle Designer 6.5 - User Guide

Action Items ....................................................................................................................... 14-29
Buttons/Action Items in a Multi-Record Block .................................................................. 14-30
List of Values ..............................................................................................................14-31
Built-in List of Values ........................................................................................................ 14-31
Row List of Values ..................................................................................................... 14-31
Filter Before Display .................................................................................................. 14-32
LOV Forms......................................................................................................................... 14-32
Querying in an LOV Form.......................................................................................... 14-33
Windows .....................................................................................................................14-35
Window Styles.................................................................................................................... 14-35
Find Window ...................................................................................................................... 14-35
Known Restriction ...................................................................................................... 14-37
Window Titling and Positioning......................................................................................... 14-37
Window Titling........................................................................................................... 14-37
Window Positioning ................................................................................................... 14-37
CHAPTER 15 Runtime Behaviors ......................................................................................................15-1

Runtime Initializations ..................................................................................................15-2
Form Initializations............................................................................................................... 15-2
Date Format .................................................................................................................. 15-2
Block Initializations.............................................................................................................. 15-3
Block Navigation Style................................................................................................. 15-3
Allowed Block Operations............................................................................................ 15-3
Item Initializations................................................................................................................ 15-3
Insert Only Items .......................................................................................................... 15-3
Update Only Items........................................................................................................ 15-4
Required Items.............................................................................................................. 15-4
Read Only Items ........................................................................................................... 15-4
Item Tooltip .................................................................................................................. 15-5
Repositioning of Items.................................................................................................. 15-5
Assigning a Special Visual Attribute ............................................................................ 15-5
Adding Your Own Block and Item Initialization.................................................................. 15-5
Inter-Form Navigation...................................................................................................15-6
Argument Passed Values and Named Passed Values ........................................................... 15-6
Sharing of Library Data ........................................................................................................ 15-7
Multi-Select Functionality.............................................................................................15-8
Clear or Delete Multiple Selected Records........................................................................... 15-8
Perform User-Defined Action on Multiple Selected Records............................................... 15-8
Multi-Select LOV ................................................................................................................. 15-8
Shuttle Control Object Selector .......................................................................................... 15-10
Transfer Multiple Details to Other Master Record ............................................................. 15-13
Known Restrictions .................................................................................................... 15-14
Item Relations..............................................................................................................15-15
Dependent Items ................................................................................................................. 15-15
Note 1 ......................................................................................................................... 15-16
Note 2 ......................................................................................................................... 15-16
Note 3 ......................................................................................................................... 15-16
Conditionally Dependent Items .......................................................................................... 15-16
Multiple Dependent Items .................................................................................................. 15-17
Two Master Items and One Dependent Item ...................................................................... 15-18
Cascading Dependence....................................................................................................... 15-19
Mutually Exclusive Items ................................................................................................... 15-21
Mutually Inclusive Items .................................................................................................... 15-22
Mutually Inclusive Items with Dependent Items ................................................................ 15-23
Conditionally Mandatory Items.......................................................................................... 15-26
Example from the Headstart Demo..................................................................................... 15-27
Date Handling .............................................................................................................15-32
Date Format Environment Variables .................................................................................. 15-32
Headstart Oracle Designer 6.5 - User Guide Table of Contents v

Forms PLSQL_DATE_FORMAT and BUILTIN_DATE_FORMAT ............................... 15-33
Recommended Approach.................................................................................................... 15-33
CHAPTER 16 End User Assistance ....................................................................................................16-1

Message Handling .........................................................................................................16-2
Message Handling Features .................................................................................................. 16-2
Usage Conditions.................................................................................................................. 16-3
Handling Data Integrity Errors ............................................................................................. 16-4
Message Code............................................................................................................... 16-4
Recording the Constraint Name.................................................................................... 16-5
Automatic Creation of Constraint Messages................................................................. 16-5
Derived Data Integrity Errors ....................................................................................... 16-6
Raising Application Messages.............................................................................................. 16-6
Overriding the Message Type....................................................................................... 16-7
Raising Questions (Dialogs) ................................................................................................. 16-7
Raising Informational Messages in the Server.............................................................. 16-8
Raising Questions in the Server.................................................................................... 16-8
Trapping Unhandled Errors .................................................................................................. 16-9
Suppressing Application Messages....................................................................................... 16-9
Suppressing or Replacing ORA and FRM Messages............................................................ 16-9
Error Handling in Batch Programs ..................................................................................... 16-10
Transfer Messages to other Database Schema .................................................................... 16-10
Online Help .................................................................................................................16-11
HTML Online Help Generator ........................................................................................... 16-11
Invocation of the HTML Help File ............................................................................. 16-11
Item Hint and Tooltip ..................................................................................................16-13
Suppressing Default Hint Text ........................................................................................... 16-13
Headstart Hint Text Tags.................................................................................................... 16-13
About This Record ......................................................................................................16-15
About This Application ...............................................................................................16-16
Displaying Application and System Information................................................................ 16-17
System Information .................................................................................................... 16-17
Module Information............................................................................................................ 16-18
CHAPTER 17 Troubleshooting...........................................................................................................17-1
Troubleshooting Approach............................................................................................17-2
Common Problems ........................................................................................................17-3
ORA-04062 .......................................................................................................................... 17-3
ORA-06508 .......................................................................................................................... 17-3
FRM-40735 .......................................................................................................................... 17-4
FRM-41085 .......................................................................................................................... 17-4
Problem Assessment......................................................................................................17-5
Checking Application Logic................................................................................................. 17-5
Headstart Runtime Initializations ......................................................................................... 17-5
Generating without Headstart ............................................................................................... 17-5
Debug Template and Object Library ............................................................................ 17-6
Menu Attachment ......................................................................................................... 17-6
Checking Headstart Customizations ..................................................................................... 17-7
Debug Monitor ..............................................................................................................17-8
Using the Debug Monitor ..................................................................................................... 17-8
Standard Debug Messages .................................................................................................... 17-8
Adding Debug Messages ...................................................................................................... 17-9
Forms Debugger ..........................................................................................................17-10
vi Table of Contents Headstart Oracle Designer 6.5 - User Guide

Part VI Deploying your Applications
CHAPTER 18 Test and Production Environment.............................................................................18-1

Perform the Headstart Application Installation .............................................................18-3
Perform the Headstart Database Installation .................................................................18-4
Database Schema Organization ............................................................................................ 18-4
Shared Deployment or Self-Contained Deployment..................................................... 18-4
Alter Session Set Current Schema ................................................................................ 18-5
Database Server Installation ................................................................................................. 18-6
Create Schema that Owns Headstart Objects................................................................ 18-6
Run the Headstart Server Side Installer ........................................................................ 18-6
Grants and Synonyms ................................................................................................... 18-7
Execute SQL procedure ................................................................................................ 18-9
Application Specific Reference Data............................................................................ 18-9
Custom Messaging or Profiles System ....................................................................... 18-10
Description of the Headstart Middle-tier Runtime Environment ................................18-11
Headstart Oracle9ias Forms Services Environment............................................................ 18-11
Virtual Directories .............................................................................................................. 18-15
Multiple environments........................................................................................................ 18-16
Case Sensitive File Names.................................................................................................. 18-17
Description of the Headstart Objects .................................................................................. 18-17
Files ............................................................................................................................ 18-17
Environment Variables ............................................................................................... 18-19
Unix Links .................................................................................................................. 18-19
CHAPTER 19 Customizing the Headstart Template Package.........................................................19-1

Impact of Customizations..............................................................................................19-2
Customizing Headstart PL/SQL Libraries.....................................................................19-3
Name Resolution in Module Specific Libraries............................................................ 19-4
Customizing the Headstart Object Library....................................................................19-6
Limitation of Object Libraries .............................................................................................. 19-6
The FORM2LIB Utility........................................................................................................ 19-7
Creating an Object Library using FM2LIB61....................................................................... 19-7
Creating a Custom Object Library Maintenance Form................................................. 19-8
Adding a New Source Object ....................................................................................... 19-8
Modifying an Existing Object....................................................................................... 19-8
Using Your Custom Object Library............................................................................ 19-10
Food for Thought........................................................................................................ 19-10
Customizing the Menu and Smartbar ..........................................................................19-11
Customizing Required Application Forms ..................................................................19-12
Renaming Required Application Forms ............................................................................. 19-12
Changing End User Language.....................................................................................19-13
Translating Menu Template................................................................................................ 19-13
Translating Object Library ................................................................................................. 19-13
Translating Messages.......................................................................................................... 19-14
Translating Required Application Forms............................................................................ 19-14
Translating Reusable Module Components ........................................................................ 19-14
Using your own Message Tables.................................................................................19-15
CHAPTER 20 Customizing the Headstart Utilities...........................................................................20-1

Exclude CDM Quality Checks ......................................................................................20-2
Creating your own QA-set ............................................................................................20-3
Adding your own Quality Checks to existing utilities ..................................................20-4
Before creating your own utilities .................................................................................20-6
Creating new Base Layer packages ...................................................................................... 20-6
Headstart Oracle Designer 6.5 - User Guide Table of Contents vii

Creating your own Productivity Boosters .....................................................................20-7
viii Table of Contents Headstart Oracle Designer 6.5 - User Guide

CHAPTER
1 Introduction
Headstart Oracle Designer is a powerful productivity suite for Oracle Designer based on the
best practices of Oracle Consulting worldwide.
Headstart Oracle Designer consists of two major components:
• Headstart Template Package A set of, templates, libraries, reusable GUI

components and recommended preference settings for Menu, Form and Report
generation.
The Headstart Template Package is based on the best practices of Oracle Consulting
and allows you to achieve 100% generation of applications which fully comply with
the standards and guidelines established in CDM, Oracle’s Custom Development
Method.
• Headstart Utilities A set of utilities, classified into quality checks and productivity
boosters, that use the Oracle Designer API to increase the quality and speed of
application development using Oracle Designer.
The Headstart Utilities assume that your application is generated with the Headstart
Template Package. This means that several utilities create objects specifically for use
with the Headstart Template Package.
This user guide does not attempt to replace the Oracle Designer online help and training.
However, Headstart uses and leverages Oracle Designer, so it is very important that you have
a basic understanding of Designer’s functionality to be able to understand and appreciate
what Headstart has to offer.
One of the best sources of information about how to use Oracle Designer is the CDM
Standards and Guidelines library.
Headstart Oracle Designer 6.5 - User Guide Introduction 1 - 1

CDM Standards and Guidelines library
The Custom Development Method (CDM) Standards and Guidelines Library support the
development, implementation and maintenance of high quality software using the Oracle
development tools. CDM is available to customers under the name CDM Advantage.
This library consists of 4 volumes which focus on the development of systems using Oracle
Designer:
• Volume 1, Requirements Modeling using Oracle Designer

• Volume 2, Design and Generation of Multi Tier Web Applications
• Volume 3, Building Systems Using Oracle8 Programming Tools
• Volume 4, CDM Standards
These volumes provide standards and guidelines for using the Oracle Designer tool set.
1- 2 Introduction Headstart Oracle Designer 6.5 - User Guide

PART I OVERVIEW AND
SETUP
(blank page)
CHAPTER
2 Headstart Template Package

Components
The Headstart Template Package consists of the following components:
• Headstart Templates, Libraries and Preferences for Developer Generation

• Headstart Required Application Forms
• Headstart Foundation Application
• Headstart Interface Layer
• Headstart Demo Application
The following sections discuss each component in detail.
Headstart Oracle Designer 6.5 - User Guide Headstart Template Package Components 2 - 1
Templates, Libraries and Preferences for Developer Generation
The following forms and library forms are supplied to generate Forms 6i applications:
• qmstpl65.fmb: Template to use for generating normal data entry and data retrieval
forms
• qmslvt65.fmb: Template for LOV forms
• qmsolb65.olb: Object Library to use when generating any form
• qmsevh65.pll: Event Handler Library, functions as a bridge library between form,
block and item level triggers and the core Headstart Library.
• qmslib65.pll: Core Headstart Library, containing all UI related features.
• qmsolm65.fmb: Object Library Maintenance Form.
• qmsmnt65.mmb: Menu template
The following preference sets are available:
• qms65_recommended: contains all preferences you should reference at application

level
• qms65_multi_record_block: contains specific preference settings for multi-record
blocks
• qms65_no_client_constraints: contains preference settings to prevent Form Generator
from generating key constraint validation code. Apart from special use in Find
Windows, you can use this preference set if you want to build a ‘thin-client’
application where all business logic and business rule validation is executed at the
server.
• qms65_wizard_buttons: contains layout preference settings to properly layout wizard
control buttons.
• qms65_debug_module: preference set to use when generating your form ‘without’
Headstart. See chapter Troubleshooting for more information.
• qmsrep65_recommended: contains all report generator preferences you should
reference at application level.
• qms65_html_help: preference set to use when generating HTML Help.
The following reusable module components are available:
• qms_dialog_buttons: contains standard buttons for a modal dialog window: OK,

Cancel and Help.
• qms_lov_buttons: contains standard buttons for an LOV window: Find, OK, and
Cancel.
• qms_msel_lov_buttons: contains standard buttons for a Multi-Select LOV window:
Select All, Deselect All, Find, OK, and Cancel.
• qms_wiz_buttons: contains standard control buttons for a wizard page.
2 - 2 Headstart Template Package Components Headstart Oracle Designer 6.5 - User Guide
Headstart Required Application Forms
Headstart Required Application Forms are forms that are required to run your application
generated with Headstart. The need for most of these forms comes from the Headstart menu
template, which contains a number of menu options that call required application forms.
• qms0002f: Help on Message

• qms0004f: Change Password (File -> Change Password)
• qms0006f: User Preferences (Edit -> Preferences)
• qms0008f: About this Application (Help -> About this Application)
• qms0010f: About this Record (Help -> About this Record)
• qms0012f: Report Launch Form (Called for every report module that is included in
your application menu, governed through MNUDRC preference)
• qms0014f: Shuttle Control Launch Form (Called for every multi-select report
parameter)
A special form is the Headstart debug monitor form qms0002f. This form is not required to
run your application, but can be started in a separate runform session to view debug messages
raised by a Headstart-generated application. Refer to the chapter on Troubleshooting for more
information.
Except for the debug monitor form all required application forms are 100% generated with
the Headstart templates. The repository module definitions can be found in the QMS503
application system, which can be restored from the qms503.dmp dump file, located in the
\dmp directory under the Headstart-root directory.
The required application forms are set up for use in multiple applications. If you generate
multiple applications with the Headstart templates, you can use the same set of required
application forms to serve all your Headstart-generated applications (provided that they are
deployed in the same runtime environment).
Detailed information on each required application form can be found in the context-sensitive
online help file, available in both HTML format and MSHELP format. This help file,
qmshelp.htm/hlp is located in the \doc directory under the Headstart root-directory. Note that
the online help files are 100% generated as well. The .hlp file was generated using the
Designer MS Help Generator and the .htm version was generated using the Headstart Utility
‘HTML Online Help Generator’.
Headstart Foundation Application
The Headstart Foundation Application is intended for application administrators, it contains
forms to maintain the Headstart database tables that should be deployed together with your
own application tables.
The following forms are available:
• qfd0000f: Start form of the Headstart Foundation Application

• qfd0000m: Menu of the Headstart Foundation application
• qfd0014f: Maintain standard report parameters (table QMS_STND_REP_PARAMS)
• qfd0016f: Maintain (report) modules and their parameters (tables QMS_MODULES
and QMS_MDE_PARAMS)
• qfd0018f: Maintain messages (tables QMS_MESSAGE_PROPERTIES,
QMS_MESSAGE_TEXT)
The Headstart Foundation Application is 100% generated with the Headstart templates. The
repository module definitions can be found in the QMS503 application system, which can be
restored from the qms503.dmp dump file, located in the \dmp directory under the Headstart-
root directory.
Detailed information on each foundation application form can be found in the context-
sensitive online help file, available in both HTML format and MSHELP format. This help
file, qfdhelp.htm/hlp is located in the \doc directory under the Headstart root-directory. Note
that the online help files are 100% generated as well. The .hlp file was generated using the
Designer MS Help Generator and the .htm version was generated using the Headstart Utility
‘HTML Online Help Generator’.
Headstart Interface Layer
The Headstart Interface Layer (HIL) is a set of database packages that act as an Application
Programming Interface (API) between the PL/SQL libraries that are part the Headstart
Template Package, and some of the Headstart database tables.
The Template Package currently accesses two types of data sources:
• A data source containing user preferences information

• A data source containing messaging information.
Headstart ships with a default implementation of these two data sources:
• User preferences are stored in table QMS_USER_OPTIONS, which is accessed

through the HIL_PROFILE package. The HIL_PROFILE package calls program units
in the QMS_PROFILE package, which directly accesses the QMS_USER_OPTIONS
table
• Messages are stored in tables QMS_MESSAGE_TEXT and
QMS_MESSAGE_PROPERTIES, which are accessed through the HIL_MESSAGE
package. The HIL_MESSAGE package calls program units in the QMS_PROFILE
package, which directly accesses the QMS_MESSAGE_TEXT and
QMS_MESSAGE_PROPERTIES tables
By accessing these data sources through the Headstart Interface Layer, we have created data
independence for the Template Package. If you want to change the underlying table structure,
you do not need to change the Headstart libraries, you only need to replace the QMS calls in
the HIL_PROFILE or HIL_MESSAGE packages.
Refer to the chapter on Template Package Customization for more information.
Headstart Demo Application
Headstart supplies a demo application, HSD65, which is 100% generated and demonstrates
many of the powerful features of the Headstart Template Package.
All of the features presented in this user guide are demonstrated in the demo application.
You can examine both the definitions in the Designer repository and the generated modules.
The Headstart Demo Application contains comprehensive online help. You can access the
online help context-sensitive while running the demo application. The online help file was
generated using the Headstart Utility ‘HTML Online Help Generator’.
CHAPTER
3 Headstart Utilities
Components
The implementation of the standards and guidelines presented in the CDM Standards and
Guidelines library leads to two challenges.
• many (manual) tasks are time consuming and error prone

• how to check if the standards and guidelines are really applied
The Headstart Oracle Designer Utilities provide a set of tools to support the implementation
of the CDM Standards and Guidelines by addressing the above challenges. There are two
type of utilities.
• Productivity Boosters - to enforce standards and guidelines

• Quality Checks - to check standards and guidelines
Apart from these two components, the Headstart Utilities have two more components to help
you run and manage the utilities:
• Run Utility Form

• Utilities Administration Application
The following sections discuss each component in detail.
Headstart Oracle Designer 6.5 - User Guide Headstart Utilities Components 3 - 1

Headstart Utilities Components
Productivity Boosters
These utilities perform inserts, updates and deletes in the Oracle Designer repository that
otherwise should have been carried out manually. In most cases, the elements created by
these utilities are actually maintained by the utility. By running the utility again, obsolete
elements will be deleted and existing elements will be updated according to changes that may
have taken place which influence the element definitions.
By using the Productivity Boosters a considerable productivity gain can be achieved in

implementing the CDM Standards and Guidelines. Also, because of the automatic consistent
creation of elements, a very high level of quality is guaranteed for these elements.
Quality Checks
These utilities check the Oracle Designer element definitions against the CDM Standards and
Guidelines. The results can be viewed in an HTML browser. User preferences specify
whether to show summary and/or detailed information.
By using the Quality Checks a large number of CDM Standards can be checked with very
little effort.
Run Utility Form
All utilities, the Productivity Boosters as well as the Quality Checks, are run from a single
user interface; the Run Utility Form. Log in as a Utilities User.
Administration Application
The administration of Utilities Users and the grouping of Utilities in the Run Utility Form can
be maintained by using the Administration Application. Log in as the Headstart Utilities
owner.
3 - 2 Headstart Utilities Components Headstart Oracle Designer 6.5 - User Guide

CHAPTER
4 Development Team Access

to Headstart
This chapter describes how to give your Development Team access to the Headstart Utilities
and to Headstart generated applications. It is assumed that at least the Thin Client installation
is already run for each user (see the [HSD65_HOME]\doc\install.htm for details).
Headstart Oracle Designer 6.5 - User Guide Development Team Access to Headstart 4 - 1
Headstart Utilities
To grant users access to the Headstart Utilities, you use the Utilities Administration
Application.
Log into the Utilities Administration as the Headstart Utilities owner.
Maintaining User Groups
The Headstart Utilities come with two User Groups pre-defined, ‘All Productivity Boosters’
and ‘No Productivity Boosters’. If you like, you can define one or more custom User Groups
which contain only a subset of the productivity boosters.
When you grant a user access to the Headstart Utilities, you must assign that user to a User
Group. By defining custom User Groups, you can limit access to the Productivity Boosters.
Everyone always has access to the Quality Checks.
To create a new User Group, you perform the following steps.
1. Choose the menu option Administration => User Groups and Productivity Boosters
2. On a blank record, enter the new User Group name.
3. In the Productivity Boosters field, open the List of Values. Select one or more
Productivity Boosters from the List of Values and press OK. (This List of Values
allows you to select multiple rows at once.)
4. Save.
Note that in order to add a Productivity Booster to a User Group, this Productivity Booster
must already be installed. If you want to create a new Productivity Booster and add it to a
User Group, you should read the information in the chapter ‘Customizing the Headstart
Utilities’.
Creating and Reconciling Users
In order to be a Headstart Utilities user, a user must first be defined as an Oracle Designer
user and a Headstart Template Package user (see previous Section).
To create a new Headstart Utilities user, perform the following steps.
1. Choose the menu option Administration => Users

2. Enter the required information.
4 - 2 Development Team Access to Headstart Headstart Oracle Designer 6.5 - User Guide
• Username - the user’s Oracle Username
• Group - select a User Group from the List of Values
• Name - the user’s name
• For a description of the other fields on this screen, see the User Preferences
Section of the chapter ‘Running the Headstart Utilities’.
3. Save.
4. Press [Reconcile user] to grant the correct privileges to the current user, or
[Reconcile all] to do the same for all recorded Utilities users.
Headstart Oracle Designer 6.5 - User Guide Development Team Access to Headstart 4 - 3
Headstart generated applications
To be able to use Headstart generated applications (like the Demo Application, or your own
generated application), each Oracle user account you use to access such an application must
have access to the Headstart database objects and a copy of procedure qms_exec_sql.
To grant this access, you should perform the following steps.
1. Connect to SQL*Plus as the Headstart Template Package owner.

2. Run the script GRT_SYN.SQL. This script is located in the
<HSD_HOME>\hst\scripts directory.
3. You will be prompted for the Oracle username you want to give access to Headstart
applications.
4. Connect to SQL*Plus as the user who owns the TAPI packages.
5. Run the script EXEC_SQL.SQL. This script is located in the
6. Grant execute on the procedure qms_exec_sql to [HST65 OWNER]
The script will grant access to the Headstart Database Objects, and it will also create private
synonyms for them in the schema of the specified user.
Attention: It is assumed here that you will have shared deployment of the
Headstart Database Objects, at least in the Development Environment. If you
decide to create a self-contained application (for more information about this
choice see the Section ‘Database Schema Organization’ in chapter ‘Test and
Production Environment’), you will have to create the Headstart Database
Objects in the application schema and use Alter Schema Set Current Schema, as
described in chapter ‘Test and Production Environment’. In that case you don’t
need to run GRT_SYN.SQL for every end user.
4 - 4 Development Team Access to Headstart Headstart Oracle Designer 6.5 - User Guide
CHAPTER
5 Running the Headstart

Utilities
This chapter explains how to run the Headstart Oracle Designer Utilities using the supplied
Run Utility Form.
Headstart Oracle Designer 6.5 - User Guide Running the Headstart Utilities 5 - 1
Important Terms
Context Workarea
When you start the Run Utility Form you will have to specify the workarea you want to work
in. To be able to use the Productivity Boosters in a specific workarea you must be granted
Select, Update, Insert and Delete access rights to both the workarea and the application
system/folder by their respective owners. For using the Quality Checks, Select access is
sufficient.
The workarea you work in is referred to as the Context Workarea. It is visible in the window
title and at the bottom of the Run Utility Form.
Context Container
There are two types of Context Container:
1. Container to create new objects in

2. Container to select objects from
Creation Context Container

Some of the Productivity Boosters are able to create new primary elements. Primary elements
belong directly to an Application System or Folder, like Entities, Domains or Table
Definitions. The utility must know in which Application System or Folder these new objects
have to be created.
You can specify that container in the upper right hand corner of the Utility Parameter
window. It is the item with the prompt ‘Create new objects in’. The list of values contains all
folders/application systems of the workarea that you have Insert privileges for. If you leave it
at the default value <default>, the utility will create any new objects in the same container as
the object it is based on.
For example, the utility ‘Create CAPI Definition’ can be executed for multiple tables from
different containers in one run. For each of these tables, it will create the CAPI in the same
5 - 2 Running the Headstart Utilities Headstart Oracle Designer 6.5 - User Guide
container as the table the CAPI belongs to. This way the utility can create new primary
elements in multiple containers in the same run.
Selection Context Container

The second context container item, ‘Select objects from’, restricts the Lists of Values of the
Utility parameters to those objects that are directly owned by the selected folder or
application system (NOT including its subcontainers). So, for example, when for a certain
utility you have to select one or more Table Definitions, it won’t show you all Table
Definitions in the workarea to choose from, but only those Table Definitions that are owned
by the selected container. This is particularly useful if you have a large workarea with a lot of
objects, because it improves the performance of calling the LOV for a utility parameter. The
selected container remains if you switch to a different utility.
If you leave it at the default value <whole workarea>, the parameter LOV’s will not be
restricted and show all objects in the context workarea, regardless the owning application
system or folder.
Application Code
Many CDM Standards use the so-called Application code in naming conventions. Standard
OMS-42113 for example states that primary key constraints must be named using the
convention
<application_code>_<table/view_alias>_PK
The standard for specifying the application code is described in OMS-61605:
Include an application code of 3 alphanumeric characters in the application name, in one of

the following ways:
1. make the application name equal to the application code,
2. append the application code between brackets at the end,
3. start with the application code and extend it with a version number,
4. start with the application code and extend it with an underscore followed by a logical
name
The Headstart Oracle Designer Utilities assume that this standard has been followed, and
derive the Application Code from the Application System name. To clarify this derivation
some examples are given below.
Application System Name Application Code

ABC ABC
MICKEY (MKY) MKY
DONALD (DNLD) DON
XYZ_DEVELOPMENT XYZ
XYZ_TEST XYZ
PLUTO PLU
AZ AZ
Run Utility Form
The Run Utility Form itself consists of two components.
• The Navigator where you can select a productivity booster or a quality check
• A Parameter window that brings up the parameters that you can fill in for the specific
utility that you have selected in the Navigator.
Navigator
The navigator gives you all the functionality that you normally find in a navigator. You can
expand, expand all, collapse, collapse all, refresh the entries and search forward or backward.
Expand, expands the current node.
Collapse, collapses the current node.
Expand All , expands the current node and the nodes below it.
Collapse All, collapses the current node and the nodes below it.
Refresh, Refreshes the nodes for instance after installing a new utility.
Parameter Window
If you have selected a utility, the parameter window will automatically pop up and show you
the parameters for the selected utility. Parameters with light yellow background are
mandatory.
Most of the parameters you have to enter with the help of a list of values (LOV) . The list
of values can have two forms: multi select or single select. In the multi select LOV you can
select multiple objects (for instance tables) by using <Ctrl> click and/or <Shift> click. The
parameter item will display <multiple selection> if you have selected more than one element.
Parameters that don’t have a List of Values, have a button which pops up a multi-line text
editor. This is useful for entering long texts.
You can run the utility by clicking the green light button. The question mark button
gives you online help for the selected utility. The button lets you view the QA
run results. The run results are automatically shown in the browser so you normally will not
use this. The lets you view the log results. You also have the possibility to view the log
results after you have run a productivity booster, which means that you normally will not use
this button either.
After you have run a quality check the browser will be opened automatically (if the
preference is checked) and the output is shown in HTML format. Depending on your user
preferences you can get different forms of output. For more information see the Section on
user preferences.
If you have run a productivity booster you will get the following window.
We advise you to look at the logging first before you save your data to the repository. If you
are not satisfied you can press the undo button and the changes are not saved.
Sometimes a utility completes with errors. This can be an error found by the utility itself, or a
violation of the Oracle Designer API (in which you will see an error code). For example if
you want to create a view and give an alias that already exists in the repository the utility will
report an error. The logging gives the error and you should change the alias and run the
utility again.
User Preferences
The run utility form gives you a number of user preferences to steer the output and logging.
You can edit the user preferences from the Edit-menu.
QA Details Creation
The output of the QA-checks consists of four parts:
• Summary
• by element
• by standard
• CDM Standards (static)
The summary part consists of the following items:
• Element types, with a numeric overview of the violations for each element type
• Timing Statistics of the QA-check that you performed
• Violated standards, with a list of all standards that are violated. You can click on the
number of violations to start the ‘by standard’ part
• Elements with violations, with a list of all elements that are violated. You can click on
the number of violations to start the ‘by element’ part.
The ‘by element’ part orders the violations per element. This is especially useful for
Developers that want to fix the violated errors for the element that falls under their
responsibility.
The ‘by standards’ part orders the violations per standards. This is especially useful for QA-
persons that want to get a feeling of which standards are violated in a project. It consists of
the following items:
• Violated standards, gives the standard and the elements that violated this standard
• Checked standards, all standards that have been checked
• Standards that are not checked (Comply to is set to No).
• Standards which have to be checked manually
The CDM Standards are a list of all standards with their rationale, examples, annotation etc.
These files are not included in Headstart Oracle Designer but are included in the Standards
and Guidelines Library of CDM Advantage.
If you are not interested in one of more of these parts you can regulate this with the following
user preferences.
By Standard
If you check this check box the ‘by standard’ part will be created.
By Element
If you check this check box the ‘by element’ part will be created.
Non Complied Standards

If you have ‘turned off’ a standard in the administration application by setting ‘Comply To’
to No, these will be listed in the output if you check this checkbox. This only works for QA-
sets not for QA-checks by element. This is especially useful for a QA person that wants to
know which standards are ‘turned off’.
Standards to be Checked Manually

Not all standards are checked automatically. By listing the standards that need to be checked
manually the QA-person gets a full overview of what he or she still needs to do. This only
works for QA-sets not for QA-checks by element.
QA Run Results
View Run Results

If this checkbox is checked the browser automatically starts to show you the run results.
Delete Data
The output of the utilities is written to the database so you can make your own report to show
the output. Checking this checkbox leads to the situation that starting a QA check will delete
the data of the previous run. If you do not need that save the results to the database because
the output says it all check this check box.
Suggestion: If you did not check this check box, you can delete the old QA
Run data later using the Utilities Administration Application (menu:
Administration => Cleanup old data).
Logging
Log Messages Level

Here you define the level of detail of the logging. There are five choices:
• Errors, only shows errors

• Warnings, shows errors and warnings
• Information, shows errors, warnings and the actions that are performed by the utility,
this is the default setting
• Debug, shows errors, warnings, information and high level debug information
• Debug detailed, shows errors, warnings, information, high level debug information
and detailed debug information.
Delete Data
The logging of the utilities is written to the database so you can make your own report to
show the logging. Checking this checkbox leads to the situation that starting a utility will
delete the logging of the previous run. If you do not need to save the results to the database
because the logging says it all, check this check box.
Suggestion: If you did not check this check box, you can delete the old
Logging data later using the Utilities Administration Application (menu:
Administration => Cleanup old data).
Process the Following Objects

If you are using a versioned Repository, you can only make changes to unversioned or
checked out objects. If the objects are checked in, you can not change them.
Before running a utility, you could check out all objects that you think the utility will need,
but it can be hard to guess which objects you need. There is an easier way: let the utility
check out the objects just before it changes them.
Folders and Application Systems

If a utility needs to create a new primary object in a folder/application system that is checked
in, the utility will always check out that container. It will report this in the log messages, and
if you undo the results of the utility, the check out will also be undone.
Primary Objects
Each utility determines the primary objects it should modify and whether or not it has access
to those objects based on the setting of the user preferences ‘checked out by…’ and ‘…and
also checked in objects’.
• The utility always processes unversioned objects .

• The utility always processes checked out objects, though you can restrict this to
process only objects checked out by you.
• If you allow the utility to process objects checked out by anyone, you also have the
option to process checked in objects. If you choose to also process checked in objects,
the utility will check the object out for you. However, you must specify whether the
utility should check the object out with or without a lock.
If the utility determines that it should process an object but does not have access, then the
utility will err out. The log messages will list the first object that could not be accessed and
why.
Check In
It remains your own responsibility to check folders, application systems and other objects
back in, if needed.
CHAPTER
6 Running the Headstart

Foundation Application
This chapter explains how to use the Headstart Oracle Foundation Application.
The Foundation Application allows users to interactively maintain two important features of
the Headstart Template Package.
• Headstart Message Dictionary

• Headstart Report Modules and Parameters
Headstart Oracle Designer 6.5 - User Guide Running the Headstart Foundation Application 6 - 1
Messages
Headstart provides a multi-lingual message dictionary for recording message text used in
your application.
Each message is identified by a code with the following format.

XXX-99999
XXX is the 3 letter application system code

99999 is a 5 digit sequential number
You must use this format when defining your messages. (Note: It is possible to change this
format, but you must also change the format of all existing messages if you do this.)
When a message is raised on the client, the message code is passed to a procedure which
retrieves the correct message text from the dictionary taking the end user’s language
preference into consideration.
If the message is used for a constraint violation, the constraint name should be recorded. If
an error is raised on the server, the constraint name is passed to the client. Since no message
code is known at this point, the constraint name is passed to the procedure which retrieves the
message text.
Headstart provides a utility to automatically generate messages for primary key, unique key
and foreign key constraints. For other messages, you must manually record the message
using this form.
6 - 2 Running the Headstart Foundation Application Headstart Oracle Designer 6.5 - User Guide
Module and Parameters
Headstart provides a single dynamic launch form for all reports. This means you do not have
to create individual parameter forms for every report.
In Designer, you will define your report and its required user parameters.
You will then run a Headstart Utility to automatically populate the report parameter tables
with this information.
You can then use this form to add the Standard Report Parameters (Destination Type,
Destination Format, Orientation, etc.), and to record details about the user parameters.
• datatype, length, default value and description, optionality

• prompt, format
• validation where clause
In the Default Value and Description, you can use SYSTEM and GLOBAL variables,
SYSDATE and USER, in addition to literal values.
The validation where clause is used to validate the input parameter against data stored
in a table. It is recorded as a where clause using the following standard format:
exists ( select ‘1’ from <table_name> where <column_name> = :<parameter_name> )
For example:
exists (select ‘1’ from hsd_departments where id = :p_dep_id )
• list of values
You can also define a list of values query for parameter values that can be selected
from data stored in a table.
You have three options for creating the LOV.
• Native Forms LOV

• Multi-Select LOV
• LOV Form
Native Forms LOV

For the Native Forms LOV, you must define the query that will be used for the LOV
record group. The LOV is built dynamically at runtime.
The query must use the following format:

select <character value> “VALUE”
<character value> “DESCRIPTION”
from <table_name(s)>
where …
order by …
The <character value> can be a single field or a concatenated list of fields. If it

contains numeric data, it must be converted to a character string using the to_char
function.
The DESCRIPTION is displayed to the user on the report launch form and the
VALUE is hidden. The VALUE is what is actually passed to the report.
You can define the display width of the VALUE and DESCRIPTION fields as well
as the LOV as a whole. If you only want the DESCRIPTION field to be visible in the
LOV, set the VALUE field width to 0.
Multi-Select LOV
For the multi-select LOV, you define a query just as you did for the Native Forms
LOV above. Use the ‘Multi Select LOV’ checkbox to indicate that you want a multi-
select LOV.
Multi-select LOVs will be shown using the Shuttle Control Object Selector form,
qms0014f.
If you have a multi-select LOV, you can enter a list of values in the Default Value
and Default Description properties for the parameter as well. Separate the items in
the list using a comma.
If you choose multi-select, the LOV, VALUE and DESCRIPTION widths are
ignored.
LOV Form
To use an LOV form for a report parameter, you must first create the LOV form in
Designer. Follow the instructions in the Designer online help for creating an LOV
form.
In the LOV Query field, instead of defining a query, use html-like tags to define the
name of the LOV form.
<FORM>hsd0024f</FORM>
When the user selects a record using the LOV form, the VALUE is filled in.
Unfortunately, the LOV form created by Designer does not contain a mechanism to
also return the DESCRIPTION to the calling form. Therefore, you must also define a
query that will fetch the DESCRIPTION to display to the user. The query must use
the following format.
<SELECT>
select <character value>
from <table_name(s)>
where <column_name> = :<parameter_name>
( and …)
</SELECT_DESC>
This query must return exactly one record. The <character value> may be a single
column or a concatenated list of columns. If it contains numeric data, it must be
converted to a character string using the to_char function.
If you choose an LOV Form, the LOV, VALUE and DESCRIPTION widths, as well
as the Multi Select LOV property, are ignored.
Standard Report Parameters
This form allows you to define Standard Report parameters for use with your generated
reports. Headstart supplies default definitions with validation and appropriate lists of values
for all system parameters.
You can customize which parameters are displayed to users in the Report Options window of
the report launch form, and you can customize the default values for any standard parameter.
(blank page)
PART II ROADMAP TO
APPLICATION
DEVELOPMENT
(blank page)
CHAPTER
7 Headstart Application
Development Approach
The three-layer model introduced by the Gartner Group provides a framework for
modularizing an application system into the following three basic components:
Presentation Business Data

Logic
• The presentation layer contains the services to support the application end user. This
includes screen- and input-handling, such as menus, window navigation, graphical
screen design, and mouse-activated actions.
• The business logic layer implements business functions and business rules.
• The data layer handles access to the database, data manipulation and preserves data
integrity.
Headstart Oracle Designer 6.5 - User Guide Headstart Application Development Approach 7 - 1
Benefits of Three Layer Approach
More Adaptable To Change
Applications can be made more adaptable to changes in business requirements and
technology. For example, an application that clearly separates presentation logic from
business logic would be easier to convert from windows mode to a web-interface than one
that mixes these two layers.
Distribute Application workload

Application workload can be more easily distributed across multiple processing nodes to
eliminate CPU, network and I/O bottlenecks.
Minimize Dependencies Between Layers

Dependencies between layers can be minimized. The business logic layer can encapsulate
access to multiple data sources to enable integration between new and legacy applications.
More Manageable
Individual components organized into well-defined layers can be managed more easily than
an application based on a monolithic architecture. Upgrades can be staged on a layer-by-
layer basis, while system monitors can be more effective at discovering and analyzing
performance problems of individual modules.
Improved Reusability
Modularity, well-defined interfaces between software and the centralization of application
logic are all prerequisites for reuse.
More Robust
Distributing the workload has the additional benefit of eliminating single points of failure.
Data Independence
Theoretically, the business logic and presentation tiers can be built independently of the data
source, allowing different databases to be used without modification.
7 - 2 Headstart Application Development Approach Headstart Oracle Designer 6.5 - User Guide
Logical versus Physical Partitioning
The distinction between logical and physical partitioning is very important.
Logical Partitioning
• design of the software components is based on a clear specification of each tier
• software interfaces are defined between the tiers
• more than one logically defined tier may be implemented on the same physical tier
(either hardware or software)
• prerequisite for physical partitioning
Physical Partitioning
• the three tiers are both logically and physically separated
• presentation is relegated to the browser
• business logic to one or more application servers
• data management to one or more database servers
• middleware handles the interactions between tiers
• different, non-integrated development toolsets may be used in each tier
Three Layer Architecture in an Oracle Environment

Very few applications require strict physical partitioning. We recommend a Logical Three
Layer - Physical Two Layer approach for Oracle applications for the following reasons.
• The Oracle Server has evolved over the years into a platform for internet computing
with very strong capabilities for hosting business logic, written in either PL/SQL or
Java. In other words, the Oracle Server has become both a Database Server and an
Application Server.
• Many business rules are implemented with data-driven logic. The tight binding of
data and business logic justifies a close physical coupling to cut down on network
traffic.
• Security and performance concerns cut across all tiers. Network performance, in
particular, may suffer from over-partitioning and an increase in middleware overhead.
• Physical partitioning adds cost and complexity to routine management tasks such as
security administration and software distribution.
• A close link between data structure and presentation is sometimes required to guide
users through informational data access (data mining, ad hoc query, etc.).
• Non-integrated approaches will often have multiple languages in each tier; for
example, a screen-building tool, graphical report writer, and 3GL for complex logic at
the workstation, a production report writer, 3GL, and scripting language for batch
processing on the application server, and a stored procedure language in the database.
Not only do multiple languages increase complexity, maintenance costs, and learning
curves, they also reduce the opportunities for reuse, since application logic cannot be
shared or re-partitioned, without re-coding or wrappering.
• Complex, interactive transactions require an affinity between the business logic and
presentation layers. The presentation layer must adapt to underlying business rules to
give the user navigational flexibility and control over transaction boundaries.
Headstart Application Development Approach
The application development process using Oracle Designer and Headstart Oracle Designer
can best be described as a matrix. It consists of 3 logical layers: the Data Layer, the Business
Logic Layer, and the Presentation Layer. For each of these layers, activities are performed
during the Analysis Phase and the Design and Implementation Phase.
Business Logic Presentation

Data Layer Layer Layer
Analysis Entities Rule Definition Functions
Transformation
Design Database Design Rule Design Module Design
Generation
Implementation Oracle Database RuleFrame WebForms
HTML
Headstart Oracle Designer Development Matrix
The remainder of this user guide is organized around this development approach matrix.
The following chapter presents a brief roadmap for each of the phases of the development
process. For each phase, the activities for the Data Layer, Business Logic Layer and
Presentation Layer are outlined. These roadmaps show when to use Headstart in your
development process.
Then each of the three Layers is presented in its own Part. There, you will find detailed
information on how to use the various Headstart features.
(blank page)
CHAPTER
8 Development Process
Roadmaps by Phase
This chapter presents a brief roadmap for each of the phases of the development process. For
each phase, the activities for the Data Layer, Business Logic Layer and Presentation Layer
are outlined.
These roadmaps show when to use Headstart in your development process.
Business Logic Presentation

Data Layer Layer Layer
Analysis Entities Rule Definition Functions
Transformation
Design Database Design Rule Design Module Design
Generation
Implementation Oracle Database RuleFrame WebForms
HTML
Headstart Oracle Designer Development Matrix
Headstart Oracle Designer 6.5 - User Guide Development Process Roadmaps by Phase 8 - 1
Analysis Phase Roadmap
The tasks listed in this roadmap are described in detail in the CDM Standards and Guidelines
Library, Volume 1: Requirements Modeling using Oracle Designer.
• Chapter 2: Process Modeling

• Chapter 3: Business Rule Modeling
• Chapter 4: Entity Relationship Modeling
• Chapter 5: Function Modeling
The four types of modeling described below are usually done in parallel and each feeds off of
information gathered in the others. Although the steps are presented here as sequential, it is
very likely that you will iterate around some of these steps, refining the details at every pass
of the iteration.
Business Process Modeling
Tasks
1. Identify Primary Processes
2. Define Business Units
3. Develop Process Flow Diagrams for Primary Processes
4. Identify Events to which each Business Area Responds
5. Identify and Document Business Processes Associated with each Event
6. Develop Business Process Flow Diagrams
Headstart Quality Checks (deliverables)

RD.005 - Context Process Model
RD.010 - Business Process Model
RD.011 - High Level Business Process Model
RD.020 - High Level Business Descriptions
RD.049 - Detailed Business Process Model
RD.050 - Detailed Business Descriptions
RD.100 - System Process Model
RD.115 - Revised Business Requirements Models
8 - 2 Development Process Roadmaps by Phase Headstart Oracle Designer 6.5 - User Guide
Data Layer - Entity Relationship Modeling
Tasks
1. Define Entities and their Relationships
2. Define Attributes
Headstart Productivity Booster: Enforce CDM Ordering Standard for Attributes
3. Define Constraint Rules
4. Add Entity Detail
Headstart Productivity Boosters

Enforce CDM Ordering Standard for Attributes
Headstart Quality Checks (elements)

Entities

RD.040 - Initial Business Data Model
RD.041 - High Level Business Data Model
RD.060 - Business Data Model
RD.080 - System Data Model
Business Logic Layer - Business Rule Modeling
Tasks
1. Create events for entities
Headstart Productivity Booster: Maintain Default Events for Entities
2. Record your business rules using the Business Rule Function object
3. Associate Triggered By events with your business rules
4. Record Business Rule - Data Usage
5. Clean up redundant events
Headstart Productivity Booster: Cleanup Unused Events for Entities
Headstart Productivity Boosters

Maintain Default Events for Entities
Cleanup Unused Events for Entities

Events
Presentation Layer - Function Modeling
Tasks
1. Define Function Hierarchy (screens, reports, etc.)
2. Define Function Entity Usage and Function Attribute Usage
3. Add Function Detail

Functions

RD.030 - High Level Business Function Model
RD.031 - Composite Business Function Model
RD.070 - Detailed Business Function Model
RD.090 - System Function Model
Design and Implementation Phase Roadmap
The tasks listed in this roadmap are described in detail in the CDM Standards and Guidelines
Library, Volume 2: Designer and Generation of Multi Tier Web Applications.
• Chapter 2: Application System Architecture

• Chapter 3: Application Design
• Chapter 4: Logical Database Design
• Chapter 5: Physical Database Design
• Chapter 6: CDM RuleFrame, Framework for Implementing Business Rules
• Chapter 7: Implementing the Rule Layer
• Chapter 8: Accessing the Rule Layer from Webforms
• Chapter 9: Implementing Business Rules in Webforms
• Chapter 10: Webforms User Interface Design and Generation
Although the steps are presented here as sequential, it is very likely that you will iterate
around some of these steps, refining the details at every pass of the iteration.
Technical Application Architecture
Before you start your design you need to make important architectural decisions. Making or
changing these decisions later on will probably cost you a lot of rework
Tasks
1. Identify Necessary Tools
2. Define Batch Scheduling Mechanism
3. Define Debugging and Tracing Facilities
Headstart provides a debugging and tracing environment.
4. Decide on Business Logic Layer Structure
CDM RuleFrame supports an independent business logic layer.
5. Create or Buy Template Package
Headstart provides a sophisticated template package, which can easily be customized
and extended to meet application specific needs
6. Define Help System
Headstart HTML Online Help Generator provides a utility that generates context
sensitive on-line help in HTML files. This utility uses the help text recorded against the
various design objects in Oracle Designer.
7. Define Messaging System
Headstart offers a messaging component with help on messages, displaying cause and
action to be taken.
8. Multi-lingual Requirements
Headstart provides multi-lingual support for the messaging component.
9. Prepare to Address Performance Issues
Data Layer
Application Design (MD.030)

1. Map Entities to Tables
Logical Database Design (DB.010)

1. Create First-Cut Database Design
2. Apply CDM or project-specific naming conventions
Headstart Productivity Booster: Enforce CDM naming conventions for constraints
3. Specify a method for populating artificial keys
Headstart Productivity Booster: Create sequences for columns
4. Add tables and columns for data auditing purposes
Headstart Productivity Booster: Create About This Record Columns
Headstart Productivity Booster: Create journal tables
Headstart Template Package: About This Record form
5. Apply CDM or project-specific ordering conventions
Headstart Productivity Booster: Enforce CDM ordering standard for columns
6. Define views to reflect subtype implementations, pre-package complex queries, or
restricted data access
Headstart Productivity Booster: Create view definition based on table definitions
Database Authorization Scheme (DB.030)

1. Define Database Role Structure
Headstart Productivity Booster: Create roles based on low level business units
2. Assign System Privileges to Roles
3. Assign Object Privileges to Roles
Headstart Productivity Booster: Create role obj. privs based on module access and data
usages
Physical Database Design (DB.040)

1. Create Default Index Design
2. Confirm and Verify Index Definitions
Headstart Productivity Booster: Create indexes for foreign key constraints
Headstart Productivity Booster: Delete redundant indexes
3. Consider Denormalization Techniques
4. Define Clusters
5. Define Tablespaces
Headstart Productivity Booster: Assign objects to tablespace
6. Define Storage Definitions
7. Define Rollback Segments
Create Database DDL (DB.050)

1. Create Database Objects
Business Logic Layer

1. Identify and Define Rule Components
Headstart Productivity Booster: Business Rule Design Transformer

Headstart Productivity Booster: Create Domains for Discriminator Columns
Headstart Productivity Booster: Maintain Super/Subtype Business Rules
Headstart Productivity Booster: Maintain Journalling Business Rules
2. Identify and Define other Business Logic Layer Components
3. Identify (Business) Views
Detailed Business Logic Layer Component Design (MD.050)

1. Design Business Views (VAPIs)
Headstart Productivity Booster: Create VAPI Definition

Headstart Productivity Booster: Create view definition based on table
Headstart Productivity Booster: Add Instead-Of Trigger to a View
2. Design and Code Rule Components
Headstart Productivity Booster: Create Business Rule Design Definition
3. Design and Code Other Business Logic Layer Components (Custom Services)
Headstart Productivity Booster: Create Custom CAPI Service
Business Logic Layer Components Generation and Build (MD.090)

1. Generate Custom API’s
Headstart Productivity Booster: Set unique key constraint as descriptor columns

Headstart Productivity Booster: Create CAPI definition
2. Generate the DDL for the TAPI, CAPI, VAPI and other Business Logic Layer
Components
Presentation Layer

1. Create First-cut Design of Presentation Modules
2. Refine Design of Presentation Modules
3. Determine Rules that Require Implementation in Presentation Components
4. Create Module Network
User Interface Standards (Part of MD.010)

1. Define Standards and Guidelines for Screen Design and User Interface Objects
Headstart Template Package
2. Define Standards and Guidelines for Screen Behavior
3. Define Menu Layout
4. Design Messaging Display
5. Design Online Help System
Headstart Productivity Booster: Set MS Help generation properties of screen modules
Headstart Productivity Booster: HTML Online Help Generator
6. Customize and extend Template Package
Detailed Module Design (MD.050)

1. Define Table and Column Display Properties
Headstart Productivity Booster: Copy properties of columns in a domain
Headstart Productivity Booster: Copy display properties from bound items to columns
Headstart Productivity Booster: Copy display properties from columns to bound items
Headstart Productivity Booster: Copy properties from base table to view
Headstart Productivity Booster: Set column display length
Headstart Productivity Booster: Set unique key components as descriptor columns
2. Define Module Data Usage
Headstart Productivity Booster: Copy display properties from bound items to columns
Headstart Productivity Booster: Copy display properties from columns to bound items
3. Define Module and Module Detail Preference Settings
Headstart Productivity Booster: Adapt form modules for VAPI use
Headstart Productivity Booster: Create Find Window(s)
Headstart Productivity Booster: Set Module Revision Numbers
Headstart Productivity Booster: Create Headstart report and report parameter definitions
Menu Structure and Security (MD.060)
1. Create Menu Structure
2. Enforce Function Access Rules
Headstart Productivity Booster: Create role module access based on bus. Unit function
access
Module Generation and Build (MD.090)

1. Generate Menus, Forms and Reports
2. Build non-generatable user interface components
(blank page)
PART III DATA LAYER
(blank page)
CHAPTER
9 Implementing the Data

Layer
This chapter describes the support that Headstart offers for the tasks involved in defining the
Data Layer.
For more detailed information on these tasks, refer to the CDM Standards and Guidelines
Library.
Headstart Oracle Designer 6.5 - User Guide Implementing the Data Layer 9 - 1
Data Layer Roadmap
This Part summarizes the activities that need to be performed for the Data Layer.
Analysis Phase
Tasks
1. Define Entities and their Relationships
2. Define Attributes
Headstart Productivity Booster: Enforce CDM Ordering Standard for Attributes
3. Define Constraint Rules
4. Add Entity Detail
Design and Implementation Phase

1. Map Entities to Tables
Logical Database Design (DB.010)

1. Create First-Cut Database Design
2. Apply Naming Conventions
Headstart Productivity Booster: Enforce CDM naming conventions for constraints
3. Define Auto-generated Primary Keys
Headstart Productivity Booster: Create sequences for columns
4. Implement Data Structures for Auditing
Headstart Productivity Booster: Create About This Record Columns
Headstart Productivity Booster: Create journal tables
Headstart Template Package: About This Record form
5. Enforce Ordering Standards
Headstart Productivity Booster: Enforce CDM ordering standard for columns
6. Define Views
Headstart Productivity Booster: Create view definition based on table definitions
Database Authorization Scheme (DB.030)

1. Define Database Role Structure
Headstart Productivity Booster: Create roles based on low level business units
9 - 2 Implementing the Data Layer Headstart Oracle Designer 6.5 - User Guide
2. Assign System Privileges to Roles
3. Assign Object Privileges to Roles
Headstart Productivity Booster: Create role obj. privs based on module access and data
usages
Physical Database Design (DB.040)

1. Create Default Index Design
2. Confirm and Verify Index Definitions
Headstart Productivity Booster: Create indexes for foreign key constraints
Headstart Productivity Booster: Delete redundant indexes
3. Consider Denormalization Techniques
4. Define Clusters
5. Define Tablespaces
Headstart Productivity Booster: Assign objects to tablespace
6. Define Storage Definitions
7. Define Rollback Segments
Create Database DDL (DB.050)

1. Create Database Objects
Attention: When you generate the Table Definitions using Designer’s Server
Generator, make sure that you don’t include the Allowable Value Constraints
(check constraints named AVCON_…), by unchecking the checkbox ‘Generate
Valid Value Constraints’ in the Options of the Generate Server Model
Definitions (see figure below).
A better way to enforce these constraints is by running the Headstart Utility

‘Maintain Static Domain Business Rules’ and implementing them in CDM
RuleFrame. For more information, see chapter ‘Implementing the Rule Layer’ in
part IV (Business Logic Layer).
Implementing the Data Layer
The following utilities are provided by Headstart Oracle Designer to assist in creating the
Data Layer.
Apply Naming Conventions
Enforce CDM naming conventions for constraints

This utility enforces the CDM naming convention for primary key, unique key, foreign key
and check constraints.
Define Auto-generated Primary Keys
Create sequences for columns

This utility creates sequences for use with auto-generated primary keys. To benefit most
from this utility, you should use a standard name for your primary key columns. Example:
ID
The utility will create a sequence for every column with the given name, and assign the
sequence to the corresponding column.
Depending on the value of the parameter Set to server defined? the column will also be set to
be server defined.
If you enter the Database and User parameters, the utility will also create a sequence
implementation for the sequence.
You can generate a Table API which (among other things) assigns a value to the primary key
column when inserting a record.
The parameter "primary keys only" is used to limit the utility so it only creates sequences for
primary key columns. If you set this value to No, you can use this utility to create sequences
for other columns as well.
Implement Data Structures for Auditing
In Volume 2 of the CDM Standards and Guidelines Library, two methods of data auditing are
discussed: last change columns (which are shown in the About This Record form of the
Headstart Template Package) and journaling.
Create About This Record Columns

This utility creates audit columns on the selected tables. You may use the default column
names or give your own names. If you blank out a name, that column is not created.
You may choose whether these columns should be server derived (in the TAPI), or client
derived (in the Form).
In order for these columns to be displayed in the About This Record form, the columns must
be included as non-displayed items in any module component based on the associated table.
If you have already created modules before running this utility, you can specify that you want
to add these columns to existing module components as needed.
Maintain journal tables

This utility, together with the ‘Maintain Journaling Business Rules’ utility, supports the
recommended server-side implementation of populating journal tables.
You can specify the tables you want to journal by adding the following tags in the notes of
the table definition.
<JN>Journal</JN> or
<JN>Journal Old New</JN>
When you choose the tag <JN>Journal</JN> the resulting journal table will contain the same
columns as the underlying table and the addition columns JN_USER, JN_DATE_TIME and
JN_OPERATION
When you choose the tag <JN>Journal Old New</JN> the resulting table will contain two
copies of each column in the underlying table; one for the old value and one for the new
value.
It is also possible to specify which columns you want to journal. You can do this by adding
the tag <JN>Journal</JN> in the notes of the column. If you do not specify any tag it is
assumed that you want journaling for all columns.
The ‘Maintain journal tables’ utility will create and maintain journal tables based on these
journaling tags. The utility uses the naming convention <table name>_JN when a journal
table is created or when the existence of a journal table is checked.
See the Business Logic Layer Part for information on the ‘Maintain Journaling Business
Rules’ utility.
Enforce Ordering Standards
Enforce CDM Ordering Standard for Attributes

This utility re-orders the attributes in the selected entities according to the CDM standards.
The following ordering sequence is applied:
1. primary unique identifier attribute(s)

2. other unique identifier attribute(s)
3. all other attributes
Within those categories, the original order is preserved.
All attributes are also re-sequenced with the given increment.
Enforce CDM ordering standard for columns

This utility re-orders to columns in the selected tables according to the CDM standards. The
following ordering sequence is applied:
1. primary key columns

2. unique key columns
3. foreign key columns
If spacing must be optimized, the rest of the columns are ordered as follows:
4. all other mandatory columns

5. all other optional columns
Otherwise, the original order is preserved.
The columns are also re-sequenced using the specified increment.
Define Views
Create view definition based on table definitions

This utility provides a quick and easy way to create view definitions. The view’s base table
may be joined with one or more lookup tables. All columns of these tables will be included
in the created view. The view columns which are not needed can easily be deleted using the
Repository Object Navigator.
All properties of the table columns will be copied to the view columns, except the property
Denormalization Via Foreign Key, which can only get a value if a suitable foreign key is
created for the new view.
The utility will create the join conditions (i.e. where validation condition) based on the
foreign key constraints between the base and lookup tables. This where validation condition
can be extended by using the Repository Object Navigator.
A primary key constraint and/or unique key constraints will be created for the view, if the
base table has a primary key and/or unique keys. You can also add foreign keys to the view
based on the foreign keys of the base and look-up tables.
It is also possible to add an Instead Of trigger to the view, which redirects DML on the view
to the TAPI DML procedures of the base table. This makes the view into a Business VAPI
for CDM RuleFrame. The default values of the last three parameters reflect the appropriate
choices for Business VAPIs. For more information on CDM RuleFrame and Business
VAPIs, see the Business Logic Layer Part.
Be sure you defined aliases for all used tables. Otherwise it is possible that the utility will fail
because of non-unique foreign key names.
Data Security
Headstart provides two utilities to assist in building a Role based security scheme.
Create roles based on low level business units

This utility creates a Role for each lower level business unit. A lower level business unit is a
business unit which has no “child” business units, i.e. leafs in the business unit hierarchies.
The created roles will have the same name as the underlying business unit. Spaces in the
business unit name are replaced by underscores in the Role name. For example, role
‘ORDER_ENTRY_MANAGERS’ based on business unit ‘ORDER ENTRY MANAGERS’.
Create role obj. privs based on module access and data usages
This utility creates role object privileges based on the module component table usages of the
modules to which the role has access. The utility will label the created object privileges. If
an object privilege created by the utility is no longer applicable the object privilege will be
deleted. If however the object privilege was manually created or the label is modified it will
not be deleted. In these cases a message will be included in the log messages.
Physical Database Design
Create indexes for foreign key constraints

This utility creates indexes for foreign key constraints.
If an index already exists for a given foreign key constraint, the name of the index is
corrected if it does not meet the CDM naming conventions, and the columns in the index are
updated to match those of the foreign key.
If an index exists which does not reference a foreign key constraint, but which has the correct
columns, the reference is created.
If you do not want the utility to create an index for a given foreign key, specify 'NO FK
INDEX' in the Notes of that foreign key.
Delete redundant indexes

This utility deletes redundant indexes. An index is considered redundant if a second index
exists with a column list starting with the complete column list of the first index.
If an index is identical to another index, the utility is unable to determine which index to
delete. Therefore, neither index is deleted. Instead, a warning is given in the log messages
and you will have to delete one of the indexes yourself.
Indexes which reference no columns are also deleted. If the index of a foreign key is deleted,
the following text is added to the Notes of this foreign key: 'NO FK INDEX, Index of this
foreign key is deleted by Headstart Utility Delete Redundant Indexes because other index
exists which started with the same columns.'
Assign objects to tablespace
This utility assigns objects to tablespaces. You must choose a database, a tablespace, a user
and tables. The utility will create table implementations for every combination of the
database, users and tables you have chosen. With parameters you can choose which objects
of the chosen tables you want to assign to the tablespace. Indexes, primary and unique keys
are assigned to a tablespace through User Object Index Storages. These will be created and
the tablespace will be assigned to it.
Headstart Quality Checks
The following Headstart Quality checks are available for the Data Layer.
Elements
• Domains
• Entities
• Table Definitions
• View Definitions
• Sequences
• Oracle Databases
• Non-Oracle Databases
Deliverables
• DB.010 - Logical Database Design
• DB.020 - Index Design
• DB.030 - Database Object Authorization Scheme
• DB.040 - Physical Database Design
• DB.050 - Product Database DDL
• RD.040 - Initial Business Data Model
• RD.041 - High Level Business Data Model
• RD.060 - Business Data Model
• RD.080 - System Data Model
PART IV BUSINESS LOGIC
LAYER
(blank page)
CHAPTER
10 CDM RuleFrame
This Part provides information on the use of the CDM RuleFrame, the Business Logic Layer
component of Headstart Oracle Designer.
The Business Rule Roadmap in this chapter presents an overview of the tasks involved in
implementing a business logic layer. If you want to get full understanding of the CDM
RuleFrame concepts we recommend that you read the following documents:
• CDM Standards and Guidelines Library, volume 1, chapter: Business Rule Modeling
• CDM Standards and Guidelines Library, volume 2, chapter: CDM RuleFrame
• CDM Standards and Guidelines Library, volume 2, chapter: Implementing the Rule
Layer
• Oracle Designer online help concerning the Table API (TAPI)
This Part covers the following subjects:
• Business Rule Roadmap A roadmap that gives you a step by step explanation on how
to analyze, design and generate business rules. You can use this roadmap as a cheat
sheet.
• Implementing the Rule Layer Explains every step mentioned in the business rule
roadmap in detail. This chapter will help you to implement business rules fast and
easy.
• Accessing the Rule Layer This chapter discusses the Headstart support for the creation
of a common access layer, the View API. It also discusses Headstart support for
several front ends (Forms, PL/SQL, WebDB, WebServer Generator, Java) for opening
and closing transactions and error handling .
Headstart Oracle Designer 6.5 - User Guide CDM RuleFrame 10 - 1

Business Rule Roadmap
Below you can find a roadmap for implementing the Business Logic Layer of your
application following the concepts of CDM RuleFrame and using the RuleFrame Utilities of
Headstart Oracle Designer. Each of these steps are described in more detail in the next
chapter. You can easily find them because they have the same titles and step numbers.
Business Rule Analysis
You only do step 1 and 5 once. Step 2, 3 and 4 you do for all business rules.
1. Create process events using the utility Maintain Default Events for Entities
This Headstart utility creates all possible process events for all entities in your application.
Running this utility makes it easy to associate your business rules with events.
Attention: Before you run this utility there have to be entities, relationships and
attributes. If you add or remove some later you can run the utility again.
Record your business rules using the Business Rule Function object in Oracle Designer as
described in the CDM Standards and Guidelines Library. Apply the naming convention as
described in standard OMS-60005, otherwise the Business Rule Design Transformer won’t
recognize them.

For all rules record the process events that trigger your business rule. Use the Triggered By
association of the business rule and link it to the appropriate events created in step 1.
Suggestion: Attribute and Tuple rules do not need events, because later on the
Business Rule Design Transformer derives these from the business rules data
usage. This is also valid for Entity and Inter Entity rules where the usage and
the triggering event is the same. By the same we mean that a retrieve usage of
an attribute is translated to a create entity event and an update attribute event.

Record the data usage of all rules. For validation rules this is always 'retrieve', only for
Change Event rules the usage can also be 'create', 'update' or 'delete'. You do not have to
record the entity/attribute usages if the entities and attributes in the related 'Triggered By'
events are the same. The Business Rule Design Transformer allows you to create this usage
for you based on these events.
5. Clean up redundant process events

After you have specified all your business rules, clean up all redundant process events by
running the 'Cleanup unused events for entities' Headstart utility.
10 - 2 CDM RuleFrame Headstart Oracle Designer 6.5 - User Guide

Business Rule Design
You only do step 1 and 2 once, step 4, 5 and 6 for all business rules and step 3 only for
business rules that cannot be supported on analysis level.
1. Run Business Rule Design Transformer Utility

Run the Headstart Utility 'Business Rule Design Transformer'. This utility creates Business
Rule Design Definitions. Remember that for each triggering entity a rule design definition is
made. That means that one rule can lead to more than one rule design definition.
Attention: Run the Database Design Transformer before you run the Business
Rule Design Transformer. The Business Rule Design Transformer does not
create rules that relate to entities that have not yet been mapped to tables. It also
skips events and usages for attributes/relationships that do not have a
corresponding column or foreign key.
2. Run other Business Rule Utilities

Run the following Headstart Utilities
• Create Domains for Discriminator Columns

• Create Default Error Messages for Constraints
• Maintain Super/Subtype Business Rules
• Maintain Static Domain Business Rules
• Maintain Journalling Business Rules (make sure that you also run the Data Layer
utility Maintain journal tables)
These utilities either prepare the enforcement of certain rule patterns in CDM RuleFrame, or
they create business rule design definitions that also include the code for the specified rule
patterns (so you don’t have to write any validation code yourself for these patterns).
3. Create additional rules using Business Rule Design Definition Utility

The Business Rule Design Transformer cannot handle rules that include self referencing
entities, because it is not allowed to record the usage of the same entity twice. You can use
the Headstart Utility 'Create Business Rule Design Definition' to add the rule design
definitions that are missing.
If you did not specify your rules at analysis level you can use this utility to create the business
rule design definitions.
4. Check the triggering events for each business rule

In this step you check if all triggering conditions are correct. Potentially add a Trigger When
Condition to prevent validation when it is not necessary. This will improve performance.
If operations on multiple rows can lead to the same violation of a business rule, you want to
make sure that the business rule is only validated once, and only one error message is shown
to the user. You can do this by using a special procedure (not_on_stack_yet) in the When
Condition.

5. Code your rule in the related PL/SQL Definition
In the PL/SQL definition of the rule you need to write the validation code. Use the standard
Table API and Custom API services for easy and fast coding. You will hardly have to write
any cursor, your code is compact and protected against changes and much of the complexity
is hidden by the services.
The following services are available:
• Insert, Update and Delete service of the Table API. Always use these services if you
want to code a DML Statement.
• Exists Row, determines the existence of a given row in a given table, using a
structured set of query conditions.
• Aggregate Value, gets COUNT, SUM, MIN, MAX or AVG of a column in a table
using a structured set of query conditions.
• Get Char, Date, Number Value, gets the value of any column in any row of the table.
• Display Label, displays descriptor columns for the indicated row, which can be used
for end user messages.
• You can also add your own custom services to the Custom API.
6. Check arguments of PL/SQL Definition

If you did not record your rule data usage correctly you will notice that you cannot compile
the Custom API. Always check the arguments for completeness, this can save you a lot of
time further on.
Business Rule Generation
1. Create Custom API Definition

Run the Headstart utility, 'Create CAPI Definition' for all tables at once. It takes all the
business rule design definitions that have the property Enable? = Yes and all the custom
services, to generate a CAPI package definition for each given table.
Suggestion: The CAPI utility uses the descriptor columns of the table to
determine the display label of a row. Before running this utility, check that your
descriptor columns are defined correctly. You can also use the utility ‘Set
unique key constraint components as descriptor columns’.
2. Generate Custom API's using Server Generator

At the moment you generate your database objects with the Oracle Designer Server Generator
you can also generate the CAPI packages. The CAPI will be invalid but you will correct that
in step 4.
3. Generate Table API using Table API Generator

Generate the Table API for all tables using the TAPI generator utility of Oracle Designer. The
TAPI package bodies will be invalid but you will correct that in step 4.

4. Recompile invalid PL/SQL packages
Since the Table API calls the Custom API and vice versa you will always start out with
invalid packages. By using the recompile script (recompl.sql) of Headstart you can easily
recompile these packages. If you still have invalid packages (check with the invalid.sql script)
you have probably made an error in your business rules coding. Go back to step 5 in Business
Rule Design.

(blank page)

CHAPTER
11 Implementing the Rule

Layer
This chapter explains the necessary steps to use CDM RuleFrame in your application. It
consists of the following Sections (corresponding to the Roadmap in the previous chapter):
• Business Rule Analysis

• Business Rule Design
• Business Rule Generation
Headstart Oracle Designer 6.5 - User Guide Implementing the Rule Layer 11 - 1
Business Rule Analysis
The CDM RuleFrame utilities include a Business Rule Design Transformer. This utility takes
Business Rule Functions, and transforms them into Business Rule Design Definitions.
The Business Rule Design Transformer assumes that the Business Rules have been recorded
in Oracle Designer according to the CDM Standards and Guidelines version 6 (CDM
Advantage 2.0). See the CDM Standards and Guidelines Library, Volume 1: Requirements
Analysis, Chapter ‘Business Rule Modeling’ for more information on how to model business
rules. See the Headstart Demo Application for examples of how to record Business Rule
analysis information.
To get the most out of the Business Rule Design Transformer, the Business Rule Functions
should be recorded as follows:
1. Create process events for entities
Run the Headstart Utility ‘Maintain default events for entities’ that creates all possible
process events for all entities, attributes and relationships. You can run it once for all entities.
If you add or remove entities, attributes or relationships you can run the utility again. The
utility will create process events with the following property values:
• The Type is Change

• The On Condition property is either CREATE, UPDATE, or DELETE
• The entity on which the event is triggered is specified in the Entity property
• If the event is triggered by a change in a certain attribute, then this attribute is

specified in the attribute property.
11 - 2 Implementing the Rule Layer Headstart Oracle Designer 6.5 - User Guide
• If the event is triggered by a change in a relationship, then the relationship name and
other end entity is given in the description using the following convention:
<RL>[relationship name]->[other end entity name]</RL>
Attention: The same process event cannot trigger both a change in a and a
change in an attribute, they each need a separate event.
Record your business rules in Oracle Designer as described in the CDM Standards and
Guidelines Library. Use native properties for structured recording wherever possible, and use
the Business Function object for the others. Apply the naming convention as described in
standard OMS-60005, otherwise the Business Rule Design Transformer will not recognize
the rule.
Recording a Business Rule as a Function

Oracle Designer does not provide a structured object for recording business rules during the
analysis phase of a project. Some business rules can be recorded in the structured elements
associated with the data model. If it is possible to record a business rule in one of these
structured elements, do so.
• attribute definition properties

• relationships
• unique identifiers
CDM recommends that, if no structured element exists for recording a business rule, you
should record the business rule using the Business Function object. This means that the
Oracle Designer repository will now contain two kinds of business functions:
• presentation/batch functions
• business rule functions
Create a separate hierarchy for each of these two types of function. Organize the business
rule function hierarchy per entity. Use common functions to record Inter-Entity rules under
both entities. Place Change Event rules under the entity that triggers the rule, not the entity
that is insert, updated or deleted.
What to Record
The following items discuss properties of the Function definition that you should use when
recording business rule functions.
• Label - In order for the Business Rule Transformer to work correctly, business rule
functions must be named according to the following convention.
BR_[entity short name]###([decomposition id])_[type abbreviation]
where…
• the entity is the ‘main’ entity triggering the rule

• decomposition id is A, B, C, etc.
• ### is a 3-digit sequence number making the rule unique within the entity,
regardless of the decomposition id or rule type
• the rule type abbreviations that apply are as follows. (See Business Rule
Classification Scheme below for details):
Rule Type Abbreviations

ATT Other Attribute Rules
TPL Tuple Rules
ENT Other Entity Rules
RER Restricted Entity Relationship Rules
IER Other Inter-Entity Rules
CRE Create Rules
TRS Attribute Transition Rules
UPD Other Update Rules
MOD Modify Rules
RDL Relationship Delete Rules
DEL Other Delete Rules
DFT Default Rules
CEV Other Change Event Rules
CEW Change Event Rules without DML
AUT Authorization Rules
• Short Definition - This will be used as the default error message text for this business
rule.
• Description - This property is optional and can be used to record thoughts about
implementation of this rule.
Business Rule Classification Scheme

There are five main classes of business rules:
• constraint rules
• static
• dynamic
• change event rules
• with data manipulation
• without data manipulation
• authorization rules
Constraint rules define restrictions to the state of data (static) or the change of the data
(dynamic)
Change event rules define automatic actions to be taken after the state of the data has
changed. The automatic action can either be another change in data (insert, update, delete) or
an action outside the database such as sending an e-mail or printing a report.
Authorization rules define which business unit, person or group of people is able to perform
a function or manipulate (a set of) data.
Strangely enough, making the distinction between static constraints and change events is not
always straight forward. This is because some rules can be implemented as both static
constraints and change events. In other words, for the same rule, you can either display an
error when the data is invalid (static constraint) or you can automatically correct invalid data
(change event). You should always discuss with the users how they want such a rule
implemented.
Making the distinction between static and dynamic constraints is easier.
• A dynamic constraint must be true at the moment of the data operation (insert, update,
delete), but does not have to be true later.
• Static constraints must always be true. You can check a static constraint when
creating or modify data, but you can also check it a week later and it must still be true.
Dynamic Rule Example: ‘If a project is complete, you may not create a new project
assignment.’ This only has to be true at the moment the insert is done on the project
assignment table. A week or a year later, the project assignment still exists, even though the
project may have long since completed.
Static Rule Example: ‘A project assignment date range must fall within the project date
range.’ You also want to check this rule while inserting a new project assignment, but it must
still be true a week or a year later.
Generally, if you must use any of the following items in order to write your business rule, the
rule is Dynamic.
• inserting, updating, deleting

• old values
• sysdate, user
Static Data Constraint Rules
Sub-class Rule Recording
Attribute Rules Simple Attribute Different Attribute

- rule involves only one Properties
attribute Domain Domain object
Other Attribute Function Description
Tuple Rules Tuple Function Description
- rule involves one or more
attributes in the same row
Entity Rules Unique Identifier Unique Identifier
- rule involves attributes of Other Entity Function Description
more than one row in the same
entity
Inter-Entity Rules Relationship Entity Relationship
- rule involves attributes Restricted Relations Function Description
and/or relationships from Other Inter-entity Function Description
different entities
Attribute Rules
Simple Attribute Rules
These rules have a dedicated properties in the Attribute Definition.
• format
• maximum length
• decimal places
• required
• uppercase
Examples
Department code must be numeric.
Salary has a maximum length of 8.
Department name must be in uppercase.
Each employee must have a name.
Recording
Use the format, maximum length, decimal places, and optional? properties of the attribute.
Use the derivation property to record the word UPPERCASE.
Unfortunately, the database design transformer does not use the derivation field. This means
that after you have transformed the entities to tables, you must manually set the uppercase
indicator for each column that maps to an uppercase attribute.
Domain Rules
A domain rule defines attribute allowable values for an attribute. It either enumerates all
allowable values (enumerated domain), or restricts the allowable values by specifying ranges
of lowest and highest value allowed (range domain).
Examples
Employee job must be ‘CLERK’, ‘SALES REP’, or ‘MANAGER’. (enumerated)
Employee salary must be between 30,000 and 300,000. (range)
Recording
Record these rules using the domain object in Oracle Designer. Associate the domain with
one or more attributes.
Other Attribute Rules (ATT)
These include all other allowable value rules for an attribute. In some cases the attribute
value depends on the value of a constant.
Examples
Employee salary must be multiple of 1000.
Employee bank account number must fulfill conditions of ‘eleven-test’.
User name must contain at least 5 characters.
Postal code consists of 4 digits and two letters.
Recording
Use the Business Rule Function to record this rule.
Tuple Rules (TPL)
Tuple rules define allowable values for attributes which depend on the value of other
attribute(s) within the same entity occurrence (tuple).
Examples
Employee exit date must be later than employee hire date.
An employee with job ‘SALESMAN’ must have a value for commission.
Recording
Use the Business Rule Function object to record an entity rule.
Entity Rules
Entity rules define allowable values for attributes and combination of attributes which depend
on the values of attributes of other occurrences of the same entity.
Unique Identifier Rules
An entity unique identifier rule defines which (combination of) attribute(s) and relationship(s)
can be used to identify an occurrence of the entity.
Examples
Each employee is uniquely identified by an employee number.
Recording
The Oracle Designer repository provides a separate element for structured recording of
unique identifier entries. An entity can have multiple unique identifiers, each consisting of
one or more unique identifier entries: an attribute or relationship.
Other Entity Rules (ENT)
Other entity rules consist of all allowable value rules which you can define within an entity.
Examples
No more than 20 departments are allowed.
Recording
Use the Business Rule Function object to record an entity rule.
Attention: When using self referencing entities be aware that if you use
the relationship in your rule this will result in an inter entity rule not an
entity rule.
Inter-Entity Rules
Inter-entity rules define attribute allowable values which depend on the values of attributes in
one or more occurrences of another entity. They also define the relationships between
entities, and their conditions.
Relationship Rules
An entity relationship rule defines how an entity relates to another entity. Three main types of
relationships are recognized:
• one-to-one relationship (1:1, drawn as ------------)
• one-to-many relationship (1:m, drawn as ----------<)
• many-to-many relationship (m:n, drawn as >-----------<)
Each relationship end can be set to optional or mandatory.
Examples
Each employee can work for one and only one department. (optional)
Each employee must work for one and only one department. (mandatory)
Recording
The Oracle Designer repository provides the Entity Relationship Diagrammer with graphical
creation and representation of entity relationship rules. You can also use the Repository
Object Navigator (RON), to create a relationship between two entities.

Restricted Relationship Rules (RER)
A restricted relationship rule restricts the set of entity occurrences to which an entity
relationship can refer.

Example
An employee can only be managed by an employee with job ‘MANAGER’.
Recording
Use the Business Rule Function to record this type of rule.
Other Inter-Entity Rules (IER)
Other inter-entity rules consist of all other static rules that exist between entities.
Examples
The project assignment dates (start and end date) of a project should lie between the project
dates (start and end date).
The project assignment dates (start and end date) of a project should lie between the project
dates (start and end date).
Recording
Dynamic Data Constraint Rules
Create Create Rule Function Description

- rule must be true when
record is inserted
Update Attribute Transition Function Description
record is updated Transferable Transferable Property
Relationship
Other Update Function Description
Modify Modify Rules Function Description
record is inserted, updated
and/or deleted
Delete Relationship Relationship Notes
- rule must be true when Other Delete Function Description
record is deleted
Create Rules (CRE)
A create rule restricts the creation of an occurrence of entity.
Example
You may not create a project assignment for a project that is already finished (end date in the
past).
Recording
Update Rules
An update rule defines conditions for the update of an attribute, entity, or relationship.
Attribute Transition Rules (ATS)
Transition rules define attribute allowable values that depend only on the previous value of
the same attribute.
Example
Allowed transitions for civil state of employee
unmarried -> married

married -> divorced
divorced -> married
married -> widow
widow -> married
Recording
Transferable Relationship Rule
For every relationship the transferability must be. In other words whether it is allowed to
transfer a child to another parent.
Example
You may not transfer on order item from one order to another.
Recording
Use the transferable property of a relationship to record the transferability rule.
Other Update Rules (UPD)
Other update rules consist of all other update rules that can exist.
Example
You may not update the standard rate of an employee if the exit date is in the past.
Recording
Modify Rules (MOD)
Modify rules are a combination of a create, update or delete rule. This combination makes it
possible to specify one rule that is valid for creating, updating and or deleting.
Example
You may not create or update a Project Assignment if the related Project is already finished
(end date in the past)
Recording
Delete Rules
A delete rule defines conditions for the deletion of an entity or relationship.

Relationship Delete Rule
The Relationship Delete Rule is part of the relationship rule.
Example
Suppose you have a rule which states that an employee must be assigned to a department
(mandatory relationship rule). You have to decide what will happen to the employees if you
delete a department. Possible options are as follows:
• restricted — deletion of parent should be prevented when children exist

• cascade — all children of the parent are deleted also (this is a change event rule, see in
following section)
• nullify — the children concerned no longer have a parent
In most cases you will use the restricted relationship delete rule because cascade is rather
rigorous. Nullifying is almost never used because it cannot be implemented for mandatory
relationships.
Recording
For the relationship delete rule the default is restricted and nothing needs to be recorded.
If a cascade delete is desired write the word CASCADE in the relationship notes to indicate
the cascade implementation of this rule. Unfortunately, the database design transformer does
not transform the CASCADE word in the notes. This means that you have to indicate this
yourself at design level.
Other Delete Rules (DEL)
Other delete rules consist of all other allowable delete rules.
Examples
You may not delete a file when the end date of that file is not in the past.
You may not delete customer when the related projects are not finished (end date in past). (in
addition to a cascade delete rule.
Recording
Change Event Rules with DML
Default Value Rules Default Property/

Function Description
Other Change Event Function Description
Rule
Default Rules (DFT)
A default rule defines the value of an attribute that will be automatically populated when an
occurrence of an entity is created and no value is given.
There is a distinction between a simple and complex default rule. A complex default rule
means that the default value for an attribute has to be derived from other data and/or has to be
derived through calculation.
Examples
When inserting a Customer the default value of the ‘total project limit’ should be set to
‘100000’. (simple)
When inserting a new Employee the default value for the department is the department of his
manager.(complex)
Recording
Record the simple default rule in the default property of the attribute. Record the complex
default rule as a function.
Other Change Event Rules (CEV)
Change event rules can have different levels. At first you will look at real business events.
Later on at system requirements level you will look to more detail system events; for instance
default change event rules or a change event rule that implements a tuple rule.
Examples
When the exit date of an employee is set, create an occurrence in the entity work order (not
shown in the diagram) of the type ‘revoke computer access’, so the IS department will make
sure the employee has no access anymore to the company’s computer systems after the exit
date.
When the salary of an Employee is changed, create an occurrence in the Audit Employee
entity.
Recording
Change Event Rules without DML (CEW)
Change Event without Function Description

DML
A change event rule without DML defines an automated action not involving data
manipulation, that takes place after a data state change. Examples of this type of rule are
sending an e-mail and printing a report.
Example
When the end date of a Project Assignment is changed, the manager of this employee should
be informed with an e-mail.
Recording
Authorization Rules (AUT)
Function Access Business Unit -

Function Association
Vertical Data Business Unit -
Entity/Attribute
Association
Horizontal Data Model as Entity
Function Access Rules
These rules define all of the functions that are accessible for a business unit / agent.
Example
Only employees that are managers have access to the function ‘Change Salary’.
Recording
You can record business units in the Process Modeler or the Repository Object Navigator
(RON) of Oracle Designer. The relationship between the business unit and the functions it
performs can be recorded in the Matrix Diagrammer or the RON.
Vertical Data Access Rules Authorization
These rules define all the entities and attributes that are accessible for a business unit / agent.
Example
Only the project manager has access to the entity ‘Project’.
Recording
Use the Matrix Diagrammer to populate the Business Unit Entity/ Attribute matrix. In
general, you only need to record this rule if the application is to be implemented in a
distributed environment, to get insight into the distribution requirements.
Horizontal Data Access Rules
These rules define the conditions that an entity occurrence must meet in order to be accessible
for a business unit / agent.
Examples
A manager can only update the salary of his own employees.
A manager can only update project information of projects that fall under the department he
manages.
Recording
This type of authorization rule can only be implemented if the entity relationship model
allows you to describe the rule. In the last example above, you have to include a relationship
between the project and the department and need a username in the employee entity to be able
to match the current user with the username of the manager of that specific department.
Horizontal data access rules can be implemented as Dynamic Data Constraint rules, so use the
Business Rule Function to record this type of rule.
For all rules record the process events that trigger your business rule. Use the 'Triggered By'
association of the business rule and link it to the appropriate events created in step 1.
Suggestion: Attribute and Tuple rules do not need events because later on the
Business Rule Design Transformer can derive these from the business rules
data usage. This is also valid for those Entity and Inter Entity rules where the
usage and the triggering event is the same. By the same we mean that a retrieve
usage of an attribute is translated to a create entity event and an update attribute
event.
Record the data usage of all rules. For validation rules this is always 'retrieve', only for
Change Event rules the usage can also be 'create', 'update' or 'delete'.
Suggestion: If the validation of the Business Rule requires the value of the same
Attributes and/or Relationships specified in the triggered by Events, then you can let
the Business Rule Design Transformer create the usages for you by setting the
parameter 'Create Attr/Relationship Usages' to Yes. This is often the situation for
Static Business Rules. In other words you can choose either not to record the events or
not to record the usages for static business rules.
• If the validation of the Business Rule requires the value of an Attribute as input
parameter, then this Attribute must be registered as a Usage for the Business Rule
Function. The Retrieve? property of this Usage must be set to Yes, both at Entity and
at Attribute level.
• If the validation of the Business Rule requires the value of a Relationship as input
parameter, then this Relationship must be registered by
• Including the ‘From’ Entity as usage for the Business Rule Function
• Setting the Retrieve? property of this Entity usage to Yes
• Entering the Relationship in the Comment property of the Entity usage. Use the
following convention:
<RL>[relationship name]->[other end entity name]</RL>
Don’t put any spaces in between the tags, except the spaces that are part of the
relationship name or entity name. It is possible to record multiple relationship
usages for one entity, just by repeating the tags.
Example: To validate the business rule BR_PAS001_ENT, we need to know which
employee is assigned, and for which project the assignment is.
5. Clean up redundant events
After you have specified all your business rules, clean up all redundant events by running the
'Cleanup unused events for entities' Headstart utility.
Business Rule Design
During the business rule design you create Business Rule Design Definitions that form the
basis for the generation of the business rules. A business rule design definition consists of:
• a Table Trigger
• a PL/SQL Definition of type Trigger Logic
both named after the business rule.
There are five utilities that can be used to create Business Rule Design Definitions:
1. Business Rule Design Transformer, transforms Business Rule Functions to

Business Rule Design Definitions (you have to add the validation code manually).
See step 1. Run Business Rule Design Transformer Utility.
2. Maintain Super/Subtype Business Rules, maintains Business Rule Design
Definitions including the code for the rules that follow implicitly from the supertype
implementation of subtype entities. See step 2. Run other Business Rule Utilities.
3. Maintain Static Domain Business Rules, maintains Business Rule Design
Definitions including the code for the rules that follow implicitly from the allowable
values of static domains that are referenced by columns. See step 2. Run other
Business Rule Utilities.
4. Maintain Journalling Business Rules, maintains Business Rule Design Definitions
for the rules including the code that follow from a Journalling Requirements
Definition (a dedicated PL/SQL Definition). See step 2. Run other Business Rule
Utilities.
5. Create Business Rule Design Definition, to add individual Business Rules. See
step 3. Create additional rules using Business Rule Design Definition Utility.
All the above utilities will also create a message in the Headstart Message tables if the
Business Rule did not have a message yet.
You can modify a Business Rule Design Definition directly in Oracle Designer. See steps 4
and 5 in this chapter.
Attention: Note that if a Business Rule is triggered by events in more than one
table, you need one Business Rule Design Definition per triggering table. The
Business Rule Design Definitions are used as input for the utility Create CAPI
Definition.
1. Run Business Rule Design Transformer Utility
Run the Headstart Utility 'Business Rule Design Transformer'. This utility creates Business
Rule Design Definitions. Remember that for each triggering entity a rule design definition is
made. That means that one rule can lead to more than one rule design definition. The
transformer links the PL/SQL Definition to the business rule function.
Attention: Run the Database Design Transformer before you run the Business
Rule Design Transformer. The Business Rule Design Transformer does not
create rules that relate to entities that have not yet been mapped to tables. It also
skips events and usages for attributes/relationships that do not have a
corresponding column or foreign key.
2. Run other Business Rule Utilities
Run the following Headstart Utilities
• Create Domains for Discriminator Columns

• Create Default Error Messages for Constraints
• Maintain Super/Subtype Business Rules
• Maintain Static Domain Business Rules
• Maintain Journalling Business Rules (make sure that you also run the Data Layer
utility Maintain journal tables)
• Set unique key constraint components as descriptor columns
These utilities either prepare the enforcement of certain rule patterns in CDM RuleFrame, or
they create business rule design definitions that also include the code for the specified rule
patterns (so you don’t have to write any validation code yourself for these patterns).
3. Create additional rules using Business Rule Design Definition Utility
The Business Rule Design Transformer cannot handle rules that include self referencing
entities, because it is not allowed to record the usage of the same entity twice. You can use
the Headstart Utility 'Create Business Rule Design Definition' to add the rule design
definition that is missing.
If you did not specify your rules at analysis level you can use this utility to create the business
rule design definitions.
4. Check the triggering events for each business rule
In this step you check if all triggering conditions are correct. An example of the Database
Trigger part of a Business Rule Design Transformer is shown below.
Note that the Trigger When Condition refers to :new.job, which is not recommended unless
you repeat the condition in the validation code (see the Section Trigger When Condition for
details).
Complete?
The Complete? property is set to No, to ensure that the trigger will not be generated to the
database as a table trigger. It is not a real database trigger, but it is part of a Business Rule
Design Definition that must be included in the CAPI package.
Enabled?
Enabled? is set to Yes. Set it to No if you do not want to include the business rule in the
CAPI (because it is currently not valid).
Insert? / Update? / Delete?

Depending on the events for the business rule the these properties are to specify on which
events the business rule must be checked.
Trigger Column Usages

If Update? = Yes, use the Trigger Column usages to further specify which column updates
must trigger the rule. The rule will be triggered if that column actually changes its value.
Trigger When Condition
Use the When condition to further detail the events that trigger the rule. The When condition
must be a boolean expression in which you can use the following constructs:
• :new.<column name> and :old.<column name> for any column in the table that the
Database Trigger belongs to
• inserting, updating and deleting (boolean values)
• user and sysdate
Attention: In this expression, you should not access any table data except by
the :new.[column name] or :old.[column name] construction, nor should any
procedures/functions be called that access table data.
Warning: If you use :new.[column name] in the When Condition, repeat the
condition in the Rule Validation code. You can only omit that if you are certain
that the new value can not change anymore in the same transaction. Otherwise
you might get an error message even though the Change Event corrected the
situation. It is safer to use just the :old.[column name] construction.
Example of what might go wrong: Business Rule 1 has when condition

:new.column1 = ‘Y’ and :new.column2 = ‘N’, and the validation code always
returns false. An update is performed with column1 = Y and column2 = N, the
when condition applies, so Rule 1 is placed on the rule stack. The same update
triggers Business Rule 2, a change event, which is also put on the stack. Now
the transaction closes, and first the change events are executed. Business Rule 2
updates column2 to Y, so now Rule 1 is not violated anymore. But after the
change events the constraints are checked, and Rule 1 was already on the stack.
The validation code returns false, so an error is reported, even though the rule is
not violated in the end!
Attention: If you used the Business Rule Design Transformer for rules that are
triggered by a subtype entity, the corresponding Business Rule Design
Definition will have a when condition to check if the row is of the right
subtype. This assumes that the discriminator column is not updateable. If your
discriminator column is updateable (change of subtype is allowed), then you
will probably have to add the discriminator column as triggering column and
change the when condition at the design level.
The Not_On_Stack_Yet service
Some business rules need to be performed only once, even though they were triggered by
more than one row. By calling the Not_On_Stack_Yet service from the Trigger When
Condition, you can make this happen.
Example BR_DEP001_IER - The sum of the salaries in each department may

not exceed 1 million.
Suppose that 5 new employees are added to the same department, during the same
transaction. This would mean that for each employee, the above business rule must be
validated. For this type of rule, however, it would have been sufficient to perform the rule
only once in this transaction.
Performing the rule for each employee is not only bad for performance, but when violated, it
will also have the consequence that the message handler shows 5 messages at the end of the
transaction, all saying approximately the same thing!
The above problem only applies to certain types of business rules. Most of the time the
validation of such a rule includes an 'aggregate' or group function like count or sum (for
instance they use the CAPI Service called Aggregate_Value).
To avoid multiple checks where only one is needed, you must specify to CDM RuleFrame
that the 5 occurrences of the business rule are really the same, even though they were
triggered by different rows. You must specify which values should be part of the ‘unique key’
for the business rule.
You can do this in the When Condition of the Business Rule, by calling
qms_transaction_mgt.not_on_stack_yet. The signature of this function is:
function not_on_stack_yet
( p_br_name in varchar2
, p_uk_comp1 in varchar2 default null
)
return boolean;
An example of a When Condition illustrates this:
Example :new.salary > :old.salary

and
qms_transaction_mgt.not_on_stack_yet
( p_br_name => 'BR_DEP001_IER'
, p_uk_comp1 => to_char(:new.dep_id)
)
This means that the Business Rule that has this When Condition, is only enforced (checked) if
the new salary is higher than the old and if there is not a rule with name ‘BR_DEP001_IER’
on the Transaction Management Stack yet, which has as its first UK component the same
Department Id. So, this rule is enforced only once, even if there were 5 rows triggering this
rule but all 5 had the same Department Id.
Note that the Department Id was used as a unique key component, but had to be converted to
character because the function parameters are of datatype varchar2.
Warning: If you want to use an optional column as a Unique Key Component,

use the nvl function around it. If one of the UK Components is null, it is ignored
by the Transaction Management package.
Warning: You should not use the service Not_On_Stack_Yet if the validation
code of the business rule relies on old values of the triggering row, unless the
value is the same for all rows that have the same UK components. The reason is
that the rule could also be validated for another row that has the same UK
components, and it should then have the same result.
Suggestion: If you have an Aggregate Rule that can be triggered from more than
one CAPI, you need more than one Business Rule Design Definition, each with
its own name. You can still ensure that they are treated as one ‘logical’ business
rule, by adding multiple calls to not_on_stack_yet in your when condition:
( 'BR_DEP001A_IER'
, to_char(:new.dep_id)
)
and
( 'BR_DEP001B_IER'
, to_char(:new.dep_id)
)
5. Code your rule in the related PL/SQL Definition

The most important part of the rule is the validation code of the rule it self. If you have used
the Headstart Utility 'Business Rule Design Transformer' you only need to do the coding of
the rule in the PL/SQL block of the PL/SQL definition. Use the standard and custom services
of the Custom API to make your code compact, understandable and resilient to change.
Notes
The Notes property contains the type of the business rule and the message code, both
enclosed between HTML-like tags <TY>…</TY> and <MG>…</MG>, respectively. If it is
a subtype, static domain or journaling business rule, it will also contain a tag further
identifying the kind of rule. Don’t remove these tags because that’s how the Headstart
Utilities recognize the Business Rules.
Rule Type Record the type of the business rule in the Notes between the tags <TY> and </TY>.
The allowable values for the rule type are (case insensitive):
• Static Data Constraint
• Dynamic Data Constraint
• Change Event with DML
• Change Event without DML
Reference: For explanation of these types, see the CDM Standards &
Guidelines Library, volume 1, chapter Business Rule Modeling.
Message Code Record the violation message code in the Notes between the tags <MG> and </MG>.
The message code must correspond to a message in the Headstart Message tables
(available through the Headstart Foundation Application). The message will be
raised when the Business Rule is violated.
Suggestion: Some business rules should only give a warning when they are
violated, instead of an error. If that is the case, you can go to the Headstart
Foundation Application and set the severity of the relevant message to
Warning. The default severity is Error.
Attention: The message text should contain at least one parameter <p1>, which
will be replaced with the display label of the row that violated the rule. If this is
omitted, it will be difficult to tell which row generated the error message when
all errors of the transaction are shown.
Attention: For Change Event business rules (both with DML and without
DML), the message code is never used because all errors are handled normally
either through the CAPI or as server side errors. However, the message code
must still exist in order for the utilities to work properly. For this purpose you
can use the ‘dummy’ message code ‘QMS-00151’.
PL/SQL Block
The PL/SQL Block contains a comment block with sections Purpose, Remarks and Revision
History. You can change the Purpose and the Remarks. You can also add new Revision
History Records (on top), in the same structure that was used by the utility. Don’t change the
heading or layout of the Revision History, and don’t change the end-of-comment marker
(*******/).
Enter code that sets l_rule_ok to false when the Business Rule is violated. New column
values of the triggering row can be referred to as p_[column name] (if specified in the
Arguments of the PL/SQL Definition). Old column values of the triggering row can be
referred to as p_old_[column name] (if specified in the Arguments of the PL/SQL
Definition).
Example -- Shipments are not allowed to be delayed

l_rule_ok := p_date_shipped <= p_old_date_shipped;
In the PL/SQL Block program code you can use the Standard CAPI Services (see section
Using Standard CAPI Services below) and any Custom CAPI Services you defined.
Attention: If you want to do DML within the code, don’t use direct insert,
update or delete statements but use the TAPI DML procedures (ins, upd, del)
instead. This way you don’t run the risk of bypassing the Business Rules that
apply.
Using Standard CAPI Services

Each CAPI contains (amongst other program units) some important Standard Services, which
can be used in the validation code of the Business Rules. These services are described below
along with information about how to influence the composition of the service.
Exists_Row
Use Exists_Row in the validation code of your business rules when violation of the rule
depends on the existence of a given row in a given table. You pass in the query criteria via
the named input parameters.
Example -- check if there is a department in France

l_rule_ok := hsd_dep_capi.exists_row(p_location => 'FRANCE');
You can also check for a row in the same table, with a Primary Key different from the current
row.
Example -- check if another employee exists with the same manager

l_rule_ok := hsd_emp_capi.exists_row
( p_not_id => p_id
, p_emp_id => p_emp_id
);
This service allows you to easily check if a row exists which meets the requested query
criteria. The service will have one named parameter for each column that…
• is in a Primary, Unique or Foreign Key
• is a discriminator column for subtypes
• has an enumerated domain.
Each time the CAPI utility is run, the columns that satisfy one of the above criteria will get
the tag <EXISTS_ROW> in their Notes.
The service will have one ‘not’ parameter for each column in the Primary Key.
You can add additional parameters by putting the literal text <EXISTS_ROW> in the Notes
property of the column.
Attention: If a column originally qualified for automatic addition of the tag

<EXISTS_ROW>, but because of changes in the Server Model the column now
no longer qualifies, then the tag will remain in the Notes until you delete it
manually. In this way, existing code that uses this column parameter of
exists_row will not become invalid.
Exists_Row - Dynamic
If you have a specific condition for the exists_row service, which can not be specified
through the provided parameters (not even by adding new column parameters), you can also
use the dynamic version of exists_row.
This overloaded function has a parameter called p_where which expects a free text where
clause, and one or more parameters p_not_[PK column name] to exclude a certain row.
You can specify anything you like in this where clause, if you adhere to the following rules:
• don’t include the word where itself

• if you want to include a single quote inside the where clause, you must supply it as
two single quotes
• only refer to column names of the table that the CAPI is related to
Example -- there must be no other row with a later end date
l_rule_ok := not hsd_ord_capi.exists_row
( p_where => 'end_date > to_date('''
|| to_char
( p_end_date
, 'DDMMYYYY'
)
|| ''' ,''DDMMYYYY'')'
, p_not_id => p_ord_id
);
Aggregate_Value
Use Aggregate_Value to get the COUNT, SUM, MIN, MAX or AVG (average) of a column
of a table.
Except for COUNT, the specified column must be a NUMBER column. If you use COUNT,
it will count the column you specify. So if you want to count the total number of records,
pass in a mandatory column. You pass in the query criteria via the named input parameters.
Example -- get the total salary of this department

l_salary_total := hsd_emp_capi.aggregate_value
( p_aggregate_function => 'SUM'
, p_aggregate_column => 'SALARY'
, p_dep_id => p_id
);
This service allows you to easily determine the count, sum etc. of all rows which meet the
query criteria. The service will have one named parameter for each column that…
• is in a Primary, Unique or Foreign Key
• is a discriminator column for subtypes
• has an enumerated domain.
Each time the CAPI utility is run, the columns that satisfy one of the above criteria will get
the tag <AGGREGATE_VALUE> in their Notes.
The service will have one ‘not’ parameter for each column in the Primary Key.
You can add additional parameters by putting the literal text <AGGREGATE_VALUE> in
the Notes property of the column.
Attention: If a column originally qualified for automatic addition of the tag

<AGGREGATE_VALUE>, but because of changes in the Server Model the
column now no longer qualifies, then the tag will remain in the Notes until you
delete it manually. In this way, existing code that uses this column parameter of
aggregate_value will not become invalid.
Attention: Denormalizations that do not involve aggregate functions (sum,
count, etc.) must be added to the TAPI (not the CAPI) using the mechanism
provided by Oracle Designer. Denormalizations that do involve aggregate
functions should be added to the CAPI in the form of a Business Rule of type
Change Event with DML, as these rules will be performed at the end of the
transaction.
Get_Char_Value / Get_Num_Value / Get_Date_Value
These services can be used to get the most recent value of any column in any row of the table,
given the Primary Key value(s) of the desired row. It will use cached rows of the CAPI as
much as possible.
Use get_char_value to get the value of a character column, get_num_value for number
columns and get_date_value for date columns.
Example l_emp_job := hsd_emp_capi.get_char_value

( p_column_name => 'JOB'
, p_id => p_emp_id
);
Suggestion: If you do multiple calls to get_char_value, get_num_value or

get_date_value for the same primary key, without any DML operations in
between the calls, specify p_same_record => true for the second and
further calls (even if first call was get_char_value and second call
get_num_value). This way the CAPI Service will use the cached row of the first
call and will not check the database again, to gain performance.
Display_Label
Use Display_Label when you want to give a message to the end user and want to refer to a
certain row of the table.
Example qms$errors.show_message
( p_mesg => 'HSD-00328'
, p_param0 => hsd_emp_capi.display_label(p_id => l_emp_id)
, p_rftf => false
);
Attention: Note that p_rftf (raise form trigger failure) is false. If the message
is an Error, and the call to show_message was made during an open transaction,
the message will be postponed until the transaction is closed and will be shown
with all the other errors and warnings of the transaction.
If you want to see the message immediately, set p_rftf to true.
The Display_Label service will use the descriptor columns of the table to create a meaningful
display label to identify a row to the end user. This service is always used for parameter <p1>
of the Business Rule violation messages.
You can include columns by giving a value to the Descriptor Sequence property. If no
descriptor columns are found, it uses the Primary Key and Unique Key columns.
Trace
Use Trace for debug messages, which you can view through the Headstart Debug Monitor.
Trace is identical to qms$errors.show_debug_info, except that it prefixes your message with
the schema name and the CAPI package name.
Reference: For more information about activating the debug mode and using
the Headstart Debug Monitor, see chapter ‘Troubleshooting’ in Part V
‘Presentation Layer’.
Creating and Using Custom CAPI Service Definitions

A Custom CAPI Service is a procedure or function that will be generated into the CAPI
package, that can be used in the program code of the Business Rule implementations.
Suggested naming convention:
CS_[table alias]_[logical name].
There are a number of reasons you want to create custom services:
• reuse of code, you may want to create a custom service that is used by more than one
business rule or even used by the front end.
• encapsulation, rather than adding code in component A that retrieves information of
another component B you want to add that code as a service in component B and
request that service from component A. This makes your code more resilient to
change.
• information hiding, hides the complexity of a component by communicating through
services on a need to know bases.
The Headstart Utility 'Create Custom CAPI Service Definition' allows you to create a design-
level definition of a Custom CAPI Service in Oracle Designer. This is used as input for the
utility Create CAPI Definition.
You can modify the Custom CAPI Service Definition directly in Oracle Designer. How to do
this is described in this section. The Custom Service is stored in a PL/SQL Function or
Procedure Definition.
Type
Set the Type property to either Procedure or Function.
Return Type
If it is a Function, also specify the Return Type property.
Scope
If the Custom Service must also be available for Business Rules of other tables, set the Scope
property to Public. If the Scope is Private, it will only be available inside its own CAPI
package.
WNDS? / WNPS? / RNDS? / RNPS ?

If the Scope is Public, and you want to restrict the references of the Custom Service (so that it
can be used in SQL expressions for example), set the relevant restriction property to Yes.
The Restrict References settings are ignored if the Scope is Private.
Suggestion: If your Custom Service has only the WNDS restriction, you can
still use the standard exception handler with qms$errors.unhandled_exception,
because that procedure also has the WNDS restriction.
PL/SQL Block
The PL/SQL Block contains a comment block with sections Purpose, Remarks and Revision
History. You can change the Purpose and the Remarks. You can also add new Revision
History Records (on top), in the same structure that was used by the utility. Don’t change the
heading or layout of the Revision History, and don’t change the end-of-comment marker
(*******/).
Arguments
Add or modify the Arguments of the PL/SQL Definition and use them in your program code
of the CAPI Custom Service. The arguments can have any name and can be defined through
either a Datatype, a Domain, a Column, or a Table. When it is defined through a Datatype,
you can add a Default Value. Use the Input Output property to specify whether it’s an input
parameter, an output parameter, or both.
Program Data
The link to the table in whose CAPI the custom service will be included, is registered through
a dummy Program Datum called ‘CAPI Custom Service’. Note that these Program Data can
only be modified in the Repository Object
Navigator (RON).
Examples of Using a Custom Service

Some change event rules are best implemented using a Derivation Expression of type
Function Call. Following the principle of encapsulation, the function you are calling should
be a Custom Service in the CAPI of the relevant table. In the following example Derivation
Expression, GET_TOTAL_PRJ_LIMIT is a Custom Service of the OMS_CTR_CAPI.
Attention: Due to a limitation of the TAPI-generator (call it a bug if you want

to) the TAPI does not set the cg$ind value for columns that are derived using a
Derivation Expression. Because of this, CDM RuleFrame does not recognize
that such a column has been changed and does not put rules triggered by that
column on the stack. To avoid this problem, add a parameter (modify) to the
Custom Service that is called in the Derivation Expression.
Another example shows how a Custom Service can be used for information hiding and reuse
of code.
Example In a form we want to color so-called ‘problem orders’ red, and

there is a business rule that a customer can not place any new
orders when he already has a ‘problem order’.
In this case you can create a Custom Service called CS_ORD_IS_PROBLEM, that receives
as input an order id and returns true if that order is a ‘problem order’. This service can then be
used both by the form, to color the order red, and by the business rule validation code, to
determine if a customer can place a new order. They don’t need to know when an order is
defined as a ‘problem order’, and when the definition of problem order changes, you only
need to modify the custom service.
For Inter-Entity Rules, it is sometimes best to put the actual validation code in a different
CAPI than the one where the business rule is added. In these cases you can use a Custom
CAPI Service.
Example The sum of the salaries in each department may not exceed 1
million.
This rule is about departments, so according to the principle of encapsulation, the logical
place to put the validation code is in the Departments CAPI. But, there is no triggering event
that applies to Departments, only triggers for Employees!
This can be solved by creating a Custom Service in the Departments CAPI, that takes the
department id as input and raises an error message (showing the Department display_label) if
needed.
The program code of this example Custom Service (let’s call it CS_DEP_CHK_TOT_SAL)
would be:
begin
-- if the total salary of this department
-- is larger than 1 million
if hsd_emp_capi.aggregate_value
( p_aggregate_function => 'SUM'
, p_aggregate_column => 'SALARY'
, p_dep_id => p_id
) > 1000000
then
-- give the appropriate error message
qms$errors.show_message
( p_mesg => 'HSD-99999'
, p_param0 => display_label(p_id => p_id)
, p_rftf => false
);
end if;
end;
The HSD-99999 message is for example: ‘The sum of the salaries in department <p1> has
exceeded the limit of 1 million.’ Note that CS_DEP_CHK_TOT_SAL is part of the
Departments CAPI, therefore the call to display_label is to the one in the Departments CAPI.
Attention: Note that in this case it is essential that show_message is called

with p_rftf (raise form trigger failure) set to false. If it was set to true, the error
message would pop up immediately, instead of it being shown with all the other
errors and warnings of the transaction.
In the Employees CAPI, the validation code of the business rule always returns true and just
calls the Custom Service in the Department CAPI:
l_rule_ok boolean := true;

begin
hsd_dep_capi.cs_dep_chk_tot_sal(p_dep_id);
return l_rule_ok;
end;
Only in this way can the error message include the Department display label, while it was
triggered from the Employees CAPI. If the error message was raised by the Employees CAPI,
<p1> would always become the Employee display label.
6. Check arguments of PL/SQL Definition
If you did not record your rule data usage correctly you will notice that you cannot compile
the Custom API. Always check the arguments for completeness, this can save you a lot of
time further on.
Arguments
You can modify the Arguments of the PL/SQL Definitions and use them in your program
code, as long as the argument names are either p_<column name> or p_old_<column name>.
‘<column_name>’ must be a column in the table to which the business rule belongs, and the
Argument definition must reference that particular column in the Column property.
Warning: Don’t use p_old_ arguments for Static Business Rules. Static rules are
included in Validate_All_Static_BR and during execution of
Validate_All_Static_BR, old column values are not available. If you need an old
value, your rule is Dynamic (or a Change Event).
Attention: If the column name is very long (prefixed with p_ or p_old_),

truncate the column name at the end, so that the argument name has 30
characters. The CAPI utility relies on that method.
Business Rule Generation
1. Create Custom API Definition
You can create (or re-create) the Custom API (CAPI) package definition in Oracle Designer
by running the Headstart utility 'Create CAPI Definition' for one or more tables.
The CAPI works together with the Table API (TAPI) from Oracle Designer and the
Transaction Management package (included with Headstart) to provide complete Business
Rule enforcement on the Server. The name of the CAPI is [application code]_[table
alias]_CAPI.
The utility uses the following Designer data for each table:
• the Table Definition with its Columns, its Primary/Unique/Foreign Keys and its Entity
Usages
• the Business Rule Design Definitions
• the Custom Service Definitions
and uses them to create (or replace) a PL/SQL Definition containing the CAPI Package
Definition.
Attention: If you change anything in the above mentioned parts of a Table

Definition, even if it is only the order of the columns, recreate the CAPI and
regenerate both the TAPI and the CAPI (see also the other steps of Business
Rule Generation).
All business rules in the CAPI are enforced at the transaction level. A transaction must be
explicitly opened and closed (see chapter Accessing the Rule Layer). All DML following the
open transaction will cause rules to be added to the rule stack. No rules are actually checked
until the transaction is closed. When the transaction is closed, all rules are evaluated and if an
error occurs, the error message is written to a message stack. After all rules have been
evaluated, if any errors occurred, an application error is raised.
Table API / Trigger Logic

The utility also creates Table API/Trigger Logic for each table selected, depending on the
value of the utility parameter ‘Do you install TAPI Triggers?’. For this reason, it is important
to know if the Table API Triggers are going to be installed in your environment. If they are,
you need user logic in them that will save the old data for use in the CAPI, and that will open
and close the transaction if needed. If there will be no TAPI Triggers installed, you need user
logic in the TAPI package to enforce the TAPI rules that would otherwise only be validated
by the triggers.
If you entered Yes for the parameter ‘Do you install TAPI Triggers?’, the utility will create
the code segments described in table 2-1. If you entered No, the utility will create the code
segments described in table 2-2. The Pre- and Post-<event> logic is included in the generated
Table API package. The Before- and After-<event> logic is included in the TAPI triggers.
Event Code segment
Post-After-Delete-stmt CDM RuleFrame - Close transaction

Post-After-Insert-stmt CDM RuleFrame - Close transaction
Post-After-Update-stmt CDM RuleFrame - Close transaction
Pre-Before-Delete-row CDM RuleFrame - Save old data
Pre-Before-Delete-stmt CDM RuleFrame - Open transaction
Pre-Before-Insert-stmt CDM RuleFrame - Open transaction
Pre-Before-Update-stmt CDM RuleFrame - Open transaction
Post-Delete CDM RuleFrame - Call CAPI
Post-Insert CDM RuleFrame - Call CAPI
Post-Update CDM RuleFrame - Call CAPI
Pre-Delete CDM RuleFrame - Call CAPI
Pre-Insert CDM RuleFrame - Call CAPI
Pre-Update CDM RuleFrame - Call CAPI
Table 2-1: Events created in the Table API/Trigger Logic when you use TAPI Triggers
Event Code segment
Post-Delete CDM RuleFrame - Call CAPI

Post-Insert CDM RuleFrame - Call CAPI
Post-Update CDM RuleFrame - Call CAPI
Pre-Delete CDM RuleFrame - Call CAPI
CDM RuleFrame - Save old data
Pre-Insert CDM RuleFrame - Call CAPI
Pre-Update CDM RuleFrame - Call CAPI
Table 2-2: Events created in the Table API/Trigger Logic when you don’t use TAPI Triggers
CAPI Structure
The CAPI contains the following public program units:
Public procedures
• post_insert, post_update, post_delete (used by TAPI)
• enforce_rule (used by transaction management)
• enable_br, enable_all_br, disable_br, disable_all_br, validate_all_static_br (possibly
used by batch programs)
• optional: (public) Custom Services defined in Designer
Public functions
• One function for each business rule, returns boolean (possibly used by front end)
• display_label, exists_row, aggregate_value, get_char_value, get_num_value,
get_date_value (possibly used by other CAPIs)
• br_enabled, revision (possibly used by batch programs)
• optional: (public) Custom Services defined in Designer
Reference: For more information on the Standard Services for Business Rules
see section Using Standard CAPI Services.
For more information on the Standard Services for Batch Programs see section
Error! Reference source not found..
2. Generate Custom API's using Server Generator
Generate the CAPI for all tables using the Server Generator of Oracle Designer. You can
generate the CAPIs at the same time as you generate the other database objects, such as tables
and views.
Warning: If the Design Editor was open while the CAPI utility was running, the
PL/SQL text of the CAPI package will not show the current content. To fix this,
go to the menu item File => Change Application System and choose the same
Application as before.
3. Generate Table API using Table API Generator
Generate the TAPI package (and if you wish, also the TAPI triggers) for all tables using the
TAPI Generator utility of Oracle Designer.
Warning: If you generate the Table API from Oracle Designer and set the
Target for Generation to File, Designer includes a call to (re)create the
CG$ERRORS package. This call is included at the top of the shell .sql script,
and will look like this:
PROMPT Creating Table API Error Package CG$ERRORS
@ C:\ORANT\cgens72\sql\cdsaper.PKS
@ C:\ORANT\cgens72\sql\cdsaper.PKB
This code should not be performed, as Headstart uses its own version of
CG$ERRORS.
The easiest way to prevent this problem is copying the files cdsaper.pks and
cdsaper.pkb to a safe place, and replacing them at the original location with
files that only contain the following text:
prompt CG$ERRORS is not recreated.
4. Recompile invalid PL/SQL packages
Since the Table API calls the Custom API and vice versa you will always start out with
invalid packages. By using the recompile script (recompl.sql) of Headstart you can easily
recompile these packages. If you still have invalid packages (check with the invalid.sql script)
you have probably made an error in your business rules coding. Go back to step 5. Code your
rule in the related PL/SQL Definition in Business Rule Design.
CHAPTER
12 Accessing the Rule Layer
One of the things you have to decide on, is how you access the Rule Layer. You have the
following options:
• Using View API's (VAPIs)

• Using the Table API Triggers
• Accessing the Table API directly (calling the TAPI DML procedures)
For more information on the concepts of an access layer and these options, see the CDM
Standards and Guidelines Library volume 2, chapter 6. In short you can say:
• For WebServer Generated applications, the only possibility is to access the Table API
directly; for other applications, it is usually easier to use either VAPIs or TAPI
Triggers.
• Compared to TAPI Triggers, using VAPIs has the advantage that the transaction is not
automatically aborted when a declarative constraint is violated.
• Using Business VAPIs has the advantage that you can achieve true data independence,
which hides the complexity of your data model from the front end (and the front end
developers).
• If you create your forms based on tables in Designer, but run them against VAPIs in
the deployment environment, the implementation is more complex. For more
information, see the section Using VAPIs in generated Forms, later in this chapter.
• If you use database replication, it might be preferable not to use triggers, because they
also fire during snapshot refreshments.
If you choose to use VAPIs, Headstart Utilities will help you create these views. This chapter
describes how you can use these utilities. It also discusses some things you need to be aware
of for every front end.
Headstart Oracle Designer 6.5 - User Guide Access the Rule Layer 12 - 1
Using the VAPI
The View API or VAPI allows your applications to act like they are working on Tables, while
in fact they are working on Views with Instead Of triggers. Those triggers redirect the DML
on the View to the Table API and Custom API. Headstart offers ample support for the
creation of the View API. You can either create
• One to One views with instead-of trigger

• Business Views with instead-of trigger on the base table
• Instead-Of trigger for an existing view
At the end of this section you’ll find some additional information about using VAPIs in
generated Oracle Forms applications.
Create View API Definition

The Headstart utility 'Create VAPI Definition' allows you to build default 1:1 VAPIs for the
requested tables.
These views are called <application code>_V_<logical part of table name> and include the
following:
• All columns of specified table

• These columns have the same properties as the table columns they are based upon
• Instead-Of Trigger <application code>_V_<table alias>_IO (with appropriate calls to
TAPI and QMS Transaction Management)
• The Primary Key and the Unique Key constraint(s) of the table
• The Foreign Keys owned by and referring to the table, are mirrored in Foreign Keys
between the new VAPI and other VAPIs (if they already exist)
Create Business View API’s

The Headstart utility 'Create view definition based on table definition' allows you to create a
Business VAPI, with a base table and several lookup tables. By setting a parameter you can
include the Instead Of trigger that calls the Table API of the base table.
If you want to use Business View API’s that are able to do DML on more than one table, you
must manually adapt the Instead Of Trigger in Oracle Designer. After the open_transaction,
copy the code related to inserting/updating/deleting of the default 1:1 VAPI of both tables,
and then do the close_transaction. It might also be necessary to perform record locking in the
Instead-of trigger.
Create Instead of Triggers for Views

The Headstart Utility 'Add Instead-Of Trigger to a View' creates Instead-Of Triggers for
views that you already have. Just choose a view, give the base table and an instead of trigger
is created.
12 - 2 Access the Rule Layer Headstart Oracle Designer 6.5 - User Guide
Note that the created Instead-Of trigger will only perform DML on the specified base table. If
you need it to do DML on multiple tables, you have to modify the Trigger PL/SQL Definition
in Designer.
Attention: If you create a view on a VAPI, and this view does not have any
instead-of triggers, you will be unable to do DML (insert/update/delete)
through this view (you will get an ORA-01732: data manipulation operation not
legal on this view).
To avoid this, use Business VAPIs as much as possible, they might eliminate
the need for views on top of the VAPIs. If you still need views on top of VAPIs
and you want to do DML on them, you will have to create instead-of triggers
for those views as well.
Using VAPIs in generated Forms

When you generate your Oracle Forms application from Oracle Designer, and decide to use
VAPIs, there are some additional actions you need to perform.
• If the column properties or constraints of the underlying tables change, you have to
apply the same changes to the VAPI definition manually (or create your own utility to
do that).
• If you base a Form Module on a Table but intend to have a VAPI of that name in the
runtime environment (so the form actually runs against a VAPI), run the utility ‘Adapt
form modules for VAPI use’ before generating the form. This makes sure that the
form does not expect a rowid where it cannot find it. If you choose this
implementation, you will also run into bug #1541443, Unable to set ‘DML Returning
Value’ property on generated block. The result is a runtime error on these forms. The
only solution is a POST GENERATION MODIFICATION to set the ‘DML Returning
Value’ property to No for each block based on a table but run on a view. For more
information on why you might want to choose this option in spite of these problems,
see the section ‘Accessing the Rule Layer’ in the CDM Standards and Guidelines
Library, volume 2, chapter ‘Implementing Business Rules’.
Attention: Make sure that you set the Validate In property of the foreign keys
to Both (or Client). If you don’t enforce the foreign keys in the form, and a
block based on a VAPI includes server derived items, you can get an ORA-
01403 (no data found) in the POST-INSERT trigger, when the form violates a
foreign key (see bug 1574906).
Runtime Environment
CDM RuleFrame needs to have several Headstart Database Objects installed. If you also use
the Headstart Template Package, this installation can best be done following by performing
the steps described in the chapter ‘Test and Production Environment’. If you don’t use the
Headstart Template Package (you don’t have a Forms front end), you should pick out the
following steps from the chapter ‘Test and Production Environment’:
• Perform the Headstart Deployment Installation (you only need the files that are
installed in [HSD65_HOME]\hst\scripts)
• Perform the Headstart Database Installation
• Check the installation using the list of Headstart Database Objects at the end of the
chapter ‘Test and Production Environment’.
Opening and Closing a Transaction
Apart from installing the right objects in the database (see previous section) and generating
the Table API and Custom API as explained above, CDM RuleFrame needs one final step to
enforce the Business Rules for all data. Each transaction needs to be opened and closed by
calling the QMS Transaction Management mechanism. This should be done by the front end
(e.g. Forms, Java, HTML, PL/SQL batch).
If the front end does not do so, there is a fallback mechanism within the following layers:
1. If you are using the View API access layer (see section Using the VAPI), the VAPI
will open and close the transaction.
This means that a transaction consists of only one VAPI row manipulation (insert,
update or delete). For Business View API’s, one view row manipulation can involve
multiple table row manipulations.
2. If you are not using the VAPI but are using TAPI triggers, they will open and close
the transaction (but remember to move the After-stmt code to the end of the trigger,
see step 3. Generate Table API using Table API Generator of Business Rule
Generation). This means that a transaction consists of only one table manipulation
(insert, update or delete statement).
3. If you are neither using the VAPI nor the TAPI triggers, but access the TAPI DML
procedures directly (for instance by using WebServer Generator or the MAPI), the
CAPI will open and close the transaction.
This means that a transaction consists of only one row manipulation (insert, update
or delete).
With all of the above mechanisms, the best you can achieve is statement level rule
enforcement. However one of the important advantages of CDM RuleFrame is transaction
level rule enforcement. Transaction level rule enforcement can only be achieved if the
front end itself opens and closes the transaction, enclosing a full transaction with possibly
multiple statements.
Performing a Rollback
If you want to perform a rollback during a CDM RuleFrame transaction, it is important that
the transaction is also rolled back (that is, the rule stack and message stack should be cleared,
and the CAPI caches should be reset). This can be achieved by calling
• qms_transaction_mgt.abort_transaction;
This will also perform the SQL rollback statement.
Business Rule Enforcement in the Front End
The CDM Standards & Guidelines recommend enforcing all business rules in the Database
instead of the Front End. Only when user feedback is very important you should also enforce
a rule in the front end.
For attribute and tuple rules, you should first try to enforce the rules using GUI items and
other item properties. If you must code the rule, you can choose between calling the CAPI
rule function (which implies a network round trip to the Database Server) or copying the rule
code in the application (which implies a network round trip to the Application Server). You
must balance the performance impact of the network round trips against the maintenance
effort of duplicate code.
For entity and inter-entity rules, where you have to make a network round trip to the
database anyway, call the public rule function from the CAPI (which has the same name as
the business rule). This avoids duplication of the code and eases maintenance of the rule.
Oracle Forms Applications
Forms generated with the Headstart Template Package will automatically open the transaction
in the Pre-Commit trigger. The Post-Forms-Commit trigger in the form will close the
transaction and, if necessary, open a window to display errors and/or warnings. So you do not
have to do anything extra, Headstart does it for you.
This window (‘Errors and Warnings in this Transaction’) is subclassed from the Headstart
object library in each generated form.
Figure 12-1 Oracle Form showing errors and warnings in the transaction
Warning: If a form directly calls a CAPI program unit (for example a public
CAPI Service or a Business Rule validation function), sometimes the wrong
procedure or function is executed or the Form crashes. This can happen if the
CAPI package specification has changed after the Form has been compiled.
Cause: The Form references the internal sequence number of the program unit
within the package, which now refers to a different program unit.
Solution: Recompile the Form (create a new .fmx file).
Business Rule Enforcement in the Form
Using Client side Check Constraints

For rules that also need to be enforced in the form (see also the section ‘Business Rule
Enforcement in the Front End’), there is the option of calling the relevant CAPI rule function
from a Check Constraint of type Function Call. If you decide to do that, you can use the
utility ‘Maintain Client side Check Constraints’ to easily generate the calls.
Be aware that in this way, you can not include the When Condition of the rule (if there is
one), because you can not code an if-statement around the function call in the check
constraint.
The other thing you need to know, is that the only triggering events will be Insert and Update
of the columns that are passed as parameters to the function call. If the Business Rule has
other triggering events, you can not use a check constraint.
Performing DML When Button Pressed

When adding a button whose WHEN-BUTTON-PRESSED trigger will perform DML, you
must explicitly code the open and close transaction calls as well as the error handling.
Example:
begin
qms_transaction_mgt.open_transaction
( p_trans_opened_by => '<program unit>');
<… your code here …>
qms_transaction_mgt.close_transaction
( p_trans_opened_by => '<program unit>');
:system.message_level := 5;
commit;
:system.message_level := 0;
exception
when form_trigger_failure
then raise;
when others
then
qms$errors.unhandled_exception('<program unit>');
go_block('QMS$TRANS_ERRORS');
qms_transaction_mgt.abort_transaction;
end;
Testing CDM RuleFrame in SQL*Plus
When you are developing business rules, it is often useful to do a quick test in SQL*Plus.
There are a few things you have to be aware of when doing that.
Strange error messages

When your actions in SQL*Plus have violated one or more rules, you will not be able to see
the rule error messages immediately. You’ll see something like:
SQL> update hsd_employees

2 set commission = null;
update hsd_employees
*
ERROR at line 1:
ORA-20998: Transaction Failed
ORA-06512: at "HST65.QMS$ERRORS", line 121
ORA-06512: at "HST65.QMS_TRANSACTION_MGT", line 806
ORA-06512: at "HDEMO65.CG$AUS_HSD_EMPLOYEES", line 100
ORA-04088: error during execution of trigger 'HDEMO65.CG$AUS_HSD_EMPLOYEES'
The important line is ORA-20998: Transaction Failed. When you see that, you know that the
real error messages are on the CDM RuleFrame error stack. You can make them visible by
calling the script messages.sql, which is located at <Headstart Home>\hst\scripts.
SQL> @messages.sql
Error HSD-00213: Employee TURNER; An employee with job SALESMAN must have a
value for Commission.
Error HSD-00213: Employee MARTIN; An employee with job SALESMAN must have a
Error HSD-00213: Employee WARD; An employee with job SALESMAN must have a
Error HSD-00213: Employee ALLEN; An employee with job SALESMAN must have a
PL/SQL procedure successfully completed.
Note that because the exception was raised by a trigger that fired during the update statement,
the update statement did not succeed and its changes were rolled back. So, if you should
commit now, you don’t commit the update but the situation before the update.
SQL> commit;
Commit complete.
Transaction level rules

If you have a true transaction level rule, like ‘An order must have at least one order line’, you
can never insert an order unless an order line is also inserted in the same transaction. If you
want to test this rule in SQL*Plus, and you would just insert in the orders table and then
insert in the order lines table, the first statement would already fail, because by default each
statement is one RuleFrame transaction. You can enlarge the transaction by explicitly opening
and closing it.
SQL> exec qms_transaction_mgt.open_transaction('my test');
Then perform your DML statements (you won’t get any errors yet), and when you’re done,
close the transaction using the same description you used when opening it.
SQL> exec qms_transaction_mgt.close_transaction('my test');
If instead of just ‘PL/SQL procedure completed successfully’, you see the ORA-20998:
Transaction Failed, your transaction has errors.
SQL> exec qms_transaction_mgt.close_transaction('my test');

BEGIN qms_transaction_mgt.close_transaction('my test'); END;
*
ERROR at line 1:
ORA-20998: Transaction Failed
ORA-06512: at "HST65.QMS$ERRORS", line 121
ORA-06512: at "HST65.QMS_TRANSACTION_MGT", line 806
ORA-06512: at line 1
Now, if you should commit even though there were errors, you get the following:
SQL> commit;
commit
*
ERROR at line 1:
ORA-02091: transaction rolled back
ORA-02290: check constraint (HST65.QMS_NEED_TO_CLOSE_TRANSACTION) violated
The close_transaction did not succeed, so the RuleFrame transaction is still open. To avoid
commits while a transaction is still open, a deferred check constraint
(QMS_NEED_TO_CLOSE_TRANSACTION) was created. It is now violated, and the violation of any
deferred constraint automatically causes the database to rollback. If you would not have tried
to commit, the changes would still be present in the database. You could have corrected the
errors and tried to close the transaction again.
Batch Processing with CDM RuleFrame
You can also use CDM RuleFrame in combination with PL/SQL Batch Programs. This
section explains how.
Accessing CDM RuleFrame from PL/SQL
In a batch program, you must explicitly code the open and close transaction calls as follows:
• Open (before any DML takes place):

( p_trans_opened_by => '<program name>'
);
• Close (just before commit):
( p_trans_opened_by => '<program name>'
);
• Rollback (instead of SQL rollback command):
Use a unique program name that is not used by any other sessions running in parallel. When
closing, use the same program name as when you opened the transaction, otherwise it won’t
be closed.
Closing a transaction neither commits or rolls back the transaction. If an error in a transaction
occurs, the transaction management package raises a generic exception
qms$errors.qms$exception, which causes an 'ORA-20998: Transaction Failed'. The batch
program must include an exception handler to trap for this exception.
If a transaction is closed successfully, the calling program must still commit the data. If a
transaction has errors, the calling program must rollback or correct the data and close the
transaction again.
A procedure cg$errors.get_error_messages has been provided to get the contents of the error
stack. For each error it includes the table name and the rowid of the row that caused the error,
so that the batch program can produce an exceptions report, or even correct the errors itself. If
you want a nice text for the error, you can call cg$errors.get_display_string (p_msg_code,
p_msg_text, p_msg_type(=severity)). If you want to abort the transaction, do so after
retrieving the messages.
Example declare
..
l_message_rectype_tbl hil_message.message_tabtype;
l_message_count number := 0;
l_raise_error boolean := false;
..
l_run_number number := <get unique number>;
begin
( p_trans_opened_by => 'Batch ABC, Run '
||to_char(l_run_number)
);
..
.. (do the DML)
..
-- when closing, program name must be exactly the same
-- as when opening
( p_trans_opened_by => 'Batch ABC, Run '
||to_char(l_run_number)
);
commit;
exception
when qms$errors.qms$exception
then
cg$errors.get_error_messages
( l_message_rectype_tbl
, l_message_count
, l_raise_error
);
if l_message_count > 0
then
for i in 1..l_message_count loop
-- now you have access to the error stack:
.. l_message_rectype_tbl(i).msg_code
.. l_message_rectype_tbl(i).msg_text
.. l_message_rectype_tbl(i).severity
.. l_message_rectype_tbl(i).table_name
.. l_message_rectype_tbl(i).table_rowid
..
end loop;
end if; -- l_message_count
-- either correct the changes & close again, or abort
when others
then
..
end;
Standard CAPI Services for Batch Programs

Each CAPI contains a few standard services that are especially useful for batch programs and
SQL scripts.
Enable/Disable Business Rules

The Business Rules that are included in the CAPI are enabled by default, but can be disabled
and enabled again.
You can approach this in two ways.
• Enable all rules (using procedure enable_all_br) and disable individual rules (using
procedure disable_br)
• Disable all rules (using procedure disable_all_br) and then enable individual rules
(using procedure enable_br)
The function br_enabled can be used to check if a business rule is enabled or disabled.
Attention: The enabling and disabling only applies to the current user session.
In a new session all business rules are again enabled by default.
Suggestion: If you need to disable all rules but you don’t have the opportunity
to call disable_all_br during the session (for example in a SQL*Loader
session), you can instead (temporarily) modify the package
qms_transaction_mgt for this schema: in procedure add_business_rule,
comment out the code for the Static and Dynamic constraints. You could leave
the code for the Change Events as is, or also comment that out (whatever you
wish).
Don’t forget to recreate the original version of qms_transaction_mgt
afterwards!
Validate All Static Business Rules

Static Data Constraints are Business Rules that must be valid at all times, regardless of the
operation being performed. This means it is possible to also validate them for existing data.
This can be useful in several situations:
• when introducing a new business rule to a system that already includes data
• when the project phasing requires that data are already entered into the system before
all business rules have been implemented
• when accepting data from an outside source before it is entered into the system
• for performance reasons (see section Performance Issues)
The checking of the Static Constraints can be done using the CAPI procedure
Validate_All_Static_BR. This procedure loops through all rows of the table and validates all
static Business Rules. (It immediately calls the validation functions, and does not put the
rules on the Transaction Management stack). You can also supply the primary key values of
a specific row as parameters. In that case only the requested row is validated.
Validate_All_Static_BR places an error message on the message stack for each violation of a
rule by a certain row. You can check if there were rule violations and retrieve the messages
by performing the script <Headstart Home>\hst\scripts\messages.sql.
Example set serveroutput on size 1000000

declare
begin
hil_message.set_debug_flag(true);
&appcode._&tabalias._capi.validate_all_static_br;
end;
/
@messages
There are two ways to call Validate_All_Static_BR:
• from within a transaction

• outside of a transaction
If you call the procedure from within a transaction (after a call to Open_Transaction has been
made), the errors that are put on the message stack will prevent a successful closing of the
transaction.
If you call the procedure outside of a transaction (at the beginning of a session or after a call
to Close_Transaction), the errors that are put on the message stack will have no influence on
DML operations. As soon as a new transaction is opened, the message stack is cleared.
Performance Issues
CDM RuleFrame is optimized for DML against individual rows, and for small transactions.
All rule checks are saved until the end of the transaction, and then each rule is checked once
for each row. During interactive processing (e.g. forms), this is appropriate. However,
during large batch transactions and during the validate all process, this is an inefficient way to
check business rules.
There are several ways to improve the performance (listed in order of preference).
• Create smaller transactions

• Disable rules that can not be violated
• Use set validations
• Use validate all static
You can also use a combination of these techniques.
Create smaller transactions

If your batch program allows it, this is the best way to enhance the performance. It is faster to
do 100 transactions of 10 records than 1 transaction of 1,000 records.
Disable rules that can not be violated

If you are certain that some of the business rules can never be violated by the batch program,
it is a good idea to disable them before performing the DML. Of course, this requires
thorough testing. Also make sure that the execution of change events can not introduce any
violations of the rules you want to disable.
Use set validations

For many business rules, it is more efficient to write special validation code that checks all
rows of a table at once, instead of one row at a time.
Some examples will help to clarify this.
Example Master - Teams, Detail - Team Members

Business rule: Each team must have one and only one member
designated as the team leader.
The CAPI for Team Members will contain the following rule.
Event = Insert, Update (team_leader_ind)
Code = l_rule_ok := app_tmr_capi.aggregate_value
( 'COUNT'
, p_aggregate_column => 'ID'
, p_tem_id => p_tem_id
, p_team_leader_ind => 'Y'
) = 1;
When Condition = qms_transaction_mgt.not_on_stack_yet
( p_br_name => <Business Rule Name>
, p_uk_comp1 => to_char(:new.tem_id)
)
In CDM RuleFrame, the validation code will be performed for every team that is touched by
the batch program. If the batch program inserts or updates the team leader indicator of team
members of 100 different teams, this results in 100 dynamic SQL statements. Depending on
the total size of the tables, a more efficient way of checking this rule is possible. You really
only need two select statements to determine if this rule is violated by any rows in the table.
...to determine teams without a team lead...
select tem_id
from teams
minus
select tem_id
from team_members
where team_leader_ind = 'Y'
;
...to determine teams with more than one team lead...
select tem_id
from team_members
where team_leader_ind = 'Y'
group by tem_id
having count(*) > 1
;
Example Business Rule: Start Date must be <= End Date
The CAPI will contain the following rule.
Event = Insert, Update (start_date, end_date)

Code = l_rule_ok := start_date <= nvl
( end_date
, start_date
);
In CDM RuleFrame, this rule will be performed for every row that is touched by the batch
program. If the batch program inserts or updates the start or end date of 1,000 rows, the
validation code is performed 1,000 times. This comparison between package variables does
not take long, but if you apply it to a lot of rows the cost adds up. Depending on the total size
of the table, it could be done more efficiently with a single SQL statement.
select id
from table
where start_date > nvl
( end_date
, start_date
);
You can make the set validations even more efficient by restricting the rows you check to
those touched by the batch program. For that, it is necessary that some identification of this
particular batch run is present in the rows. You could add an optional column
BATCH_RUN_ID to every table that is being processed in batch runs, and let the batch
program fill it with a unique run identification each time it performs an insert or update. In
that case you can extend the where clause with
and batch_run_id = <Batch Run id>
If you decide to use these set validations for certain rules, you must disable those rules before
performing the DML, and call the set validations afterwards. Of course, if the SQL statements
return one or more rows, those are rows that violate the rule and they should be processed in
the same way you would process normal CDM RuleFrame rule violations.
If you want the rule violations to be added to the normal CDM RuleFrame error stack, you
can call
qms_transaction_mgt.process_rule_violation
Parameter Type Mode Default?
--------------- -------- ---- --------
P_BR_NAME VARCHAR2 IN Y
P_MSG_CODE VARCHAR2 IN Y
P_DISPLAY_LABEL VARCHAR2 IN Y
P_TABLE_NAME VARCHAR2 IN Y
P_TABLE_ROWID ROWID IN Y
If you use set validations, the structure of your batch program should be as follows.
1. Disable rules that cannot be violated or that are checked in another way.
2. Open the transaction.
3. Do your DML.
4. Close the transaction, handle the ‘Transaction Failed’ exception.
5. Call the set validations.
6. If there were no errors (ignore messages with severity = ‘W’, they are just
warnings), commit.
7. If there were errors, either correct the changes and repeat from step 4 onwards, or
report the errors and abort the transaction.
Use validate all static

Another possibility is to disable all static business rules, and use Validate_All_Static_BR
afterwards.
For large tables, performing Validate_All_Static_BR on the whole table can take a very long
time. It may be better to call the procedure for one row at a time (using the primary key
values as parameters), and then only for the rows that were touched during the batch program.
Violations are automatically reported on the CDM RuleFrame error stack. If you want to use
it to prevent faulty DML, call it after closing the transaction but before committing, and
commit only if there are no errors on the message stack.
WebDB Applications
This section assumes the use of WebDB version 2.2.
To make sure that transactions are opened and closed, and that errors are shown, you have to
replace a few package bodies of the WebDB owner.
First, you should provide the WebDB owner to the Headstart database objects. You can do
this by logging into SQL*Plus as the owner of the Headstart database objects and running the
script <Headstart Home>\hst\scripts\grt_obj.sql. When asked for the application owner
schema, supply the schema name of the WebDB owner.
To install the modified WebDB package bodies, log into SQL*Plus as the WebDB owner,
and run the following scripts from the <Headstart Home>\webdb folder:
• RFstderr.pkb takes care of the messaging, see example below.

• RFmdgen.pkb, takes care of open and close transaction for a master detail form
The RFstderr.pkb script ensures that CDM RuleFrame errors are added to the WebDB error
stack, and displayed in the same way as WebDB errors.
The RFmdgen.pkb script only applies to WebDB master-detail forms. It ensures that DML
actions on the master and the detail table are handled as one transaction. This is important if
you have business rules that involve both tables. (For example: an Order must have at least
one Order Line). If you have existing Master-Detail forms, you should regenerate the
PL/SQL package of the form to ensure the changes are picked up.
The original WebDB package body sources are also included in this folder, in case you want
to revert the changes.
Attention: Warning messages are only displayed if the transaction fails due
to other error messages. If there are no error messages, and the transaction is
successful, the warning messages are not displayed.
Figure 12-2 WebDB Error Page with CDM RuleFrame Errors displayed.
WebServer Generated Applications
For WebServer Generator you do not need to change anything because it will automatically
use the Headstart version of the cg$errors package to display all the errors of the transaction.
Attention: Warning messages are only displayed if the transaction fails due to
other error messages. If there are no error messages, and the transaction is
successful, the warning messages are not displayed.
Figure 12-3 WebServer Generated form showing errors and warnings in transaction
JDeveloper/BC4J Applications
The file <Headstart home>\java\rf_prj.zip contains a JDeveloper 3.1 project (called
CDMRuleFrame) which contains Java classes to use CDM RuleFrame with Business
Components for Java.
What you need to do is the following:
• Use the BC4J wizards as usual to create your BC4J objects (EO's, VO's, AM's) for the
Headstart demo tables.
• Import the CDMRuleFrame project into your JDeveloper workspace and compile it.
• Change the parent class of your Application Module Implementations:
By default, all Application Module classes extend
oracle.jbo.server.ApplicationModuleImpl. To use CDMRuleFrame, they should now
extend oracle.idevcoe.ruleframe.RuleFrameApplicationModuleImpl
• Create a Business Components JSP application (or Business Components Data Form)
as usual (using the wizards) to create the presentation layer on top of BC4J
That's all! The JSP or DAC Form application will automatically display the CDM RuleFrame
errors when you hit the commit button.
Other Front Ends
Make sure that at the beginning of a transaction, the following command is performed:
• qms_transaction_mgt.open_transaction
( p_trans_opened_by => <program name, e.g. 'FRAMEWORK'>
);
Make sure that just before any commit statement, the following command is performed:
• qms_transaction_mgt.close_transaction
( p_trans_opened_by => <program name, e.g. 'FRAMEWORK'>
);
Use a unique program name that is not used by any other sessions running in parallel. When
closing, use the same program name as when you opened the transaction, otherwise it won’t
be closed.
Closing a transaction neither commits or rolls back the transaction. If an error in a transaction
occurs, the transaction management package raises a generic exception
qms$errors.qms$exception, which causes an 'ORA-20998: Transaction Failed'. The front end
must be able to handle this exception.
If a transaction is closed successfully, the calling program must still commit the data. If a
transaction has errors, the calling program must abort or correct the data and close the
transaction again.
If necessary, you can rollback by calling
• qms_transaction_mgt.abort_transaction;
This procedure also calls the database rollback routine.
After the transaction is closed, make sure that any errors and warnings raised by the
Transaction Management package are shown to the end user. Check the CDM RuleFrame
message stack (by calling cg$errors.getErrors). If there were messages on the CDM
RuleFrame stack, show them.
Example code:
• l_message := cg$errors.getErrors;
if l_message is not null
then
… show the errors …
end if;
PART V PRESENTATION LAYER
(blank page)
CHAPTER
13 Getting Started
This chapter begins with a brief overview of the Headstart Template Package architecture.
Next, the steps are detailed which prepare your application for generation with the Headstart
Template Package.
1. Reference the application level named preference sets

2. Blank out language specific command lines
3. Create shortcuts to Headstart objects (optional)
4. Set the Generator Options
5. Create and attach the application library
6. Create and attach the application menu
7. Create a start form for your application
8. Create an html launch document for your application
Next, the chapter outlines a number of iterative development tasks you should perform before
generating your modules.
1. Create Key Constraint Error Messages

2. Generate Change History Columns
3. Generate HTML Help ID’s
4. Create Module Revision Parameter
5. Generate Report Module Parameters
Finally, there is a brief discussion about using Module Libraries in your applications.
This chapter assumes you have already performed the following steps.
Headstart Oracle Designer 6.5 - User Guide Getting Started 13 - 1

• Install the Headstart Template Package as documented in the installation guide. This
includes:
• installing the Headstart files in the file system
• creating the Headstart environment variables
• creating the registry settings which instruct Oracle Designer to use the Headstart
renamed versions of the OFG libraries
• installing the Headstart database objects
• Grant the development team access to the Headstart database objects as described in
this user guide in the chapter ‘Development Team Access to Headstart’.
13 - 2 Getting Started Headstart Oracle Designer 6.5 - User Guide

Template Package Architecture
Template Package Structure
The following is a schematic representation of the template package structure:
Subclassed by Object Library Subclassed by

(qmsolb65.olb)
Template Form Application

(qmstpl65.fmb) Library Attached Generated
through Forms
Attached to MODLIB
Event Handler Calendar Library

Headstart Template Package Library (ofgcall65.pll)
Structure (qmsevh65.pll)
MS Help Library
Designer Components (ofghpl65.pll)
Attached to
Message Library
Headstart Components Core Headstart (ofgmes65.pll)
Library
Application Components (qmslib65.pll) Attached to Error Handling
Library
(ofgtel65.pll)
The template structure is characterized by the following:
• The Object Library contains form level triggers which are subclassed into the template
form (qmstpl65.fmb) through three object groups:
• QMSSO$MODULE: contains form level triggers required in each and every form
• QMSSO$STND_MODULE: contains form level triggers required in normal data
entry forms
• QMSSO$LOV_MODULE: contains form level triggers required in LOV forms
• The trigger code for all of these form level triggers consists of one line of code: a call
to procedure QMS$EVENT_FORM which resides in the event handler library
(qmsevh65.pll). The name of the form level trigger is passed as a parameter to
QMS$EVENT_FORM.

• The Object Library contains (standard) source objects for blocks and items. The
trigger code for the associated block and item level triggers consists of one line of
code: a call to procedure in the Event Handler Library (qmsevh65.pll). The procedure
invoked depends on the type of object:
• Data blocks invoke QMS$EVENT_DATA_BLOCK
• Control blocks invoke QMS$EVENT_CTRL_BLOCK
• Items invoke QMS$EVENT_ITEM
• The special LOV source block, and items, invoke QMS$EVENT_LOV
• The special Multi-Select source block invokes QMS$EVENT_MSEL
• The special Multi-Select LOV buttons invoke QMS$EVENT_MSEL_LOV
• All Alerts, the CALENDAR block, canvas and window, including associated triggers
and items, and visual attributes are grouped into object groups which are owned by the
object library and subclassed by the template form.
• The application library form is NOT attached to the template form. Upon generation,
the library specified in the application level setting of the MODLIB preference is
attached to the generated form, which also causes the Headstart libraries (qmsevh65
and qmslib65) to be attached to the generated form.
• As a result of this structure, it is not possible to compile the form level triggers in the
template form. The procedure invoked in all form level triggers
(QMS$EVENT_FORM) is only attached upon generation. This does not affect the
generation process at all.
OFG*65.PLL Libraries
Oracle Designer 6i uses a set of libraries to implement standard functionality in generated

forms. These libraries are located in the [ORACLE HOME]\cgenf61\admin directory. These
libraries are automatically attached as needed to the generated forms.
Unfortunately, Oracle Designer 6i uses the exact same library names as were used by Oracle
Designer 2.x/6.0, but with significantly different code. This presents a problem for people
who want to deploy forms generated from Designer 2.x/6.0 and 6i in the same runtime
environment. Forms generated from Designer 2.x/6.0 cannot run with the ofg*.pll libraries
from Designer 6i, and vice versa.
At first glance, you might think you can just include both versions of the ofg*.pll libraries but
in different directories. However, this will not work. In the runtime environment, the
FORMS60_PATH variable determines where the forms runtime engine will search for
libraries. It will always use the first occurrence of a given library in the path. So, even if you
put both directories in the path, it will never get to the second directory.
The only solution is to rename one or the other set of libraries. Of course, when you rename
the libraries, you will have to re-generate the forms to get the new libraries attached. Since
Designer 6i is the newer release, it makes sense to rename the libraries provided with it before
you begin generating forms.
Headstart has renamed the libraries as follows.

Original Name New Name
OFGBSL.pll OFGBSL65.pll
OFGCALL.pll OFGCALL65.pll
OFGHPL.pll OFGHPL65.pll
OFGMES.pll OFGMES65.pll
OFGMNL.pll OFGMNL65.pll
OFGNAVL.pll OFGNAVL65.pll *
OFGTAB.pll OFGTAB65.pll
OFGTEL.pll OFGTEL65.pll
OFGTREEN.pll OFGTREEN65.pll
* includes bug fix in cgnv$ package
The renamed versions of these libraries are in the [HSD65_HOME]\hst\admin directory. You
can leave them there or move/copy them to the [ORACLE_HOME]\cgenf61\admin directory.
In order to instruct Oracle Designer to use the renamed versions of these libraries, you must
create new string values in the registry. The Headstart installation process creates the
following new items in the registry.
Under HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\CGENF61\OPTIONS
String Value Data

FMLABS ofgbsl65.pll
FMLAMG ofgmnl65.pll
FMLATE ofgtel65.pll
FMLCAL ofgcall65.pll
FMLHPL ofghpl65.pll
FMLMSG ofgmes65.pll
FMLNAV ofgnavl65.pll
FMLTAB ofgtab65.pll
FMLTRE ofgtreen65.pll
If you do not need to run forms generated from both Designer 2.x/6.0 and 6i in the same
environment, you can revert back to using the default names if you like. Simply remove the
string values from the registry. (You may want to apply our bug fix to OFGNAVL.pll.)
Advantages
This template structure has the following advantages:
• The event handler structure allows you to plug in new events, delete events, or replace
events with your own code very easily.
• As the various object types have their own event handler, overhead is minimized, and
you immediately have an overview of the triggers and actions associated with a certain
object type.
• Each event handler includes standard debug information that will be displayed in the
Headstart Debug Monitor. This allows you to quickly localize your problem.

• By putting all the logic in libraries, instead of in the template form and the object
library, it is much easier to make changes quickly. You only have to recompile the
libraries modified to let the change take effect in all generated forms. The generated
forms need no modification whatsoever.
• If you want to change the definition of an object type (for example, the navigation
style in multi-record blocks, or the buttons displayed on the toolbar), you change the
definition of the corresponding object in the object library. To let the change take
effect, you only have to create new forms executables ( .fmx files) by recompiling
(‘Forms Generate’) the forms source files (.fmb files). You do not have to create new
source files with the Form Generator because the objects are not owned by the
generated source file but subclassed from the object library.
• By grouping objects into object groups which are subclassed into the template form
and subsequently into the generated forms, you can easily add objects to already
generated forms.
• By attaching the libraries through the MODLIB preferences, and not through the
template form, you can use the same template form for multiple applications. See next
section for more information.

Prepare Your Application for Generation
There are a number of steps you must perform to prepare your application for generation with
the Headstart Template Package. These steps are generally performed once or once per
application.
1. Reference the application level named preference sets

2. Blank out language specific command lines
3. Create shortcuts to Headstart objects (optional)
4. Set the Generator Options
5. Create and attach the application library
6. Create and attach the application menu
7. Create a start form for your application
8. Create an HTML launch document for your application
Reference the Application Level Named Preference Sets
Headstart supplies a number of preference sets and reusable module components you can
(and should) make use of when generating your applications. These objects are stored in a
Designer application system shipped with Headstart. You should have imported the
application .dmp file during the Headstart installation process.
Perform the following steps to make these objects available in your own application systems:
1. Create a workarea which contains (at least) the following application folders.
• QMS65
• HSD65
• your application folder(s)
2. Open the Design Editor, click on your Application System folder node, invoke the
Preferences window, select Form Generator in the product poplist, and reference the
named set QMS65_RECOMMENDED.
3. Change the Product poplist to Report Generator and reference named set
QMSREP65_RECOMMENDED
4. Change the Product poplist to Help Generator and reference named set
QMS65_HTML_HELP.
Blank out Language Specific Command Lines
By default Oracle Designer determines the command line to use when calling forms and
reports from a menu by the Language specific settings in the System Folder. Designer also
provides a mechanism for overriding this default, the user preference MNUUCL, Use
Command Line from Module.

This preference is set to Yes in the QMS65_RECOMMENDED. This means that Designer
will go through a three step hierarchy in determining the proper command line.
• First, it will look at the individual module. If the module has a command line, it will
be used whenever this module is called from a menu.
• If the module has no command line, the Forms Generator will look at the command
line for the appropriate language defined in the System Folder.
• Finally, if the language specific command line is null, the Forms Generator will look
at the application preferences MNUDFC and MNUDRC for forms and reports
respectively.
For Headstart, you must use the values defined in MNUDFC and MNUDRC in the
QMS65_RECOMMENDED preference set unless specifically instructed to use a module
specific command. Therefore, you must blank out the preferences set for the languages in the
System Folder.
1. In the Repository Object Navigator, open the System Folder.

2. Expand the Languages node.
3. Select Oracle Forms and blank out the command line.
4. Select Oracle Reports and blank out the command line.
Create Shortcuts to Headstart Objects (optional)
The following lists are objects in the QMS65 application system which you will use
frequently in your applications. While not strictly necessary, you might find it useful to
create shortcuts in your application system folders to these objects. (A shortcut simply makes
the object a bit quicker to locate in the various dialog windows you will use.)
You create a shortcut in the RON. Simply drag and drop the desired object from the owning
container to the target container. Note that you must drop the object on the target Application
System folder node, not on the sub-node for the object type.
• Preference Sets:
QMS65_RECOMMENDED
QMS65_MULTI_RECORD_BLOCK
QMS65_NO_CLIENT_CONSTRAINTS
QMSREP65_RECOMMENDED
QMS65_WIZARD_BUTTONS
QMS65_DEBUG_MODULE
QMS65_HTML_HELP
• Reusable Module Components:

QMS_DIALOG_BUTTONS
QMS_LOV_BUTTONS
QMS_MSEL_LOV_BUTTONS
QMS_WIZ_BUTTONS
• Library Modules:
QMSLIB65
QMSEVH65
Set Generator Options
In the Design Editor, you can set generator options for all the generators. (Options menu ->
Generator Options).
You must instruct the Form Generator where to find the Headstart Template form.
1. Choose Options -> Generator Options -> Forms...

2. Select the Dependencies tab if it is not already visible.
3. Set Path to: <Headstart home>\HST\ADMIN
4. Click OK
If you have not already done so, you should also set up the other Forms, Reports and Library
generation options at this time.
Create and Attach the Application Library
The application library is used for:
• application-specific initializations required by the Headstart Template Package

• setting application and version information that should be displayed in the Application
About window
• storing customizations on Headstart library program units (see chapter on Template
Package Customizations for more information)
• storing any other program units that are used by forms all through the application.
Note that if you use Headstart to develop multiple applications, you might consider creating a
company-wide library, in addition to the application library. Refer to chapter on Template
Package Customizations for more information.
Creating the Application Library

Creating the application library consists of three steps.
1. Copy hsdapp65.pll from the Headstart Demo Application.

2. Modify the three procedures to be specific to your application.

3. Attach qmsevh65.pll to your application library.
The simplest way to create an application library is to copy the application library from the
Headstart Demo Application, hsdapp65.pll.
You can make a copy on the file system and design capture the application library into your
application system, or copy the library within Designer from the QMS65 application system.
The application library must contain at least the following procedures:
• QMS$INIT_APPLICATION, to perform various initializations

• QMS$ABOUT_THIS_APPLICATION, to set the application specific information that
should be displayed in the application About window
• A function named <library name>_REVISION which returns the version number of
the application library. This function is used in procedure
QMS$ABOUT_THIS_APPLICATION to show the version information.
Once you have copied the demo application library, you will need to open and modify each of
these procedures to make the library specific to your application.
Attention: It is assumed here that you will have shared deployment of the
Headstart Database Objects, at least in the Development Environment. If you
decide to create a self-contained application (for more information see the section
‘Database Schema Organization’ in chapter ‘Test and Production Environment’),
you will have to make an extra change in your application library, as described in
chapter ‘Test and Production Environment’.
You should attach library qmsevh65 to the application library, which in turn will attach
library qmslib65 and a number of OFG libraries, as shown in the schematic representation in
the previous section. It is important to keep this sequence of library attachments for two
reasons:
• The application library should be sequenced before the Headstart libraries for
customized QMS program units to overrule the same program unit in a Headstart
library. See the chapter on Template Package Customization for more information.
• The Headstart library qmslib65 contains a modified version of procedure
CGHP$CALL_MS_HELP, an Oracle Form Generator procedure stored in OFG
library ofghpl65. The modified version is required to allow for invocation of HTML-
based help when running on the WEB. (HTML help can also be used when running
client/server on Windows). This implies that qmslib65 should always be sequenced
before ofghpl65.
Attaching the Application Library

There are two options for attaching the application library to the generated forms:
• By defining the application library as a module of type ‘Library’ in the repository and
adding this module to the module network of each form module.
• By setting the MODLIB preference at application level to the name of your
application library.
It is clear that the second option is much less work, and therefore preferred.

1. In the Design Editor, select the application node and open the Preferences navigator.
2. Set the MODLIB preference to the name of your application library. The name
should be in lowercase and does not need the ‘.pll’ extension.
Create and Attach the Application Menu
The application menu includes the following types of items.
• standard menu options (query, edit, undo, etc.)

• the Smartbar
• application forms and reports (optional)
The standard menu options and the Smartbar are included in the Headstart menu template.
You can add your application forms and reports to your menu using the module network in
the Design Editor.
You may choose to create a Navigator Tree for your application instead of a menu for
accessing your application forms and reports. However, even if you choose this option you
should still generate a menu so that you have the standard menu options and Smartbar.
Creating the Application Menu

The following steps are required to create your application menu.
1. In the Designer Editor, create a menu module.

2. Attach application forms and reports to this menu if desired using the module
network.
3. Attach your application library to this menu using the module network. You must
attach the library using the module network as the Forms Generator will not use the
MODLIB preference when generating menu modules.
Attaching the Application Menu

You must attach the application menu to each form that is generated. You do this by setting
the FMNDMA preference at the application level.
1. Select the application level node and open the Preferences Navigator.
2. Set the FMNDMA preference to the name of the menu module. Enter the name in
lowercase letters and do not include the .mmx extension.
Create a Start Form for your Application
You need to create some sort of a launchpad for your application. This may be a simple Start
Form with a graphic, or it could be a navigator tree.
You can copy the start form from the Headstart Demo Application, hsd0000f.fmb. After you
have copied the form module to your application, you must edit the window title to be
appropriate for your application. You may also want to replace the image with your company
logo.

Create an HTML Launch Document for your Application
Once your have generated your start form, you can create an html launch document for
launching your application.
Headstart 6.5 is optimized for forms deployed in a web environment. As such, deploying
Headstart generated forms in a client/server environment is not recommended. (There are a
number of know issues with using Oracle Forms 6i in a client/server environment. Headstart
6.5 has not attempted to overcome these issues.)
For a sample and information on creating an html launch document, see the chapter Test and
Production Environment in the Part Deploying Your Applications.

Iterative Development Tasks
There are a number of other tasks you should also perform before generating your modules.
These tasks may need to be performed several times during an iterative development process
since they can be influenced by changes to the Data Layer, the Business Logic Layer and to
the Presentation Layer. You can perform these tasks for a subset of your application.
1. Create Key Constraint Error Messages

2. Generate Change History Columns
3. Generate Context Sensitive HTML Help ID’s
4. Create Module Revision Parameter
5. Generate Report Module Parameters
Create Key Constraint Error Messages
You can record an error message against primary keys, unique keys, foreign keys and check
constraints. Use the Headstart Utility ‘Create default error messages for constraints’ before
generating your forms to set up these error messages using the Headstart message tables.
More information: Chapter User Assistance, section Message Handling; Online help
Headstart Utility ‘Create default error messages for constraints’.
Generate Change History Columns
If you want to record information about the user and date the record was created and last
updated, you should run the Headstart utility, ‘Create About This Record columns’, prior to
generating your database tables from Designer.
You should also include these change history columns as hidden columns in your base table
definitions in your modules.
More Information: Chapter User Assistance, section ‘About This Record’
Generate Context Sensitive HTML Help ID’s
To ensure your online help system will be fully context-sensitive, you should run the
Headstart Utility ‘HTML Online Help generator’, prior to generating your forms.
More Information: Chapter User Assistance, section Online Help
Create Module Revision Parameter
To be able to view module revision information at runtime, you should add a module
argument P_REVISION to each forms module.

More Information: Chapter User Assistance, section ‘About This Application’.
Generate Report Module Parameters
Headstart supplies a generic report launch form (qms0012f) which can be used to launch all
reports. When you attach a report to a menu and generate the menu, the Form Generator will
automatically generate a call to the Headstart report launch form in the menu, rather than a
direct call to the report.
This launch form uses two tables to store information about reports and their associated
parameters. When you choose the report from the menu, the report launch form will open
and will attempt to query the requested report in the tables.
Headstart also supplies a Headstart Utility, Create Headstart Report and Report Parameter
Definitions, to automatically populate these two tables based on the report and parameter
information stored in the Designer repository.
Perform the following steps to create the report and report parameter definitions.
1. Run the utility Create Headstart Report and Report Parameter Definitions. You may
run this for one or more modules.
2. Open the Headstart Foundation Application and choose Parameters -> Module and
Parameters from the menu.
3. Query the report definition(s) that were created in step 1.
4. In the Parameter block, place your cursor on the first empty record (after the report
specific parameters). Press the ‘Add Standard Report Parameters’ button.
5. Select all parameters that you wish to have available to your users.
6. Press OK. The selected parameters will be added to the parameter list for this report.
7. Save your changes.
Refer to the online help of the Headstart Foundation application, qfdhelp.htm/hlp located in
the \doc directory for more detailed information.

Module Libraries
Oracle Designer has the ability to store module specific application logic directly against the
module definition in the repository. This allows you to define all appropriate Forms triggers
against the module, module component (block) and items in the Designer repository. You
can also define modules of type Library, and store all the program units of the library in the
Designer repository. Either way, all logic can be stored in the repository.
Which leaves the question where to store the actual logic.
• in module libraries, restricting the module application logic to single line calls to
program units in the module library
• all the logic in the module itself, without creating any module specific libraries.
Both approaches have pro’s and con’s.
Advantages of storing the actual logic in a separate module library are:
• Maintenance and debugging will be easier, all custom code for a module is
centralized, and by viewing the content of a module library, one can quickly trace all
custom logic.
• Module libraries will encourage reuse. Code common to multiple forms modules can
be put into one library that is shared by multiple modules.
• Program units in a module library use dynamic loading. They are only read into
memory when they are needed, whereas the form itself is loaded entirely at forms
start-up. When all logic is stored in the module itself, the form might grow
considerably in size, which will slow down start-up time of the form.
• You can modify code in the library without having to regenerate or even recompile the
associated form(s) .
Advantages of storing all logic in the module itself are:
• It is quicker to build. For smaller program units with only a few lines of code it might
be perceived unnecessary overhead to create separate program units in a module
library.
• Direct references to forms objects can be made. In the module library, the Name_In
construct must be used to reference globals, forms parameters, blocks and items.
Direct references are checked at compile time, errors in object names within the
Name_In construct are only discovered at runtime.
• Logic stored in the module itself can call CG$ program units generated by the Form
Generator.
Note that the centralization of code can also be achieved in the form itself, by grouping
related program units in packages, and using event handlers within these packages.
A side effect of storing all application logic against the forms module definition itself, might
be a drop in performance of the Form Generator, as much more custom code must be loaded
before the generation process can start.

In general, you will probably make this decision on a form by form basis depending on the
level of complexity of the code involved.
Attaching Module Libraries
As with the application library, we have the choice of using the MODLIB preference or the
module network to attach module libraries to the form. For reasons of documentation and
impact analysis, we strongly recommend the following.
• Always use the module network to record module library attachments.
Module Libraries that Customize Headstart

Now, consider a situation where module specific requirements force you to override the
standard behavior of the application. As is explained in more detail in chapter ‘Template
Package Customizations’, this might result in a module specific version of a program unit that
also resides in either the application library, or one of the Headstart QMS libraries. If this is
the case, the sequence of library attachments becomes important, the module library should
be the first in the sequence to ensure the module specific version of the modified program
unit is executed.
The following steps are required for attaching a module specific library to a form.
1. Attach qmsevh65.pll to the module library via the module network.

2. Attach the module library to the form via the module network.
3. Clear the MODLIB preference at the module level.
The library specified in the MODLIB preference is always attached before any libraries
recorded in the module network. Therefore, if you do not clear the MODLIB preference at
module level, it will inherit the application level setting, which is set to the name of the
application library. This would cause the application library, and attached Headstart libraries,
to be sequenced before your module library, causing the module specific customization to be
ignored at runtime.

Case Sensitivity of File Names
If you use a UNIX application server, you will have to deal with the fact that filenames under
UNIX are case sensitive. Although uppercase/lowercase sensitivity of UNIX is no Headstart
specific issue, Headstart can be of great help in creating a case-sensitive application.
Two situations can occur:
• You are about to generate a new application that will be deployed on a UNIX
application server and therefore must be case-sensitive.
• You have an existing Oracle Forms application which must be deployed on a UNIX
application server, but the application currently does not handle case-sensitive
filenames.
The next two subsections discuss each situation.
Generating a Case-Sensitive Application
If the first situation applies, most of the case-sensitivity is already taken care of by Headstart:
• Generated filenames will be in lowercase due to preference LWCFLN (Filenames in
lowercase, uppercase, or mixed case) which is set to LOWER in named set
QMS65_RECOMMENDED.
• The filenames of all Headstart libraries are in lowercase, and library attachments are
lowercase as well (although displayed as uppercase in Forms Designer).
• The filename of the 'subclass information' (qmsolb65) of the object groups in the
Headstart template form (qmstpl65) is in lowercase.
You should stick to the following rules to ensure your generated application is completely
case-sensitive, and ready to be deployed on a UNIX platform:
• If you change the MODLIB preference for a module, make sure the new library name
is in lowercase.
• Preference FMNDMA, which specifies the name of your menu file, should be in
lowercase.
• Assign a lowercase name to any additional forms and libraries you create manually.
• If you subclass objects from either the Headstart Object Library, or from your own
object library, make sure the filename of the subclass information is in lowercase.
• Any calls to other modules, coded in the module library, should be in lowercase.
• Calls to explicit LOV Forms are generated in uppercase by Form Generator. This
means that you will have to modify the KEY-LISTVAL trigger post-generation, and
convert the LOV filename to lowercase.
Making an Application Case-Sensitive
If you generated your application without paying attention to lowercase/uppercase filenames,
it is a difficult and time-consuming task to convert it into a case-sensitive application. Read
the previous section for an outline of the issues you need to be aware of.

Headstart supplies the Elcheapo script to automate the steps you need to take to make your
application case-sensitive.
Refer to the Elcheapo user guide (elcheapo.doc, located in \doc directory) for detailed
instructions on using the elcheapo script to migrate your application to a UNIX application
server.
An alternative solution is to make a link in UNIX.
Example: suppose you have a file named qmslib65.pll, but one of your libraries refers to it as
QMSLIB65.pll.
Go to the UNIX folder where you stored qmslib65.pll and perform the following command:
ln qmslib65.pll QMSLIB65.pll
This creates a 'synonym' QMSLIB65.pll which points to the real file qmslib65.pll, and the
reference from your other library will work.

CHAPTER
14 User Interface Generation
This chapter provides you with detailed information on various aspects of user interface
generation using Oracle Designer and Headstart Oracle Designer.
Headstart Oracle Designer 6.5 - User Guide User Interface Generation 14 - 1

Menu Template
Headstart provides a menu template, qmsmnt65, to enable the generation of a GUI pull-down
menu, that can be attached to a form, and is based on the Oracle Applications style guides.
The menu template has the following structure:
File Menu
Save Saves any pending changes
Save and Proceed Saves any pending changes, and returns the form to a state where the
next transaction can be started
Log on as a Opens the logon screen
Different User
Print Prints the current screen in which the cursor is located
Close Form Closes current form
Close All Closes all open forms
Exit Closes all open forms and exits the application
Edit Menu
Undo Record Undoes all changes in the selected record
Cut Cuts current selection to the clipboard
Copy Copies current selection to the clipboard
Paste Pastes from the clipboard
New Record Creates a new record
Duplicate Field Above Copies the value from the preceding row
Duplicate Record Above Copies the preceding record to the current record.
Delete Record Deletes the current database record
Clear Field Clears the current field
Clear Record Clears the current record, and does not ask for
confirmation if pending changes might be lost.
Clear Block Clears all records in the current block
Clear Form Clears any pending changes in the current form.
Clears all child windows (even if they are not
coordinated) but does not close them.
Select All Selects all records (for blocks with multi-select functionality)
Deselect All Deselects all selected records, except for the current record (for blocks
with multi-select functionality)
List of Values Invokes the LOV Window
Edit Field Invokes the Editor. The Editor to be used can be specified by setting the
SYSTEM_EDITOR environment variable. By default the Oracle Forms
editor is invoked.
Preferences Change Invokes a window that allows the user to change
Password their Oracle password
Preferences Preferences Invokes window to set a number of end user options
to influence the look and feel of the application.
View Menu
Find Shows the Find Window, or Row-LOV to retrieve all records
Find All Retrieves all records
14 - 2 User Interface Generation Headstart Oracle Designer 6.5 - User Guide

Enter Invokes Query-By-Example mode
Run Retrieves all records, or if in Query-By-example mode runs the currently
entered query.
Cancel Exits Query-By-Example mode
Count Matching Counts the number of records that will be retrieved using Query-By-
Records Example mode
Show Last Criteria Recovers the previous criteria while in Query-By-Example mode
Record First Moves the cursor to the first record
Record Last Moves the cursor to the last record
Order by Current Ascending Changes the block to order ascending by the current
Field field. Changes take effect on the next query.
Order by Current Descending Changes the block to order descending by the current
Field field. Changes take effect on the next query.
Clear Order By
Window Menu
Cascade Displays any open windows in a 'cascaded' or stair-stepped fashion.
Tile Horizontally Displays any open windows in a horizontal 'tiles' (non-overlapping)
fashion.
Tile Vertically Displays any open windows in a vertical 'tiles' (non-overlapping) fashion.
Help Menu
Help Topics Invokes top level of online help system
What's This Displays context-sensitive reference help on the current item
Keyboard Help Displays the current key mappings
Show Item Hint Toggles the item hint text on and off.
Diagnostics Headstart Debug Toggles Headstart debug mode on and off.
Mode
Diagnostics Display Error Displays the last database error
Diagnostics Last Query Displays the SELECT statement last issued in the
current runform session.
Diagnostics Set Break Turns on the Oracle Forms Debugger, provided the
form you are currently in was started in debug mode
Diagnostics Trace Toggles the SQL Trace facility for the current
session. SQL Trace provides performance
information on individual SQL statements
Record History Displays audit columns for the currently selected record
About This Displays information about the current form and application.
Application

Smartbar
The default Smartbar included in the Headstart menu template contains buttons that replicate
the following common standard Forms functions:
Save Saves any pending changes
Save and Saves any pending changes, and returns the form to a state where the
Proceed next transaction can be started
Print Prints the current screen in which the cursor is located
Undo Undoes all changes to the currently selected record
New Record Creates a new record
Delete Record Deletes the current database record
Clear Record Clears the current record, and does not ask for confirmation if pending
changes might be lost.
Clear Form Clears any pending changes in the current form. Clears all child
windows (even if they are not coordinated) but does not close them.
List of Values Invokes the LOV Window
Edit Field Invokes the Editor. The Editor to be used can be specified by setting the
SYSTEM_EDITOR environment variable. By default the Oracle Forms
editor is invoked.
Find Invokes Row-LOV or Find Window on the current block
Enter Query Invokes Query-By-Example mode
Run Query Retrieves all records, or if in Query-By-example mode run the currently
entered query.
Cancel Query Exits Query-By-Example mode
Previous Moves the cursor to the previous record
Record
Next record Moves the cursor to the next record
What's This Displays context-sensitive reference help on the item that will be
clicked on after this menu option has been invoked.
As previous, doesn’t this now display context sensitive
The Smartbar buttons are enabled and disabled context-sensitive, controlled through an end
user preference. If a certain function replicated by a button toolbar is not available in the
current context, the button is disabled.

Menu and Smartbar in Your Application
There are a number of features available for using the Headstart menu and Smartbar in your
application systems.
Required Preference Settings
A number of preferences as well as the Language specific command lines must be set in order
for proper functioning of menus generated with the Headstart menu template. Note that the
preferences are already set in the named set QMS65_RECOMMENDED which should be
referenced at application level, and you should have blanked out the language specific
command lines in the Getting Started chapter.
If nevertheless your generated menu does not behave as expected, you should check whether
the following settings are correct.
In the System Folder, under the Languages node, the command line for both Oracle Forms
and Oracle Reports must be blank.
In your application folder, at the application level, the following preferences should be set.
• MNUUCL = Yes
• MNUDFC = qms$menu.call_form('<MODULE>');
• MNUDRC = qms$menu.set_current_action('LAUNCH_REPORT','<MODULE>');
execute_trigger('qms$menu_item');
Note that these preference settings imply the following:
• The menu item code to call a form is taken from the Command Line property of the
module. If the command line is blank, the menu item code is taken from the language
specific command line in the System Folder. Since we ensure that command line is
blank, the command line will be taken from the preference MNUDFC. We
recommend only using the Command Line property to pass module specific
parameters to the form. Refer to section Passing parameters to forms for more
information.
• Reports are assumed to be launched through the Headstart Report Launch Form.
Reports are not called directly from the menu. This is implemented using the
MNUDRC preference.
Form-Menu Attachment
When generating a form, the menu that will be associated with the form is determined by the
value of preference FMNDMA. Usually, you will create one application-wide menu, and set
preference FMNDMA at application level to the name of this menu.
However, in complex environments with multiple applications, you might have forms that are
used in multiple applications. This would force you to create application-specific copies of
these forms, only to attach the appropriate menu.

From a maintenance point of view, this is not an optimal situation. Therefore, Headstart
supplies a procedure which allows you to specify the name of the application menu at
application start-up. This procedure, QMS$APPLICATION.SET_START_MENU, should be
invoked at application start-up, in procedure QMS$INIT_APPLICATION. For example:
QMS$APPLICATION.SET_START_MENU('HSD0000M');
By default, the menu attached to the form is still the menu specified in the FMNDMA
preference. If you want to override the menu specified in FMNDMA with the menu set
through procedure QMS$APPLICATION.SET_START_MENU, you should include the
following procedure call in the PRE-FORM trigger of your module definition:
QMS$FORM.KEEP_START_MENU
The sequence of this user code segment with respect to Form Generator code segments does
not matter.
By calling this procedure in the PRE-FORM trigger, Headstart dynamically replaces the
design-time specified menu with the application menu through a call to the
REPLACE_MENU built in. As the REPLACE_MENU built-in cannot be used in conjunction
with the Forms Debugger, you must comment out this procedure call before running the form
in debug mode, or use the Headstart Debug Monitor instead.
Menu Call Method
The end user of a Headstart-generated application can control what happens when they
invoke a new form from the menu.
The following options are available:
• Replace current form: The NEW_FORM built-in is used to call the form from the
menu.
• Stack forms, save all changes at once: The OPEN_FORM (NO_SESSION) command
is used.

The user can select their preferred option through the User Preferences form which is
accessed via the ‘Edit -> Preferences’ menu option.
Sharing of Library Data
Headstart always uses the SHARE_LIBRARY_DATA parameter in combination with the

NEW_FORM and OPEN_FORM built-ins when calling forms from the menu. By sharing
library data, performance is increased, as multiple forms share the same library instance.
As a result of this parameter setting, package variables that are assigned in one form keep
their value when another form is invoked that has the same library attached.
Passing Parameters to Forms
Oracle Designer has the concept of Argument Passed Values (APVs) and Named Passed
Values (NPVs) to pass data from one form to another. APVs and NPVs are defined against a
module network link. Unfortunately, they are only taken into account for a form-calling-form
network link which is implemented through an action item. For menu-calling-form network
links, the recorded APVs and NPVs are currently ignored (enhancement request 772098).
Headstart supplies functionality which allows you to pass up to five parameters to a form
called from the menu. To use this functionality you should invoke procedure
QMS$MENU_CALL_FORM from the Module Command Line property.
The specification of this procedure is as follows:

procedure qms$menu_call_form
(p_form_name in varchar2
,p_param_name1 in varchar2 default ''
,p_param_value1 in varchar2 default ''
)
For example, to call a form which should be opened cascaded to the previously active form,
you set the menu command line as follows:
qms$menu_call_form('<MODULE>','QMS$WINDOW_POS','CASCADE');
As you can see from the example, Headstart supplies a number of pre-defined parameters you
can use when calling a form from the menu. The table below lists these parameters as well as
the standard parameters supported by Oracle Designer.

Parameter Allowable Values Use
QUERY_MODE QUERY_ONLY, To invoke a form that allows for

NO_QUERY_ONLY insert, update and/or delete in
query-only mode (regardless of
menu call method!)
SWITCH_MENU DO_REPLACE, Set to DO_REPLACE if you

NO_REPLACE want the called form to keep the
current application menu
(regardless of call method)
QMS$WINDOW_POS See section Window Set (relative) position of first

Titling and Positioning window of called form. See
section Window Titling and
Positioning for more information.
QMS$PROCEED_BLOCK Any block in the form When the user Presses the Save
and Proceed Button on the
Toolbar, changes are saved and
the cursor is placed in the first
navigable block of the form. By
specifying this parameter you can
explicitly set the block the cursor
should navigate to after saving
the changes.
CG$STARTUP_MODE NORMAL, NEW, Define the startup mode of a

ENTER QUERY, form. See Designer online help
AUTO QUERY, for more information.
RESTRICTED NEW,
RESTRICTED ENTER
QUERY,
RESTRICTED AUTO
QUERY
In addition to these pre-defined parameters, you can specify your own parameters which you
define as Argument against the forms module in the repository. Assume you want to call the
employee form from the menu, and you want to restrict access to those employees that work
for the same department as the user (we assume the user’s department is stored in a global.).
To do so, perform the following steps:
• Create an argument P_DEPTNO against the module to be called

• Create an argument item usage for P_DEPTNO, linking the parameter to the item that
holds the department number.
• Set the Module Command Line property of the forms module to:
qms$menu_call_form('<MODULE>', 'P_DEPTNO',
:global.user_deptno, 'CG$STARTUP_MODE', 'RESTRICTED AUTO
QUERY');
Note that any restricted start-up mode will satisfy the requirement.

Calling the Same Form with Different Parameter Values
It is a common requirement that the same form should be called multiple times from the
menu, with different parameter values. Ideally, the different parameter values should be
recorded against each module network link, but as explained in the previous version, this is
currently not supported by Oracle Form Generator.
You can achieve the requirement in a slightly different way, by creating a ‘secondary’ module
definition in the repository, which acts as a shell module to call the original form. The shell
module definition (no module components need to be defined) has the Command Line
property defined such that the original form (generated from the ‘primary’ module definition)
is called with a different set of parameters.
An example will clarify this:
Assume you have module EMP that needs to be included twice in the menu: once as a module
to insert, query, update and delete employee information, once as a query only module.
Perform the following steps to achieve this:
• Create the ‘primary’ module with Short Name/Implementation Name EMP as normal,
including the EMP module component which allows for insert, update, delete and
query.
• Set the Short Title of EMP to something like ‘Maintain Employee Information’
• Create the ‘secondary’ module with Short Name EMP_QO, Implementation Name
EMP and the Command Line set to:
qms$menu_call_form('EMP', 'QUERY_MODE', 'QUERY_ONLY');
• Set the Short Title of EMP_QO to something like ‘Query Employee Information’
• Add both modules to the menu structure.
• Generate the menu and form EMP.
Changing Menu Items at Runtime
Headstart provides a number of pre-built procedures to dynamically change the appearance of

your menu at runtime. You can enable, disable, hide or display menu items (and their
associated Smartbar items), and change the label of a menu item programmatically by calling
one of the following procedures:
QMS$MENU.ENABLE_ITEM('<submenu name>', '<item name>');
QMS$MENU.DISABLE_ITEM('<submenu name>', '<item name>');
QMS$MENU.DISPLAY_ITEM('<submenu name>', '<item name>');
QMS$MENU.HIDE_ITEM('<submenu name>', '<item name>');
QMS$MENU.SET_ITEM_LABEL: ('<submenu name>', '<item
name>','<label>');
Note that for all procedures an overloaded version is available which does not require the
specification of the submenu name. If this overloaded version is used, the submenu is
determined based on the structure of the menu templates shipped with Headstart.
If you want to enable or disable a menu option that is associated with a standard form
function, you should use the following procedures:

QMS$FORM_FUNCTION.ENABLE('<form function>');
QMS$FORM_FUNCTION.DISABLE('<form function>');
For example:
QMS$FORM_FUNCTION.DISABLE('CLEAR_FORM');
This procedure will enable/disable the form function in both the Smartbar and the menu, and
in the item popup menu if it is an item level form function.
Item Popup Menu
In addition to the pulldown-menu, Headstart will generate an item popup menu. Clicking the
right mouse button on an item invokes this popup menu with the following item-specific
options:
• Cut
• Copy
• Paste
• Clear Field
• Field Above
• Order Ascending
• Order Descending
• List of Values…
• What's This? Help
The items in the popup menu are displayed and hidden context-sensitive, instead of enabled
and disabled. A popup menu is intended for quick access to item level functions, so it
therefore does not include a number of disabled functions which are not valid for the current
item. Exception to this behavior are the Cut, Copy and Paste options which are always
displayed for text items. The enabling and disabling of these options is handled automatically
because they are defined as magic menu items.
Like the items in the pulldown menu, you can enable, disable, and hide or display the items in
the popup menu, by calling one of the following procedures:
QMS$MENU.ENABLE_POPUP_ITEM('<item name>');
QMS$MENU.DISABLE_POPUP_ITEM('<item name>');
QMS$MENU.DISPLAY_POPUP_ITEM('<item name>');
QMS$MENU.HIDE_POPUP_ITEM('<item name>');
If you do not want the item popup menu to be available in your forms, you should clear the
Popup Menu property of CGSO$DEFAULT_ITEM in the Headstart object library. Refer to
the chapter on Template Package Customizations, section Customizing the Headstart Object
Library for more information.
If you want to enable or disable a popup menu option that is associated with a standard form
function, you should use the following procedures:
QMS$FORM_FUNCTION.ENABLE('<form function>');
QMS$FORM_FUNCTION.DISABLE('<form function>');

For example:
QMS$FORM_FUNCTION.DISABLE('CLEAR_FORM');
This procedure will enable/disable the form function in both the Smartbar and the menu, as
well as in the item popup menu if it is an item level form function.
Preventing Recurrent Load of Smartbar Gif Files
Each time you open a new menu which contains the Headstart Smartbar, the gif files of the
iconic buttons are reloaded from the application server. This can be prevented by creating a
jar file which contains these items, and set up the base HTML file to load this .jar file at
application start-up.
Headstart ships with the hst65.jar file, located in the <HSD_HOME>\java directory, a
preconfigured .jar file that includes all the gif files from the Headstart Smartbar as well as a
number of java class files.
To use this .jar file, you should change do the following:
• Place the Headstart Jar file hst65.jar in a directory which maps to a virtual directory
included in your java_CODEBASE.
• Include the name of the Headstart .jar file in the java_ARCHIVE entry in the base
HTML file.
• In the registry.dat file, located in <ora_home>\FORMS60\java\oracle\forms\registry,
the default.icons.iconpath entry should point to the virtual directory of the Headstart
.jar file, and the default.icons.iconextension should be set to ‘gif’.
Example:
Both f60all.jar and hst65.jar are located in <ORA_HOME>\FORMS60\JAVA directory

which maps to the virtual directory /forms60java/.
The Forms Cartridge will have the following entries:

java_CODEBASE="/forms60java/"
java_ARCHIVE="f60all.jar,hst65.jar"
The Registry.dat file will have the following entries:
default.icons.iconpath=/forms60java/
default.icons.iconextension=gif
If you use different .gif files in your own application, you should create your own .jar file. To
do this, you need program jar.exe which can be downloaded from the Sun website on the
Internet.
Preventing Recurrent Load of the Menu
Using the set_menu_item_property built-in to change the label and the visibility (hide /show)
of a menu item at runtime causes the whole menu to be reloaded.

For this reason, the menu label ‘Enter Query’ is NOT changed into ‘Last Query Criteria’
when the form enters query mode.

Calendar
If the cursor is on a date or datetime field, the user can invoke a calendar form using the form
function ‘List of Values’, available through the toolbar, the menu and the item popup menu.
The calendar window provides easy navigation between different dates, months and years and
allows the user to quickly enter a date. The calendar window cannot be invoked in enter-
query mode.
By default, the calendar window is invoked with all dates being enabled. However, it is
possible to disable (ranges of) dates when invoking the calendar window to prevent the user
from picking an invalid date from the calendar.
Advanced Calendar Options
You can customize the display of the calendar for a specific item, as is appropriate in the
context of the item. The specification of the procedure is as follows:
procedure show
( p_new_type varchar2 default null
, p_low_date date default null
, p_high_date date default null
, p_sql_string varchar2 default null
, p_first_date date default null
, p_title varchar2 default null
)
The usages of the parameters are:
• p_new_type = 'WEEKEND' : all weekends are disabled.

• p_new_type = 'DISPLAY' : the calendar is opened as display-only, no dates can be
picked

• p_low_date: All dates higher than this date are disabled
• p_high_date: All dates lower than this date are disabled
• p_sql_string: SQL statement that should select two date values, aliased to low_date
and high_date. All dates in this range will be disabled.
• p_first_date: The calendar opens at the date passed to p_first_date. If First Date is not
set, the calendar opens on sysdate. First Date is ignored if the current item already has
a valid date value in it. In that case the calendar opens on that date.
• p_title: Overrides the default title of the calendar window.
Calendar Examples
Example - Weekdays Only

To invoke the calendar with only the weekdays enabled, you set the PL/SQL Block property
of the date item in the repository to:
qms$calendar.show('WEEKEND');
If you want to change the calendar window title to indicate only weekdays are enabled, you
can set the PL/SQL block property to:
qms$calendar.show
( 'WEEKEND'
, null
, null
, null
, null
, 'Calendar - Weekdays'
);
or, a cleaner method using named parameter passing:
qms$calendar.show
( p_new_type => 'WEEKEND'
, p_title => 'Calendar - Weekdays'
);
The examples that follow all use named parameter passing as this makes the examples easier
to read.
Example - Range of Days Enabled

To invoke the calendar with only the week before the current date, and the week after the
current date enabled, you set the PL/SQL Block property of the date item in the repository to:
qms$calendar.show
( p_low_date => sysdate+8
, p_high_date => sysdate-8
);
Note that the low and high dates are disabled as well.
Instead of using the sysdate pseudo column, you can also refer to a date item in the form. For
example:
qms$calendar.show( p_high_date => :EMP.HIREDATE + 1);

will enable all days after the hiredate of the employee.
Instead of hardcoded low and high dates you can also disable dates which are stored in a
table, by using the p_sql_string parameter. Assume you have a table HOLIDAYS which
holds all the holidays. To invoke the calendar with only working days enabled, you set the
PL/SQL block property to:
qms$calendar.show
( p_new_type => 'WEEKEND'
, p_sql_string => ' select action_date LOW_DATE'
||', action_date HIGH_DATE'
||' from HOLIDAYS'
, p_title => 'Calendar - Working Days'
);
Note that the selected columns must be aliased to LOW_DATE and HIGH_DATE.
Example - Display Only Calendar

Most of the time, you will use the calendar to facilitate quick date entry on date(time) items.
However, you can also use the calendar to provide a graphical view on a number of special
dates.
Assume you want to have a button in your form that invokes the calendar with the hire dates
of your employees marked. To do so, create a button action item in the module in the
repository and, using application logic, specify the WHEN-BUTTON-PRESSED as follows:
qms$calendar.show
( p_new_type => 'DISPLAY'
, p_sql_string => ' select hiredate LOW_DATE'
||', hiredate HIGH_DATE'
||' from EMP'
, p_title => 'Employee Hiring Dates'
);

Visual Attributes
Visual Attributes are applied through the (standard) source object in the object library. A
generated object subclasses from a source item in the object library, and this source item has a
visual attribute attached, which is subsequently inherited by the generated object.
The table below shows the various source objects in the Headstart object library and the
visual attributes they use.
Object Type Source Object Item Visual Attribute Prompt Visual

Attribute
Item cgso$default_item, qms$item_font qms$prompt_font

cgso$default_item_do,c
gso$char_mline,
cgso$char_mline_do,
cgso$date, cgso$date_do
Item cgso$check_box, qms$gui_item_font qms$prompt_font

cgso$check_box_do,
cgso$button, cgso$radio,
cgso$image, all qmsso$
buttons, qmsso$text
Canvas cgso$canvas, cg$title N/A

cgso$canvas_tab,
cgso$canvas_popup,
cgso$canvas_spread
LOV cgso$lov, qms$black_on_grey N/A

qms$rep_param_lov (*)
Block and Item Group Titles
The Form Generator generates block and item group titles as boilerplate text. Boilerplate text
cannot be based on a source object in the object library, therefore the visual attributes of these
titles are still determined through the Designer version 1.3.2 style of CG$ visual attributes.
This is the reason that CG$TITLE is included as a font, which inherits all its properties from
qms$item_font, except for the background color which is set to gray.
Ideally, the background color for titles should be set to ‘automatic’, but due to a forms bug,
this results in black text on a black background.

List of Values
Ideally, the List of Values object, cgso$lov, should inherit from the qms$gui_item_font with
‘automatic’ as its Visual Attribute. However, due to a forms bug, this results in black text on
a black background. Therefore, this object is set to visual attribute
QMS$BLACK_ON_GREY.
Setting Font Typeface, Size and Weight
By default, the Headstart Visual Attributes enforce Oracle look and feel. The font typeface
used is MS Sans Serif, 8-point, with a medium font weight. The foreground and background
colors are set to the value ‘automatic’ which is interpreted at runtime according to settings in
the base html file and the registry.dat file.
The subclassing mechanism in the object library makes it very easy to modify the supplied
object library to change the font typeface, size and weight.
For example, to generate your objects with Oracle Applications compliant fonts, you should
make the following modifications:
• Set size to 10 in qms$item_font and qms_prompt_font

• Set font weight to Bold in qms$item_font
Refer to the chapter on Template Package Customization for general instructions on how to
modify the object library.
Assigning Special Visual Attributes
The Headstart Object Library contains a large number of pre-defined visual attributes you can
use to display an item with specific background and foreground colors.
To attach such a visual attribute to a specific item, you specify the name of the visual attribute
in the hint text of the item, enclosed between the HTML-like tags: <VA> and </VA>. For
example:
<VA>QMS$BLACK_ON_RED</VA>
Open the object library maintenance form, qmsolm65, for a complete list of all the predefined
visual attributes.

Layout Generation
This section does not cover all possible layout styles that can be generated. It focuses on the
layout styles where Headstart adds specific support, or layout styles that can be generated
using more advanced techniques which are not trivial for the average Designer user.
Blocks on Tabs
To generate blocks on tabs, you simply set the Placement property of the module component
to either ‘New Tab canvas page’ or ‘Same Tab canvas page’.
There are a number of issues and restrictions you should be aware of when generating blocks
on tab canvas pages. We strongly recommend you read the Designer online help topic
‘Generating blocks onto native Form Builder tab canvases’ which documents all of these
issues.
Group Tabs Nested within Block Tabs

One of the documented restrictions is the limitation that 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 (nested tabs), the first item in the block must not be in one of
the stacked item groups (i.e. the first item must be placed on the underlying tab canvas page).
If you ignore this restriction the form will generate and compile, but at forms startup the
following error is displayed:
FRM-41053: Cannot Find Canvas: invalid ID
Furthermore, if you navigate to an item in a stacked item group, the underlying block tab is
no longer visible.
You can work around this restriction by ‘fooling’ the generator by creating an invisible
unbound item as the first item of the module component with the following properties:
• Unbound Type = 'Custom'

• Insert, Update = No
• Display = Yes
• Prompt = <Null>
• Display Type = 'Current Record'
• Width = 0
• Height = 1
Because the width of this item is set to 0, the layout does not change. When you click on the
tab, the OFG code navigates to this item, and because the display type is set to 'Current
Record', the generated WHEN-NEW-ITEM-INSTANCE trigger fires, which navigates to the
next item, which is the first visible item displayed on a tabbed item group page.

Wizard Layout
A wizard is a special form of user assistance that automates a task through a dialog with the
user. Wizards help the user accomplish tasks that can be complex and require experience.
Novice users often do not avail themselves of the full power of a product because they are
intimidated by its high-end functionality. They may be unsure of what actions to take or what
order in which to perform those actions, or they may be overwhelmed by the quantity of
options they are faced with.
Experienced users may be comfortable with the complexity but still find some repetitive
processes tedious, especially if they do not take a wide variety of paths through the process.
In these cases, a direct manipulation interface may make users feel they are constantly
reinventing the wheel.
A wizard can address these problems by doing some or all of the following:
• Sequence: If a process involves multiple steps which must be performed in a

particular order, a wizard can formalize this structure. Even if order does not matter,
the wizard can impose one simply to remove the burden of choice, and to ensure that
no steps are missed.
• Simplify: The “80/20” rule says that 80% of the time, users only need to use 20% of
the product’s features. The wizard can optimize for the common case by only offering
the most often-used options. This can help lower the feeling of being overwhelmed
often associated with learning new products.
• Explain: Because fewer options are shown, and because they are split across multiple
pages, a wizard has a better opportunity to explain the task and guide the user.
• Automate: If the options are often combined in the same way, a wizard can speed up
the user’s task by making some choices for them, or by letting them choose from
preset combinations of settings.
The result for novices can be a comfortable starting place that helps them get results and feel
successful quickly – and experts can increase their efficiency by leaving some of the
repetitive details to the computer.
Building a Wizard
Building a wizard is not straightforward. Carefully design the wizard before you start
building your module definition. Issues to consider:
• Number of pages, which items should be placed where, and in which sequence. Note
that Headstart allows you to split items belonging to the same table over multiple
pages.
• Use of images to embellish the wizard.
• Page instructions, short and concise text description at the top of a page to explain the
goal and usage of a page.
• Wizard size and positioning of control buttons.
• Availability of control buttons.

The next sections discuss each of these issues in more detail, explaining how Headstart
supports you in dealing with these issues. The last section summarizes the steps required to
build a wizard.
Wizard Page Images

Typically, a wizard includes a graphic panel at the left side of each page, which should be
used to aid communication with the user, and to make the page more visually appealing.
Note that sometimes you might want to omit this graphic panel if you are running out of
space on a specific wizard page.

Refer to the section on Image Items for general information on generating images. In the
context of wizards, the display dimensions of the image are important:
• The larger the width, the less space remains for any items.
• The height should fit within the height of the wizard window. If the height is too
small, the Generator might generate items below the image, which is uncommon in a
wizard style layout.
Within the Headstart demo application, the wizard image items have a width of 30 and a
height of 15, which is an appropriate setting for a wizard that is sized 6 inches x 4 inches.
Wizard Page Instructions

Typically, each page in a wizard has a short text at the top to explain the usage of the page.
To generate such instructions which should look like boilerplate text, you have two options:
• Generate the text through the derivation expression of an unbound item

• Generate the text as prompt of an invisible unbound item
Both options have pro’s and con’s, your choice will depend on the specific situation, as is
explained below.
Using the first option, you are not restricted in the length of the text. However, the first
option is only possible if the unbound item is part of a module component that has a base
table usage. Otherwise, the module will fail to generate as Designer validates the derivation
expression against the base table of the module component.
Detailed steps to generate each option are discussed below.
Generating text through unbound derivation item

Create an unbound item with the following properties:
• Unbound Type = SQL Expression

• Display = Yes
• Template/Library Object = QMSSO$TEXT, QMSSO$TEXT_MLINE,
QMSSO$BLUE_TEXT or QMSSO$BLUE_BOLD_TEXT
• Width = Available width, depends on width of wizard and wizard picture if
appropriate
• Height = depends on length of the text
• Derivation text = ‘<The actual instructions, enclosed between quotes>’
Create a When-New-Form-Instance trigger to enable the text item on form startup.
• set_item_property(‘<block.item>’,ENABLED,PROPERTY_TRUE);
Using this option, you are not restricted in the length of the text. However, you can only use
it if the unbound item is part of a module component that has a base table usage. Otherwise,
the module will fail to generate as Designer validates the derivation expression against the
base table of the module component.

The Template/library object value ensures that the ‘derived’ text looks like boilerplate text:
the item has a gray background and no bevel. The When-New-Form-Instance trigger ensures
that the text is not grayed out.
You can force ‘carriage returns’ within the text by concatenating the CHR(10) ASCII-code.
Generating text through prompt of invisible unbound item

Create an unbound item with the following properties:
• Unbound Type = Custom

• Display = Yes
• Template/Library Object = QMSSO$TEXT, or QMSSO$BLUE_TEXT or
QMSSO$BLUE_BOLD_TEXT
• Prompt = <The actual instructions>
• Width = 0
• Height = 1
Using this option, the length of your text is limited to the length of the Prompt property which
is 130 characters. You can of course work around this limitation by creating multiple
unbound items.
You can force ‘carriage returns’ within the text by including the symbol which is set as
‘Force Split Prompt Marker’ in preference ITMFPS. This preference is set to ‘#’ in
QMS50_RECOMMENDED.
Splitting a Table over Multiple Pages

When building wizards, a common requirement will be to split items based on columns that
belong to the same table, over multiple wizard pages. Or, in Form Builder terminology, we
want to split a block over multiple content canvasses.
Headstart provides support for this, by allowing you to define separate module components
for each content canvas that will behave as one ‘virtual block’ at runtime.
To do so, you specify separate module components for each wizard page, all of which are
based on the same table. The first of these module components (‘the primary module
component’) is the one that takes care of the DML, it includes displayed items that must be
displayed on the first wizard page, and it includes all other items (non-displayed!) which
are placed on subsequent wizard pages.
For the subsequent wizard pages, you define ‘secondary’ module components, which only
include the items that should be displayed on that specific page (content canvas). To make
the primary and secondary module components behave as one ‘virtual block’ at runtime, you
should do two things:
• Apply the following naming convention to the secondary module components:

<name of primary module component>_SB#<sequence number>

For example, if you want to split table EMP over three wizard pages, and the primary
module component is called ‘EMP’, the ‘secondary’ module components are named
‘EMP_SB#2’ and ‘EMP_SB#3’ .
• Set the Template/Library Object property of the secondary module components to

‘QMSSO$WIZARD_SPLIT_BLOCK’
This source block QMSSO$WIZARD_SPLIT_BLOCK, contains two special triggers ON-

LOCK and WHEN-VALIDATE-RECORD. Both triggers call a procedure to reset the block
status to QUERY, which make the block behave as a control block, preventing Forms from
issuing DML statements on commit. Furthermore, trigger WHEN-VALIDATE-RECORD
calls a procedure which copies the item values of the blocks generated from the secondary
module components, to the corresponding (hidden!) items in the first block, which is
generated from the primary module component. The corresponding item in the primary block
is found by matching the item names.
Wizard Control Buttons

Typically, a wizard has the following buttons at the bottom of every page:
• Cancel: Leave the wizard without saving data

• Help: Invokes context-sensitive help for the wizard
• < Back: Navigates to previous wizard page
• Next >: Navigates to next wizard page
• Finish: Saves data entered in wizard and leaves the wizard.
Headstart provides a reusable module component QMS_WIZ_BUTTONS which contains

these five buttons. When building your own wizard, you can copy (not reference!) this
Reusable Module Component (RMC) multiple times into your wizard module, once for each
wizard page. This saves you the effort of recreating the five button definitions each time.
Furthermore, preference set QMS_WIZARD_BUTTONS referenced by
QMS_WIZ_BUTTONS ensures that the buttons are laid out properly, based on a wizard
width of 6 inches and a zero page margin (preference PAGMAR=0).
You must copy the RMC because you will need to customize the button definitions for each
page:
• Buttons that are not applicable for a certain page should be disabled. For example, the
Back button will be disabled on the first wizard page. To disable a button, you should
set the Template/Library Object of the button to QMSSO$DISABLED_BUTTON.
• The PL/SQL Block property of the Back and Next buttons should be modified to
navigate to the first block on the previous and next page.
Due to a limitation in the Design Editor, copying the RMC is not straightforward. Follow
these steps to include the RMC:
• Switch to the Data View in the Module Diagram

• Click on the ‘Include Reusable Module Component’ iconic button
• The ‘Include Module Component’ dialog pops up. Select QMS_WIZ_BUTTONS,
check the ‘Copy Reusable Module Component’ checkbox, and click on the OK button.

• A copy of QMS_WIZ_BUTTONS is created in a newly created window.
• Invoke the property sheet of the copy of QMS_WIZ_BUTTONS, change the Window
name to the name of the wizard window (typically named WINDOW), and change the
Placement property to ‘Same Content Canvas’.
• Change to the Display View in the Module Diagram, select the copy of
QMS_WIZ_BUTTONS, and press the right-mouse button. Select ‘Resequence
Module Components...’ from the popup menu.
• The ‘Resequence’ dialog pops up. Move the copy of QMS_WIZ_BUTTONS to the
correct position, using the up and down arrows, and press OK.
• Delete the window which was created as part of the copy operation of
QMS_WIZ_BUTTONS.
The control buttons should be disabled until they are available. Use application logic to
dynamically enable and disable the control buttons, dependent on the data entered by the user.
Most likely you will use the POST-TEXT-ITEM and WHEN-LIST-CHANGED events to
enable and disable the Next and Finish buttons. Note that you cannot use the WHEN-
VALIDATE-ITEM event, as this trigger does not fire when the user nullifies an item.
Wizard Size and Button Positioning

One of the big problems with wizard generation is the consistent positioning of the control
buttons at the bottom of each page.
Normally, the control buttons is placed directly below the last item on the page. Since the
items on each page do not necessarily take the same amount of vertical space, this causes the
y-position of the control buttons to be different for each page.
Headstart has solved this by using a special source block in the object library,
QMSSO$WIZARD. This block contains an item called WIZARD_HEIGHT which has a
Height of 3.5 inches and a Width of 0. At runtime, the item is not visible because of the zero
width, however, because the Visible property of this item is set to ‘Yes’, the layout algorithm
of the Form Generator takes this item into account when computing the vertical space the
module component will need. Each module component that is placed on a new content
canvas (a new wizard page) should subclass from this source block QMSSO$WIZARD (or
QMSSO$WIZARD_SPLIT_BLOCK which also contains this item) to ensure that the same
amount of vertical space is consumed and the control buttons will be positioned consistently
at the bottom of each page.
The consequence of this technique is that you cannot place another module component
between the first module component of the page, and the control buttons module component,
as this would increase the page height. If you need to put items on a page that originate from
more than one module component, you must use a stacked canvas which you then display
beside the first module component.
However, you cannot use the <PP>AUTO_SHOW</PP> window title tag to display this
stacked canvas, as this would display the Stacked Canvas on top of every wizard page! Refer
to the section on generating side by side blocks for instructions on generating this within a
wizard style layout.
The height of 3.5 inch of the WIZARD_HEIGHT item, together with margins and the control
buttons module component, will lead to an overall height of the wizard of 4 inches. If you

wish to use a different wizard height, you should modify the height of this item in the object
library.
The horizontal layout of the control buttons is based on a wizard width of 6 inches. If you
want to use a different width, you will have to change the block tabulation preference
BLKTAB, in preference set QMS_WIZARD_BUTTONS, to reposition the buttons based on
the new wizard width.
Summary of Building Steps

Having explained all the issues and tasks related to wizard generation, you are ready to build
one yourself!
Below, a summary of steps is included to help you perform this challenging task:
• Create a module definition and set preference PAGMAR to 0 for the module.
• Decide on the wizard size. If you use a wizard width other then 6 inch, you must
modify preference BLKTAB in preference set QMS_WIZ_BUTTONS accordingly. If
you use a wizard height other then 4 inches, you must modify the height of item
WIZARD_HEIGHT in QMSSO$WIZARD accordingly.
• Set the Template/Library Object property of the window to
QMSSO$MODAL_DIALOG_WINDOW.
• For each wizard page, create a module component with the following characteristics:
• Template Library/Object is set to QMSSO$WIZARD or
QMSSO$WIZARD_SPLIT_BLOCK
• Placement property is set to ‘New Content Canvas’
• Rows displayed is 1
• Canvas Width is 60
• The first item is an unbound image item
• The second item is an unbound item to generate the page instructions
• Unbound and/or bound items you want to display on the page
• Non-displayed bound items if the module component is the ‘primary module
component’ of a virtual block split over multiple pages.
• For each wizard page, include a copy of reusable module component
QMS_WIZ_BUTTONS, set the Placement property to ‘Same Content Canvas’, and
change the PL/SQL block of the navigation buttons to ensure correct navigation
• If the wizard page should contain a multi-record block, and/or items from more than
one base table, create additional module components for these blocks with the
Placement property set to ‘New Stacked Canvas’. Set the size and the x, y coordinates
of these module components such that the block does not obscure the image, the page
instructions or any other items.
• Create application logic to:

• Bind keyboard block navigation to one wizard page and its associated stacked
canvasses.
• Enable and disable the control buttons when the user enters or clears required
data. Usually, the Next and Finish buttons are disabled until all required fields are
entered to move on to the next page (Next button), or to complete the transaction
(Finish button).
• Show and hide stacked canvasses when the user navigates from one page to
another
The Headstart demo application contains two wizard modules, hsd0008f and hsd0020f.
Examining the module definitions and libraries of these two modules might be of great help
in understanding the complex process of building a wizard.
Side By Side Blocks
Side-by-side blocks can be generated by placing a block on a popup page.
By default, the Form Generator only raises a popup page if you navigate to the block which is
placed on the popup page. You can drive Headstart to automatically display popup pages at
forms startup, by including the following string in the window title of the window containing
the popup page(s):
<PP>AUTO_SHOW</PP>
The window title itself should be enclosed between <WT> and </WT> tags, to ensure that at
runtime only this tagged window title is displayed, without the Popup Page tags.
Note that you cannot use this technique when generating wizard style layouts. In a wizard,
the popup pages should only be displayed when a specific content canvas is displayed. With
the PP window title tag, the popup pages are displayed all the time, regardless of the active
content canvas.
To get side-by-side blocks in a wizard layout, you will have to programmatically raise and
hide the popup pages when the user navigates through the wizard pages:
• Use the SHOW_VIEW and HIDE_VIEW built-ins to raise and hide the popup pages
when the user presses the Next and Back navigation buttons.
• Disable the canvas management code generated by Form Generator, by using the
following application logic as the first event segment in the form level WHEN-NEW-
BLOCK-INSTANCE trigger:
copy(get_item_property(name_in('system.cursor_item'),
item_canvas),'cg$ctrl.cg$last_canvas');
Refer to library hsd0008l in the Headstart demo application for an example.
Resizable Spread Tables

Spread tables can be generated by setting the ‘Overflow’ property on the Module Component
to ‘Spread table’. Items that are used as context information to identify the record, should be

placed outside the scrolling region. This can be achieved by checking the ‘Context’ flag for
these items.
Headstart allows you to implement resizable spread tables: if the user resizes the window
width, the width of the scrolling region is changed accordingly. To make your spread tables
resizable, you simply include the following statement in procedure
QMS$INIT_APPLICATION in your application library:
QMS$CONFIG.SET_SPREADTABLES_RESIZABLE('TRUE');
Restrictions
Note that if you want to use resizable spread tables, two restrictions apply:
• Preference BLKSBP (Block Scrollbar Position) should be changed to LEFT.

• Preference BLKDEC (Block Decoration) should not be set to a rectangle value.
The reason for these restrictions is that it is not possible to reposition the scrollbar at runtime,
nor is it possible to resize the block decoration. Therefore, the scrollbar and/or block
decoration would have been obscured by the scrolling region when the user increases the
default window width.

Control Block Generation
To generate a control block from Oracle Designer, you must first create a module component
that has no table usages. Include only unbound items.
Set the block’s Template/Object Library property to: QMSSO$CTRL_BLOCK.

Item Generation
This section discusses the generation of various types of items:
• Image Items
• Action Items
Image Path
By default, Forms will look for the image file in the working directory of the application
start-up icon, and in the directories as specified in the FORMS60_PATH.
Headstart has added a specific environment variable HSD65_IMAGEFILE_PATH to allow

you to store all your images in a central directory which is not in the FORMS60_PATH.
To use this feature, you must define your image items in a special way.
• Create an unbound item of type custom

• Set display type to 'Image'
• Set width and height as desired
• Set preference IMGDFI to N. Note that due to Form Generator bug 733939, you must
set this preference at Module Level or higher.
• Instead of specifying the name of the image file to be displayed in the Default Value
property of the item, record it in the hint text of the item, enclosed between the
HTML-like tags: <IM> and </IM>. For example:
<IM>hsdlogo.gif</IM>
You can also store the name of the .gif file in a forms parameter or forms global. For
example:
<IM>:PARAMETER.P_IMAGE_FILE</IM>
When Headstart encounters an image tag in the item hint text, it will start looking for the
image in the directory as specified in the HSD65_ IMAGEFILE_PATH environment
variable. If it cannot find the image, it will continue with the normal search path of Forms,
the working directory followed by the FORMS60_PATH.
Note that the HSD65_IMAGEFILE_PATH can only contain one directory. If you want to
store your images in multiple directories, you should include those directories in the
FORMS60_PATH.
Action Items
Generation of action items is standard Designer functionality. When using Headstart, there is
one rule you should stick to:
Do not define the height of the action item in the repository.

The rationale for this rule is the algorithm used by Form Generator to determine the height of
an action item:
item height in repository * character height of template coordinate system
The Headstart template form uses a real-inch coordinate system, with both the character width
and height set to 0.1 inch. This means that if you set the height of an action item to 1, the
generated button will have a height of 0.1 inch, which looks very odd, and makes the button
label unreadable. If you leave the height of the action item blank, the button inherits the
height of it's source object (cgso$button) in the object library, which is set to 0.219 inch (the
same height as for text items with a Plain MS Sans Serif 8-point font).
You might set the height to 2 or higher, but that will cause the action items to have a different
height than unbound button items, as for unbound button items, Form Generator uses the font
(ITMBIF is set to Yes) to determine the height.
Buttons/Action Items in a Multi-Record Block
By default, Headstart sets the Mouse Navigate property of buttons to False. In most cases,
this is the desired setting. However, if you have a button in each record of a multi-record
block, the cursor will not navigate to the selected record when the user clicks on the button.
If the code attached to that button contains logic to read or update the selected record (which
it usually does), then the code will go wrong because it will be working against the wrong
record.
Solution: Add a when-new-form-instance trigger after the Headstart initialization to change

the Mouse Navigate property of the affected buttons to True.

List of Values
Built-in List of Values
You can generate three types of Built-in List of Values:
• Row List of Values

• Foreign Key List of Values
• Domain List of Values
Generation of these LOV types is clearly documented in the Designer online help. In this
section we provide some additional information.
Row List of Values

A row list of values is a list showing all the records that can be queried in a block. As such it
can be used as an alternative to query mode or Find Windows. Row LOVs are useful when
the base block is a single record block, and the number of available records is small (< 50-
100).
To generate a Row LOV, simply set preference ROWLOV to Yes for the module component
you want to have the Row LOV.

Filter Before Display
Built-in LOVs have a property called ‘Filter Before Display’.
When this property is set to True, the List of Values window is displayed without any records
displayed. The user first has to enter a ‘filter value’ in the Find Item at the top of the window.
This feature is useful if you want to use built-in List of Values on large tables. You can set
this property for both the Row LOV and foreign key LOVs. To set this property, invoke the
property palette for the base table usage (in case of a Row LOV), or the lookup table usage
(in case of FK LOV). The property is included in the group with title ‘Lookup’.
The Filter Before Display property is one way to implement List of Values for large tables.
An alternative to this property is the generation of explicit LOV forms, as discussed in the
next section.
LOV Forms
To generate an explicit LOV form module, you should perform the following steps:
• Set Module Layout Format (only accessible through property sheet) to ‘Lov’
• Set the Template/Library Object property of the item that should invoke the LOV form
through the <List> function to ‘QMSSO$LOV_FORM_ITEM’.
• Set the Template/Library Object property of the module component which is based on
the LOV Table to 'QMSSO$LOV_BLOCK'. This ensures that double-clicking on a
row will select the row, and close the LOV window.

• Assign preference set ‘QMS65_MULTI_RECORD_BLOCK’ to the module
component which is based on the LOV table.
• Include reusable module component QMS_LOV_BUTTONS as the last module
component in your form. This will provide you with a row with Find, OK and Cancel
buttons at the bottom of the window.
• Set the Template/Library Object of the window to
'QMSSO$MODAL_DIALOG_WINDOW'.
• Assign preference set ‘QMS65_LOV_MODULE’ for the LOV module
• Add the LOV module to the module network of the calling module.
• Remove the Action Item that Designer automatically creates for the module network
link.
• Generate the LOV module with template QMSLVT65 and object library QMSOLB65.
• Generate the calling module.
Refer to the section on Multi-Select Functionality in the chapter on Runtime Behaviors, for
instructions on generating Multi-Select LOV windows.
Querying in an LOV Form

Pressing the Find button will always requery the LOV block, regardless of the form mode.
The idea behind this behavior is that instead of using enter-query mode (which is still
accessible through the keyboard for power users), it is more user friendly to include a search
block at the top of the LOV form. The user then has the ability to restrict the number of
records queried by entering search criteria in the search block, and pressing the Find button.
The search criteria are easily applied by creating application logic against the PRE-QUERY
trigger of the LOV table block. For example, assume a search block called FIND, with an
item called FIND, and an LOV block EMP with ENAME being the first item, then the PRE-
QUERY trigger code against EMP should be:
:EMP.ENAME := :FIND.FIND;

In case of a search block containing only one search item, you should add a KEY-NEXT-
ITEM trigger to this item that duplicates the behavior of pressing the Find button. The code
of this trigger should be:
QMS$EVENT_LOV('FIND');
Note that this recommended implementation is consistent with the built-in LOV where the
Find button (or Tab key on the Find item) also applies the search criteria as entered in the
‘Find’ item.
If a search block is not needed, you might want to query all records when the LOV form is
invoked. To do so, add a module argument by the name of CG$STARTUP_MODE and set
the Default Value of this argument to ‘AUTO QUERY’.

Windows
Window Styles
Headstart supports the following window styles:
• Modeless Document Window: This is the default window style generated.

• Modal Document Window: Set Template/Library Object of the Window in the
repository to QMSSO$MODAL_DOCUMENT_WINDOW.
• Modal Dialog Window which hides on exit: Set Template/Library Object of the
Window in the repository to QMSSO$MODAL_DIALOG_WINDOW.
• Modal Dialog Window which does not hide automatically on exit: Set
Template/Library Object of the Window in the repository to
QMSSO$MODAL_DIALOG_WINDOW _NHOE. This window style is useful if you
want to display nested modal dialog windows within the same form. The About This
Application form supplied with Headstart is an example of this.
Find Window
A Find Window is a type of window that enables the user to locate one or more records
without having to invoke enter-query mode. All fields for which a user may want to enter
search-criteria should be placed in the Find Window so that the user does not need to use
Query By Example.
This functionality is complimentary to Row-LOV, which can be generated by setting

preference ROWLOV to Yes. Row-LOVs will be used for smaller tables, the Find Window

is appropriate for larger tables where the user should enter search criteria to reduce the
number of rows returned.
Both the Row LOV and the Find Window are invoked from the same 'Find' button in the
button toolbar.
The Headstart Utilities contain a very powerful utility ‘Create Find Window(s)’ which
creates the required window and module component definitions in the repository to generate
the Find Window. Refer to the online help of this utility for more information. You can also
create a Find Window manually, by performing the following steps:
• Create a Module Component (MCO) in a new window. Base this Find MCO on the
same table as the block that must be queried. Set Rows Displayed to 1. Add lookup
table usages if you want LOVs on items in the Find Window.
• Set Insert?, Select? and Update? flags of this MCO to TRUE. Make sure the MCO
Alias is set according to the following naming convention: 'QF_'<Result_Block>.
Example: QF_EMP.
• Add bound and unbound items as required for the Find Window. Create bound items
if the item in the Find Window should have the same display dimensions as a column
in the base table. Add unbound items if you need additional items in the Find Window
which have unique display dimensions, or have display dimensions that match with a
column of the target table that is already bound to another item in the Find Window.
(You cannot bind two items to the same base column, as the Form Generator will
generate the second item as a mirror item of the first item.) For example, if you want
the ability to do a range select on deptno, you need two items in the Find Window:
DEPTNO_FROM and DEPTNO_TO. You can bind item DEPTNO_FROM to
column DEPTNO, and must create DEPTNO_TO as an unbound item.
• Define all items in the Find Window as optional. Note that items that are part of
mandatory foreign key are always generated as required items by Form Generator.
Headstart fixes this by making the item optional again at runtime.
• For each item in the Find MCO, the target item in the result block must be defined.
By default, Headstart assumes the target item is the item with the same name as the
item in the find MCO. For example, the value of item ENAME in QF_EMP will be
applied to item ENAME when the query is executed. You can use the Hint Text
property of the item in the Find MCO to deviate from this default behavior. As the
hint text is used for other purposes as well, the query find driving information is
enclosed between HTML-like tags: <QF> and </QF>. The following syntax applies
for the Hint Text.
• <QF> COPY_TO: target fieldname </QF>
• <QF> RANGE_FROM: target fieldname </QF>
• <QF> RANGE_TO: target fieldname </QF>
Examples:
<QF> COPY_TO:ENAME </QF>
<QF> RANGE_FROM:HIREDATE </QF>
• Set the Template/Library Object of the Find MCO to 'QMSSO$FIND_BLOCK'. This
source object will ensure the block will behave as a Find Block, and will generate
three buttons: Clear, New and Find into the Find Window.

• Reference preference set QMS65_NO_CLIENT_CONSTRAINTS at the Find MCO
level, to prevent Form Generator from generating code to validate key constraints
defined against the table the Find MCO is based on.
Known Restriction
The Module Component that must be queried through the Find Window must have the
Datasource Type set to either 'Table' or 'View'.
Window Titling and Positioning
A (secondary) window frequently contains data that can only be understood in the context of
data presented in a master window. As the master window can be hidden by the current
window, or any other window, the necessary context information should be displayed in the
window title.
The Window Positioning feature offers developers the possibility to position a newly opened
window relative to the previous active window.
To implement window titling and positioning features, you must set preference NAVWND to
Yes (already set in QMS65_RECOMMENDED)
The window title in the repository is used to record information on the context information on
the window title, and to indicate the positioning style (see below).
To indicate which part of the repository window title is used to construct the dynamic
window title, and which part contains the window positioning information, you should use
the following HTML-like tags:
The <WT> and </WT> tags enclose the window title information
The <WP> and </WP> tags enclose the window positioning keyword
The next two sections contain a number of examples.
Window Titling
Define the context items of the master block in the Window Title property of the Window
holding the detail Module Component (e.g. Employees). You must enclose these master
block items between brackets. For example:
<WT>Employees in department [DEP.DEPTNO][DEP.DNAME]</WT>
Note that you can reference an unlimited number of master block items in the window title.
You can also reference forms parameters and globals. For example:
<WT>Employees in department [:PARAMETER.P_DEP_NAME]<WT>
Its is not possible to use concatenations or the Decode-function.
Window Positioning
Headstart implements the following window positioning algorithm:

• If the window is the first window in the form: Positioning according to the value of
PARAMETER.QMS$WINDOW_POS.
• If this parameter is null, the window positioning is extracted from the repository
window title (see below)
• If no window positioning information is included in the window title, the positioning
style is FIRST_WINDOW if ‘Hide on Exit’ property is set to No (this usually
indicates a document window). If the ‘Hide on Exit’ property is set to Yes (this
usually indicates a modal dialog window), the positioning style is CENTER.
For secondary windows, the positioning rules are as follows:
• Window positioning is extracted from the repository window title (see below)
• If no window positioning information is included in the window title, the positioning
style is CASCADE if ‘Hide on Exit’ property is set to No (this usually indicates a
document window). If the ‘Hide on Exit’ property is set to Yes (this usually indicates
a modal dialog window), the positioning style is CENTER.
If you want to deviate from this standard positioning algorithm, you can explicitly set the
window positioning style for each window in the window title property of the Designer
repository.
The window positioning keywords available are:
• CASCADE: Child window overlaps the parent window, with an offset to the right and
down from the current position of the parent window.
• RIGHT: Child window opens to the right of the parent window without obscuring it.
• BELOW: Child window opens below the parent window without obscuring it.
• OVERLAP: Detail window overlaps the parent window, aligned with its left edge,
with offset down.
• CENTER: Windows open centered relative to MDI window (or monitor size when not
running on MS Windows platform).
• CENTER_DOCUMENT: Windows open centered relative to MDI window (or
monitor size when not running on MS Windows platform). This keyword must be
used when the window you want to center is a document window.
• CENTER_WITHIN_PARENT: Windows open centered relative to another window.
Note that both windows must have the same style, either document or dialog. If the
window styles differ, the positioning will be not correct.
• FIRST_WINDOW: Positions the window immediately below the toolbar. Usually
used for main entity windows.
For example:
<WT>Employees in department [DEP.DNAME]</WT>
<WP>RIGHT</WP>

CHAPTER
15 Runtime Behaviors
This chapter covers the following topics:
• Runtime Initializations
• Inter-Form Navigation
• Multi-Select Functionality
• Date Handling
Headstart Oracle Designer 6.5 - User Guide Runtime Behavior 15 - 1

Runtime Initializations
This section does not discuss all runtime initializations The following runtime initializations
are not covered here, because they can be controlled separately, and are discussed elsewhere
in this user guide:
• Replace menu with application start menu

• Raise Find Window or Row-LOV at form start-up.
• Show Popup Pages
• Window Positioning
• Image Items
All initializations discussed below can be easily switched off at any point, by making a call to
the following procedure:
QMS$CONFIG.DISABLE_RUNTIME_INIT
Form Initializations
The form is initialized in procedure QMS$FORM.INIT which is called in the PRE-FORM

trigger, after the code generated by Oracle Form Generator.
The form level initializations performed are discussed below
Date Format
Oracle Form Generator generates the following code in the PRE-FORM trigger to support
Year 2000 compliant code:
/* CGYR$SET_DATE_FORMAT */
BEGIN
set_application_property(DATE_FORMAT_COMPATIBILITY_MODE
, '5.0');
set_application_property(PLSQL_DATE_FORMAT
, 'YYYY/MM/DD HH24:MI:SS');
set_application_property(BUILTIN_DATE_FORMAT
, 'YYYY/MM/DD HH24:MI:SS');
forms_ddl('ALTER SESSION SET NLS_DATE_FORMAT =
''YYYY/MM/DD HH24:MI:SS''');
END;
Unfortunately, you cannot configure the date format that is used within these statements.
Headstart has added a form initialization, which re-executes the above statements with the
date format as set by the first date environment variable that is set:
• FORMS60_OUTPUT_DATE_FORMAT
• FORMS60_USER_DATE_FORMAT (first value used)
• NLS_DATE_FORMAT
Refer to the Oracle Developer documentation for more information on these environment
variables.
15 - 2 Runtime Behavior Headstart Oracle Designer 6.5 - User Guide

The format of the time component can be set by calling procedure
QMS$CONFIG.SET_TIME_FORMAT in procedure QMS$INIT_APPLICATION.
Apart from supporting a general desire to be able to change this date format, Headstart has to
change the date format to support the calendar window on character items. (Used in the report
launch form.)
Block Initializations
Block and item initialization is handled per window. The WHEN-WINDOW-ACTIVATED

trigger (indirectly) calls procedure QMS$BLOCK.INIT_BLOCKS_IN_WINDOW which in
turn calls procedure QMS$BLOCK.INIT for each block in the window.
As part of the block initialization, all items within the block are also initialized.
Blocks in subsequent windows are only initialized when the user navigates to the window,
preventing unnecessary initialization overhead at forms start-up.
This section discusses the runtime block initialization settings performed by Headstart.
Block Navigation Style

The default navigation style for all single-record blocks inheriting from CGSO$BLOCK is
‘Change Block’. If there are no other blocks in the window, this setting is changed at runtime
into ‘Same Record’, to allow for navigation wrapping.
Note that if there are multiple blocks in the same window, the NAVWRP = Yes and
NAVBWN = Yes preference settings already ensure that navigation wraps round within the
window.
Allowed Block Operations

If the form is called in query-only mode, the insert, update and delete allowed properties are
switched off.
Item Initializations
This section discusses the runtime item initialization settings performed by Headstart.
Insert Only Items

All insert-only items in a block that is both insertable and updateable, are stored in a record
group. This record group is used during the post-query event to change the background color
of insert-only items to the read-only color as set by the user through the ‘Edit Preferences’
menu option, and to make the items non-navigable.

Update Only Items
All update-only items in a block that is both insertable and updateable, are stored in a record
group. Regardless of the block operations allowed, the background color of these items is set
to the read-only color as set by the user through the ‘Edit Preferences’ menu option.
Required Items
Headstart suggests that you use the following settings in the Registry.dat file to set the
background color of required items to a light yellow as recommended for the Oracle Look
and Feel (OLAF).
app.ui.requiredFieldVA=true
# The background color is specified as an RGB triple.
app.ui.requiredFieldVABGColor=255,242,203
However, users can also use the ‘Edit Preferences’ menu option to change the prompt of all
required items that are insertable to a user specified color.
If the user has chosen to set this option and if the block allows insert, the prompt of all
required items that are insertable is set to the required item color as set by the user.
Read Only Items

In line with the Oracle Look and Feel (OLAF), Oracle Webforms provides a parameter which
can be set in the Base HTML file for your application which automatically handles setting the
background color for read-only items to a light gray.
PARAM NAME="readOnlyBackground" VALUE="automatic"
However, there are two problems with this feature.
• If you have used read-only items to create dynamic prompts, you don’t want these
items to have a gray background. Headstart provides a special object,
QMSSO$TEXT, in the object library which you can reference in the Template /
Library Object property of these items. QMSSO$TEXT uses a special java class to set
the background of these items to match the canvas color for the colorScheme
parameter specified in the Base HTML file. Unfortunately, the readOnlyBackground
parameter overrides all other settings including the java class in QMSSO$TEXT.
• This parameter automatically colors all poplists gray in order to contrast between
poplists and combo boxes.
Therefore, Headstart recommends that you do not use the parameter readOnlyBackground in
your Base HTML file.
Instead, Headstart provides an alternate mechanism which identifies all read-only items (that
don’t use QMSSO$TEXT) and sets the background color to the read-only color as specified
by the user through the ‘Edit Preferences’ menu option.
Headstart sets the background color of poplists to ‘white’ instead of using the automatic
setting. The Headstart mechanism described above takes care of graying out poplists that are
read-only.

Item Tooltip
By default, the item tooltip property is not populated by the Form Generator. Headstart
supports this Developer feature by copying at runtime the hint text of the item (populated
with the repository hint text) to the item tooltip, if the ‘Show Item Hint’ menu option is
checked. Note that any Headstart specific tags in the hint text are stripped off before the hint
text is copied to the tooltip.
Repositioning of Items
Headstart allows you to align an item with another ‘master’ item by repositioning the item at
runtime. To do so, you specify the name of the ‘master’ item in the hint text of the item that
must be aligned, enclosing the item name between <AI> and </AI> tags. For example:
<AI>ORL.AMOUNT</AI>
This is particularly useful to align summary items with the item that is summarized.
Assigning a Special Visual Attribute

You can specify the name of a visual attribute that should be assigned at runtime to the item.
To do so, you specify the name of the visual attribute in the hint text of the item, enclosing
the visual attribute name between <VA> and </VA> tags. For example:
<VA>QMS$BOLD</VA>
Note that although this is a quick way to set a special visual attribute, you can achieve the
same result by creating a new source item object in the object library, and set the
template/Library Object property of this item in the repository to the name of the new source
item.
Adding Your Own Block and Item Initialization
The Headstart block and item initialization routines contain hooks to allow you to easily plug
in your own runtime initializations. These hooks are provided through two procedures in
qmsevh65, QMS$INIT_BLOCK and QMS$INIT_ITEM, which are called twice for each
block and each item in the form:
• QMS$INIT_BLOCK is called both before and after the Headstart block initializations
as discussed before. In addition to the block name and ID, this procedure contains a
third parameter which indicates the call sequence: BEFORE or AFTER the Headstart
block initialization code
• QMS$INIT_ITEM is called both before and after the Headstart item initializations as
discussed before. In addition to the Item Name, Item ID and Item Type, this
procedure contains a fourth parameter which indicates the call sequence: BEFORE or
AFTER the Headstart item initialization code
To add your own initialization code, you simply drag and drop these procedures to your
application or module library, and add the required initialization code. You should make sure
your library is attached before qmsevh65 to ensure your modified version of these hook
procedures will be executed.

Inter-Form Navigation
Headstart allows you to implement inter-form navigation with the following features:
• When calling a form from another form it is possible to use either OPEN_FORM or
CALL_FORM as the call method.
• when using OPEN_FORM, either a new database session or the same database session
can be used.
• Increased performance as library data are shared between forms, when a call method
other then OPEN_FORM with new database session is used.
• ability to keep the same menu as the calling form, regardless of the call method
• ability to invoke the called form in query-only mode, regardless of the call method
• ability to specify the window position of the first window in the called form, relative
to the active window in the calling form.
Argument Passed Values and Named Passed Values
Designer provides the ability to pass context information from one form to another by
defining Argument Passed Values (APVs) and Named Passed Values (NPVs). Refer to the
Designer online help for more information.
Headstart leverages the powerful concept of APVs and NPVs to implement the functionality
described above:
• Set Named Passed Value CALL_METHOD to one of the following:

• 'QMS$AI_OPEN_FORM', if an OPEN_FORM must be used.
• 'QMS$AI_CALL_FORM', if CALL_FORM must be used as the call method.
• By default, the OPEN_FORM built-in uses the NO_SESSION parameter. If you want
to open a new database session with OPEN_FORM, you must set Named Passed
Value SESSION_MODE to SESSION.
• If the called form must be started in query-only mode, set Named Passed value
QUERY_MODE to QUERY_ONLY
• By default the called form will use its own menu, as specified in the FMNDMA
preference. If you want the called form to keep the current application menu, you
must set Named Passed Value SWITCH_MENU to 'NO_REPLACE'. The application
menu can be set/modified by calling procedure
QMS$APPLICATION.SET_START_MENU in procedure
QMS$INIT_APPLICATION in your application library.
• By default the first window of the called form will cascade relative to the active
window of the calling form. If you want a different window position, you can add a
user-defined Named Passed Value called QMS$WINDOW_POS, and set this NPV to
one of the following allowable values

• CENTER
• RIGHT
• BELOW
• OVERLAP
Sharing of Library Data
Headstart uses the SHARE_LIBRARY_DATA parameter when calling another form through
the QMS$AI_OPEN_FORM or QMS$AI_CALL_FORM built-in. By sharing library data,
performance is increased, as multiple forms share the same instance of a library.
As a result of using this parameter, package variables that are assigned in one form keep their
value when another form is invoked that has the same library attached.
Note that library data are never shared when a new database session is opened, which will
happen when you set Named Passed Value SESSION_MODE to SESSION.

Multi-Select Functionality
Clear or Delete Multiple Selected Records
You can apply the Headstart multi-select functionality to the standard form functions, Clear
Record and Delete Record.
• Set the Template/Library Object of the module component to

'QMSSO$MSEL_BLOCK and generate the form.
The clear record and delete record functions will operate on the selected records.
If no record is selected, the current record is cleared/deleted, just like in a normal block
without multi-select functionality.
If multiple records are selected and the deletion of a given record fails due to referential
integrity constraints, that record will not be deleted and remains selected. The records which
do not fail will be deleted.
Perform User-Defined Action on Multiple Selected Records
You can use the Headstart Multi-Select functionality for your own user-defined actions.
Perform the following steps:
• Set the Template/Library Object of the multi-select module component to

'QMSSO$MSEL_BLOCK
• Add a user-defined trigger to the multi-select module component which contains the
action that must be performed on each selected record
• Create an action item of type Custom, and define a WHEN-BUTTON-PRESSED
trigger for this item with the following code:
QMS$MSEL.PROCESS_RECORDS('<NAME OF USER DEFINED
TRIGGER>','<NAME OF MODULE COMPONENT>');
Note that instead of creating an action item, you can also create an unbound item of type
'Custom', set the display datatype to 'Button', and add the call to
QMS$MSEL.PROCESS_RECORDS to the PL/SQL Block property. This allows you to
place the button anywhere you want. (Action items are always generated at the bottom of a
module component or window.)
Multi-Select LOV
This functionality is completely driven by repository definitions, you do not need any
PL/SQL logic in the repository or a module library to implement this functionality.
It is important to understand that the multi-select LOV window will be part of the same
module definition that contains the intersection table. The LOV window cannot be generated
as a separate LOV form!

Perform the following steps to generate the required functionality:
• Create a module with a master and a detail module component in Designer with the
detail module component representing the intersection table.
• Set Template/Library Object property of the item that should invoke the LOV window
when KEY-LISTVAL is pressed, to 'QMSSO$MSEL_LOV_ITEM'.
• If the detail module component that is based on the intersection table includes a
lookup table usage on the multi-select LOV item, all lookup items (displayed and non-
displayed) should have the 'Display in LOV' property set to No.
• Add another Module Component to the module with the base table being the LOV
table and the columns you want to see in the LOV window. Name the LOV Module
Component as follows:
ML_<target block name>
For example, a multi-select LOV on block PEM, will have the LOV module
component named ML_PEM.
• Set Template/Library Object property of the LOV Module Component to

'QMSSO$MSEL_BLOCK'.
• Define a WHERE clause which restricts the records displayed in the LOV module
component to those not yet added to the intersection table. Refer to the definition of
module QFD0016F in the QMS502 application system, for an example.
• Set Template/Library Object of the window containing the LOV Module Component
to 'QMSSO$MODAL_DIALOG_WINDOW'.
• Include Reusable Module Component QMS_MSEL_LOV_BUTTONS as the last
module component in the LOV window.
• For each item in the LOV Module Component that needs to be copied to the target
module component, the hint text property should be set as follows to indicate the
target item the value must be copied to:

<MS>target item name </MS>
For example, item EMPNO in module component ML_PEM could have a hint
text like: MS>EMP_EMPNO</MS>
By default, a query will be executed automatically on the LOV table. If you want the user to
enter search criteria first (which you should add as the first module component in the LOV
window), you must set the following tag in the hint text of the item that has the LOV
attached:
<ML>FILTER_BEFORE_DISPLAY</ML>
The Headstart demo application contains a module, hsd00012f which implements the multi
select LOV functionality. This module definition may clarify the steps required.
Shuttle Control Object Selector
This required application form allows you to create and manipulate a set of selected items.
You can use this as an alternative to the multi-select LOV or for any action you need to
perform on a user-defined set of records.
The Report Launch Form, qms0012f, uses this feature to implement multi-select report
parameters.
You can display and manipulate the shuttle control object selector form through the following
API.

procedure qms$shuttle_ctrl.display
( p_shuttle_ctrl_name in varchar2
, p_shuttle_ctrl_title in varchar2
, p_shuttle_ctrl_query in varchar2
, p_shuttle_ctrl_datatype in varchar2
);
Use this procedure to open the shuttle control object selector form (qms0014f). If the
requested shuttle control name does not yet exist, it is created and the window is initialized
with unselected records from the query. If the requested shuttle control name already exists,
the window displays the current state of selected and unselected records. (This happens when
the user re-visits a shuttle control they have already visited.)
The shuttle control title is used as the window title.
The query must be an sql query using the following format.

select <value column(s)> "VALUE",
<description column(s)> "DESCRIPTION",
from <table(s)>
where <condition>
;
where...
<value column(s)>
• 1 character value
• can be multiple columns concatenated
• must be a UNIQUE identifier (e.g. Primary Key)
• this value will be hidden from the user
• must use the alias "VALUE"
<description column(s)>
• 1 character value
• can be multiple columns concatenated
• should be unique (e.g. Unique Key) so the user can
• always distinguish between values
• this value will be displayed to the user
• must use the alias "DESCRIPTION"
function qms$shuttle_ctrl.get_return
) return varchar2;
This function returns 'OK' if the user closed the shuttle control window by pressing the OK
button. It returns 'CANCEL' if the user pressed the Cancel button.
This function should be called immediately after calling procedure display.

procedure qms$shuttle_ctrl.set_return
, p_shuttle_ctrl_return in varchar2
);
This procedure records the return value of the specified shuttle control in the global shuttle
control list. This procedure is called by the shuttle control window.
function qms$shuttle_ctrl.count_selected
) return number;
This function returns the number of rows selected by the user in the requested shuttle control.
function qms$shuttle_ctrl.get_value
, p_selected_record in number
) return varchar2;
This function returns the VALUE from the requested shuttle control and selected record.
function qms$shuttle_ctrl.get_description
, p_selected_record in number
) return varchar2;
This function returns the DESCRIPTION from the requested shuttle control and selected
record.
function qms$shuttle_ctrl.get_value_list
, p_delimiter in varchar2 default ','
) return varchar2;
This function returns a list of all selected VALUEs from the requested shuttle control. The list
is delimited by the requested delimiter which defaults to a comma.
function qms$shuttle_ctrl.get_description_list
) return varchar2;
This function returns a list of all selected DESCRIPTIONs from the requested shuttle control.
The list is delimited by the requested delimiter which defaults to a comma.
procedure qms$shuttle_ctrl.reset
);
This procedure resets all items in the requested shuttle control to unselected. If the requested
shuttle control does not exist, an error is returned.
procedure qms$shuttle_ctrl.cleanup
( p_form_name in varchar2 default null
);
This procedure closes all shuttle controls that have been opened by the requested form. If no
form is given, the procedure closes shuttle controls for the current form.

This procedure should be called in the EXIT_FORM trigger of any form that calls the shuttle
control form.
procedure qms$shuttle_ctrl.default_selected
, p_shuttle_ctrl_title in varchar2
, p_shuttle_ctrl_query in varchar2
, p_datatype in varchar2
, p_default_value in varchar2
, p_default_description in varchar2
);
This procedure defaults the requested shuttle control to the given value which may contain
one or more objects delimited by the requested delimiter.
Transfer Multiple Details to Other Master Record

This is a highly specialized type of shuttle control form which is used to set the value of a
foreign key column in a record. Like the multi-select LOV, this functionality is mostly driven
by repository definitions. You only need to write some PL/SQL logic if you allow querying
on the master and/or detail block (see Known Restrictions). Also, unlike the Shuttle Control
Selector Form, this is not implemented as a separate form.
To generate a form which uses multi-select functionality to transfer multiple details to another
master record, you must perform the following steps:

• Set Template/Library Object property of the source and target module components to
'QMSSO$MSEL_BLOCK'.
• Add unbound items of type BUTTON, and set the label of these buttons to something
like 'Insert <<' or 'Delete>>'.
• The PL/SQL block of the buttons that perform the transfer of the records must be set
as follows:
QMS$MSEL.PROCESS_RECORDS('TRANSFER_FK','<source
block>','<destination block>');
The Headstart demo application contains a form, hsd0008f, which implements the transfer of
multiple records to another master (on the second window). This module definition may
clarify the steps required.
Known Restrictions
If you transfer a record, transfer it back again, and re-transfer it (three moves in a row), you
will get error ‘QMS-00123: Cannot move record again, requery the record first’. This error is
raised to prevent the ‘Record Changed by another user’ error, which would have been
confusing to the user. The internal implementation of this functionality makes it impossible
to remove this limitation.
If you allow query on the master block, and/or the detail block, you should add application
logic to synchronize with the block that contains the records not linked to the current master
record:
• Create an ON-POPULATE-DETAILS trigger on the master block that re-queries the

‘unlinked’ block.
• Create KEY-ENTQRY and KEY-EXEQRY triggers in the detail block and the
‘unlinked’ block to synchronize both blocks if the user attempts to query while
transferred records exist which are not yet saved.

Item Relations
There are many business rules involving relationships between items which can be enforced
in the Form using dynamic enabling and disabling of items. This is more user friendly than
allowing the user to enter incorrect information and then only raising an error when the user
commits the changes to the database.
• Dependent Items
• Conditionally Dependent Items
• Multiple Dependent Items
• Two Master Items and One Dependent Item
• Cascading Dependence
• Mutually Exclusive Items
• Mutually Inclusive Items
• Mutually Inclusive Items with Dependents
• Conditionally Mandatory Items
Dependent Items
To make a text item, check box or poplist that is enabled only when a master item is
populated, use the procedure qms$item_instance.set_dependent_field.
• The dependent item is either cleared or made invalid when the master item changes.
• If the master item is NULL or the condition is FALSE, the dependent item is disabled.
In this example, a block order has items item_type and item_name. Item_name is dependent
on item_type. Thus, item_name is enabled only when item_type is NOT NULL.
Step 1
In the ‘POST-TEXT-ITEM’ trigger for item_type, add the following code.
qms$item_instance.set_dependent_field
( 'INIT'
, 'order.item_type' -- master item
, 'order.item_name' -- dependent item
);
(See note 3 below)
Step 2
In the WHEN-CREATE-RECORD trigger for the order block, add the following code.
( 'INIT'
, 'ORDER.ITEM_TYPE' -- master item
, 'ORDER.ITEM_NAME' -- dependent item
);

Step 3
In the POST-QUERY trigger for the order block, add the following code.
( 'POST-QUERY'
);
Step 4
Create a form level user-named trigger called ‘UNDO_DEPENDENT’ with the following
code.
( 'POST-QUERY'
);
Note 1
In a multi-record block, if the dependent item is the last item in the record, the cursor
navigates to the next record when tabbing from the master. To work around this behavior,
code a KEY-NEXT-ITEM trigger that does a VALIDATE(item_scope) and then a
NEXT_ITEM.
Note 2
If the dependent item is a required list or option group, set the ‘invalidate’ parameter in the
call to qms$item_instance.set_dependent_field to TRUE. When this flag is TRUE, the
dependent item is marked as invalid rather than cleared.
Note 3
If the master item is displayed as a poplist, radio button, or checkbox, you can use the
appropriate trigger ‘WHEN-LIST-CHANGED’, ‘WHEN-RADIO-CHANGED’, or ‘WHEN-
CHECKBOX-CHANGED’ instead of the ‘POST-TEXT-ITEM’ trigger in Step 1.
Conditionally Dependent Items
A conditionally dependent item is enabled or disabled depending on the particular value of

the master item.
In this example, block order has items item_type and size. Size is only enabled when
item_type is ‘SHOES’.
Step 1
( 'INIT'
, (:order.item_type = 'SHOES') -- condition
, 'order.size' -- dependent item

);
(See note 3 in Dependent Items)
Step 2
( 'INIT'
, 'ORDER.SIZE' -- dependent item
);
Step 3
( 'POST-QUERY'
);
Step 4
code.
( 'POST-QUERY'
);
Multiple Dependent Items
There are cases where multiple items are dependent on a single master item. For example,
only certain item_types can specify a color and size. Therefore, the color and size fields are
dependent on the master field item_type, and there are enabled only when item_type is
RAINCOAT.
Step 1
( 'INIT'
, (:order.item_type = 'RAINCOAT') -- condition
);
( 'INIT'
, 'ORDER.COLOR' -- dependent item
);

Step 2
( 'INIT'
);
( 'INIT'
);
Step 3
( 'POST-QUERY'
);
( 'POST-QUERY'
);
Step 4
code.
( 'POST-QUERY'
);
( 'POST-QUERY'
);
Two Master Items and One Dependent Item
There may also be cases where an item is dependent on two master items. Suppose that
difference sizes of sweaters come in different colors. You cannot fill in the color of the
sweater until you have filled in both item_type and size.
Step 1
In the ‘POST-TEXT-ITEM’ triggers for both item_type and size, add the following code.
( 'INIT'
, ((:order.item_type is not null) and
(:order.size is not null)) -- condition

);
Step 2
( 'INIT'
);
Step 3
( 'INIT'
);
Step 4
code.
( 'POST-QUERY'
);
Cascading Dependence
With cascading dependence, item_3 depends on item_2, which in turn depends on item_1.
Usually all items are in the same block.
For example, the block order contains the items vendor, site, and contact. The list of valid
sites depends on the current vendor.
• Whenever vendor is changed, site is cleared.

• Whenever vendor is null, site is disabled.
The list of valid contacts depends on the current site.
• Whenever site is changed, contact is cleared.

• Whenever site is null, contact is disabled.
Step 1
In the ‘POST-TEXT-ITEM’ trigger for vendor, add the following code.

( 'INIT'
, 'ORDER.VENDOR' -- master item
, 'ORDER.SITE' -- dependent item
);
Step 2
In the ‘POST-TEXT-ITEM’ trigger for site, add the following code.
( 'INIT'
, 'ORDER.SITE' -- master item
, 'ORDER.CONTACT' -- dependent item
);
Step 3
( 'INIT'
);
( 'INIT'
);
Step 4
( 'POST-QUERY'
);
( 'POST-QUERY'
);
Step 5
code.
( 'POST-QUERY'
);
( 'POST-QUERY'

);
Mutually Exclusive Items
Use the procedure qms$item_instance.set_exclusive_field to code two items where only one
item is valid at a time.
If both mutually exclusive items are NULL, then both items are navigable. If one item is
populated, then the other item is unnavigable (you can still click there), and any value in that
item is cleared.
If one item must not be null, set the Required property of both items to True. If both items
may be null, set the Required property of both items to False.
Qms$item_instance.set_exclusive_field reads the initial Required property and dynamically
manages the Required properties of both items.
You can also use qms$item_instance.set_exclusive_field for a set of three mutually exclusive
items. For more than three items, you must write your own custom logic.
In this example, a block lines has mutually exclusive items credit and debit.
Step 1
In the ‘POST-TEXT-ITEM’ triggers for both credit and debit, add the following code.
qms$item_instance.set_exclusive_field
( 'INIT'
, 'LINES.CREDIT'
, 'LINES.DEBIT'
);
Step 2
In the PRE-RECORD trigger for the line block, add the following code.
( 'PRE-RECORD'
, 'LINES.CREDIT'
, 'LINES.DEBIT'
);
Step 3
In the POST-QUERY trigger for the line block, add the following code.
( 'POST-QUERY'
, 'LINES.CREDIT'
, 'LINES.DEBIT'
);

Step 4
If one of your mutually exclusive items is required, then in the WHEN-CREATE-RECORD
trigger for the line block, add the following code.
set_item_property
( 'lines.credit'
, item_is_valid
, property_true
);
set_item_property
( 'lines.debit'
, item_is_valid
, property_true
);
Step 5
code.
( 'POST-QUERY'
, 'LINES.CREDIT'
, 'LINES.DEBIT'
);
Mutually Inclusive Items
Use the procedure qms$item_instance.set_inclusive_field to code a set of items where the

items are not required, but if any of the items is entered, all of the items must be entered.
The item values may be entered in any order. If all of the items are null, then the items are
optional.
You can use the procedure qms$item_instance.set_inclusive_field for up to five mutually

inclusive items. For more than five items, you must write your own custom logic.
In this example, a block payment_info has two mutually inclusive items payment_type and
amount.
Step 1
In the ‘POST-TEXT-ITEM’ triggers for both payment_type and amount, add the following
code.
qms$item_instance.set_inclusive_field
( 'INIT'
, 'PAYMENT_INFO.PAYMENT_TYPE'
, 'PAYMENT_INFO.AMOUNT'
);
Step 2
In the PRE-RECORD trigger for the payment_info block, add the following code.

( 'PRE-RECORD'
);
Step 3
In the POST-QUERY trigger for the payment_info block, add the following code.
( 'POST-QUERY'
);
Step 4
code.
( 'POST-QUERY'
);
Mutually Inclusive Items with Dependent Items
Lets look at a more complex example combining dependent items and mutually inclusive
items.
This example shows a block payment_info with mutually inclusive items payment_type and
amount. (just as in the previous section)
The block also contains two regions, one for check information and one for credit card
information. Check information has a single item, check_number. Credit Card information
has three items: card_type, card_number, and expiration_date.
Payment Type can be Cash, Check, or Credit.
• When Payment Type is Check, the Check Information region is enabled.

• When Payment Type is Credit, the Credit Card Information region is enabled.
Step 1
In the ‘POST-TEXT-ITEM’ trigger for payment_type, add the following code.
( 'INIT'
);
( 'INIT'
, (:payment_info.payment_type = 'Check')
, 'PAYMENT_INFO.CHECK_NUMBER'

);
( 'INIT'
, (:payment_info.payment_type = 'Credit')
, 'PAYMENT_INFO.CARD_TYPE'
);
( 'INIT'
, 'PAYMENT_INFO.CARD_NUMBER'
);
( 'INIT'
, 'PAYMENT_INFO.EXPIRATION_DATE'
);
Step 2
In the ‘POST-TEXT-ITEM’ trigger for amount, add the following code.
( 'INIT'
);
Step 3
In the PRE-RECORD trigger for the payment_info block, add the following code.
( 'PRE-RECORD'
);
Step 4
In the WHEN-CREATE-RECORD trigger for the payment_info block, add the following
code.
( 'INIT'
);
( 'INIT'
);
( 'INIT'
);

( 'INIT'
);
( 'INIT'
);
Step 5
In the POST-QUERY trigger for the payment_info block, add the following code.
( 'POST-QUERY'
);
( 'POST-QUERY'
);
( 'POST-QUERY'
);
( 'POST-QUERY'
);
( 'POST-QUERY'
);
Step 6
code.
( 'POST-QUERY'
);
( 'POST-QUERY'
);
( 'POST-QUERY'
);

( 'POST-QUERY'
);
( 'POST-QUERY'
);
Conditionally Mandatory Items
Use the procedure qms$item_instance.set_required_field to code an item that is only

mandatory when a certain condition is met. If the condition is FALSE, the dependent item is
optional. Any value in the dependent item is not cleared. If an item is both conditionally
required and dependent, call qms$item_instance.set_dependent_field before calling
qms$item_instance.set_required_field.
In the example, the block purchase_order has items quantity, unit_price and vp_approval.
Vp_approval is required when total is more than $10,000. (total = quantity * unit_price)
Step 1
In the ‘POST-TEXT-ITEM’ triggers for quantity and unit_price, add the following code.
qms$item_instance.set_required_field
( 'INIT'
, (:purchase_order.quantity * :purchase_order.unit_price)
> 10000 -- condition
, 'purchase_order.vp_approval' -- dependent item
);
Step 2
In the PRE-RECORD trigger for the order block, add the following code.
( 'PRE-RECORD'
);
Step 3
( 'POST-QUERY'
);

Step 4
code.
( 'POST-QUERY'
);
Example from the Headstart Demo
In the Headstart Demo Application, the form Subtype Consistency, HSD0010F, is used to
maintain both customers and suppliers. The Type item identifies whether the current row is a
customer or supplier.
If the row is a Supplier, the following items are affected and should be displayed
accordingly.
Item Display Attributes

Category grayed out
Discount grayed out
Credit Limit grayed out
Contact Person enabled
Fax enabled and required
Email Address enabled
If the row is a Customer, the following items are affected and should be displayed
accordingly.
Item Display Attributes

Category enabled
Discount enabled
Credit Limit enabled and required
Contact Person grayed out
Fax grayed out
Email Address grayed out
Necessary Information
• Identify the module component which contains the conditional items.
Example: BUR
• Identify the ‘master’ item.
Example: BUR_TYPE
• Identify the dependent items.
Example: CATEGORY
DISCOUNT
CREDIT_LIMIT
CONTACT_PERSON

EMAIL_ADDRESS
FAX_NUMBER
• Identify the conditionally mandatory items.
Example: CREDIT_LIMIT
FAX_NUMBER
• Identify the condition(s).
Example:
If BUR_TYPE=’S’ then
CONTACT_PERSON is dependent
EMAIL_ADDRESS is dependent
FAX_NUMBER is dependent and mandatory
If BUR_TYPE=’C’ then
CATEGORY is dependent
DISCOUNT is dependent
CREDIT_LIMIT is dependent and mandatory
WHEN-LIST-CHANGED trigger for BUR_TYPE
-- dependent items
( 'INIT'
, :BUR.BUR_TYPE='S'
, 'BUR.CONTACT_PERSON'
);
( 'INIT'
, :BUR.BUR_TYPE='S'
, 'BUR.EMAIL_ADDRESS'
);
( 'INIT'
, :BUR.BUR_TYPE='C'
, 'BUR.CATEGORY'
);
( 'INIT'
, :BUR.BUR_TYPE='C'
, 'BUR.DISCOUNT'
);
( 'INIT'
, :BUR.BUR_TYPE='S'
, 'BUR.FAX_NUMBER'
);
( 'INIT'
, :BUR.BUR_TYPE='C'
, 'BUR.CREDIT_LIMIT'
);
-- conditionally mandatory items

( 'INIT'
, :BUR.BUR_TYPE='S'
, 'BUR.FAX_NUMBER'
);
( 'INIT'
, :BUR.BUR_TYPE='C'
);

POST-QUERY trigger for module component BUR
-- dependent items
( 'POST-QUERY'
, :BUR.BUR_TYPE='S'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='S'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='C'
, 'BUR.CATEGORY'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='C'
, 'BUR.DISCOUNT'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='S'
, 'BUR.FAX_NUMBER'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='C'
);

( 'POST-QUERY'
, :BUR.BUR_TYPE='S'
, 'BUR.FAX_NUMBER'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='C'
);
WHEN-CREATE-RECORD trigger for module component BUR
-- dependent items
( 'INIT'
, :BUR.BUR_TYPE='S'
);
( 'INIT'
, :BUR.BUR_TYPE='S'
);
( 'INIT'
, :BUR.BUR_TYPE='C'
, 'BUR.CATEGORY'

);
( 'INIT'
, :BUR.BUR_TYPE='C'
, 'BUR.DISCOUNT'
);
( 'INIT'
, :BUR.BUR_TYPE='S'
, 'BUR.FAX_NUMBER'
);
( 'INIT'
, :BUR.BUR_TYPE='C'
);
PRE-RECORD trigger for module component BUR

( 'PRE-RECORD'
, :BUR.BUR_TYPE='S'
, 'BUR.FAX_NUMBER'
);
( 'PRE-RECORD'
, :BUR.BUR_TYPE='C'
);
UNDO-DEPENDENT trigger for module hsd0010f
-- dependent items
( 'POST-QUERY'
, :BUR.BUR_TYPE='S'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='S'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='C'
, 'BUR.CATEGORY'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='C'
, 'BUR.DISCOUNT'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='S'
, 'BUR.FAX_NUMBER'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='C'

);

( 'POST-QUERY'
, :BUR.BUR_TYPE='S'
, 'BUR.FAX_NUMBER'
);
( 'POST-QUERY'
, :BUR.BUR_TYPE='C'
);

Date Handling
Headstart uses the date formats you can specify in various environment variables, and uses
this format to handle and display dates.
Date Format Environment Variables
Oracle Forms supports the following date format environment variables:
• FORMS60_OUTPUT_DATE_FORMAT (display format)

• FORMS60_OUTPUT_DATETIME_FORMAT (display format)
• FORMS60_USER_DATE_FORMAT (entry format; this variable can hold multiple
formats, but Headstart will only use the first format)
• FORMS60_USER_DATETIME_FORMAT (entry format; this variable can hold
multiple formats, but Headstart will only use the first format)
• NLS_DATE_FORMAT (obsolete, supported for upwards compatibility)
Oracle Reports only uses the NLS_DATE_FORMAT.
Refer to the Oracle Developer documentation for more information on these environment
variables.
Headstart evaluates the value of these environment variables to determine the date and
datetime format that is used to handle and display dates.
The date format is determined as follows:
1. Value of FORMS60_OUTPUT_DATE_FORMAT. If not set,

2. First value of FORMS60_USER_DATE_FORMAT. If not set,
3. Value of NLS_DATE_FORMAT. If not set,
4. Format DD-MON-YYYY.
The datetime format is determined as follows:
1. Value of FORMS60_OUTPUT_DATETIME_FORMAT. If not set,

2. First value of FORMS60_USER_DATETIME_FORMAT. If not set,
3. Value of date format (see above), concatenated with a space and the time format as
set by the developer through call to QMS$APPLICATION.SET_TIME_FORMAT.
If this procedure is not used to set the time format, the time format used is
'HH24:MI:SS'.
Note that dates entered into a CHAR item (for example, date parameters in the report launch
form!) must be entered in the format of FORMS60_OUTPUT_DATE_FORMAT. The
formats in FORMS60_USER_DATE_FORMAT are ignored for CHAR items.

Forms PLSQL_DATE_FORMAT and BUILTIN_DATE_FORMAT
In Oracle Forms, you can set the following properties using the
SET_APPLICATION_PROPERTY built-in.
• PLSQL_DATE_FORMAT
• BUILTIN_DATE_FORMAT
Oracle Form Generator generates the following code in the PRE-FORM trigger to set these
two properties (and NLS_DATE_FORMAT):
set_application_property(PLSQL_DATE_FORMAT, 'YYYY/MM/DD
HH24:MI:SS');
set_application_property(BUILTIN_DATE_FORMAT, 'YYYY/MM/DD
HH24:MI:SS');
forms_ddl('ALTER SESSION SET NLS_DATE_FORMAT =
''YYYY/MM/DD HH24:MI:SS''');
As you can see, the date formats are hardcoded into the generated forms. Headstart re-
executes the same statements after the generated code, but uses the datetime format from the
environment variables as described in the previous section, instead of a hardcoded format.
This ensures that the same date format mask is used in all date-related operations.
Recommended Approach
Always specify the FORMS60_OUTPUT_DATE_FORMAT and

FORMS60_OUTPUT_DATETIME_FORMAT environment variables. Both formats should
include four-digit rendering of the year (either YYYY or RRRR). The date component of
both environment variables should be the same.
Only specify the FORMS60_USER_DATE_FORMAT and

FORMS60_USER_DATETIME_FORMAT environment variables if you want to provide the
end user with quick date entry facilities in a format different from
FORMS60_OUTPUT_DATE_FORMAT.
For example, with a format of DD in FORMS60_USER_DATE_FORMAT, the user only has

to enter the day number, the month and year will be added based on the system date. This is
convenient for the end user, but increases the risk of wrong dates being entered.

CHAPTER
16 End User Assistance
This chapter discusses the following topics related to end user assistance in your generated
application:
• Message Handling
• Online Help
• Item Hint and Tooltips
• About This Record
• About This Application
Headstart Oracle Designer 6.5 - User Guide End User Assistance 16 - 1

Message Handling
This section discusses the message handling system provided with Headstart. The first
subsection provides an overview of the functionality, followed by general conditions that
must be met to use the message handling system successfully.
The remaining subsections discuss how to perform specific tasks related to message handling.
Message Handling Features
The Headstart message handling provides you with the following functionality:
• The messaging is multi-lingual. The end user can set their preferred language and will
receive all application messages in this language. (… provided of course that the
message translations have been added to the Headstart Message Dictionary.)
• You can use up to 10 substitution parameters while invoking the message procedure.
The substitution parameters can be used in the message text and/or in the help text.
• If you have recorded the cause and action of a message in the message table (help_text
column), the message alert box is shown with an extra 'Help' button which shows a
'Help on Message' form when pressed.
• Messages hardcoded by the Form Generator are captured and replaced with an error
message code which subsequently is used to get the corresponding message text from
the message table.
• Server-side application errors raised in Table API, database triggers, or stored
procedures and functions, are trapped and stripped to extract the message code that
must be used to fetch the message text from the message table.
• Declarative constraint violations in the Oracle database are trapped and replaced with
a user-friendly message.
• Unwanted FRM and ORA messages can be suppressed or rephrased.
• You can set the severity of a message:
16 - 2 End User Assistance Headstart Oracle Designer 6.5 - User Guide

• Information: information that is displayed to the user. This information is
displayed in an alert box to make sure the user sees the information and dismisses
the alert box.
• Warning: a possible error has occurred or the end-user has to confirm the action
before they continue. The user can halt processing or accept the conditions and
continue with the processing.
• Error: a fatal error has occurred and all processing will stop.
• Message: information is passed to the user but it is displayed on the message line.
The information provided is not so vital that the user has to be aware of it.
• Question: a question is presented to the end-user and they have to accept (Yes) or
reject (No) it.
Usage Conditions
Two general conditions must be met to be able to use the Headstart message handling system:
• Form Generator preference MSGSFT should be set to QMS$FORMS_ERRORS

(already set in QMS65_RECOMMENDED).
• The Headstart modified version of package CG$ERRORS must be installed instead of
the default CG$ERRORS package shipped with Oracle Designer.
The CG$ERRORS package is used by the Designer Table API packages and triggers.
Headstart replaces this package with a Headstart specific version to ensure that messages
raised in the Table API, are handled in the same way as all other messages. The Headstart
version of this package replaces the hardcoded Table API errors, with a Headstart message
code which is used to access the Headstart message table.
Warning: Oracle Designer includes a call to (re)create the CG$ERRORS package when you
generate the Table API scripts from Designer. This call is included at the top of the shell .sql
script, and will look like this:
PROMPT Creating Table API Error Package CG$ERRORS
@ C:\ORANT\cgens70\sql\cdsaper.PKS
@ C:\ORANT\cgens70\sql\cdsaper.PKB
You must ensure that this version of the package is not loaded. The easiest way to ensure this
is to save the cdsaper.pks and .pkb scripts to another name and replace the contents in the
original scripts with a NULL statement. You have to repeat this step at each workstation
where Oracle Designer is installed.
If this script is inadvertently executed, the result depends on the user account you use to run
the script:
• If the user has a synonym pointing to the Headstart version of CG$ERRORS you will
get error ‘ORA-00955: name is already used by an existing object’ on the creation of
the package specification of CG$ERRORS, and the package body (without its
specification!) is created with numerous compilation errors. To correct this situation,
logon to SQL*Plus as the same user and execute the following command:
drop package body cg$errors;

• If the user is the owner of the Headstart version of CG$ERRORS, the result is more
damaging. The Headstart version of CG$ERRORS is replaced with the Designer
version. This invalidates the QMS$ERRORS and QMS_MESSAGE package bodies.
Furthermore, all TAPI packages and triggers that already existed are invalidated,
unless they are recreated in the script. When running a Headstart-generated
application, you will get the following error at start-up when you have overridden the
CG$ERRORS package:
FRM-40735: ON-ERROR trigger raised unhandled exception

ORA-06508.
To correct this situation, run the following scripts connected as the owner of the
Headstart Template Package database objects:
• cg$err.pks
• cg$err.pkb
• recompl.sql (possibly repeated until all objects are valid again)
The scripts are located in <headstart_home>\hst\scripts directory. The last script,
recompl.sql, should also be run under all other user accounts that have synonyms
pointing to the CG$ERRORS package you just recreated.
Handling Data Integrity Errors
Oracle Designer allows you to enter an ‘Error Message’ against the following constraint
objects:
• Primary Key Constraint

• Unique Key Constraint
• Foreign Key Constraint
• Check Constraint
When you record the actual message text in this property, this message text will be hardcoded
in the generated forms. We strongly recommend you not use these hardcoded messages,
because you will lose important functionality:
• No support for multiple languages

• No ability to provide additional help on the message
• Unless the table is the base table in the form, server-side violations of the constraint
will result in an Oracle error displayed to the end user of the form.
Instead, you should record a message code in the ‘Error Message’ property, and record this
message code and the constraint name in the message table, along with a message and help
text for each language you wish to support. There are several Headstart Utilities which add
messages to the message dictionary automatically. You can also use the Headstart
Foundation application Messages Form to add and edit messages manually.
Message Code
The message code used in the Headstart Message Dictionary must use the following format.

XXX-99999
where XXX is the 3 letter application code and 99999 is a 5-digit sequence number,
left-padded with 0’s as needed.
This format follows the precedent set in Forms messages (FRM-00001), Designer messages
(OFG-00001) and Server messages (ORA-00001).
Notice this format implies that you must follow the CDM Standard for naming applications
using 3-letter codes. For example, the Headstart Utility ‘Create Default Error Messages for
Constraints’ uses your application name to create error message codes. If you need to use a
longer name for your application, you can work around this restriction by also including a 3-
letter abbreviation in the application name as shown below.
MYAPP (MYA)
The utility will then use the value in parentheses as the application code in generated
messages.
Recording the Constraint Name

Oracle Form Generator creates an ON-ERROR trigger to trap server-side constraint
violations, and displays the correct message for you. However, there are two important
limitations to this functionality:
• Only constraints defined on the base table usages of your module are trapped. If for
example, you have a module with a block based on table A and you have a database
trigger on this table which does an update of table B, the ON-ERROR trigger will not
be able to replace the general Oracle constraint violation message raised by a violation
of a constraint on table B.
• Each time you add a key or check constraint you will have to regenerate your form to
update the ON-ERROR trigger
Both limitations go away if you record the constraint name in the Headstart message tables.
When a server-side constraint violation takes place, Headstart traps the Oracle error, strips the
constraint name from the Oracle Error, uses this constraint name to look up the proper
message in the message table, and displays this message to the end user instead of the Oracle
error
Note that this implies that you cannot use substitution parameters in key constraint and check
constraint messages, as each constraint message must have its own unique constraint name.
The additional work of creating separate messages can be automated using a Headstart utility,
as the next section explains.
Automatic Creation of Constraint Messages

The Headstart Utility ‘Create default messages for constraints’ assigns a message code to
each constraint in the repository, and creates a record in the message table. The message text
is based on a message template parameter for each type of constraint. If you have an existing
repository which already contains message text in the error message property, the utility will
replace this text with an error code, and store the recorded message text in the message tables,
ignoring the message template parameter values of the utility.
You can run this utility multiple times to insert messages for each language you need to
support.

Derived Data Integrity Errors
It is not possible to record an error message in the Designer repository for violations of the
following rules:
• Arc rules: either too many or too few columns filled in

• Non-updateable Unique Keys
• Non-transferable Foreign Keys
Headstart allows you to show a user-friendly error message for when these rules are violated
in the server (they are checked by the Table API).
For each possible rule violation, you can use the Headstart Utility ‘Create default messages
for constraints’ to add an error message to the message table. A special naming convention
for the constraint name property in the message table will allow Headstart to look up the
appropriate message in case of such a rule violation.
The naming conventions that apply are:
Rule Naming Convention
Arc rule, missing column <Table Name>_ARC<sequence number>_M
Arc rule, too many columns <Table Name>_ARC<sequence number>_T

filled in
Non-updateable Unique Key <UK Constraint Name>_NU
Non-transferable Foreign <FK Constraint Name>_NT

Key
Raising Application Messages
Application messages are coded in the application by you, the developer. You should ensure
that you use a unique message code and record the message code and text correctly in the
message handling tables. This is done using the Headstart Foundation Application.
You raise client-side and server-side messages by invoking procedure

QMS$ERRORS.SHOW_MESSAGE. The complete syntax of the procedure is
PROCEDURE show_message
( p_mesg IN VARCHAR2
, p_param0 IN VARCHAR2 DEFAULT NULL

, p_errtp IN VARCHAR2 DEFAULT NULL
, p_rftf IN BOOLEAN DEFAULT NULL
);
Use of the parameters:
• p_msg is the message code as it is stored in the message tables.

• p_param0 to p_param9 are substitution parameters you can use in the message text
and/or message help text.
• p_errtp specifies the error type ('E', 'I', 'W', 'M'), the error type stored in the Message
table is used if you do not specify this parameter.
• p_rftf : raise exception. By default the exception is raised dependent on the error type
(either in the qms message table or the p_errtp parameter). You can use this parameter
to override the default processing
Using Substitution Parameters

You can place a substitution parameter into the message text or help text of a message using
the special tags <p1> through <p10>.
Warning: The tags are case sensitive and must be in lowercase!
Example: User <p1> is not authorized to perform this action.
Overriding the Message Type

If you want to override the default error type and/or exception raising, you must use named
parameter assignments (unless you have a message with 10 substitution parameters).
Example: Message QMS-12345 which does not have any substitution parameters, is
recorded as an informational message in the message tables, but should be displayed as an
error, and processing should stop. The following statement will accomplish this:
qms$errors.show_message
( p_mesg => 'QMS-12345'
, p_errtp => 'E'
, p_rftf => TRUE
);
Note that procedure qms$errors.show_message is available at both the client and the server.
This allows you to drag and drop program units from the client to the server, and vice versa,
without the need to rewrite the message handling calls.
Raising Questions (Dialogs)
Sometimes a program needs to ask a question to the user and act on the feedback provided.
This can be done by specifying a message of type ‘Q’ (question) . Such a message will be
displayed in an alert with three buttons: Yes, No and Help.
To raise a question, use the qms$errors.show_message function which returns a boolean

value TRUE if the user pressed Yes and False if the user pressed No.

Example:
if qms$errors.show_message('QMS-00014')
then
exit_form;
end if;
Raising Informational Messages in the Server

Headstart allows you to display information messages which were raised by a program unit
executed in the server, but that should not stop processing.
To do so, you must call the informational message in the normal way, using
qms$errors.show_message. Directly after the call to the server-side program unit which
raises the message, you must add the following statement:
qms$trans_errors.display_messages;
This procedure call will read the stack of messages, and display them to the user, and clear
the stack. If you forget to include this call, the message remains on the stack, and will be
displayed to the user when another (probably unrelated!) message is raised in the application.
For messages which are raised in the server as part of a standard DML action of Forms, the
call to qms$trans_errors.display_messages is not required. This procedure call is already
included in Headstart at the POST-INSERT and POST-FORMS-COMMIT events. This
means that informational messages raised (indirectly) in database triggers, or in the Table API
are automatically displayed to the user.
Raising Questions in the Server

Similar, to informational messages, you are able to raise questions in the server. Again, you
should include a call to qms$trans_errors.display_messages to ensure the message is
displayed to the end user.
With Questions, the feedback from the user should determine further processing. You can
use function qms$forms_errors.get_dialogfeedback to evaluate the response of the user after
the call to qms$trans_errors.display_messages.
Example: We want to raise a question message ‘Are you sure you want to delete this
record?’ each time a user tries to delete a department from the DEPT table. We record this
message with severity ‘Question’ in the message tables, and call qms$errors.show_message
with the appropriate message code in the pre-delete database trigger on table DEPT. To show
this message to the user, and handle processing according to the user’s response, you should
include the following code in the POST-DELETE trigger in your form:
qms$trans_errors.display_messages;
if not qms$forms_errors.get_dialogfeedback
then
raise form_trigger_failure;
end if;
Note that the function qms$forms_errors.get_dialogfeedback will always return the feedback
of the last question. Therefore, you can only raise one question in the server during one
database transaction.

Trapping Unhandled Errors
Important! In order for Headstart message handling to work properly, you must include this
exception handler in every program unit in your application, both client and server.
Unhandled errors are captured by the WHEN OTHERS exception. This will allow the
message handling system to capture all unhandled exceptions and provide the user with
detailed information on the error that occurred and the program unit that had the error.
The exceptions syntax in the client is:

when form_trigger_failure
then
raise;
when others
then
The exceptions syntax in the server is:
when others
then
Suppressing Application Messages
It is possibly to suppress a message either permanently or temporarily. You may want to

suppress a message during one process but have it displayed in all other processes.
Headstart maintains a stack of messages which should be suppressed. To permanently

suppress a message, record the message in the Headstart Message dictionary, and check the
‘Suppress Always?’ checkbox.
To temporarily suppress a message, you must add it to the stack programmatically. To show
the message again, you must delete it from this stack.
To suppress a message:
qms$forms_errors.Add_Suppress_Message (<error code>);
To show the message again:
qms$forms_errors.Delete_Suppress_Message (<error code>);
Suppressing or Replacing ORA and FRM Messages
You can also suppress or replace the text for ORA and FRM messages displayed in forms.
To replace the standard text for and ORA or FRM message, record it in the Headstart
Message dictionary with the desired text. To suppress the message permanently, check the
‘Suppress Always?’ checkbox.
To temporarily suppress ORA and FRM messages:

qms$forms_errors.Add_Oracle_Message (<error code>);

To show the message again:
qms$forms_errors.Delete_Oracle_Message (<error code>);
Error Handling in Batch Programs
The server side error handling of Headstart can also be used for batch programs. The
example below shows the framework of using Headstart for batch programs. All
messages/errors are placed in a PL/SQL table inside the cg$errors package. The “start”
program must read this table using cg$errors.pop (p_errorrec) to read the stack and place it in
a log file (using utl_file or dbms_output).
DECLARE
l_errorrecord hil_message.message_rectype;
BEGIN
my_batch_procedure;
EXCEPTION
WHEN OTHERS
THEN
ROLLBACK;
cg$errors.pop(l_errorrecord);
WHILE v_errorrecord.msg_text IS NOT NULL
LOOP
dbms_output.put_line(l_errorrecord.msg_text);
cg$errors.pop(l_errorrecord);
END LOOP;
END;
Transfer Messages to other Database Schema
A script to unload messages from the Headstart tables into a file is included. The script
(unld_msg.sql, located in hst\scripts directory) creates a SQL*Plus script that can be run on
another database schema, for example the test or production environment. You can adapt this
script to include a where clause if you want to unload all messages created or updated after a
certain date (creation_date or last_update_date column in both tables), or unload messages
with a specific prefix.

Online Help
Headstart allows you to use context-sensitive online help in HTML format.
The Headstart Utility ‘HTML Online Help Generator’, creates an HTML help file, following
the same algorithm as applied by the MS Help Generator.
HTML Online Help Generator
The HTML Online Help Generator adds a context help ID prefix/suffix to all modules,
module components and items, regardless of whether or not help text is recorded against the
element. It then generates a Help file in HTML format and uses the context help ID
prefixes/suffixes to construct bookmarks in the Help file. These bookmarks are prefixed with
‘BM’ since HTML bookmarks cannot start with a number.
Refer to the online help of the HTML Online Help Generator Utility for detailed information
on how the help file is structured and laid out.
This means that if you run the HTML Online Help Generator once before you start generating
your forms, you ensure that KEY-HELP triggers with unique context ID's will be generated
for ALL blocks and items in the form. You can record the actual help text later on, and re-
run this utility to add content to the generated help file. The bookmarks will stay the same.
Important note: If you run the MS Help Generator provided by Oracle Designer to
create an MS Help version of your help files, you should NOT save the changes in the
repository. This utility clears the context help ID suffixes for elements without help text.
You can re-run the HTML Online Help Generator to re-assign them, but the ID’s will be
different, forcing you to regenerate all your forms!
Invocation of the HTML Help File

The Headstart Template Package core library, qmslib65.pll, contains a modified version of
the OFGHPL Library procedure CG$HP_CALL_MS_HELP, the procedure which is invoked
by the KEY-HELP triggers with the help context ID as ingoing parameter. In this Headstart
modified version, the context help ID is prefixed with BM, and a call is made to the
WEB.SHOW_DOCUMENT built-in.
The WEB.SHOW_DOCUMENT built-in expects a URL as the parameter which specifies the
document to show. This URL should be set through the environment variable
HSD65_HELPFILE_WEB_PATH. This environment variable should include the server
name and the virtual directory that contains the help file. For example:
'nlt1460.nl.oracle.com/webforms/'
You should, of course, change the server name (nlt1460.nl.oracle.com) and virtual directory
path (/webforms/) according to your local set-up.
Note: this implementation relies on the library attachment sequence in the generated forms:
QMSLIB65 is attached before OFGHPL65, therefore the modified version of
CG$HP_CALL_MS_HELP is executed.

Note that the HTML Cascading Style Sheet (see Utility online help for more information)
used to layout the helpfile, should be located in the same (virtual) directory as the help file.

Item Hint and Tooltip
Oracle Developer has two properties to help the user understand the use and meaning of an
item:
• The item hint text, displayed at the bottom of the screen in the status bar
• The item tooltip, displayed in a small balloon window, just below the item
The Oracle Designer repository only supports the item hint text, the item tooltip cannot be set
in the repository, and is not set in the generated form. The only way a tooltip can be set, is to
specify the tooltip against the source item in the object library. Generated items that will
subclass from this item, will inherit the tooltip as well. This feature is of little use, because
tooltips are by definition item specific, and source items in the object library are subclassed
by many items.
From a usability point of view, tooltips are preferred over item hint text. It is less user
friendly when the user has to look at the bottom of the screen, each time they want a hint on
the current item. Furthermore, they can only get the hint on the item the cursor is in. If they
want to get help on another item, they first have to navigate to the item. Tooltips are easier
and quicker to use, they appear with a short delay when the user moves the mouse to an item.
The user does not have to click on the item, and they show immediately below the item, not at
the bottom of the screen.
Headstart supports item tooltips by copying the item hint text to the tooltip property at
runtime.
The user can switch on and off the tooltips through the Show Item Hint menu option.
Suppressing Default Hint Text
If you do not specify a hint text in the repository, Oracle Form Generator (OFG) creates a
default hint text of the form ‘Enter value for <prompt name>’. A tooltip with this text does
not make much sense, therefore Headstart does not copy this default, OFG generated, hint
text. For National Language Support, you can configure this default OFG hint text at
application start-up in procedure QMS$INIT_APPLICATION, by calling the following
Headstart built-in:
QMS$CONFIG.SET_DEFAULT_OFG_HINT_TEXT('<language specific
hint text>');
Headstart Hint Text Tags
Headstart also uses the item hint text for extended ‘declarative generation’. Using special
HTML-like tags in the hint text, you can easily align items, assign special visual attributes,
etc. Headstart strips these special tags from the hint text before copying to the item tooltip, so
the user will not see them. Because of the tooltip support, and the use of these special
generation tags in the hint text, the ‘Display Hint Automatically’ property has been switched
off for all source items in the object library.

You can of course change the object library, and switch on the ‘Display Hint Automatically’
property if you want to have item hint text in the status bar. If you do this, you probably
should not use the special Headstart generation tags in the hint text, as the user will be
confused by these tags.

About This Record
Applications generated with the Headstart menu template contain the menu option ‘About
This Record’ under the Help submenu. This menu option invokes a form that shows change
history information on the currently selected record :
• Created By : specifies the Oracle username of the user who inserted the record into the
database
• Creation Date : specifies the date and time which the Created By user inserted the
record
• Updated By : specifies the Oracle username of the user who last updated the record in
the database.
• Last Updated : specifies the date and time which the Updated By user updated the
record
In addition the database table name in which the record is stored is displayed.
The audit columns can be created using a Headstart Utility. A full description of this can be
found in the chapter ‘Implementing the Data Layer’.
The display of the change history information relies on naming conventions of the change
history columns. If you deviate from the default column names as suggested by the Headstart
Utility, you should add a call to procedure QMS$CONFIG.SET_AUDIT_COLUMNS in
procedure QMS$INIT_APPLICATION in your application library.
For example:
qms$config.set_audit_columns
( 'USER_CREATED'
, 'DATE_CREATED'
, 'USER_LAST_UPDATED'
, 'DATE_LAST_UPDATED'
);
Note that you must include the change history columns as hidden columns in your base table
usages in your module definition. The Headstart Utility will add these column usages if
needed.

About This Application
Applications generated with the Headstart menu template contain the menu option ‘About
This Application’ under the Help submenu.
This menu option invokes a form that shows the following types of information:
• Application Information: logo, title and copyright notice

• Session Information: User, Logon Time, Database, Connect String, Current Schema,
Terminal and Session ID
• Module Information: name and version number
• System Information: names and version numbers of application components
The next subsections discuss the steps you should take to display the correct application,
module and system information. (The session information is derived at runtime!)

Displaying Application and System Information
The application information displayed is set through procedure

QMS$ABOUT_THIS_APPLICATION which should be included in your application library
(see chapter Getting Started). In this procedure you should call
QMS$APPLICATION.SHOW_ABOUT passing the following information as parameters:
• application title
• application copyright line 1
• application copyright line 2
• application version information
• file name of the application logo image
• version of Headstart event handler library qmsevh65
• version of Oracle Form Generator
The Headstart demo application contains a library, hsdapp65, which contains an example of
the QMS$ABOUT_THIS_APPLICATION procedure which you can base your own version
on.
System Information
The system information of the About This Application form contains two types of versioning
information:
• version information of application specific components, as specified in

QMS$ABOUT_THIS_APPLICATION
• version information of system generation components
The version information of system generation components is derived as follows:
• The Oracle Form Generator version is specified in

QMS$ABOUT_THIS_APPLICATION
• Headstart Template Package version number is derived in function HST_RELEASE.
This is the overall Headstart release number which you should never change.
• Template form: the name is taken from the initial value of the Forms parameter
TEMPLATE_NAME included in the Headstart template form. The version number is
taken from the initial value of Forms parameter TEMPLATE_REVISION. If you
customize and rename the default Headstart templates (qmstpl65 or qmslvt65), you
should also change the initial value of these parameters to have the correct template
form information displayed in the System Information window.
• Object Library: the name is taken from the initial value of the Forms parameter
OBJLIB_NAME. The version number is taken from the initial value of Forms
parameter OBJLIB_REVISION. Both parameters are subclassed from the Headstart
object library into the Headstart template form through object group
QMSSO$MODULE. If you customize and/or rename the default Headstart object
library (qmsolb65), you should also change the initial value of these parameters to
have the correct object library information displayed in the System Information
window.

Important Note: If you customize the Headstart object library or template form, you
should not change the first four digits of the version number to prevent numbering
conflicts when a new version of Headstart is released. Use a five digit number instead,
or append a letter to the four-digit Headstart version number.
Module Information
The name of the module is derived from the system variable system.current_form. The
version number is derived from the initial value of Forms parameter P_REVISION. You
should define a module argument with this name for each forms module in the repository in
order to have version information displayed. If you do not define an argument
P_REVISION, the module version number will be displayed as ‘UNKNOWN’ in the About
This Application form.
The module version number should be specified in the Default Value property of the
P_REVISION argument.

CHAPTER
17 Troubleshooting
This chapter discusses the following topics related to problems you might encounter when
building and running your application:
• Troubleshooting Approach
• Common Problems
• Problem Assessment
• Headstart Debug Monitor
• Forms Debugger
Headstart Oracle Designer 6.5 - User Guide Trouble Shooting 17 - 1

Troubleshooting Approach
When an application generated with Headstart exhibits unexpected behavior, you are advised
to take the following steps:
• Check whether it is a known problem. Known restrictions of Headstart are

documented in the Headstart Release Notes. The release notes also include a list of
Designer and Developer bugs tightly related to the use of Headstart. Common
problems caused by an error in the set-up of your application are discussed in the next
section.
• Check the Oracle Bug Database or Metalink for the most recent and complete
information on known bugs and workarounds in Headstart, Designer and Developer.
If you do not have direct access to the Oracle Bug Database or Metalink, you can
contact Oracle World Wide Support (WWS), who will be able to search the database
for you. Note that although Headstart is not officially supported by WWS, they
should be willing to help you with your request for information on known bugs. After
all, at this stage neither you nor WWS knows whether Headstart is the source of the
problem!
• If the problem is not a known problem, it is important to establish the source of the
problem: Is it a Headstart problem or not? Refer to the section on ‘Problem
Assessment’ for more information on how to do this.
• If it is a Headstart problem which you are unable to solve yourself, you can contact
your Oracle Consulting representative and ask for assistance. Oracle Consulting will
charge you on a Time and Material basis for this assistance.
• If it is not a Headstart problem, you can ask Oracle World Wide Support for further
assistance.
17 - 2 Trouble Shooting Headstart Oracle Designer 6.5 - User Guide

Common Problems
ORA-04062
When starting a Headstart-generated application, you might get the following error:
QMS-00100: Unhandled Exception ORA-04062: PL/SQL: signature of package

‘HST65.HIL_MESSAGE’ in PL/SQL Program Unit qms$event_form (PRE-FORM) has been
changed. Contact Helpdesk.
This error is caused because you installed the Headstart database objects under a new schema
owner. You will have to recompile all program units (Program -> Compile -> All) in the
following libraries:
• qmslib65
• qmsevh65
Note that there is a SQL*Plus script available, compile.sql located in \hst\admin directory,
that launches a .bat file to recompile these libraries in batch. You are prompted for the
username/password of the owner of the Headstart database objects.
ORA-06508
QMS-00100: Unhandled Exception ORA-06508: PL/SQL: Could not find program unit being
called in PL/SQL Program Unit <program unit name>. Contact Helpdesk.
Possibility 1
The error text is quite misleading, you didn’t loose a program unit, you just need to
recompile all program units (Program -> Compile -> All) in the following libraries:
• qmslib65
• qmsevh65
Sometimes, you also need to recompile your application library, and your application
menu.
If the problem persists, it might be caused by invalid .plx files. The <hsd_home>\admin
directory contains renamed versions of all Form Generator libraries. Remove all .plx
files in this directory, and recompile all libraries starting with the OFG libraries, then
qmslib65, qmsevh65 and your application library.
Possibility 2
To be able to use Headstart generated applications, each Oracle user account you use to
access such an application must have access to the procedure qms_exec_sql.

To grant this access, you should perform the following steps.
1. Connect to SQL*Plus as the user who owns the TAPI packages.

2. Run the script EXEC_SQL.SQL. This script is located in the
3. Grant execute on the procedure qms_exec_sql to [HST65 OWNER]
FRM-40735
FRM-40735: ON-ERROR trigger raised unhandled exception ORA-06508.
This error can have different causes:
• An attached library cannot be found. Check if all required libraries are located in
directories which are included in the FORMS60_PATH environment variable, or are
located in the working directory of your application start-up icon.
• The Headstart database packages have become invalid. This happens frequently when
you generate and execute TAPI scripts from Designer, and accidentally overwrite the
Headstart specific version of the CG$ERRORS package. (See chapter User
Assistance, section Message Handling, section Usage Conditions for more
information)
To correct this situation, run the following scripts, connected as the owner of the
Headstart Template Package database objects:
• cg$err.pks
• cg$err.pkb
• recompl.sql (possibly repeated until all objects are valid again)
The scripts are located in <headstart_home>\hst\scripts directory. The last script,
recompl.sql, should also be run under all other user accounts that have synonyms
pointing to the CG$ERRORS package you just recreated.
FRM-41085
FRM-41085: Error Getting Group Row Count
followed by
FRM-40735: PRE-FORM trigger raised unhandled exception ORA-04067.
This error is raised if you try to run the application under an Oracle user who does not have
access to the Headstart database objects. Chapter 18 describes the necessary actions on how
to grant a user to headstart.

Problem Assessment
As outlined in the section on Debugging Approach it is important to establish the source of
the problem. The problem can be caused by:
• Application specific logic

• Headstart logic
• Customization of Headstart
• Bug in another Oracle tool
Checking Application Logic
Check your application library for ‘suspect’ program units, and comment out any suspect
code.
Generate your module without any custom logic you have added that might be related to the
problem. Note that the custom logic you have added to a module can be easily excluded from
generation:
• Invoke the ‘Generate Form’ dialog in the Design Editor.

• Check ‘Ignore User Application Logic’ checkbox.
• Generate the module.
Headstart Runtime Initializations
Headstart performs various runtime initializations at form, window, block and item level.
Unexpected behaviors might be caused by such a runtime initialization, or by application
logic interfering with these runtime initializations.
You can easily switched off these runtime initializations by temporarily adding a call to the
following procedure in QMS$INIT_APPLICATION:
QMS$CONFIG.DISABLE_RUNTIME_INIT
Refer to the chapter Runtime Behaviors, section Runtime Initializations for information on
the types of initialization you switch off with this statement.
Generating without Headstart
Headstart supplies a special debug preference set, QMS65_DEBUG_MODULE to help you

to quickly generate your form module without the Headstart templates and (object) libraries.
By referencing this preference set at module level, the following preferences are set:
• MSGSFT = CG$FORM_ERRORS. This setting ensures that default message

handling package, stored in the OFGTEL library, will be used.

• FMNDMA = DEFAULT&SMARTBAR. This setting will attach the default Forms
menu and toolbar to the generated form, instead of the Headstart-generated menu.
• STFFMB = dbgtpl65.fmb This setting will use the special debug template to generate
your module. See below for more information.
• STOOLB = dbgolb65.olb
Note: Forms generated without Headstart in this manner will still use the renamed versions
of the OFG libraries. (See Chapter ‘Getting Started’, Section ‘OFG*65.PLL Libraries’ for
more information.)
If the problem does not occur anymore after generation with this debug preference set, it is
likely to be a Headstart or Headstart customization problem.
If the problem persists in the form, it cannot be a Headstart problem.
In both cases, we recommend you use the Headstart Debug Monitor and/or the Forms
Debugger to further localize the code segment that is causing the problem before asking
Oracle for further assistance.
Debug Template and Object Library

You might have gotten a bit suspicious by the fact that you use a template and object library
provided with Headstart, to generate your application without Headstart!
The reason for supplying the debug template and object library is twofold:
• To prevent you from being forced to change the call method of the action items which
call other forms. The call method will usually be set to QMS$AI_OPEN_FORM or
QMS$AI_CALL_FORM. Both procedures are included in the template form, and
consist of a single statement, OPEN_FORM or CALL_FORM, to invoke the other
form.
• To ensure the generated layout is similar to the Headstart-generated form. To
accomplish this, a minimum set of source objects is included in the debug object
library to set the font for text items and GUI items. The source objects do not contain
any trigger logic or any other reference to Headstart functionality.
Neither the template form nor the object library contain any references to Headstart
functionality. Forms generated with the debug template can be run without any QMS library
attached! Whether or not the Headstart libraries will actually be attached to the generated
form, depends on the setting of the MODLIB preference, and the libraries that are attached
through the module network.
Menu Attachment
By applying the debug preference set, the form will be generated with the default Forms
menu attached (controlled through FMNDMA preference). If your problem is related to the
invocation of a form through the menu, you probably want to reset FMNDMA to the original
application menu. To be able to run your form in this case, you will have to generate your
application menu structure without Headstart. To do so, you should set the following
preferences at application level:
• MNUDFC = OPEN_FORM ('<MODULE>');

• MNUDRC = RUN_PRODUCT ( REPORTS,
'<MODULE>',SYNCHRONOUS,RUNTIME,FILESYSTEM,'','');
• MNUUCL = N
• STMMMB = Null (or nullify the menu template name in the generator dialog)
These preferences must be set at application level, because they are ignored when set at
module level (bug 777036). Instead of using OPEN_FORM, you are free to use
NEW_FORM or CALL_FORM as the call method in MNUDFC.
Do not forget to re-inherit these preferences from QMS65_RECOMMENDED after you have
finished debugging!!
Checking Headstart Customizations
If the problem does not occur anymore when generated with the debug template, the problem
might be caused by a Headstart customization, or caused by the core Headstart code.
To check this, you should remove any modified QMS program unit from your application or
company libraries, and generate the form with the standard shipped Headstart template and
object library.

Debug Monitor
In addition to the standard debug capability provided by Forms Builder, Headstart provides a
Debug Monitor which you can use to debug your application.
Reasons to use the Headstart debug monitor include:
• You can view debug messages raised in the Forms client, as well as in the database.
• You can view debug messages raised in an application running on the WEB.
• Some errors or unexpected behaviors do not reproduce when using the Forms
Debugger. The Headstart debugger does not interfere with normal processing
whatsoever, therefore Headstart debug messages are 100% reliable.
• Headstart has included a number of pre-defined standard debug messages, that can
point you in the right direction when tracking down a particular problem.
Using the Debug Monitor
To be able to view the debug messages in the debug monitor, the user of the runform session
you want to debug must have switched on the Headstart debug mode. You can enable the
Headstart debug mode in two ways:
• At application start-up, by specifying the command line parameter

QMS$DEBUG_INFO=YES
• When running your application, by invoking the Help -> Diagnostics -> Headstart
Debug Mode menu check option.
You should run the Headstart Debug monitor (form qms0002f, located in the
<headstart_home\hst\admin directory) in a separate runform session. In the debug monitor
form, there is a poplist to choose the user you want to debug.
The Debug Monitor uses a DBMS Pipe to send and retrieve the debug messages. The debug
messages are refreshed every 5 seconds.
In order to run the debug monitor you need to have execute privilege on the hil_message
package (to read the pipe) and SELECT privilege on data dictionary view
SYS.V_$DB_PIPES (to select the pipename).
Standard Debug Messages
All event handling procedures in qmsevh65 already contain a debug message which displays
the name of the procedure and the name of the event, together with the name of the current
form, the trigger block and the trigger item.
Various runtime initialization actions also log debug messages, describing the runtime setting
performed.

Adding Debug Messages
To include debug message in your application, you can use the following procedure call, in
both the forms client and the server:
QMS$ERRORS.SHOW_DEBUG_INFO(‘<debug message>’);

Forms Debugger
The Forms debugger allows you to debug your application on a statement by statement level.
Refer to the Oracle Developer documentation for more information on using the Forms
Debugger.
There is an important restriction you should be aware of when using the Forms Debugger in
conjunction with Headstart. If a Headstart-generated form contains a call to
qms$form.keep_start_menu in the PRE-FORM trigger, and you try to run the form in debug
mode, the debugger runs into an infinite loop. This is caused by the REPLACE_MENU
command in procedure qms$form.keep_start_menu in qmslib65.pll which sets the application
menu as specified in QMS$INIT_APPLICATION.SET_START_MENU. Work around is to
remove the call to QMS$FORM.KEEP_START_MENU temporarily.
Note that all required application forms include a call to qms$form.keep_start_menu in the
PRE-FORM trigger.

PART VI DEPLOYING YOUR
APPLICATIONS
(blank page)
CHAPTER
18 Test and Production

Environment
This release of Headstart must be deployed with Oracle9ias Forms and Reports Services. The
Oracle9ias Forms and Reports Services deployment architecture and configuration steps
deviates significantly from the previous deployment method using a cgi and a windows forms
server. It is therefore highly recommended to consult the following documentation for a
detailed description of Oracle9ias Forms and Reports Services architecture and involved
middle-tier configuration files:
• Oracle 9i Application Server Release 2 , Forms Services Overview May 2002
• Oracle9iAS Forms Services Deployment Guide Release 9.0.2 January 2002 Part No.
A92175-01
• Managing Oracle9iAS Forms Services with Enterprise Manager April 2002
• Oracle9iAS Reports Services Publishing Reports to the Web Release 9.0 Part No.
A92102-01 February 2002
• How to Execute Reports Services from 9iDS An Oracle9i Reports Technical Note
May 2002
All documentation mentioned above is available above otn.oracle.com
In addition to above documentation look-out for the following white paper regarding
Forms/Reports deployment: “… usage of RUN_REPORT_OBJECT with Oracle9iAS
Reports Services …” available at OTN in the December 2002 timeframe.
This chapter will discuss the following subjects:
Headstart Oracle Designer 6.5 - User Guide Runtime Environment 18 - 1

• An overview of the Headstart Application Installation – detailed instructions are
provided in the Install Guide (<<>>)
• How to Perform the Headstart Database Installation

Before installing the Headstart Database Objects, you will need to make an
important choice between Shared Deployment and Self-Contained Deployment. This
is described in the second section of this chapter.
• A detailed description of the Headstart middle-tier runtime environment, the

deployment files and their interrelationships for reuse for your custom application
18 - 2 Runtime Environment Headstart Oracle Designer 6.5 - User Guide

Perform the Headstart Application Installation
To install Headstart you will have to:
1. Unzip the provided zip (PATCH6530_for_9i.zip) file in a directory. Make sure to

expand the subdirectories as well
Do not copy it over an existing Headstart release!
2. Follow the instructions in the Headstart Installation Guide

<HSD_HOME>\doc\install_for_9i.htm
Note that you should only use the Oracle9ias Forms and Reports Services in a
Development, Test and Production environment. You should only use the 9ids r2
deployment method for demonstration purposes.
The middle-tier deployment contains the following sections:
• Referencing a custom hsd65formsweb.cfg file in the Oracle9ias OC4J

environment
• Adding virtual paths in the forms90.conf file
• Customization of the hsd65formsweb.cfg file – based on the standard

formsweb.cfg file
• Customization of the hsd65default.env – based on the default.env
• Customization of the Oracle9ias reports services
A detailed description of these files is provided in the last paragraph of this

chapter: “Description of the Headstart Runtime Environment”
From here – after a applying the middle- tier configuration steps, restart of your 9ias
application server and the database installation - you should be able to run the Headstart
demo – see also <HSD_HOME>\doc\install_for_9i.htm guide - and/or other Headstart
applications. To facilitate your deployment, Headstart provides shortcuts with url examples
that can be adapted to your deployment environment. They are available in
<HSD_HOME>\Environment_Setup\Shortcuts.

Perform the Headstart Database Installation
This section describes the choices you can make regarding the database schema organization,
and the actions you’ll have to take for each of those choices.
Database Schema Organization
You will have to choose in which schema(s) the Headstart Database Objects will be installed.
Shared Deployment or Self-Contained Deployment

It is likely that you eventually will need to deploy multiple applications that use Headstart
within the same database instance.
If this is the case, you will have to decide whether all applications share the same set of
Headstart database objects (this option is called Shared Deployment), or each application will
have its own set (this option is called Self-Contained Deployment).
Figure 18-1 Shared Deployment
Issues in favor of Shared Deployment:
• When an application modifies tables belonging to another application and these

applications share the same Transaction Management, Business Rule violations of
both application’s tables are reported together (is not possible with self-contained
applications).
• Sharing the Headstart objects will mean less maintenance, changes/patches to
Headstart object definitions need to be applied only once.
• Sharing the Headstart objects prevents duplication of common data, common
messages and end user option records are shared.
• If you have end users in your organization that should have access to multiple
Headstart applications, and you use Self-Contained Deployment, the users would need
to logon with different Oracle usernames for each application, or you would have to
use Alter Session Set Current Schema (see separate section below).

Figure 18-2 Self-Contained Deployment
Issues in favor of Self-Contained Deployment:
• Sharing the Headstart database objects increases the dependencies between

applications. Upgrades to a new Headstart version would have to be done for all
applications simultaneously. Note that middle tier application code might be
dependent on a specific version of server-side objects or vice versa. This means it is
not only a matter of synchronizing server-side upgrades, client-side upgrades would
probably need to be applied simultaneously as well.
Alter Session Set Current Schema

If you choose Self-Contained Deployment, each application has its own set of Headstart
database objects. Each Oracle user will have its own set of private synonyms, pointing to the
application it has access to. Because the name of a synonym must be unique within a schema,
this implies that one Oracle user can only access one Headstart application. This can be a
problem if end users in your organization need access to multiple Headstart applications (they
would need different Oracle usernames for different applications), unless you use Alter
Session Set Current Schema.
The Oracle Server allows you to give the following SQL command:
ALTER SESSION SET CURRENT_SCHEMA = <SCHEMA NAME>
What this statement does is simple but very powerful. When encountering references to
database objects (tables, views, packages, etc.) it resolves these references by prefixing the
name of the object with the schema owner as set above. By default, database object
references are resolved by prefixing the object name with the Oracle username that connected
to the application, which is the reason that public or private synonyms are required.
Note that the schema name set through this command is only used to resolve the reference to
the object. It does not affect your security system in any way. You still have to grant access
on the various Headstart and Application database objects to the individual Oracle usernames.
In other words, by using this feature there is no longer a need to create synonyms for each
and every database object that is directly referenced from a Forms application. This allows
you to use the same Oracle username to connect to different Headstart generated applications
which have their own set of Headstart database objects (in other words, which are self-
contained)!
Headstart will issue the Alter Session command for you when you include a call to
qms$application.set_app_schema(<p_app_owner>) to the qms$init_application procedure in
your application library. Note that you should only do this for self-contained applications!
For example, if you put

qms$application.set_app_schema('HDEMO65');
in qms$init_application, any user accessing the Headstart demo application will reference the
Headstart database objects and Demo database objects using the HDEMO65 schema.
If the application will also contain Reports, each report will need a Pre-Report trigger which
contains a call to srw.do_sql(‘alter session set current_schema = <p_app_owner>’). If you
generate your reports from Designer, you can include this trigger in your Report Template
(note that Headstart does not supply any Report Templates, you can customize one of the
standard Designer templates). In order to store the application owner schema name only once,
you could create a hidden standard report parameter p_app_owner (in the Foundation
Application) that has the schema name as a Default Value. Remember to log into the
Foundation Application with the username/password of the application owner.
Database Server Installation
Depending on the choices you make, you have to run several scripts to install and grant the
Headstart Database Objects.
Warning: Make sure that either you do a fully Self-Contained Deployment, or a

fully Shared Deployment. If you would implement a mix of those two, it can
happen that a transaction is committed even though there were business rule
violations.
Create Schema that Owns Headstart Objects

If you choose Self-Contained Deployment of the Headstart Database Objects (see Database
Schema Organization section), you must create the application schema if it does not already
exist. If you choose Shared Deployment, where the Headstart Database Objects will be
installed in a separate schema, you must create this schema.
Whichever path you have chosen, you will need to grant the following privileges to the owner
of the Headstart objects.
• select on dba_role_privs
• select on dba_tab_privs
• select on dba_synonyms
• select on sys.v_$version
• select on sys.v_$db_pipes
• select on sys.v_$session
• execute on sys.dbms_pipe
• create any synonym
• create role
• drop any synonym
Run the Headstart Server Side Installer

The server side installer can be started using the following url:

• http://<hsd65-server>:<port>/forms90/f90servlet?config=hsd65_serverinstall
On the ‘Set Installation Options’ screen, install the Template Package and optionally, the
Demo Application (for testing purposes). Do not install the Utilities in your deployment
environment.
Grants and Synonyms

Every application owner and every end user that must have access to your application, needs
access to the Headstart Database Objects (and also access to the Application Database
Objects, but that is not the topic of this section).
Suggestion: Headstart supplies scripts for granting access to the Headstart

Database Objects. The privileges included are necessary for application owners,
which must be able to run the Foundation Application, but for end users fewer
privileges are necessary. You can create one or more roles for your end users,
and include the following privileges from [Headstart
home]\hst\scripts\grt_obj.csq: execute on all packages, all privileges on
qms_user_options, just select on the other tables.
The actions you need to perform depend on how you choose to handle synonyms. You can
choose from one of the following three options.
1. Alter Session Set Current Schema (i.e. no synonyms)
2. Public Synonyms (not possible with Self-Contained Deployment)
3. Private Synonyms
Options 1 and 2 are attractive because in that case you can give an end user access just by
granting a role which contains all necessary privileges.

Figure 18-3 Flow diagram for Grants and Synonyms
Alter Session Set Current Schema

If you have chosen Self-Contained Deployment (see Database Schema Organization section),
you only need to create grants for the end users.
• Logon to SQL*Plus as the application owner.

• Run the script [HSD65_HOME]\hst\scripts\grt_only.sql and enter the name of the end
user when prompted (or grant a role in which you included the privileges).
If you have chosen Shared Deployment, you need to create grants and synonyms for your
application owner, and grants for the end users.

• Logon to SQL*Plus as the owner of the Headstart Database Objects.
• Run the script [HSD65_HOME]\hst\scripts\grt_syn.sql and enter the name of the
application owner when prompted.
• Run the script [HSD65_HOME]\hst\scripts\grt_only.sql and enter the name of the end
user when prompted (or grant a role in which you included the privileges).
Public synonyms
You need to create the public synonyms only once.
• Logon to SQL*Plus as a DBA (for example SYSTEM).

• Run the script [HSD65_HOME]\hst\scripts\publ_syn.sql and enter the owner of the
Headstart Database Objects when prompted.
For the application owner and for every end user of your application, you have to create
grants.

• Run the script [HSD65_HOME]\hst\scripts\grt_only.sql and enter the name of the
application owner or the end user when prompted (or grant a role in which you
included the privileges).
Private synonyms
For the application owner and for every end user of your application, you have to create both
grants and synonyms.

• Run the script [HSD65_HOME]\hst\scripts\grt_syn.sql and enter the name of the
application owner or end user when prompted.
Execute SQL procedure

If you have chosen Shared Deployment (see Database Schema Organization section), you
must also create the qms_exec_sql stored procedure in each application owner schema.
• Logon to SQL*Plus as your application schema owner and run the script
[HSD65_HOME]\hst\scripts\exec_sql to create the procedure.
• Grant execute on qms_exec_sql to the owner of the Headstart Database Objects.
Note: This procedure is automatically created for the Headstart Demo Application owner.
Application Specific Reference Data

You should run the following scripts, located in the [HSD65_HOME]\hst\scripts directory, to
unload the application specific Message and Report Parameter data from the development
environment into SQL script files. Once you have created those scripts, you can run them in
your deployment environment to populate your tables.
• unld_msg.sql
• unld_rpts.sql

Note: The Server Side Installer will automatically load the default Headstart reference data.
If you have customized the default Headstart Messages, you will need to also move these
customizations to the new environment.
Custom Messaging or Profiles System

If you have used the Headstart Interface Layer to use your own messaging or user profiles
system, you should install your own custom packages which are called from your customized
version of the HIL packages.

Description of the Headstart Middle-tier Runtime Environment
This section will discuss in detail how this environment is set up, allowing you to customize
it, or to include Headstart 6i in an already existing configuration.
This section will discuss the following topics.
• Headstart Oracle9ias Forms Services environment

• Virtual Directories
• Multiple environments
• Case Sensitive File Names
• Headstart Objects
Headstart Oracle9ias Forms Services Environment
This Headstart release for 9i can only be deployed with Oracle9ias Forms and Reports
Services. It contains the following custom Oracle9ias Forms and Reports Services
configuration files:
• HSD65FORMSWEB.CFG
• HSD65DEFAULT.ENV
• HSD65BASEJINI.HTM
• HSD65REG.DAT
• QMSRF65W.RES
• HST65.JAR
HSD65FORMSWEB.CFG
The hsd65formsweb.cfg file is the Forms90 Servlet configuration file – based on the default
formsweb.cfg - and defines for example:
• System parameters (like baseHTML)
• User parameters (like userid)
• Named configurations
Within the Oracle9ias release 2 OC4J environment you can use a custom formsweb.cfg
through a change of this file reference in the
<9ias r2 home>\j2ee\properties\oc4j_bi_forms.properties file.

Consider an evaluation of the hsd65formsweb.cfg file when you planning to install new 9ias
r2 software since hsd65formsweb.cfg is based on a copy of the standard formsweb.cfg from
around September 2002.
System and user parameters
System and user parameters are defined in hsd65formsweb.cfg. The following parameters
require special attention:
Parameter Description
ORACLE_HOME Your 9ias r2 Oracle home directory
baseHTML Reference to the standard or custom basejini.htm
baseHTMLjinitiator Reference to the standard or custom basejini.htm
envFile Reference to the environment file – here hs65default.env
Term Reference to a custom terminal file
CODE_BASE Should contain a virtual directory that is mapped to the
<ORA_HOME>\Forms90\Java directory.
Archive The name(s) of the jar files needed to run the application,
separated by commas. These will in general be f90all.jar
and hst65.jar. They should either be present in the
CODEBASE location explained above, or be prefixed
with a virtual path.
ServerArgs This string will be passed to the Forms Runtime process
similar to the way you would have launched the form in
Client/Server mode. If you want all keyboard mappings to
work correctly, this parameter should include a section
like: “term=<full_physical_path>/qmsrf65w.res”.
Please note the hardcoded physical path (the
FORMS90_PATH is not used). Also note that you may
use Unix-style slashes even on NT, but not the other way
around.
ServerApp If this parameter is set to anything but “default”, Forms
Server will use the value of this item, suffixed with “.dat”,
as the custom registry file (also see the section
“Registry.dat File” below).
RegistryPath The virtual directory where Forms Server will look for the
custom registry file specified in the above parameter.
When left blank, Forms Server will look for it in the
default location
<ORA_HOME>\forms90\java\oracle\forms\registry
jinit_download_page Your users will need to have JInitiator installed on their
computer to be able to run webforms in their browser. If
they do not have it, and are using Netscape, they will be
automatically redirected to the URL you enter here.
The version of Jinitiator depends on the patches that you
applied to the Oracle Forms installation.
JInitiator 1.3.1.9 is shipped with Headstart as it is certified
against 9.0.2.0.1 of iDS 9i.
LookAndFeel You can set this to ‘generic’ if you want a Windows-style
GUI, or to ‘oracle’ to use the Oracle Look And Feel
(OLAF).
DarkLook If you use lookAndFeel=oracle without darkLook=true,
some prompts will be black while others will be white.

Logo If you leave this parameter empty, it will show ‘ORACLE’
in the right hand side of the menu. Setting it to “No” will
hide this. Alternatively, you can specify your own GIF file
to be shown.
Background This sets the background image for the MDI window.
Leaving it empty displays the default Developer Server
background. Set to “No” to not use any background
image.
SplashScreen The screen to show while initializing the application.
Leaving it empty displays the default Developer Server
splash screen. Set to “No” to not use any splash screen.
Named Configurations
The hsd65formsweb.cfg already contains sections for all Headstart Applications like the
Headstart demo, server_side install, etc. For example:
[hsd65_demo]
form=hsd0000f.fmx
userid=hdemo65/hdemo65
Most likely you only need to add your configuration sections for your custom configurations
to the hsd65formsweb.cfg file for example:
[my_app]
form=myapp0000f.fmx
Note that you do not need to evaluate all other parameters in the hsd65formsweb.cfg for your
specific custom applications.
HSD65DEFAULT.ENV
The hsd65default.env file – based on default.env - is the form90 environment file where you
can setup your environment variables:
• ORACLE_HOME
• NLS_LANG
• FORMS90_MAPPING
• FORMS90_OUTPUT
• FORMS90_REPFORMAT
• HSD65_CDM_MAPPING
• HSD65_HELPFILE_WEB_PATH= “/hsd65-help/” (the virtual directory for

Headstart help files)

• HSD65_IMAGEFILE_PATH = optional. This is the physical directory which
contains all image files you have included in your application. This is only required
if you have used <IM> tags to display images in your forms. Note that you can only
specify one directory for this variable. If you want to use multiple directories to
store your images, you should include the other directories in the FORMS90_PATH
environment variable, which is searched for images as well
• FORMS90_PATH = Lists all directories that include forms and libraries used by the
application . The Headstart installer will have added the directories that hold the
Headstart required application objects, but you will need to add your application
directories.
• REPORTS_PATH= Lists all directories that include reports and report libraries used
by your application
• TNS_ADMIN
• HSD65_HOME = Physical directory that is the home directory for Headstart 6i
Typically you should evaluate the following variables to setup your custom application:
• FORMS90_PATH
• REPORTS_PATH
Note that the hsd65default.env file is referred once in the generic part of hsd65formsweb.cfg.
You are able to refer different environment files – along with other parameters - in the
configuration part of hsd65formsweb.cfg, see also section “Multiple Environments” below.
Consider an evaluation of the hsd65default.env file when you planning to install new 9ias r2
software since hsd65default.env is based on a copy of the standard default.env from around
September 2002.
HSD65BASEJINI.HTM
The hsd65basejini file – based on basejini file default.env - is the default base html file for
running a form on the web using Jinitiator-style tags.
This specific hsd65basejini.htm file is called through the baseHTML and baseHTMLjinitiator
parameters in the generic part of hsd65formsweb.cfg. Normally you do not need to make any
changes to this file for your custom application.
When making changes, please note that many settings occur in two places. That is because
the browsers that support JInitiator (Netscape and Internet Explorer) use different ways to
launch the Forms applet. The document is constructed so that each browser ‘sees’ it’s own
native code. The <PARAM> tags are used by Internet Explorer, the <EMBED> statement by
Netscape
Consider an evaluation of the hsd65basejini.htm file when you planning to install new 9ias r2
software since hsd65basejini.htm is based on a copy of the standard basejini.htm from around
September 2002.

HSD65REG.DAT
The hsd65reg.dat – based on the standard registry.dat –contains the logical [Java] Class name
and an associated [numerical] identifier that will be used to refer to objects of the class in
order to reduce the amount of information that needs to be repeatedly transmitted to the
client.
This specific hsd65reg.dat file is called through the RegistryPath and serverApp parameters
in the generic part of hsd65formsweb.cfg. Normally you do not need to make any changes to
this file for your custom application.
You may consider an evaluation of the hsd65reg.dat file when you planning to install new
9ias r2 software since hsd65reg.dat is based on a copy of the standard registry,dat from
around September 2002.
QMSRF65W.RES
Headstart supplies this terminal resource file for running Headstart applications on the web.
This resource file has the key mappings identical to running a Forms application client/server
on MS Windows. For example, F7 is set to Enter-Query and F8 is set to Run Query.
This specific qmsrf65w.res file is called through the term parameter in the generic part of
hsd65formsweb.cfg. You most likely do not need to make any changes to this file for your
custom application.
HST65.JAR
Headstart supplies a hst65.jar file that contains custom icon files – referred for example in the
iconic tool bar.
This specific hst65.jar is called through the archive_jini parameter in the generic part of
hsd65formsweb.cfg. You most likely do not need to make any changes to this file for your
custom application.
Virtual Directories
The following virtual directories are used by the Headstart Oracle9ias OC4J runtime
environment – you can lookup the forms90.conf file (see
<HSD_HOME>\Environments_setup\9iasr2conf directory) for the correct syntax file:
Virtual Directory Description
/hsd65html/ This directory stores the Headstart HTML files, and
the custom version of the Registry.dat file.
/hsd65java/ Contains the Headstart Java archive, hst65.jar. Is
referred to in the default value for the Archive
parameter.
/hsd65icons/ Contains the GIF files Headstart uses for the
toolbar icons.
/hsd65-help/ Contains the html help files and associated .gifs for
your applications. Is referred to by the environment
variable HSD65_HELPFILE_WEB_PATH.
/hsd65-cdm/ Necessary if you want to run the Headstart Utilities
on this server. Referred to by environment variable

HSD65_CDM_MAPPING.
/java/ Points to where the developer java classes are
located, typically <ORA_HOME>/Forms90/java
/forms90_output/ Directory to hold temporary output. Referred to by
environment variable FORMS90_MAPPING.
Most likely you do not need additional virtual directories for your custom application – but if
you do this is place (forms90.conf) to add your custom virtual path.
Note for example that the location of your forms and reports sources/executables is managed
through the FORMS90_PATH and REPORTS_PATH variable in the hsd65default.env file.
Multiple environments
Different stages can be identified in an application lifecycle. These stages are generally
implemented in separate environments e.g. development, test, production.
Each of the environments has its own set of database objects (tables, packages, etc.) and file
system objects (forms, libraries, etc.). The set of database objects that are used in an
application is defined by the account that is used to connect to the database. The set of file
system objects is defined by environment variables such as Forms90_path, etc.
Environment variables are defined in a so-called .env file like hsd65default.env that is
supplied with Headstart.
There are several options to implement different environments on the middle-tier:
• Each environment on a different node – most commonly used
• Multiple environments on a single node through various ports – requires extensive

resources.
If you choose the latter method it is highly recommended to consult the documentation as
mentioned at the beginning of this chapter.
Note that depending on your middle-tier environment setup you could use multiple
“default.env” files to define each environment and refer to these different files in the
hsd65formsweb.cfg:
..
..
[hsd_dev]
form=hsd0000f.fmx
envFile=[DEV_HOME]\html\hsd_dev.env
[hsd_test]
form=hsd0000f.fmx
envFile=[TEST_HOME]\html\hsd_test.env
..
..
In the example above, two configurations are defined, each using their own environment file.

The development version of the HSD application is started with:
• http://<hsd65-server>:<port>/forms90/f90servlet?config=hsd_dev
and the test version is started using:
• http://<hsd65-server>:<port>/forms90/f90servlet?config=hsd_test
Note: the environment files are in a different directory and have different names. The latter is
to stress that the files are different.
Case Sensitive File Names
If you have a lowercase file name on UNIX, but a form or library expects it to be (partly) in
uppercase, you can make a so-called link.
Example: suppose you have a file named qmslib65.pll, but one of your libraries refers to it as
QMSLIB65.pll.
Go to the UNIX folder where you stored qmslib65.pll and perform the following command:
ln qmslib65.pll QMSLIB65.pll
This creates a 'synonym' QMSLIB65.pll which points to the real file qmslib65.pll, and the
reference from your other library will work.
For a more detailed discussion on case sensitivity issues, see chapter “Getting Started”.
Description of the Headstart Objects
This section will list the objects that are used by Headstart in your deployment environment.
Files
Required Application Forms
• qms0002f: Debug Monitor form
• qms0004f: Change Password form
• qms0006f User Preferences form
• qms0008f: About this Application form
• qms0010f: About this Record form
• qms0012f: Report Launch Form
• qms0014f: Shuttle Control Object Selector
• qms0020f: Help on Message form

OFG Libraries
• ofgbsl65: Block synchronization library, only attached to master-detail forms
• ofgcall65: Calendar library
• ofghpl65: Online help library
• ofgmes65: library for softcoded messages
• ofgmnl65: Menu library
• ofgnavl65: Navigation library
• ofgtab65: Tabbed canvases library
• ofgtel65: Trap error library
• ofgtreen65: Tree navigation library
Headstart Libraries
• qmsevh65: event handler library
• qmslib65: core Headstart library
• qms0004l: module specific library for form qms0004f
Online Help Files

• qmshelp.htm
• qms0004f.gif
• qms0006f.gif
• qms0008f.gif
• qms0010f.gif
• qms0012f.gif
• qms00012f.gif
• qms0014f.gif
• olhelp.css (optional)
Button Gif Files

• qmsaccep.gif • qmsfndhl.gif
• qmscanqy.gif • qmsfndzm.gif
• qmsclral.gif • qmshelp.gif
• qmsclrrw.gif • qmsinsrw.gif
• qmsdelrw.gif • qmsleft.gif
• qmsdown.gif • qmslist.gif

• qmsedit.gif • qmslovbt.gif
• qmsentqy.gif • qmsprint.gif
• qmsexeqy.gif • qmsright.gif
• qmsfind.gif • qmssave.gif
• qmsup.gif
Headstart 9ias Forms Services Runtime

• hsd65basejini.htm
• hsd65default.env
• hsd65formsweb.cfg
• hsd65reg.dat
• qmsrf65w.res
• hsd65.jar
Server Side Installer

• hsdinst.fmx: Server Side Installer
• Required installation scripts
Environment Variables
• FORMS90_PATH
• HSD65_HOME
• HSD65_HELPFILE_WEB_PATH
• HSD65_IMAGEFILE_PATH
Unix Links
If the deployment server is a Unix server, the installer will create the following links to
overcome the problem of case sensitive file names.
• OFGBSL65.pll
• OFGCALL65.pll
• OFGHPL65.pll
• OFGMES65.pll
• OFGMNL65.pll
• OFGNAVL65.pll
• OFGTAB65.pll
• OFGTEL65.pll
• OFGTREEN65.pll
• QMSEVH65.pll
• QMSLIB65.pll

• QMS0004L.pll
• QMS0006L.pll
• QMS0012L.pll
Database Objects
Tables and Table API’s
• QMS_USER_OPTIONS
• QMS_MODULES
• QMS_MDE_PARAMS
• QMS_STND_REP_PARAMS
• QMS_MESSAGE_PROPERTIES
• QMS_MESSAGE_TEXT
• QMS_REF_CODES (no Table API)
• QMS_TRANSACTIONS (no Table API)
Oracle Sequences
• QMS_MDE_SEQ1 (populates QMS_MODULES.ID)
• QMS_MPM_SEQ1 (populates QMS_MDE_PARAMS.ID)
• QMS_SRP_SEQ1 (populates QMS_STND_REP_PARAMS.ID)
• QMS_TRANS_SEQ (populates QMS_TRANSACTIONS.ID)
Stored Packages and Procedures

• HIL_PROFILE
• QMS_PROFILE
• HIL_MESSAGE
• QMS_MESSAGE
• CG$ERRORS, customized version to be able to use Headstart messaging!
• QMS$ERRORS
• QMS_ABOUT_APP
• QMS_EXEC_SQL
• QMS_TRANSACTION_MGT

PART VII CUSTOMIZING
HEADSTART ORACLE
DESIGNER
(blank page)
CHAPTER
19 Customizing the Headstart

Template Package
This chapter discusses customization of the Headstart Template Package. The following
topics are covered:
• Impact of customizations
• Customization of Headstart PL/SQL Libraries
• Customization of Headstart Object Library
• Customization of Headstart Menu and Smartbar
• Customization of Required Application forms
• Changing End User language
• Using Your Own Message Dictionary
Headstart Oracle Designer 6.5 - User Guide Customizing the Headstart Template Package 19 - 1
Impact of Customizations
Most likely, at least one of the following situations is applicable to your organization:
• Headstart will be used simultaneously for multiple applications by multiple project

teams.
• Applications are (or will be) developed with different versions of the Headstart
template package
• Project teams will make modifications to the Headstart code, due to different User
Interface standards and/or application specific requirements
• Multiple applications will be installed in the same runtime environment, possibly
sharing common components.
Without a structured approach to the customization of Headstart, you are likely to encounter
one of the following problems:
• Two applications are using different versions of the same library form. This implies
you cannot install them in the same runtime environment!
• Two applications are using different versions of the same template and/or referenced
form. This implies you cannot maintain these applications in the same maintenance
environment.
• Configuration management becomes very (too) complex, with multiple versions of the
same source co-existing within one application as well as across multiple application
systems.
• When receiving a new version of Headstart, you risk losing customizations made to
the previous version of the Headstart code.
Part of the potential problems will be prevented by Oracle because of the naming conventions
Headstart applies. All Headstart template forms, referenced forms and library forms hold the
release number in the name (qmstpl65.fmb, qmslvt65.fmb, qmslib65.pll, etc.).
Follow the customization instructions in the next section to minimize the risk of running into
one or more of the aforementioned problems.
19 - 2 Customizing the Headstart Template Package Headstart Oracle Designer 6.5 - User Guide
Customizing Headstart PL/SQL Libraries
This section discusses the general approach to take when you want to make customizations to
the Headstart Libraries.
The golden rule is:
Never modify code directly in the two shipped libraries qmslib65.pll and qmsevh65.pll:
Instead, you should copy the event handling program unit in qmsevh65.pll you want to
change to your application library and make the desired modifications in this library. Do not
forget to update the change history record! As the MODLIB preference is set to your
application library (or a module specific library that has the application library attached), this
library will always be attached first in the sequence of attached libraries, overruling the same
procedure in qmsevh65.
The advantages of this approach are threefold:
• If several applications are installed in the same runtime environment, they can all
share the same QMS library.
• By opening the application library you immediately have an overview of the modified
QMS program units. This is very convenient for debugging purposes as well as
upgrading to a new Headstart version.
• You easily apply patches to the QMS libraries by simply copying them over the old
files.
Note: Try to avoid the drag and drop of packages from QMSLIB65 into your application
library. Instead, trap the procedures that call this package in qmsevh65.pll, and drag and drop
this procedure to your application library, and replace the call to the QMS package, with a
call to your own package. (You might cut and paste code out of the original QMS package,
as long as you give the package a different name.)
If for some reason, you do have a need to drag and drop a QMS package into your application
library, you should stick to the following rules:
• Never remove or change the datatype of an existing package variable.

• Add new package variables and program units at the end of the package specification
If you do not apply these rules, your application probably will raise runtime errors varying
from program errors and value errors to General Protection Faults! This is caused by the
PL/SQL engine in Forms which references packaged program units and variables based on
sequence numbers within the package, not on names.
If you want to make customizations to QMS program units that should apply to all your
applications, you should consider introducing a company library (organization-wide library)
in addition to the application library. This company library holds the modified QMS program
units (and additional custom made program units) that should be used by all applications.
This company library should be attached before the QMS library, but after the application
library to allow for application specific deviations from the company 'standard':
Module Library -> Application Library -> Company Library -> qmsevh65 -> qmslib65
Name Resolution in Module Specific Libraries
When making module specific customizations to the Headstart PL/SQL libraries, there is an
issue you need to be aware of.
Since version 5.0, Forms only performs name resolution once per session for performance
reasons. This means that if you have a procedure of the same name in two different libraries,
Forms will always use the first version of the procedure called during that session. The
problem this causes is best understood through an example.
• Suppose library qmsevh65 contains a procedure ‘abc’ which displays the message ‘abc
in qmsevh65’. The first line in procedure qms$event_form in qmsevh65 calls
procedure abc.
• Thus, on startup any Headstart form will display the message ‘abc in qmsevh65’.
• Module test1 has a module specific library, test1.pll, which contains its own version of
procedure ‘abc’ which displays the message ‘abc in test1.pll’. The module specific
library is the first attached library, the application library, qmsevh65 and qmslib65 are
attached to the module library.
• When you run module test1 directly, the message ‘abc in test1.pll’ is correctly
displayed.
• However, when you first start another Headstart form, Forms performs the name
resolution to the qmsevh65 version of procedure ‘abc’. That form will display the
message ‘abc in qmsevh65’ as it should. But, when you then call module test1, the
name resolution is not performed again, so test1 also displays ‘abc in qmsevh65’
instead of ‘abc in test1.pll’ !!
You will not encounter this problem with application-wide customizations which are stored in
the application library. The application library is attached to all forms, so there is no problem
in that the name resolution of the first form is re-used over and over again.
You also will not encounter this problem when the program unit is called directly from the
form. The name resolution is performed once for each calling entity. Since the calling entity
is now the form and not qms$event_form in qmsevh65.pll, the naming resolution is
performed again. This means that you can safely customize any event handler in qmsevh65,
since they are all called directly from the form.
You will only encounter this bug when you use a module specific library to customize a
Headstart program unit which is not called directly by the form, but rather by another
Headstart program unit. (This includes almost all program units in qmslib65.)
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. In the above example, this would mean
you must also copy qms$event_form to the module specific library. At runtime, the
instance of qms$event_form in the module library will be called, causing Forms to do
a new name resolution since the calling entity is different. This is the preferred
workaround, but not always feasible if the program unit being customized is called
from various places.
• Only copy the calling program unit to the module specific library and replace the call
to the program unit you want to customize with a call to a renamed version of this
program unit. In this example, this would mean that only qms$event_form is copied
to the module specific library, and the call to ‘abc’ is changed to call a new module
specific procedure ‘abc_custom’.
Customizing the Headstart Object Library
This section discusses how to customize the Headstart Object Library.
Oracle Designer 6i allows you to specify multiple object libraries when generating your
forms. Use the STOOLB preference to define a list of one or more object libraries. If you
have multiple object libraries, use semi-colons to separate object library names.
Form Generator searches through object libraries for a particular object in the order in which
you specify the object libraries. Note also that Form Generator attempts to use the first object
it locates with the correct name (regardless of the object's type).
The FM2LIB61 utility, shipped with Oracle Designer 6i, plays a key role in the approach you
should follow. The FM2LIB61 utility allows you to work around a major limitation of object
libraries in general, which will be discussed in the first two sections. This utility also allows
you to preserve as much as possible your customizations made to the Headstart Object
Library when a new version of Headstart is released, which will be discussed in the last
section.
Limitation of Object Libraries
You cannot create and maintain objects in the object library itself. You need to create an
object in a normal forms module, and drag and drop it into the object library. If you
subsequently want to modify the object definition, you will have to drag and drop it back into
a normal form, edit it, and drag and drop it back into the object library, replacing the old
object definition.
When an object is dragged to the Object Library, a Copy operation always ensues (note that
you don't get the option to "Copy" or "Subclass"). As part of the Copy operation, all
subclassing relationships are "flattened", in other words, the subclassing relationship is lost
and property values are a snapshot. The big problem here is that you also lose subclassing
links to objects that reside in the same object library.
We will illustrate the impact of this limitation with two objects in the Headstart object library:
CGSO$BLOCK and CGSO$BLOCK_MR. It makes sense to subclass CGSO$BLOCK_MR
from CGSO$BLOCK as there are many properties and triggers that will apply to all blocks,
regardless of the block being multi-record or not. You can do this in three steps:
1. Drag CGSO$BLOCK into the object library.

2. Subclass CGSO$BLOCK_MR from CGSO$BLOCK in the OL
3. Drag CGSO$BLOCK_MR into the OL as well.
Now, you start generating your forms. All your single-record blocks subclass from
CGSO$BLOCK, all your multi-record blocks subclass from CGSO$BLOCK_MR.
Then, you decide to add a trigger, say KEY-DELREC, to all your blocks. You add the trigger
to CGSO$BLOCK in the maintenance form qmsolm65.fmb that mirrors the object library,
and drag and drop the new CGSO$BLOCK definition into the object library (qmsolb5.olb),
replacing the old definition. You would expect all blocks in the forms to automatically
inherit the new KEY-DELREC trigger, but this does not happen! Only the single-record
blocks will inherit the trigger, the multi-record blocks will not. This is caused by the fact that
the subclassing link from CGSO$BLOCK_MR to CGSO$BLOCK is lost upon dragging the
block into the object library!
Fortunately, Designer is shipped with a very useful utility, FM2LIB61, that enables a very
workable work around to this problem.
The FORM2LIB Utility
Basically, the FM2LIB61 utility takes all objects in a normal forms module, and copies them
into an object library. Using this utility, you would implement the example above a little
differently:
1. Subclass CGSO$BLOCK_MR from the CGSO$BLOCK definition in the

maintenance form, instead of the CGSO$BLOCK definition in the object library.
2. Run the FM2LIB61 utility to create the Object Library with the two objects
3. Generate your forms and subclass the blocks from the two blocks in the object
library.
Now, if you want to add the KEY-DELREC trigger to all already generated forms, you
simply perform the following steps:
• Add the KEY-DELREC trigger to CGSO$BLOCK in the maintenance form.

• Run the FM2LIB61 utility
• Recompile (create a new .fmx file) all generated forms.
Because the subclassing link is kept within the maintenance form, block
CGSO$BLOCK_MR inherits the KEY-DELREC trigger as well. The FM2LIB61 utility
subsequently refreshes all object definitions in the object library, adding the KEY-DELREC
trigger to both CGSO$BLOCK and CGSO$BLOCK_MR.
The FM2LIB61.TXT readme file, located in <ORA_HOME>\CGENF61 contains detailed

information on the use of this utility.
Creating an Object Library using FM2LIB61
Headstart supplies form QMSOLM65.FMB as the object library maintenance (OLM) form.
This form mirrors the content of the Headstart Object Library.
To create the object library from this maintenance form using the FM2LIB61 utility, you
should set up the FM2LIB61 registry key as follows:
TAB 1: ID1 = 'QMSSO$', NAME = 'QMS OBJECTS'
TAB 2: ID1 = 'CGSO$' , NAME = 'CGSO OBJECTS'
A registry file, qmsolb65.reg, is supplied in the hst\admin directory to automatically create
these two entries. The registry entries are added by double-clicking on this registry file. Note
that you should not run the fm2lib61.reg file shipped with Oracle Designer, as this will create
additional TAB entries which are not required. If you already ran the fm2lib65.reg file, you
should remove the tab keys TAB 3 to TAB 8.
To recreate the Headstart Object Library, the FM2LIB61 utility can be run using the
following command line:
fm2lib61.exe -i qmsolm65.fmb -o qmsolb65.olb
Creating a Custom Object Library Maintenance Form

To create a custom Object Library, you must do the following:
• Create a new form in Form Builder.

• Set the coordinate system of this form to Real-Inch
• Save the form under a name which indicates it is your application specific object
library maintenance form.
The next steps depend on the type of customization you want to make:
• Adding a new source object

• Modifying an object that already exists in the Headstart Object Library
Adding a New Source Object

Perform the following steps:
• Create the new object in your OLM form, prefix the name with your application
shortname, concatenated with ‘SO$’ (SO stands for source object). For example, an
application to Locate Unknown Travelers will have a prefix of ‘LUTSO$’.
• Add an entry to the FM2LIB61 registry to register your application prefix, and to
create a separate tab in the object library with your application specific objects. In the
above example, you would add the following new key:
TAB 3: ID1 = 'LUTSO$', NAME = 'LUT OBJECTS'
• Run the FM2LIB61 utility to create your custom object library. If you named your
OLM form lutolm10, the command to do so would be:
fm2lib61.exe -i lutolm10.fmb -o lutolb10.olb
Modifying an Existing Object

The approach to modifying an existing object depends on the type of object you want to
change:
• Source objects that can be subclassed directly by generated objects. These objects are
prefixed with CGSO$ or QMSSO$.
• Standard objects that need to be present in generated forms, but are not ‘subclassable’
by other objects. These objects are prefixed with QMS$, and are grouped into object
groups. These object groups are prefixed with QMSSO$ and are subclassed into the
template forms.
Modifying Source Object

Perform the following steps to modify a source object (CGSO$ or QMSSO$):
• Subclass the object from qmsolm65 into your own OLM form
• Modify the object as required
• Save your object library maintenance form
• Run the FM2LIB61 utility to create your custom object library
Note that if you apply this approach, you cannot delete a trigger that belongs to the object. If
you try to delete a trigger from a block or item that you subclassed into your object library
maintenance form, the following error will be raised:
FRM-15103: Can’t delete <trigger name> because its parent
is subclassed.
You have two options to work around this limitation:
• Copy instead of subclass the object into your OLM form. This has the disadvantage,
that when a new version of Headstart is released, you do not automatically inherit the
Headstart changes. You will have to manually resolve the differences between the
new version of the object as shipped with Headstart, and the old version of the object
modified by you.
• Change the trigger text to Null.
Modifying Standard QMS$ Objects

Because standard QMS$ objects are grouped into object groups, the approach to modify such
a standard object is slightly different from source objects:
• Subclass the object group that contains the object you want to change into your own
OLM form. As you will see, all objects within the object group are subclassed into
your OLM form as well.
• Modify the object as required
• Save your object library maintenance form
• Run the FM2LIB61 utility to create your custom object library
This approach works fine, as long as your customization does not involve the deletion of a
‘child-object’ that belongs to an object within the object group. For example, it is not
possible to delete an item of a standard block, nor a trigger of an item. If you try to delete
such a child object, the following error will be raised:
FRM-15103: Can’t delete <object name> because its parent
is subclassed.
To work around this limitation, you will have to do the following:
• Before subclassing the object group as a whole into your OLM form, you copy the
object you want to modify into your OLM form.
• Now subclass the object group into your OLM form. All objects in the object group
will be subclassed into your OLM form, except for the object you already copied into
your OLM form.
• You are now able to delete any child object of the copied object.
• Save the OLM form and run the FM2LIB61 utility to create your custom object library
Because you first copied the object you want to customize, the object group changes its
reference from the original object in qmsolm65, to the copied object in your own OLM form.
However, be aware of the following: when you copy an object that is subclassed from
another object, this subclassing link is lost during the copy operation. After the copy
operation you will have to re-establish those links.
Using Your Custom Object Library

To use your custom object library, add it to the headstart object library using the APPEND
option of the object library genrator.
Fm2lib61.exe –i qmsolm65.fmb –o qmsolb65.olb
Fm2lib61.exe –i <app>olm65.fmb –o qmsolb65.olb APPEND
The object definitions in the custom object library will be used instead of similar definitions
in the headstart library.
Food for Thought

Note that the main purpose of creating your own OLM form and object library is to preserve
your changes when Oracle releases a new version of the Headstart object library. The above
mentioned work around of copying the object instead of subclassing it, undermines this
purpose. Therefore, you might consider making this type of change directly into the
Headstart Object Library maintenance form qmsolm65. If you do this, make sure you
safeguard the original version of qmsolm65, so you can revert to the default Headstart Object
Library at any time, if you encounter problems that might be related to your customizations.
Customizing the Menu and Smartbar
To customize the menu or Smartbar, perform the following steps.
• Copy the Headstart menu template to a new name.

• Customize the new menu template as desired.
• In the Designer Editor, select your application node and open the Preferences
Navigator.
• Change preference STMMMB, Name of the Menu Template, to the new menu
template name.
• Re-generate your menus.
Depending on the changes you make, you will probably also need to customize the Headstart
core library, qmslib65.pll. This library contains the code which controls the context sensitive
enabling and disabling of menu options. Specifically, you must determine if your changes
affect the following packages.
• QMS$CONTEXT
• QMS$MENU
Customizing Required Application Forms
Headstart Required Application Forms are forms that are required to run your application
generated with Headstart. The need for most of these forms comes from the Headstart menu
template, which contains a number of menu options that call the following required
application forms:
• qms0004f: Change Password (Edit -> Preferences -> Change Password)

• qms0006f: User Preferences (Edit -> Preferences -> Preferences)
• qms0008f: About this Application (Help -> About this Application)
• qms0010f: About this Record (Help -> Record History)
• qms0012f: Report Launch Form (Called for every report module that is included in
your application menu, governed through MNUDRC preference)
The last required application form is qms0020f ‘Help on Message’ which is called by the
Headstart Message Handling system, when the user presses the Help button on the message
alert box.
All required application forms are 100% generated with the Headstart templates. The
repository module definitions can be found in the QMS65 application system folder.
Basically, you can simply change the module definitions in the Designer repository according
to your requirements, and generate the forms again. Do not make the changes in the QMS
application system. Copy the modules to your own application system first.
Renaming Required Application Forms
The required application forms are set up for use in multiple applications. If you generate
multiple applications with the Headstart templates, you can use the same set of required
application forms to serve all your Headstart-generated applications (provided that they are
deployed in the same runtime environment).
Because the forms can be shared across applications they only need to be renamed if you
customize the forms.
Headstart uses a package procedure which contains variables which hold the names of the
required application forms. To change the initialization of these variables, you need to
change the form name in the following procedure calls in procedure
qms$config.set_change_password_form ('qms0004f');
qms$config.set_user_prefs_form ('qms0006f');
qms$config.set_about_application_form ('qms0008f');
qms$config.set_about_record_form ('qms0010f');
qms$config.set_report_launch_form ('qms0012f');
qms$config.set_message_help_form ('qms0020f');
Changing End User Language
If you want to change the language presented to the end user, you must make the following
modifications in the Headstart template package:
• Translate menu template

• Translate object library
• Translate messages
• Translate required application forms
• Translate reusable module components
You should copy and rename the template form before making the modifications discussed
below. Refer to the previous section for the steps to perform to carry through these name
changes.
Translating Menu Template
To translate the menu template, you must change three properties of all menu items:
• Label. (Do not forget to check for the uniqueness of the mnemonic access key of the
menu label. This key is ALT+<Letter> combination with the letter being the letter in
the label that is prefixed with &-sign.)
• Hint (text)
• Help (text)
Suggestion: The FILE, EDIT and HELP menu item labels are
largely based on MS Excel and MS Word. You can take the menu
item labels used when running MS Excel or MS Word in your native
language as a starting point.
Note that you cannot change the name of the items appearing in the WINDOW submenu.
These items are created automatically by Oracle Forms if you define the WINDOW submenu
as a ‘Magic Item’ of type ‘Window’.
One menu label is set dynamically depending on the mode the form is in. This label is set to
'Enter Query' (if form is in normal mode) or 'Show Last Criteria' (if form is in query mode).
To translate these dynamic labels, you must change the following procedure calls in
qms$config.set_entqry_label ('Enter');
qms$config.set_lstqry_label ('Show Last Criteria');
Translating Object Library

To translate the object library, you must first create your own object library maintenance
form. Refer to the section on Customizing the Headstart Object Library of you do not have
such a form yet.
To translate the object library, you must make the following modifications in your object
library maintenance form.:
• Change Button1, Button2 and Button3 for all Alerts (QMS$WARNING,

QMS$INFORMATION, QMS$DIALOG and QMS$ERROR)
• Change the Access Key and Label of all button items in block
QMSSO$FIND_BLOCK
• Change the Tooltip of all items in block QMS$TOOLBAR.
• Change the Label and Tooltip of all button items in block CALENDAR
• Change the title of window CALENDAR
• Change the label, hint and help text of the items in popup menu QMS$POPUP_ITEM
Translating Messages
You can use the Message form in the Headstart Foundation Application to add languages for
a message.
To have the messages displayed runtime in the correct language, the end user must invoke the
‘Preferences’ form under the Edit-menu and set the language as desired.
Translating Required Application Forms
To translate the required application forms, you must change the domain allowable values
and the prompts, item group labels, and user help text of the corresponding module
definitions in Oracle Designer. The module definitions of the required application forms are
stored in the QMS65 application system folder.
Translating Reusable Module Components

The QMS65 application system contains four reusable module components:
• QMS_WIZ_BUTTONS
• QMS_LOV_BUTTONS
• QMS_MSEL_LOV_BUTTONS
• QMS_DIALOG_BUTTONS
Each reusable module component contains a number of unbound button items. For each
button, you should translate the Prompt, the Hint and the User Help text.
Make a copy of each reusable module component and modify the copy instead of the original
in the QMS65 application system.
Using your own Message Tables
You might want to use your own database tables to store the message information. Changing
Headstart to use you own database tables is easy through the Headstart Interface Layer (HIL)
packages.
All read access in the Headstart Template Package to the message database tables is routed
through the package HIL_MESSAGE. Each procedure/function in this package calls a
procedure/function in the package QMS_MESSAGE. You’ll have to write your own package
(OWN_MESSAGE) and change the calls in HIL_MESSAGE to your package. Read the
package specification of HIL_MESSAGE to identify what each procedure/function must do.
Note that the HIL packages are read-only, they are intended to make the template Package
independent from the message data structure.
The form shipped with the Headstart Foundation Application to maintain the message tables,
directly operates on these tables, and does not use the HIL packages. This means that you
will have to create a new form to maintain the messages, that operates on your own message
tables.
A number of Headstart Utilities automatically create messages in the Headstart message

tables. If you want to continue to use these utilities, you must change these utilities to access
your own message tables.
(blank page)
CHAPTER
20 Customizing the Headstart

Utilities
This chapter gives you guidelines for customizing the Headstart Utilities. It includes the
following topics:
• Exclude CDM Quality Checks

• Creating your own QA-set
• Before creating your own Utilities
• Creating your own Quality Checks
• Creating your own Productivity Boosters.
Headstart Oracle Designer 6.5 - User Guide Customizing the Headstart Utilities 20-1
Exclude CDM Quality Checks
The Headstart Utilities Quality Checks are based on the standards as recorded in Oracle’s
Custom Development Method. Since you may have different standards or want to deviate
from the CDM ones, a Quality Check can be excluded. The Headstart Utility Administrator
can do this in the Administration Application by simply setting the ‘Comply to’ pop-list to
‘No’ . Standards with ‘Comply to’ = ‘No’ will not be checked anymore by the Headstart QA-
checks. They will be reported however in the QA-check results if you set the user preference
‘QA Details Creation - Non Complied Standards’.
20 - 2 Customizing the Headstart Utilities Headstart Oracle Designer 6.5 - User Guide
Creating your own QA-set
The Headstart Utilities contain the possibility to group standards of different elements
together in a QA-set. You can also leave standards out because you do not want to check
them yet. This is especially useful if you only want to check certain aspects of the elements
(e.g. only standards that apply to the ‘Logical Database Design (DB.010) and element Tables
and not aspects of the physical table implementation which are checked in DB.040 Physical
Database Design).
The standard Headstart Utility installation comes with a number of QA-sets that are directly
related with the CDM Deliverables. The Headstart Utility Administrator can create new QA-
Sets in the Utilities Administration Application.
Adding your own Quality Checks to existing utilities
If you want to create your own quality checks (for element types that are already checked by
the Utilities) take the following steps (each step is illustrated by a running example of adding
a check on the length of a column name):
1. Determine which element type you want to check.
Example: You want to add a check for the element type Column.
2. Determine the parent element type of this element type. Currently you are limited to
the primary element types for which utilities already exist (Application Systems,
Domains, Entities, Events, Functions, Tables, Views, Sequences, Modules, Reusable
Module Components, PL/SQL Definitions, Oracle Databases, Non-Oracle
Databases).
Example: The element type Column belongs to parent element types Table and
View.
3. Determine which property of the element type you want to check. If you can not
pinpoint one property, the check is for the element type in general.
Example: You want to check the column property Name.

4. Go to the Utilities Administration Application, from the menu choose
Administration -> Project Standards. Enter your standard. Make sure that the Code
does not start with OMS or OMG, Comply to is set to Yes, Checked by Utility is
checked, and the standard is linked to either an Element Type or an Element
Property. You can also add the new standard to one or more QA Sets (Deliverables).
Example: See screen shot.
5. Determine the short name of the element type (for instance from the LOV on
Element Type in the Standards form).
Example: The short name for Column is COL.

6. Open the package body creation script for the element type: [Headstart
Home]\hsu\qa\qa_<short name>.pkb.
Example: Open [Headstart Home]\hsu\qa\qa_col.pkb.

7. Go to the procedure run and find the loop going over all instances of the element
type.
Example: The run procedure in qa_col.pkb contains a line: for r_col in

blcol.c_col_tab(p_owned_by_id) loop.
8. Within that loop, find the location of the OMS-standard checks. Add your own
PL/SQL code that performs the check. Borrow the structure from one of the existing
checks. If the standard is violated, call both hsu_qa.add_property and
hsu_qa.add_violation.
Example: Within the loop the procedure perform_checks is called. Within

perform_checks there are pieces of code for the CDM standards, starting with OMS-
42207. Add your own piece of code:
--
-- PRJ-00001
--
if hsu_qa.perform_check('PRJ-00001', p_qas_id)
then
if length(p_col_row.col_name) > 28
then
hsu_qa.add_property
( 'NAME'
, p_col_row.col_name
);
hsu_qa.add_violation('PRJ-00001');
end if;
end if;
9. Save the SQL script and run it under the Utilities owner.
Example: Save the changed qa_col.pkb, log into SQL*Plus as HSU65 and run the
script.
10. Start the Run Utility form and run the Quality Checks for the parent element type.
Example: Run the Quality Checks for Tables. It will apply the check for PRJ-00001
to all columns of the selected tables.
Before creating your own utilities
Before you create your own Utility (Quality Check or Productivity Booster) you should check
if the right base layer packages are available.
• Investigate which Designer element types you will use in your utility.
• Determine the short names of those element types. You can find the correct element
type short name in file [Oracle Home]\CDOC72\model\el_defs\outer_frame_de.htm
• Look in the folder [Headstart Home]\hsu\scripts\bl for scripts named bl<element type
short name>.pks or .pkb. They contain the source code of the Base Layer package for
that particular element type. For a description of the Base Layer see file [Headstart
Home]\doc\bldoc.htm.
Creating new Base Layer packages
If one of the associated Base Layer packages does not exist, create it first.
• Check if the database initialization parameter utl_file_dir is set. The package scripts
will be generated into one of the directories specified by this parameter. If you set
utl_file_dir = * in the init.ora (or equivalent) file, you can generate the scripts to any
directory on the database server.
• Log into SQL*Plus as the Headstart Utilities owner, and run [Headstart
Home]\hsu\scripts\bl\gen_bl.sql. You will be prompted for the element type short
name and the database server directory to which the scripts must be generated.
• Still logged in as the Headstart Utilities owner, execute the bl<short name>.pks and
bl<short name>.pkb scripts to create the new base layer package.
Creating your own Productivity Boosters
If you want to create your own Productivity Boosters take the following steps (the hsu_ex.pks
and hsu_ex.pkb scripts can be used as an example).
1. Give your utility creation scripts the file names <package name>.pks and <package
name>.pkb.
Example: Write files prj_utl1.pks and prj_utl2.pkb, which create the specification
and body of package prj_utl1.
Suggestion: First look for an existing utility that loops over roughly the same
objects as your planned utility, copy the scripts of that package and modify
them.
2. Install your utility (connected as Utilities owner) using: [Headstart

Home]\hsu\scripts\pb\inst_pb.sql, enter the package name when asked for.
Example: run inst_pb, and supply the name prj_utl1

3. Add the utility to a User Group in the Administration Application.
Example: Add the new utility to the user group ‘All Productivity Boosters’.
4. Possibly add the utility to a suitable parent node.
Example: Add the new utility to the node ‘Data Layer’.

5. Run Reconcile for your Utilities user (button in Users form of Administration
Application), to make sure you get the synonym for the new package.
6. Test the utility using the Run Utility Form.
7. After changing the scripts, run inst_pb again and restart the Run Utility Form.
8. When you are satisfied with the new utility, run Reconcile All Users.

Eadstart Racle Esigner: User Guide

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Eadstart Racle Esigner: User Guide

Uploaded by

Copyright:

Available Formats

HEADSTART

ORACLE DESIGNER 6.5

Copyright © 2000-2002 Oracle Corporation.

ORACLE and SQL*Plus are registered trademarks of Oracle Corporation.

Microsoft is a registered trademark and Windows a trademark of Microsoft Corporation.

2 Table of Contents Headstart Oracle Designer 6.5 - User Guide

CHAPTER 1 Introduction ...................................................................................................................1-1

Part I Overview and Setup 3

CHAPTER 2 Headstart Template Package Components .................................................................2-1

CHAPTER 3 Headstart Utilities Components ...................................................................................3-1

CHAPTER 4 Development Team Access to Headstart .....................................................................4-1

CHAPTER 5 Running the Headstart Utilities ...................................................................................5-1

Headstart Oracle Designer 6.5 - User Guide Table of Contents i

CHAPTER 6 Running the Headstart Foundation Application ........................................................6-1

Part II Roadmap to Application Development 9

CHAPTER 7 Headstart Application Development Approach .........................................................7-1

CHAPTER 8 Development Process Roadmaps by Phase .................................................................8-1

Part III Data Layer

CHAPTER 9 Implementing the Data Layer ......................................................................................9-1

Part IV Business Logic Layer

CHAPTER 10 CDM RuleFrame..........................................................................................................10-1

ii Table of Contents Headstart Oracle Designer 6.5 - User Guide

CHAPTER 12 Accessing the Rule Layer ............................................................................................12-1

Part V Presentation Layer

CHAPTER 13 Getting Started.............................................................................................................13-1

Headstart Oracle Designer 6.5 - User Guide Table of Contents iii

CHAPTER 14 User Interface Generation...........................................................................................14-1

iv Table of Contents Headstart Oracle Designer 6.5 - User Guide

CHAPTER 15 Runtime Behaviors ......................................................................................................15-1

Headstart Oracle Designer 6.5 - User Guide Table of Contents v

CHAPTER 16 End User Assistance ....................................................................................................16-1

vi Table of Contents Headstart Oracle Designer 6.5 - User Guide

CHAPTER 18 Test and Production Environment.............................................................................18-1

CHAPTER 19 Customizing the Headstart Template Package.........................................................19-1

CHAPTER 20 Customizing the Headstart Utilities...........................................................................20-1

Headstart Oracle Designer 6.5 - User Guide Table of Contents vii

viii Table of Contents Headstart Oracle Designer 6.5 - User Guide

Headstart Oracle Designer consists of two major components:

• Headstart Template Package A set of, templates, libraries, reusable GUI

Headstart Oracle Designer 6.5 - User Guide Introduction 1 - 1

• Volume 1, Requirements Modeling using Oracle Designer

1- 2 Introduction Headstart Oracle Designer 6.5 - User Guide

2 Headstart Template Package

The Headstart Template Package consists of the following components:

• Headstart Templates, Libraries and Preferences for Developer Generation

The following sections discuss each component in detail.

The following preference sets are available:

• qms65_recommended: contains all preferences you should reference at application

The following reusable module components are available:

• qms_dialog_buttons: contains standard buttons for a modal dialog window: OK,

• qms0002f: Help on Message

The following forms are available:

• qfd0000f: Start form of the Headstart Foundation Application

The Template Package currently accesses two types of data sources:

• A data source containing user preferences information

Headstart ships with a default implementation of these two data sources:

• User preferences are stored in table QMS_USER_OPTIONS, which is accessed

Refer to the chapter on Template Package Customization for more information.

• many (manual) tasks are time consuming and error prone

• Productivity Boosters - to enforce standards and guidelines

• Run Utility Form

The following sections discuss each component in detail.