Você está na página 1de 352

Oracle 9i Forms Developer:

New Features
Instructor Guide

D14298GC10
Production 1.0
October 2002
D37333
Author Copyright Oracle Corporation, 2002. All rights reserved.
Pam Gamer
This documentation 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. Reverse engineering of the software is prohibited.
Technical Contributors If this documentation is delivered to a U.S. Government Agency of the Department of
Defense, then it is delivered with Restricted Rights and the following legend is
and Reviewers applicable:
Yanti Chang
Laurent Dereac Restricted Rights Legend
Ellen Gravina
Use, duplication or disclosure by the Government is subject to restrictions for
Jonas Jacobi commercial computer software and shall be deemed to be Restricted Rights software
Chris Lewis under Federal law, as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013,
Chris Lowes Rights in Technical Data and Computer Software (October 1988).
Marcelo Manzano
This material or any portion of it may not be copied in any form or by any means
Duncan Mills without the express prior written permission of Oracle Corporation. Any other copying
Frank Nimphius is a violation of copyright law and may result in civil and/or criminal penalties.
Kavitha Prakash
If this documentation is delivered to a U.S. Government Agency not within the
Jasmin Robayo
Department of Defense, then it is delivered with Restricted Rights, as defined in
Bryan Roberts FAR 52.227-14, Rights in Data-General, including Alternate III (June 1987).
Grant Ronald
Raza Siddiqui The information in this document is subject to change without notice. If you find any
problems in the documentation, please report them in writing to Education Products,
Sarah Spicer
Oracle Corporation, 500 Oracle Parkway, Box SB-6, Redwood Shores, CA 94065.
Jack Walsh Oracle Corporation does not warrant that this document is error-free.
Ken Woolfe
Robin Zimmerman Oracle and Express, Express Analyzer, Express Objects, Express Server, Personal
Express are trademarks or registered trademarks of Oracle Corporation.

All other products or company names are used for identification purposes only, and
Publisher may be trademarks of their respective owners.
Christine Markusic
Contents

Preface

Introduction
Course Objectives I-2
Agenda I-3
Summit Office Supply Schema I-7
The Course Application I-8

1 Why Upgrade to Oracle9i Forms?


Objectives 1-2
Oracle9i Products 1-3
Oracle9iDS Application Development 1-4
Oracle9iDS Business Intelligence 1-5
Benefits of Oracle9i Developer Suite 1-6
Oracle9i Forms Overview 1-7
Optimized for the Web 1-8
Productivity Enhancements 1-9
Globalization 1-10
Integration 1-11
Openness 1-12
Benefits of Oracle9i Forms 1-13
Streamlining Oracle9i Forms 1-14
Summary 1-16

2 Deploying Forms Applications on the Internet


Objectives 2-2
Oracle 9iAS Architecture 2-3
Oracle 9iAS Components 2-4
What Is OC4J? 2-5
What Is Oracle Forms Services? 2-6
Forms Services Architecture Overview 2-7
The Forms Servlet 2-8
The Forms Client 2-9
The Forms Listener Servlet 2-10
Benefits of the Forms Listener Servlet 2-11
The Forms Runtime Engine 2-12
Running a Form: Browser 2-13
Running a Form: Web Form Tester 2-14
Starting a Run-Time Session 2-15

iii
The Java Run-time Environment 2-19
Applet Instance Caching and JInitiator 1.3 2-20
Testing a Form: Starting Oracle Containers for Java (OC4J) 2-21
Testing a Form: Starting OC4J 2-22
Testing a Form: The Run Form Button 2-23
Customizing the Forms Services Configuration 2-24
Defining Forms Environment Variables for Run Time 2-25
Defining Forms Environment Variables for Design Time 2-26
Defining Forms Servlet Parameters 2-27
Defining Application-Specific Configurations 2-28
Summary 2-29
Practice 2 Overview 2-31

3 Migrating Existing Applications to Oracle9i Forms


Objectives 3-2
Migration Path 3-3
Upgrading from Older Versions 3-4
Upgrading from Forms Listener Deployment 3-6
Upgrading from Client-Server Deployment 3-8
Upgrading from Character Mode Deployment 3-10
Upgrading to Oracle9i Forms 3-11
Using the Oracle9i Forms Migration Assistant 3-12
Functions of the Migration Assistant 3-14
Configuring the Migration Assistant 3-15
Practice 3a 3-16
Integrating Graphics 3-18
Integrating Reports 3-19
Using RUN_REPORT_OBJECT 3-20
Step 1: Create a Report Object 3-21
Step 2: Set Properties of the Report Object 3-22
Step 3: Define Data to Pass to the Report 3-23
Step 4: Run the Report 3-24
Step 5: Display the Report 3-25
Using WEB.SHOW_DOCUMENT to Run a Report 3-26
Summary 3-27
Practice 3b 3-29

4 Designing Forms Outside the Builder


Objectives 4-2
How to Design Forms Without Forms Builder 4-3
What Can You Do with an API? 4-4
Advantages of Using an API 4-5
Using the Java API to Modify Modules 4-6
Advantages of JDAPI 4-7
JDAPI Architecture 4-8
The JDAPI Session 4-10
Creating New Modules 4-11
Adding Objects to Modules 4-12

iv
Saving and Compiling Modules 4-13
Loading Existing Modules 4-15
Using an Iterator 4-16
Modifying Forms Objects 4-17
Deleting Forms Objects 4-18
Copying and Subclassing 4-20
Handling Exceptions 4-21
Writing Generic Code 4-22
Special Cases in JDAPI Programming 4-23
Practice 4a 4-24
Why Convert Forms to XML? 4-27
XML Conversion Utilities 4-28
Converting a Forms Module to XML 4-29
Converting XML to a Forms Module: 4-30
Generating the Forms XML Schema File 4-31
Validating XML 4-32
XML Conversion Utilities Example 4-33
Summary 4-36
Practice 4b 4-38

5 Troubleshooting Forms Applications


Objectives 5-2
Debugging Tips 5-3
The Debugging Process 5-4
Setting Breakpoints 5-5
Setting Breakpoints: Stored Code 5-6
The Debug Console 5-7
Running a Form in Debug Mode 5-16
Stepping Through Code 5-17
Debugging a Forms Module 5-18
Remotely Debugging a Running Form 5-20
Practice 5a 5-23
Tracing and Logging Tools 5-28
Using Forms Trace 5-29
Configuring Forms Trace 5-30
Starting the Trace 5-31
Traceable Events 5-33
Obtaining Event Details 5-36
Viewing Forms Trace Output 5-38
Servlet Logging 5-41
Viewing the Log 5-43
Summary 5-45
Practice 5b 5-48

v
6 Integrating Java into Forms Applications
Objectives 6-2
Using Java in Forms 6-3
Support for Java 1.3 6-4
Using Client-Side Code 6-5
What Are JavaBeans? 6-7
What Are Pluggable Java Components? 6-8
Interacting with JavaBeans 6-9
Introducing the FBean Package 6-10
The FBean Package 6-11
Registering the Bean 6-13
Setting Bean Area Item Properties 6-14
Setting JavaBean Properties 6-15
Responding to Events 6-16
Interacting with Non-Event JavaBeans 6-18
Deploying JavaBeans for Forms Applications 6-19
Summary 6-21
Practice 6 Overview 6-22

7 Enhancing the User Experience


Objectives 7-2
The Cancelable LOV 7-3
Retrieving the Forms Version 7-4
The One Time Where Clause 7-5
Summary 7-6
Practice 7 Overview 7-7

8 Deploying Forms Applications Globally


Objectives 8-2
Defining Item Length for Different Character Sets 8-3
Adjusting for Different Time Zones 8-4
The Time Zone Data File 8-6
Implementing Time Zone Support 8-7
Time Zone Properties and Built-in 8-9
Time Zone Implementation Example 8-10
Displaying Applications in Multiple Languages 8-11
Detecting Browser Language Settings 8-12
Translated Applications at Run Time 8-13
Deploying Language-Specific Applications 8-14
Translating an Application 8-15

vi
Installing the TranslationHub Schema 8-16
Starting TranslationHub 8-17
The TranslationHub User Interface 8-18
Translating Applications 8-19
Constructing a Translation Project 8-20
Translating the Text 8-22
Building the Translated Software 8-23
Summary 8-24
Practice 8 Overview 8-27

A Practice Solutions

B Integrating Oracle9i Forms with Oracle 9i Application Server

C Managing the Team Development of Forms Applications

D Table Descriptions

vii
Preface
Oracle9i Forms Developer: New Features Preface - 2
Profile

Before You Begin This Course


Before you begin this course, you should have the following qualifications:
Working experience with developing applications using Oracle Forms6i.
Prerequisites
iAS Overview on OLN or experience administering the Oracle9i Application Server 9.0.2.
How This Course Is Organized
Oracle9i Forms Developer: New Features is an instructor-led course featuring lectures and hands-on
exercises. Online demonstrations and written practice sessions reinforce the concepts and skills
introduced.

Oracle9i Forms Developer: New Features Preface - 3


Related Publications

Oracle Publications
Title Part Number
Oracle9iAS Forms Services Deployment Guide A92175-01
Release 9.0.2
Oracle9iDS Forms Developer Reference Guide A97289-01
Oracle9i Forms Developer and Forms Services A92183-01
Migrating Forms Applications from Forms6i
Oracle9i Forms Developer and Forms Services
Migration Assistant (addendum to P/N A92183-01)
Additional Publications
Release notes:
<ORACLE_HOME>\doc\ids902welcome\relnotes\forms_developer\forms_relnotes.
pdf and toc.html
Release notes addendum:
http://otn.oracle.com/docs/products/forms/902docs/902formsaddendum.pdf

Oracle9i Forms Developer: New Features Preface - 4


Typographic Conventions

Typographic Conventions In Text

Convention Element Example


Bold Emphasized words and phrases To navigate within this application, do not
in Web content only click the Back and Forward buttons.

Bold italic Glossary terms (if there is a The algorithm inserts the new key.
glossary)

Brackets Key names Press [Enter].

Caps and Buttons, Click the Executable button.


lowercase check boxes, Select the Registration Required check
triggers, box.
windows
Assign a When-Validate-Item trigger.
Open the Master Schedule window.

Carets Menu paths Select File > Save.

Commas Key sequences Press and release these keys one at a


time:
[Alt], [F], [D]

Oracle9i Forms Developer: New Features Preface - 5


Typographic Conventions (continued)

Typographic Conventions In Text (continued)

Convention Object or Term Example


Courier New, Code output, Code output: debug.seti (I,300);
case sensitive SQL and PL/SQL
SQL code elements: Use the SELECT command to view
code elements, Java
information stored in the last_name column of the emp
code elements,
table.
directory names,
filenames, Java code elements: Java programming involves the
passwords, String and StringBuffer classes.
pathnames, URLs, Directory names: bin (DOS), $FMHOME (UNIX)
user input,
usernames Filenames: Locate the init.ora file.
Passwords: Use tiger as your password.
Pathnames: Open c:\my_docs\projects.
URLs: Go to http://www.oracle.com.
User input: Enter 300.
Usernames: Log on as scott.
Initial cap Graphics labels Customer address (but Oracle Payables)
(unless the term is a
proper noun)
Italic Emphasized words Do not save changes to the database.
and phrases in print For further information, see Oracle7 Server SQL
publications, titles of Language Reference Manual.
books and courses,
variables Enter user_id@us.oracle.com, where user_id is
the name of the user.
Plus signs Key combinations Press and hold these keys simultaneously:
[Control] + [Alt] + [Delete]

Quotation Lesson and chapter This subject is covered in Unit II, Lesson 3, Working with
marks titles in cross Objects.
references, interface
elements with long Select the Include a reusable module component and
names that have only click Finish.
initial caps
Use the WHERE clause of query property.

Oracle9i Forms Developer: New Features Preface - 6


Typographic Conventions (continued)
Typographic Conventions in Navigation Paths
This course uses simplified navigation paths, such as the following example, to direct you through
Oracle Applications.
Example:
Invoice Batch Summary
(N) Invoice > Entry > Invoice Batches Summary (M) Query > Find (B) Approve
This simplified path translates to the following:
1. (N) From the Navigator window, select Invoice > Entry > Invoice Batches Summary.
2. (M) From the menu, select Query > Find.
3. (B) Click the Approve button.
Notation:
(N) = Navigator (I) = Icon
(M) = Menu (H) = Hyperlink
(T) = Tab (B) = Button

Oracle9i Forms Developer: New Features Preface - 7


Oracle9i Forms Developer: New Features Preface - 8
Course Introduction

Copyright Oracle Corporation, 2002. All rights reserved.

Schedule: Timing Topic


20 minutes Lecture
20 minutes Total
Course Objectives

After completing this course, you should be able to do


the following:
Migrate Forms applications to Oracle9i Forms
Deploy Internet applications using the Forms
Listener Servlet
Use Java within Forms and modify Forms modules
Improve productivity with one-button testing and
three-tier debugging
Use new run-time features to enhance application
functionality
Deploy applications globally with different
languages, time zones, and character sets

I-2 Copyright Oracle Corporation, 2002. All rights reserved.

Course Aim
As an experienced Forms developer, you will learn how to leverage the benefits of
Oracle9i Forms. You will use the migration utility to upgrade a Forms application
developed in Forms6i, and then enhance the application using new features of Oracle9i
Forms.

Oracle9i Forms Developer: New Features I-2


Agenda

Day 1:
Lesson 1 Why Upgrade to Oracle9i Forms?
Lesson 2 Migrating Existing Applications to
Oracle9i Forms
Lesson 3 Deploying Forms Applications on the
Internet
Lesson 4 Designing Forms Modules outside
the Builder

I-3 Copyright Oracle Corporation, 2002. All rights reserved.

Lesson Topics
Lesson 1: Why Upgrade to Oracle9i Forms?
Oracle9i Developer Suite Overview
Oracle9i Forms Overview
- Productivity enhancements
- Globalization
- Integration
- Openness
- Web only
Benefits of Oracle9i Forms
Streamlining Oracle9i Forms
- Elimination of character mode and client-server run-time executables
- Elimination of item types and built-ins that are OS-specific or related to
character mode
- Elimination of features that are holdovers from older versions of Forms

Oracle9i Forms Developer: New Features I-3


Lesson Topics (continued)
Lesson 2: Deploying Forms Applications on the Internet
Oracle9i Application Server
OC4J
Oracle9iAS Forms Services:
- Forms Listener Servlet
- Forms Servlet
- Forms Client
Starting and stopping an OC4J instance
Testing from Run Form button
Lesson 3: Migrating Existing Applications to Oracle9i Forms
Migration path
Migration utility/PL/SQL Migration Assistant
Converting from Forms Listener deployment
Converting from client/server deployment
Converting from character mode deployment
Integrating graphics (from previous development)
Integrating reports using the RUN_REPORT_OBJECT command
Lesson 4: Designing Forms Modules outside the Builder
Benefits of batch modification of Forms modules
Using the Java API to modify Forms modules
Using XML conversion to modify Forms modules

Oracle9i Forms Developer: New Features I-4


Agenda

Day 2:
Lesson 5 Troubleshooting Forms Applications
Lesson 6 Integrating Java into Forms
Applications
Lesson 7 Enhancing the User Experience
Lesson 8 Deploying Forms Applications Globally

I-5 Copyright Oracle Corporation, 2002. All rights reserved.

Lesson Topics (continued)


Lesson 5: Troubleshooting Forms Applications
The Debug process
Components of the Debug Console
Setting breakpoints
Stepping through code
Debugging a Forms module
Remotely debugging a running form
Tracing and logging

Oracle9i Forms Developer: New Features I-5


Lesson Topics (continued)
Lesson 6: Integrating Java into Forms Applications
How you can use Java in Forms
JDK upgrade to 1.3
Using client-side code:
- FBean package
- JavaBeans
- Pluggable Java components
Lesson 7: Enhancing the User Experience
The cancelable LOV
Retrieving the Forms version
The one time where clause
Lesson 8: Deploying Forms Applications Globally
Detecting browser language settings
Deploying language-specific applications
Defining item length for different character sets
Adjusting for different time zones
Translating applications with Translation Hub

Oracle9i Forms Developer: New Features I-6


Summit Office Supply Schema
Order Entry
Application

I-7 Copyright Oracle Corporation, 2002. All rights reserved.

Introducing the Course Application


The Summit Office Supply Schema
The simplified table diagram shows the tables that are used throughout the course to build
the Forms application. These same tables are used in other Oracle courses as well.
Summit Office Supply is a company that sells office products to customers. Summit has a
number of employees in several departments. Some employees are sales representatives
who have a relationship with specific customers.
Customers place orders. Each order consists of one or more line items. Each line item
represents a product.
Many products have an associated image in the form of an image file.
The company products are stored in several warehouses. The contents of the warehouses
are managed in the inventory.

Oracle9i Forms Developer: New Features I-7


The Course Application

1 2 3 4 5 6 7

Customers form Orders form

I-8 Copyright Oracle Corporation, 2002. All rights reserved.

The Course Application


In this course, you will migrate a Forms6i application to Oracle9i Forms. The Forms6i
application is an order entry application consisting of two main forms: Customers and
Orders. The Orders form in the Forms6i application uses the RUN_PRODUCT command to
call Reports to display an invoice for the order.
To add functionality with new features of Oracle9i Forms, you will:
1. Use the new FBean package to integrate a hyperlink JavaBean and a color picker
JavaBean.
2. Add a cancelable LOV
3. Implement a one-time WHERE clause, so that when the Orders form is first called
from the Customers form, it displays orders for that customer, but can then be used
to query any order
4. Implement an About button to display the Forms version
5. Automatically convert the RUN_PRODUCT call to RUN_REPORT_OBJECT
6. Use a Pluggable Java Component (PJC) to implement rounded buttons, a rollover
button, and client-side data validation. This is not a new feature, but is included as
part of the topic about using Java on the client.
7. Implement automatic time zone conversion for the Order Date item.

Oracle9i Forms Developer: New Features I-8


The Course Application (continued)
In addition, you will perform the following:
Without opening Forms Builder, modify forms:
- Change the position and width of the Order Date item on Orders
- Modify the background color of the Account Manager Name on Customers
Troubleshoot the logic of a trigger in the Customers form
Debug a form that is running in a browser on another machine
Use Forms Trace to log information about triggers that fire and tabbed pages that the
user clicks in the Customers form
Perform Servlet logging to record session information when running the Customers
form
With the same URL, deploy different translations of the Orders form based on
browser language preferences
Customize the TranslationHub tool to your preferred user interface
Instructor Note
Demonstration
Before you demonstrate these forms, you will need to start OC4J and the RepSRV reports
server. There is a desktop shortcut to start OC4J (startinst.bat), and the batch file
to start the Reports Server is in your demo directory (RepSRV.bat). After starting OC4J
and the Reports Server, open Forms Builder and open the Summit form from the lab
directory.
As you discuss the features that the student will implement, run the Summit form and
invoke the Customers form from it. Invoke Orders from Customers. Demonstrate each
feature to be implemented that is listed on the previous page.
Be sure to leave OC4J and the Reports Server running. Students will be using the Reports
Server on your machine to run reports.

Oracle9i Forms Developer: New Features I-9


Oracle9i Forms Developer: New Features I-10
Why Upgrade to Oracle9i Forms?

Copyright Oracle Corporation, 2002. All rights reserved.

Schedule: Timing Topic


30 minutes Lecture
30 minutes Total
Objectives

After completing this lesson, you should be able to do


the following:
List the components of Oracle9i Developer Suite
Describe the benefits provided by Oracle9i Forms
Explain how Oracle9i Forms has been streamlined

1-2 Copyright Oracle Corporation, 2002. All rights reserved.

Lesson Aim
This lesson describes the features and benefits of Oracle9i Forms. You learn how it fits
within Oracle9i Developer Suite and how obsolete features have been eliminated in order
to streamline the product.
Note: If you encounter terminology that is unfamiliar, refer to
http://www.oracle.com/glossary for definitions.

Oracle9i Forms Developer: New Features 1-2


Oracle9i Products

Forms Services Forms Developer

1-3 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Products
Oracle9i Database manages all of your information including Word documents, Excel
spreadsheets, XML, and images. Oracle9iDS tools can automatically reuse the database
structure and its integrity constraints, which reduces the amount of manual coding.
Oracle9i Application Server (Oracle9iAS) runs all of your applications: Java, wireless,
portals, and business intelligence. Using Oracle9iAS, all applications developed with
Oracle9iDS can be deployed and managed in a single application server. The Oracle9i
Application Server contains Oracle9i Forms Services that you use to deploy your Forms
applications.
Oracle9i Developer Suite (Oracle9iDS) leverages the infrastructure offered by Oracle9i
Application Server (Oracle9iAS) and Oracle9i Database, enabling developers to build
scalable, secure, and reliable e-business applications quickly and easily. The suite
provides a complete and highly productive development environment for building
applications. Oracle9i Forms Developer is part of Oracle9i Developer Suite.
This lesson focuses on Oracle9i Developer Suite, while the next lesson provides more
detail about Oracle9i Application Server.

Oracle9i Forms Developer: New Features 1-3


Oracle9iDS Application Development

1-4 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9iDS Application Development


Modeling: Oracle9i Designer provides visual modeling, reverse engineering, and code
generation tools. Oracle9iDS also supports Unified Modeling Language (UML) by
utilizing visual tools for Activity and Class modeling within the JDeveloper component.
RAD: RAD capabilities in Oracle9iDS feature integrated builders, re-entrant wizards, live
previewers, and property inspectors in the Forms Developer component. The JDeveloper
component provides additional productivity through Business Components for Java
(BC4J), a built-in J2EE framework.
J2EE and Web Services: Oracle9iDS supports the latest J2EE 1.2 APIs, including
Enterprise JavaBeans (EJB), Java Server Pages (JSP), and Servlets. Web services support
Simple Object Access Protocol (SOAP), Web Service Definition Language (WSDL), and
Universal Description, Discovery, and Integration (UDDI).
Team Support: Oracle9i Software Configuration Management provides versioning,
dependency management and impact analysis for all objects and file types.

Oracle9i Forms Developer: New Features 1-4


Oracle9iDS Business Intelligence

1-5 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9iDS Business Intelligence


Extract, transformation, and load (ETL): Oracle9i Warehouse Builder provides a
graphical interface for mapping and transformation. It also provides an extensible
framework for integrating a diverse set of data sources and integration with Business
Intelligence Tools.
End user query and analysis: With Oracle9i Discoverer Administrator, you can create
and maintain a business-oriented view of the data that supports the Discoverer client tools:
Discoverer Plus and Discoverer Viewer (in Oracle9iAS), and Discoverer Desktop (in
Oracle9iDS).
Enterprise Reporting: Oracle9i Reports Developer enables the developer to access any
data, to publish it in any format, and to send it anywhere. Supported formats include
HTML with CSS, PDF, RTF, Postscript, and XML.
Instructor Note
This overview of iDS should not be presented in detail, but merely to show where Forms
Developer fits into the product set and the other tools that are available.

Oracle9i Forms Developer: New Features 1-5


Benefits of Oracle9i Developer Suite

Application Development

Discoverer
Designer
OWB
Forms
Reports
JDeveloper
SCM

Business Intelligence

1-6 Copyright Oracle Corporation, 2002. All rights reserved.

Benefits of Oracle9i Developer Suite


Oracle9iDS provides the following benefits:
Combines the power of Oracle Application Development tools and Oracle Business
Intelligence tools
Provides a standards-based Java and XML Integrated Development Environment
and supports the full application development life-cycle
Provides application development and modeling for PL/SQL development
Provides flexible and scalable solutions for Data Warehousing and Business
Intelligence
Optimized for the Oracle9i Database and Oracle9i Application Server
For further information on Oracle9iDS features and components, see Oracle9i Developer
Suite Product White Paper, December 2001.

Oracle9i Forms Developer: New Features 1-6


Oracle9i Forms Overview

Optimized for the Web


Productivity enhancements
Globalization
Integration
Openness

1-7 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Overview


Oracle9i Forms provides many new features that make developing and deploying Forms
applications more efficient than ever. You learn how to utilize these features in the
remaining lessons, but it helps to have an overview so that you will realize the benefits of
upgrading to Oracle9i Forms.

Oracle9i Forms Developer: New Features 1-7


Optimized for the Web

No client-server run-time executable


No character mode deployment
Why?
Single
Accessibility
Sign-on

Cost Openness
effective with Java

Ease of Call Web


maintenance Run thru services
firewalls

1-8 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Overview: Optimized for the Web


In order for the product to move forward and evolve, Oracle is refocusing Forms to
optimize it for Web deployment. This allows Oracle to improve the already rich Web user
interface based on Java, and to extend the openness of the product by allowing Java
integration on all three tiers. Client/server and character mode users must remain on
Oracle Forms6i unless they wish to migrate to Web deployment as well.
Web deployment offers the tremendous advantage of enabling businesses to distribute
information and services to a world-wide audience with comparatively minimal overhead
costs, easier maintainability, and new opportunities to integrate with other technologies:
Ease of deployment: To roll out a new application, simply give your users the
applications URL.
Centralized distribution: With Web deployment, application complexity moves off
each users desktop and onto centrally located and managed application servers.
Standards-based development: Internet application development adheres to industry
standards such as Java. Common language means faster and easier integration of
new applications.
Component-based development: Promotes increased productivity, easier
maintenance, and reusability.

Oracle9i Forms Developer: New Features 1-8


Productivity Enhancements
Development:
Run in browser directly from Forms Builder
N Tier remote debugging
Trace specific events
The Forms Java API (JDAPI)
Forms > XML > Forms conversion
Accessibility
Team development using SCM
Run Time:
Cancelable list of values
One-time WHERE clause
Built-in to get the Forms version number

1-9 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Overview: Productivity Enhancements


Oracle9i Forms enhances development productivity in a variety of ways:
You can test applications by running them in an n-tier environment directly from
Forms Builder.
You can invoke the new Forms Debugger, which is integrated into Forms Builder,
and you can even remotely debug an application that a user is running within the
Intranet.
You can log information about specific events.
You can perform modifications of modules using the new Java API or XML
conversion tool without opening Forms Builder.
Oracle9i Forms has been made easier to use for those with disabilities, both in the
development environment and in the Forms applications that you build and deploy.
Integration with Oracle9i Software Configuration Management (SCM) supports the
full application development life cycle; developers can check in and check out
modules they are developing to facilitate team development and version control.
Run-time enhancements include: a list of values that shows progress and can be canceled
by the user, a one-time WHERE clause that restricts the query on a block only the first
time the query is executed, and a new built-in that retrieves the Forms version.

Oracle9i Forms Developer: New Features 1-9


Globalization

Improved translation facilities


Browser language detection
Support for character semantics
Time zone support

1-10 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Overview: Globalization


Oracle9i Forms introduces a new tool for translating applications: Translation Hub. This
tool utilizes proven technology, as it has been used internally by Oracle for translating
applications and is now provided to customers with Oracle9iDS.
Oracle9i Forms can detect the language preference specified in the users browser. You
can configure Forms Services to deploy a language-specific application if one is available,
or a default application if there is no translation in the users language.
You can define the length of Forms items so that the correct storage is allocated,
regardless of whether the user employs a multibyte or single byte character set. And
Forms applications can now automatically perform time zone conversions.

Oracle9i Forms Developer: New Features 1-10


Integration

Application Server integration:


Internet deployment with the Forms Listener Servlet
and OC4J
Single Sign-on with Oracle Login Server
LDAP support with Oracle Internet Directory
Easy management with Oracle Enterprise Manager
Database integration: Character semantic support (new
Oracle9i feature).
Environment integration:
Time zone support
Automatic language detection

1-11 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Overview: Integration


Oracle9i Forms is tightly integrated with Oracle9iAS, and can leverage many of its
services, such as:
Oracle9iAS Containers for J2EE (OC4J): Forms applications are deployed using the
Forms Listener Servlet and OC4J to offer improved scalability and performance.
Single Sign-on (SSO), with user information stored in the Oracle Internet Directory
(OID) LDAP repository
Oracle Enterprise Manager (OEM): Oracle9iAS Forms Services can be managed
through the new browser-based user interface for OEM. Through the console, Forms
Services can be monitored for information such as response time, number of
connected sessions, CPU, and memory usage.
The previous page mentions some globalization features; some of these are made possible
because of integration with the database or the environment. Integration with the Oracle9i
database enables character semantic support, while integration with the environment
enables time zone support and deployment in multiple languages.

Oracle9i Forms Developer: New Features 1-11


Openness

Openness on the middle tier: Call Java classes with


the Java Importer.
Openness on the client:
Easily integrate Java Beans on the client
Extend Forms UI with Pluggable Java Components
JDK 1.3 support
Openness during development:
Perform bulk changes in your forms using the
Java API
Manipulate the source of a Forms application with
the XML converter

1-12 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Overview: Openness


Oracle9i Forms enables you to integrate with Java. The support for JavaBeans has been
enhanced over what was available in Forms6i with the inclusion of the FBean package.
You are not restricted to components developed with JDK 1.1 as you were with 6i,
because Oracle9i Forms uses JDK 1.3 that enables you to integrate the latest components
and services.
Adding to the Forms C API, introduced with Forms 5.0, Oracle9i Forms includes a Java
API (JDAPI). Java programmers can use the JDAPI to perform bulk changes to Forms
modules. In addition, you can convert modules to XML and back, which gives you
another way to make changes to your applications without opening Forms Builder.

Oracle9i Forms Developer: New Features 1-12


Benefits of Oracle9i Forms

With Oracle9i Forms Developer and Oracle9iAS Forms


Services, you can:
Rapidly build interactive multilanguage
applications that are optimized for the Internet and
that provide users with a rich Java UI without
writing Java code
Protect your investment by migrating legacy
client/server applications to the Internet with rich
Java user interfaces

1-13 Copyright Oracle Corporation, 2002. All rights reserved.

Benefits of Oracle9i Forms


Oracle9i Forms provides many benefits, both for new development and for existing
applications.
Oracle9iDS Forms Developer is a RAD tool that enables you to build and test applications
that, when deployed with Oracle9iAS Forms Services, display a rich Java UI in a Web
browser. The developer of the application does no Java coding; the UI is automatically
provided by Forms Services. You can deploy applications so that users can see the UI in
their own language and character set, with time zone conversion performed automatically.
You can take a legacy Forms application that was previously deployed in client/server or
character mode and use it on the Web with little or no modification after migrating the
application to Oracle9i Forms. You can use all the native capabilities of Forms, such as
built-in transaction and record management, combined with the flexibility of Java.

Oracle9i Forms Developer: New Features 1-13


Streamlining Oracle9i Forms

Oracle9i Forms is streamlined by the removal of:


Features that are holdovers from older versions of
Forms
Character mode and client-server run-time
executables
Item types and built-ins that are OS-specific or
related to client-server or character mode

See white paper


Oracle9i Forms:
Features Obsolescence

1-14 Copyright Oracle Corporation, 2002. All rights reserved.

Streamlining Oracle9i Forms


With the move to pervasive Web deployment and the release of Oracle9i Forms, Oracle is
simplifying the product set and continuing to optimize the product for building and
deploying Internet applications. This allows Oracle to put all its efforts into improving the
already rich Web user interface based on Java, and to extend the openness of the product
by allowing Java integration on all three tiers.
Features being removed:
Client server run-time executable
Character mode run-time executable
Operating system specific item types: OLE container, VBX, OCX, and sound item
Menu features:
- Plus, Form, and Macro command types
- Menu parameters (new system variable :SYSTEM.TRIGGER_MENUOPTION
to replace menu parameter :SO)
Note: Full-screen and bar menus were removed from Forms6i and remain unsupported in
Oracle9i Forms.

Oracle9i Forms Developer: New Features 1-14


Streamlining Oracle9i Forms (continued)
Obsolete and no longer supported built-ins and properties:
- Those related to obsolete item types
- Those related to full-screen menus
- Character mode properties and logical attributes
- Break and the Debug package (except Debug.Suspend)
- RUN_PRODUCT built-in (except for integrating Graphics)
- RUNTIME_COMPATIBILITY_MODE and
DATE_FORMAT_COMPATIBILITY_MODE properties
- Menu built-ins related to obsolete menu features
Forms version 2 style triggers and lists of values
Command line options to Runform that relate to obsolete features
Use of the database for module storage
Components being removed:
Oracle Forms Listener and Load Balancing Components
Oracle Forms Server Cartridge and CGI
Oracle Procedure Builder
Oracle Project Builder
Oracle Translation Builder
Oracle Graphics
Oracle Query Builder/Schema Builder (except as used internally, as in LOV Wizard)
Oracle Terminal
Open Client Adapters (OCA)
Tuxedo Integration
Performance Event Collection Services (PECS)
PVCS and Clearcase Integration
Tightening up of trigger and built-in usage:
Stricter enforcement of defining triggers at levels that make sense:
- Allowed only at block or form level:
When-Clear-Block
When-Create-Record
When-Database-Record
When-New-Record-Instance
When-Remove-Record
- Allowed only at form level: When-New-Form-Instance
Preventing programmatic navigation (GO_ITEM) to non-enabled items, unless
FORMS90_REJECT_GO_DISABLED_ITEM (new environment variable) is set to
FALSE
Note: For details about obsolete features removed from Forms, see the Oracle9i Forms:
Features Obsolescence white paper, available from
http://otn.oracle.com/products/forms/pdf/featuresobsolescence.pdf.

Oracle9i Forms Developer: New Features 1-15


Summary

In this lesson, you should have learned that:


Oracle9i Developer Suite includes the following
components:
For application development: JDeveloper, Designer,
Software Configuration Manager, and Forms
Developer
For Business Intelligence: Warehouse Builder,
Discoverer, and Reports
Oracle9i Forms enables you to:
Provide a Java UI without Java coding
Utilize built-in Forms functionality
Migrate existing applications to the Web

1-16 Copyright Oracle Corporation, 2002. All rights reserved.

Summary
Including Oracle Forms Developer as part of Oracle9i Developer Suite provides access to
a variety of tools to build Internet applications. Other application development tools
included are JDeveloper, Designer, and Software Configuration Manager. Business
Intelligence is provided by tools such as Warehouse Builder, Discoverer, and Reports.
Oracle9i Forms is optimized for Web deployment. It enables you to provide users with a
rich Java interface without any Java coding. You can rapidly develop new applications
and take advantage of the functionality built into the Forms product, such as transaction
and record management, automatic creation and coordination of master-detail
relationships, and so on. You can migrate existing character mode or client-server
applications to the Web with little or no modification by upgrading them to Oracle9i
Forms.

Oracle9i Forms Developer: New Features 1-16


Summary

Oracle9i Forms has been streamlined to remove


item types, properties, and built-ins:
Related to character mode
Related to client-server
Specific to older Forms versions
Specific to an operating system
This enables Oracle9i Forms to be focused on
Web development and deployment.

1-17 Copyright Oracle Corporation, 2002. All rights reserved.

Summary (continued)
Because Oracle9i Forms is for Web deployment, the product has been streamlined to
eliminate properties, built-ins, and item types related to character mode, client-server, and
older versions of Forms. This enables Oracle to focus its development efforts on
enhancing the functionality, performance, and scalability of applications deployed on the
Web.

Oracle9i Forms Developer: New Features 1-17


Oracle9i Forms Developer: New Features 1-18
Deploying Forms Applications
on the Internet

Copyright Oracle Corporation, 2002. All rights reserved.

Schedule: Timing Topic


60 minutes Lecture
40 minutes Practice
100 minutes Total
Objectives

After completing this lesson, you should be able to do


the following:
Describe the architecture of Oracle9i Application
Server
Explain the role of Oracle Containers for J2EE
(OC4J) in deploying applications
Describe the components of Oracle9i Forms
Services
Run a form from the Forms Builder using OC4J

2-2 Copyright Oracle Corporation, 2002. All rights reserved.

Lesson Aim
This lesson describes the architecture of Oracle9i Application Server, presenting detailed
information about OC4J and Forms Services as the components of 9iAS used to deploy
Forms applications to the Internet. You also learn how to use the OC4J that is included
with Oracle9i Developer Suite to test Forms modules from within Forms Builder.
If some of the terms used in this lesson are unfamiliar to you, refer to the glossary
available at: http://www.oracle.com/glossary.

Oracle9i Forms Developer: New Features 2-2


Oracle 9iAS Architecture

2-3 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Application Server Architecture


Oracle9iAS has a layered architecture that consists of the following services:
Communication Services: Communication management for a variety of protocols.
Application Services: A J2EE Container that provides a common Run-Time
environment for applications developed as JSPs, Servlets, EJBs, and Web Services.
System Services: A common set of Run-Time services that are necessary for J2EE
applications and Web Services, such as request dispatch and scheduling, resource
management, resource pooling,clustering, fault monitoring, transaction
management, and messaging.
Management Services: A common set of systems management services to monitor
the status, performance, and faults of the system; to monitor resource consumption
and usage; to manage a single instance or cluster of instances; to centrally
administer security for users and applications; and to provide a comprehensive
directory service framework to manage users.
Connectivity Services: Provide connectivity to a variety of systems
Solutions: A comprehensive set of solutions all built on the infrastructure described
above, including Enterprise Portals, Enterprise Integration, Business Intelligence,
Wireless, and ISV Solutions.

Oracle9i Forms Developer: New Features 2-3


Oracle 9iAS Components

Oracle9iAS
Oracle9iAS
Containers
Forms Services
for J2EE

2-4 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Application Server Components


With the components of Oracle9iAS, you can:
Extract and analyze business intelligence: Clickstream, Personalization, Reports
Services, Discoverer
Integrate your business: InterConnect, Workflow, Unified Messaging, Internet File
System
Create personalized portals: Oracle9iAS Portal
Deploy dynamic web applications: XDK, Web Services, Forms Services, OC4J,
HTTP Server
Manage and secure your web infrastructure: Enterprise Manager, Security,
Internet Directory (see Appendix B)
For further information on Oracle9iAS, see: Oracle9i Application Server Product White
Paper and Oracle9i Application Server Release 2 Data Sheet. Appendix B presents
additional information about integrating Forms with Oracle9i Application Server.
Instructor Note
The overview of iAS should not be presented in detail, but merely to show where Forms
Services fits into the product set.

Oracle9i Forms Developer: New Features 2-4


What Is OC4J?

A component of
Oracle9i Application
Server that deploys Oracle9iAS
J2EE applications containers
for J2EE

2-5 Copyright Oracle Corporation, 2002. All rights reserved.

What Is OC4J?
Oracle9iAS Containers for J2EE (OC4J) is Oracles Java 2 Enterprise Edition (J2EE)
container that executes on any Java Virtual Machine (the JVM provided on each operating
system and hardware platform). It is implemented completely in Java, making it
lightweight and easy to install. At the same time, it provides complete support for J2EE
applications, including servlets, Enterprise JavaBeans, Java Server Pages, and so on.
OC4J is ideally suited to run Forms applications. Oracle9iAS Forms Services are
deployed within OC4J, offering improved performance and scalability. When the
Oracle9iAS HTTP Server (OHS) receives a request for a Forms application, its
mod_oc4j component routes the request to OC4J.
Later in this lesson, you will see that you can also test Forms applications by running
them in OC4J directly from Forms Builder. In this case, OC4J acts as a lightweight Web
listener as well as a Servlet container.

Oracle9i Forms Developer: New Features 2-5


What Is Oracle Forms Services?

A component of
Oracle9i Application
Server that deploys Oracle9iAS
Forms applications to Forms Services
Java clients in a Web
environment

2-6 Copyright Oracle Corporation, 2002. All rights reserved.

What Is Oracle Forms Services?


Oracle Forms Services is a component of Oracle9i Application Server for delivering
Oracle Forms Developer applications to the Internet. Oracle Forms Services automatically
provides the infrastructure needed to successfully deliver applications on the Internet
through built-in services and optimizations.
Oracle Forms Services uses a three-tier architecture to deploy database applications:
The client tier contains the Web browser, where the application is displayed and
used.
The middle tier is the application server, where the application logic and server
software reside.
The database tier is the database server, where enterprise data is stored.
All trigger processing occurs on database and application servers. End users run Forms
Developer applications in a Web browser, where user interface processing occurs.
Note: See the Oracle9i Application Server Release 2, Forms Services Overview white
paper for additional information about Forms Services. This paper is available at:
http://otn.oracle.com/products/forms/pdf/forms9iarchitecture.pdf.

Oracle9i Forms Developer: New Features 2-6


Forms Services Architecture Overview
Middle Tier:
Client Tier Application Server Database Tier

Forms Listener
Servlet
Forms Servlet

Forms Runtime
Incrementally User
User interface
interface Net
downloaded layer Services DB
Application
logic layer
Data manager/
JRE PL/SQL engine

Java applet
Files containing
application code

2-7 Copyright Oracle Corporation, 2002. All rights reserved.

Forms Services Architecture Overview


Forms Services consists of four major components: the Forms Servlet, the Java client (or
Forms client), the Forms Listener Servlet, and the Forms Runtime Engine.
You may already be familiar with the Servlet architecture for deploying Forms
applications, even though it is actually a new feature of Oracle9i Forms. Because the new
architecture provides so many advantages over the previous Forms Listener and CGI
deployment, it was backported to later Forms6i patchsets.
When a user runs a forms session over the Web, a thin Java-based Forms applet is
dynamically downloaded from the application server and automatically cached on the
Java client machine. The same Java applet code can be used for any form, regardless of
size and complexity.
Although Forms Services uses a Java applet to display the form on the client browser, a
developer does not need to know Java in order to develop and deploy a Forms application.
After we now examine the components of Forms Services, we will see how each
component functions when the user requests an application.

Oracle9i Forms Developer: New Features 2-7


The Forms Servlet

URL Pointing to Forms Servlet


http://summit.com/forms90/f90servlet?form=customers.f

Desktop Client Application Server


Web Server
Static HTML files
formsweb.cfg HTTP Server
basejini.html
URL PARAMETERS: Forms Services
?form=customers.fmx
&userid=un/pw@db Forms Client
&buffer_records=NO Base HTML files
...
Forms Servlet
Dynamic Forms Listener Servlet
HTML file Forms Runtime Engine
is created

2-8 Copyright Oracle Corporation, 2002. All rights reserved.

Forms Services Architecture: What Is the Forms Servlet?


The Forms Servlet is a Java servlet that creates a dynamic HTML file by merging
information from the following sources:
The Forms Web configuration file
The Forms base HTML file
The applications URL parameters
The Forms Servlet also plays a part in Single Sign-on, which is described in Appendix B.
Instructor Note
Demonstration: In WordPad, open the formsweb.cfg file and the basejini.htm
files from the forms90\server directory. Using the module= (from
basejini.htm) and form= (from formsweb.cfg), explain how the Forms Servlet
uses these to construct the HTML file to run the designated form. Also explain that
passing a parameter on the command line overrides the specification in formsweb.cfg.

Oracle9i Forms Developer: New Features 2-8


The Forms Client

Generic Java applet Desktop Client

Responsibilities:
Displays the forms user
interface
Processes user interaction
Forms Client
back to Forms Services
Processes incoming Generic
messages Java applet
from Forms Services

2-9 Copyright Oracle Corporation, 2002. All rights reserved.

Forms Services Architecture: What Is the Forms Client?


The Forms Client is a generic Java applet. Forms Services dynamically downloads this
applet and automatically caches it on the client machine. The Forms Client consists of a
set of Java classes.
You do not have to deploy a separate Java applet for each application. The same generic
applet is used to run any Forms Services application, regardless of its size and complexity.
Responsibilities of the Forms Client
The Forms Client represents the user interface layer and has three primary functions:
To render the Forms Services application display for the user
To efficiently process user interaction back to Forms Services
To process incoming messages from Forms Services and efficiently translate them
into interface objects for the end user

Oracle9i Forms Developer: New Features 2-9


The Forms Listener Servlet

HTTP Server Forms


HTTP/
HTTPS
Listener
Servlet

Java Servlet that:


Middle Tier Forms
Creates Forms
Runtime
Runtime Process
process
for each client
Stops the Forms Runtime process at session end
Manages network communications between client
and Forms Runtime process
Communicates through Web server process

2-10 Copyright Oracle Corporation, 2002. All rights reserved.

Forms Services Architecture: What Is the Forms Listener Servlet?


The Forms Listener Servlet is a Java servlet that runs within OC4J. The mod_oc4j
component of the Oracle9iAS HTTP Server (OHS) directs HTTP requests for the Forms
Listener Servlet directly to the servlet instances.
The Forms Listener Servlet is in charge of:
Managing the creation of the Forms Runtime process for each client
Managing the network communications that occur between the client and its
associated Forms Runtime process, through the Web server
This means that the client sends HTTP requests and receives HTTP responses from the
Web server (OHS) process itself. Since OHS acts as the network endpoint for the client,
there is no need to expose additional server machines and ports at the firewall.
Prior to development of the Forms Listener Servlet, the architecture included a Forms
Server Listener that created an extra process to manage, and opened a separate port on the
Web server. The new Forms Listener Servlet architecture offers several advantages over
the Forms Listener that it replaces, as shown on the next page.

Oracle9i Forms Developer: New Features 2-10


Benefits of the Forms Listener Servlet

The Forms Listener Servlet provides several


advantages over the previous Forms Listener
architecture:
Supports broad range of firewalls
and proxies
Supports HTTP/1.1 or HTTP/1.0
No extra process to manage
No extra certificate needed to deploy forms
applications with SSL
Uses standard load balancing techniques
Native Internet Explorer 5.x+ Internet support

2-11 Copyright Oracle Corporation, 2002. All rights reserved.

Why Use the Forms Listener Servlet?


Benefits of the Forms Listener Servlet include:
Broad range of firewalls and proxies supported: With no direct connection between
the client and the Forms Runtime process, this architecture supports any firewall or
proxy able to work with any standard persistent servlet.
No protocol restriction (HTTP/1.1 or HTTP1.0): Although the use of HTTP/1.1
compliant proxies provides better performance, this architecture works as well with
proxies implementing only HTTP/1.0.
No extra process to manage: This architecture removes the need for the Forms
Listener process, thus removing the tasks to start and stop this process.
No specific certificate to purchase/manage for SSL deployment: The HTTPS
connection exists only between the client browser and the Web server. There is no
specific configuration at the Forms Services level.
Standard load balancing techniques support: You no longer need to use Forms-
specific load balancing.
Internet Explorer native support: Deploying with the Listener Servlet enables the use
with the native JVM of IE 5.x or greater for Internet deployment (not available in
initial release of Oracle9i Forms, but will be implemented in a patchset).

Oracle9i Forms Developer: New Features 2-11


The Forms Runtime Engine

The Forms Runtime Engine:


Is a process (ifweb90) that runs on the
Application Server
Manages application logic and processing
Communicates with client browser and database

2-12 Copyright Oracle Corporation, 2002. All rights reserved.

Forms Services Architecture: What Is the Forms Runtime Engine?


The Forms Runtime Engine is a process on the Application Server that is started by the
Forms Listener Servlet. You cannot start the Forms Runtime Engine directly, as you could
when running a Forms application in client/server mode with previous Forms versions.
However, it performs a similar function to the client/server Forms Runtime Engine except
that the user interface is handled by the Java-based Forms Client.
The Forms Runtime Engine handles all the application logic and Forms functionality,
executing the code written into the application. It manages requests from the Forms Client
and sends metadata to the client to describe the user interface. It connects to and
communicates with the Oracle9i database via Oracle Net Services, the replacement for
Net8 and SQL*Net.

Oracle9i Forms Developer: New Features 2-12


Running a Form: Browser

How do I
access this
application? http://summit.com:80/forms90/f90servlet?form=customers.fmx&userid=ora1/oracle@

How do I access
this new
application?

http://summit.com:80/forms90/f90servlet
?form=customers.fmx&userid=username/password@database
&buffer_records=NO&debug_messages=NO&array=YES
&query_only=NO

2-13 Copyright Oracle Corporation, 2002. All rights reserved.

Running a Form: Browser


The URL to invoke an application must have the following format:
http://host[:port]/<forms servlet or html
file>[parameters]
(optional portions of URL enclosed in square brackets)
Example: The URL shown above consists of the following components:
Protocol http
Host summit.com
Port for HTTP Server 80 default for HTTP Server OR
or OC4J 8888 default for OC4J (use only for testing)
Forms Servlet Alias /forms90/f90servlet
or static HTML file
Parameters: this section begins with form=customers.fmx
?; parameters separated by & userid=username/password@database
(can be specified in the URL or buffer_records=NO
taken from the Forms configuration debug_messages=NO
....
file)

Oracle9i Forms Developer: New Features 2-13


Running a Form: Web Form Tester

2-14 Copyright Oracle Corporation, 2002. All rights reserved.

Running a Form: Web Form Tester


It is common to provide an HTML front end to allow the user to choose the application to
start, then construct the URL based on the users choice. An example of this type of front
end is the Web Form Tester that comes with Oracle9iDS, located in the
<ids_HOME>\tools\web90\html subdirectory.
You can test your Forms applications using the Web Form Tester, which is a simple
HTML page that enables you to enter the information needed by Forms Services to run a
form. The HTML page is called runform.htm.
Because Oracle9i Forms enables you to test a form on the Web directly from Forms
Builder, you will not use the Web Form Tester in this course.

Oracle9i Forms Developer: New Features 2-14


Starting a Run-Time Session
Client Tier Middle Tier: Application Server

Web Browser
1
URL
2
http://summit.com:80/forms90/f90se
Oracle9iAS OC4J
HTTP Servlet Engine
Server Forms
Servlet
MOD_OC4J
Forms
Listener
Servlet

3 Forms
Runtime
Engine

Forms Application Executables


FMX files MMX files PLX files

2-15 Copyright Oracle Corporation, 2002. All rights reserved.

Running a Form: Starting a Run-Time Session


1. The user accesses the URL that indicates that a Forms application should be run.
2. The Oracle9iAS HTTP Server (OHS) receives an HTTP request from the browser
client. and forwards the request to OC4J, because the /forms90/f90servlet
path matches the OC4J mount directive for the Forms Servlet in the
forms90.conf file. OC4J maps the request to the Oracle9i Forms application,
whose context root is /forms90. It maps the request to the Forms Servlet, using
the f90servlet servlet mapping specified in the web.xml file.
3. The Forms Servlet dynamically creates an HTML page containing all the
information to start the Forms session. The Forms Servlet (running in OC4J)
processes the request as follows:
- Opens the servlet configuration file. If the configFileName parameter is
not specified in the forms90oc4j.properties file, the default
configuration file forms90/server/formsweb.cfg is used.
- Determines which configuration section to use from the formsweb.cfg file.
For example, if the URL contains the query parameter config=test, it will
use the [test] section.

Oracle9i Forms Developer: New Features 2-15


Running a Form: Starting a Run-Time Session (continued)
- Determines which base HTML file to use, based on the type and platform of the
browser that made the request and the settings of various parameters in the
formsweb.cfg file (specifically, baseHTMLie,
baseHTMLjinitiator, baseHTMLjpi, baseHTML, and IE).
- Performs variable substitution in the base HTML file, as follows:
Whenever a variable (like %myParam%) is encountered, the Forms Servlet
looks for a matching URL query parameter (for example, &myParam=xxx).
If there is no matching URL query parameter, it looks for a matching
parameter in the formsweb.cfg file. If a matching parameter is found, the
%myParam% variable is replaced with the parameter value.
- Sends the contents back as an HTML page to the users Web browser.
Depending on which base HTML file the Forms Servlet selected, the HTML
page sent back to the Web browser will contain an Applet, Object, or Embed
tag to start up the Forms applet. The Forms applet runs in a JVM, either the
Web browsers native JVM, or a "plugged in" JVM like Oracle JInitiator or
Suns Java plug-in. If the base HTML file selected was for a plug-in, and if the
user does not already have that plug-in installed, the user is prompted to install
the plug-in. In the case of JInitiator, the download location is under the virtual
path /forms90/jinitiator (a virtual path defined in the
forms90.conf file).

Oracle9i Forms Developer: New Features 2-16


Starting a Run-Time Session
Client Tier Middle Tier: Application Server

Web Browser
4
URL http://summit.com:80/forms90/f90se Oracle9iAS OC4J
HTTP Servlet Engine
Server Forms
Servlet
MOD_OC4J
Forms
Listener
Applet Servlet
5 6
started
Forms
Runtime
6 Engine

6
Forms Application Executables
FMX files MMX files PLX files DB

2-17 Copyright Oracle Corporation, 2002. All rights reserved.

Running a Form: Starting a Run-Time Session (continued)


4. The Oracle9iAS HTTP Server downloads a generic applet to the client after
checking that it has not already been downloaded. The client caches the applet so
that it can run future Forms applications without downloading it again. The
location of the applet is specified by the applet codebase and archive
parameters. For example, if the user is running with Oracle JInitiator, the applet
code is loaded from the forms90/java/f90all_jinit.jar file. The
virtual path definition in the forms90.conf file for /forms90/java allows
the applet code to be loaded from the Web server.
5. The client applet contacts the Forms Listener Servlet to start the session. The
Forms Listener Servlet starts an instance of the Forms Runtime Engine
(ifweb90) on the Forms Services machine (middle tier). The Forms Listener
Servlet passes to Forms Runtime any command-line parameters (such as form
name, user ID and password, database, and so on) and any user-defined Forms
Builder parameters that were included in the HTML file.
6. The Forms Listener Servlet establishes a connection with the Runtime Engine that
connects to the database if needed and loads application executable files.

Oracle9i Forms Developer: New Features 2-17


Starting a Run-Time Session
Client Tier Middle Tier: Application Server

Web Browser

URL http://summit.com:80/forms90/f90se
Oracle9iAS OC4J
7 HTTP Servlet Engine
Server Forms
Servlet
MOD_OC4J
Forms
8 Listener
Servlet
8
Forms
Runtime
Engine

Forms Application Executables


FMX files MMX files PLX files

2-18 Copyright Oracle Corporation, 2002. All rights reserved.

Running a Form: Starting a Run-Time Session (continued)


7. The Forms applet displays the applications user interface in the main window of the
users Web browser.
8. The Forms Listener Servlet, working through the Oracle9iAS HTTP Server,
manages communication between the Forms applet and the Forms Runtime Engine.
Technical Note
More information about the Oracle Forms Listener Servlet is available in the Oracle white
paper: Oracle9i Application Server Forms Services Forms6i Patch 9: Oracle Forms
Listener Servlet for Deployment of Forms on the Internet, available from
http://otn.oracle.com/products/forms/pdf/p9listenerservlet.pdf.

Oracle9i Forms Developer: New Features 2-18


The Java Run-Time Environment

The Forms applet runs in a Java Run-Time Environment


(JRE) on the client machine.
Types of JREs:
Java-enabled browser (native)
JInitiator (Oracle-supplied plug-in to Web browser)
that provides:
Incremental Java archive (JAR) file downloading
JAR file caching
Applet instance caching (not available in JInitiator
1.3.1)
Automatic Java security configuration

2-19 Copyright Oracle Corporation, 2002. All rights reserved.

The Java Run-Time Environment


The Web browser can run a Java applet because it provides a Java Run-Time
Environment (JRE). However, not all Web browsers are able to natively run the Forms
client. On Windows platforms, Oracle provides a plug-in called JInitiator that provides an
alternate JRE capable of running the Forms applet.
JInitiator provides several benefits:
It is able to incrementally download the Java archive files (JAR files) needed for the
Forms client, providing faster application startup.
It caches the JAR files locally, so that they do not need to be downloaded again.
It is automatically configured to run the Forms application in trusted mode. This
enables the application to have access to resources that the Java sandbox model
normally prohibits it from using, such as print services.
It improves application performance within a browser session by applet instance
caching. When a user navigates from the current page in the browser, the running
Forms application is cached. When the user comes back to the page containing the
applet, the applet that was running is automatically fully restored, including all of
the data entered in the application.
Note: Applet instance caching is not available with the JDK version used by
JInitiator 1.3.x, shipped with Oracle9iDS.
Oracle9i Forms Developer: New Features 2-19
Applet Instance Caching and JInitiator 1.3

No applet instance caching with JInitiator 1.3


Major behavior differences between JInitiator 1.1
and JInitiator 1.3
Will be fixed when Oracle certifies the Javasoft
1.4.1 Java Plugin
Workaround: Use a launch window that calls
JavaScript

<A HREF="javascript:void window.open


(http://www.myformsURL.com, window_name,
status=yes, resizable=yes, scrollbars=yes,
menubar=no, toolbar=no)" TARGET=_top>Run My
Forms Application</A>

2-20 Copyright Oracle Corporation, 2002. All rights reserved.

Applet Caching and JInitiator 1.3


Because of a change in Javasofts JDK 1.3, JInitiator can no longer provide applet instance
caching as it could when based on earlier versions of the JDK. When the browser destroys
the page that hosts the Forms applet, the applet is destroyed as well. The application
restarts if the user navigates back to the page, but the context and data are lost.
When Oracle certifies Forms applications with the Javasoft 1.4.1 Java Plugin, applet
instance caching will again be possible.
You can work around this limitation by using a Launch Window to host the Forms applet
and prevent the user from inadvertently navigating away and thus exiting Forms. When
the user enters the Launch URL, it executes JavaScript that opens the Forms URL in kiosk
mode, without browser toolbars, buttons, or address bar, making it more difficult to
navigate away from the Forms page.
Instructor Note
Demonstration: Open launch.htm file in Notepad and edit the URLs to use your
machine name and connect string. Show students the JavaScript code. Run the file in
Internet Explorer. Click one of the links to run a form. Point out that the Forms browser
window has no toolbars or address bar for navigation.

Oracle9i Forms Developer: New Features 2-20


Testing a Form:
Starting Oracle Containers for Java (OC4J)

Oracle Containers for J2EE


(OC4J) is included with
Oracle9iDS to enable testing.
On NT, run batch file to start
OC4J.

Forms Developer

Oracle9i Developer Suite


Programs

2-21 Copyright Oracle Corporation, 2002. All rights reserved.

Starting OC4J
As you learned earlier in this lesson, Oracle Containers for J2EE (OC4J) is the Servlet
container that is used to run a Forms application. Although it is a component of
Oracle9iAS, OC4J is also included in Oracle9i Developer Suite to enable you to test your
applications on the same machine on which you are running Forms Builder. In this role,
OC4J functions both as a lightweight Web listener and as a Servlet container. In other
words, you do not need to install Oracle9iAS to test, but you must install it to deploy your
production applications.
To use OC4J on Windows NT, you start it by executing the batch file provided, called
startinst.bat. This file is located in the j2ee\Oracle9iDS\ subdirectory of
your 9iDS ORACLE_HOME. You can execute these batch files on Windows NT from the
Start Menu: Programs > Oracle9i Developer Suite > Forms Developer > Start (or
Shutdown) OC4J Instance.
If you will be testing applications on your client machine, you can set up a desktop
shortcut to this batch file, and also to the stopinst.bat batch file used to stop the
OC4J instance.

Oracle9i Forms Developer: New Features 2-21


Testing a Form: Starting OC4J

OC4J starts in DOS window:


Minimize window
Closing window aborts OC4J
Run batch file to stop OC4J

2-22 Copyright Oracle Corporation, 2002. All rights reserved.

Starting OC4J (continued)


The batch file executes in a separate window. You can minimize this window if desired.
Do not close this window, or you will abort the OC4J instance.
When you no longer need to run OC4J, you can execute the stopinst.bat batch file
to stop the OC4J instance.

Oracle9i Forms Developer: New Features 2-22


Testing a Form: The Run Form Button

With the Run Form menu


command or button, you can:
Run a form from Forms Builder
Test the form in a three-tier environment
Run Form takes settings from
Preferences:
Edit > Preferences
Runtime tab
Set Web Browser
location if desired
Set Application Server
URL to point to Forms
Servlet:
http://<host>:8888/forms90/f90servlet

2-23 Copyright Oracle Corporation, 2002. All rights reserved.

Testing a Form with the Run Form Button


Using the Run Form menu command or button, you can run a form module in a Web
browser from within Forms Builder. This makes it easy to test your application in a three-
tier environment, with all components appearing and behaving as they would for a user of
the application.
By default, Forms Builder uses OC4J on the local machine for testing. To change this, you
can specify other settings in the Preferences dialog that you access from Edit >
Preferences:
Click the Runtime tab.
Set the Application Server URL: This must be a URL pointing to the Forms Servlet,
either on the middle tier or on the same machine where you are running Forms
Builder. You can also use the config parameter to specify a named configuration
in the Forms Web configuration file (formsweb.cfg by default).
Example: OC4J running on local machine called my_pc on default port of 8888:
http://my_pc:8888/forms90/f90servlet?config=myapp
You can click Set Default for the default setting (OC4J on local machine).
You can set the Web Browser Location if you want to run in a different browser
than the default for your machine.

Oracle9i Forms Developer: New Features 2-23


Customizing the Forms
Services Configuration

Files used to customize the default configuration:


Environment configuration: default.env
Forms Servlet configuration: formsweb.cfg
Oracle HTTP Server configuration: forms90.conf
OC4J configuration: web.xml
These files are installed and configured
automatically during installation of Oracle9iAS or
Oracle9iDS.
Other than the formsweb.cfg file that is used by
Forms Web CGI in Forms6i, all of the above
configuration files are new with the Servlet
architecture.

2-24 Copyright Oracle Corporation, 2002. All rights reserved.

Customizing the Forms Services Configuration


When you install Oracle9iAS, Forms Services is automatically configured with a default
setup that in many cases you will not modify. However, if you need to customize the
Forms Services configuration, you can modify one or more of the following files, located
in the forms90\server subdirectory of your 9iAS installation:
File name Purpose
default.env Environment control file for Forms Services: Set environment variables
formsweb.cfg Forms Servlet default configuration file: Set application-specific system
parameters and user parameters that affect the applet and HTML
settings; set envfile, which by default is default.env. Use a
different configuration file by setting configFileName in
web.xml (see description below).
forms90.conf Oracle HTTP listener configuration file for Oracle9i Forms: Defines
virtual directors (aliases) and servlet mount points to map URL
requests to the Forms Servlets running in the OC4J servlet engine

One of the configuration files for OC4J is web.xml in the subdirectory


forms90/j2ee/forms90app/forms90web/WEB-INF. This file contains the
Forms Servlet and Forms Listener Servlet aliases for OC4J and specifies the Forms
Servlet configuration file to use (configFileName).
Oracle9i Forms Developer: New Features 2-24
Defining Forms Environment
Variables for Run Time

Set on middle tier machine (used at run time):


FORMS90_PATH
ORACLE_PATH
CLASSPATH

# default.env - default Forms environment file, Windows version


#
.....
# Java class path
# This is required for the Forms debugger
# You can append your own Java code here) Settings in the
CLASSPATH=d:\oracle\iDSv2\jlib\debugger.jar; environment file
d:\oracle\iDSv2\jlib\utj90.jar;d:\oracle\iDSv2\jlib\dfc90.jar;
override system
d:\oracle\iDSv2\jlib\help3.jar;d:\oracle\iDSv2\jlib\help3-nls.jar;
settings.
d:\oracle\iDSv2\jlib\oracle_ice5.jar;d:\oracle\iDSv2\jlib\ewt3.jar;
d:\oracle\iDSv2\jlib\share.jar;d:\oracle\iDSv2\jlib\importer.jar

2-25 Copyright Oracle Corporation, 2002. All rights reserved.

Forms Environment Variables


Introduction
Oracle Forms uses many environment variables. These have default values, all of which
you can modify in your own environment for different applications.
Setting Search Paths for Run Time
Forms uses some environment variables set on the middle tier machine to search at run
time for files such as forms, menus, and libraries. This enables you to build applications
that are portable across platforms and directory structures, by avoiding hardcoded paths in
file references. Forms searches the following paths in sequence until the files are found:
The current working directory (you can set this in the formsweb.cfg file)
Directories in FORMS90_PATH
Directories in ORACLE_PATH
Forms also needs Java class files, usually contained in Java ARchive (JAR) files, for some
of its functionality. Forms searches the CLASSPATH to locate these classes.
You can set these environment variables in the operating system environment, such as the
Windows NT registry or System Properties. However, the preferred method is to set them
in the environment file (default.env) to override any system settings.

Oracle9i Forms Developer: New Features 2-25


Defining Forms Environment
Variables for Design Time

Used by Forms Builder


Set on iDS machine:
FORMS90_BUILDER_CLASSPATH

Windows: Modify in
Registry (REGEDIT.EXE
or REGEDT32.EXE)

2-26 Copyright Oracle Corporation, 2002. All rights reserved.

Forms Environment Variables (continued)


Setting Search Paths for Design Time
Forms Builder also needs access to certain Java classes for some of its features, such as
Help, the debugger, and the Java importer. To ensure that Forms Builder can find the Java
classes it needs during development and testing of an application, you set
FORMS90_BUILDER_CLASSPATH on the machine where Oracle9iDS is installed. For
Windows platforms, you set environment variables for design time in the registry.
In most cases, you will not need to modify this variable, because it is set during the
installation of Oracle9iDS.

Oracle9i Forms Developer: New Features 2-26


Defining Forms Servlet Parameters

The formsweb.cfg file contains three sections:


System parameters section
User parameters section:
Runform arguments
HTML page-related parameters
Forms applet parameters
Oracle JInitiator parameters
Java Plug-in parameters
Parameters for integration with Oracle Enterprise
Manager or Single Sign-On
Application-specific named configurations section

2-27 Copyright Oracle Corporation, 2002. All rights reserved.

Defining Forms Servlet Parameters


The formsweb.cfg file defines parameter values used by the Forms Servlet. The file
is structurally composed of three sections: a system parameters section, a user parameters
section, and a section in which you can define application-specific named configurations.
The first two sections contain the default settings. It is not recommended that you change
any of the defaults; instead, you can override those settings in a named configuration.
As an alternative to a named configuration, you can create a separate Forms Servlet
configuration file by copying the formsweb.cfg file. You could modify any of the
settings in the new file, and then modify the web.xml configuration file for OC4J so that
the new Forms Servlet configuration file is used.
Instructor Note
Open the formsweb.cfg file and point out the three main sections, along with the types
of parameters contained in each.

Oracle9i Forms Developer: New Features 2-27


Defining Application-Specific
Configurations
formsweb.cfg file:
# Example 1: configuration to run forms in a separate browser
# window with "generic" look and feel (include "config=sepwin"
# in the URL)
#
[sepwin]
separateFrame=True
lookandfeel=Generic
...
# Example 4: configuration running the Forms ListenerServlet in
# debug mode (debug messages will be written to the servlet
#engines log file)
#
[debug]
serverURL=/servlet/l90servlet/debug
...

To use specific configuration:


http://machine:port/forms90/f90servlet?config=sepwin

2-28 Copyright Oracle Corporation, 2002. All rights reserved.

Defining Application-Specific Named Configurations


You can define your own specific named configurations (sets of parameters) by adding
sections as illustrated in the following examples. Begin a named configuration by
specifying its name surrounded by brackets, such as [myconfig].
Example configuration to run forms in a separate browser window with generic look
and feel:
[sepwin]
separateFrame=True
lookandfeel=Generic
Example configuration running the Forms Listener Servlet and writing debug
messages to the log file of the servlet engine:
[debug]
serverURL=/servlet/l90servlet/debug
Note that you need only specify the parameters you want to change. The default values
are used for all other parameters, unless they are overridden by parameters specified in the
URL.
To use these application-specific parameters, add to the URL ?config= and the name of
the configuration from the formsweb.cfg file.

Oracle9i Forms Developer: New Features 2-28


Summary

In this lesson, you should have learned that:


Oracle9i Application Server has a layered
architecture that consists of a variety of services
for the Web, including those related to Forms
deployment:
Oracle Containers for J2EE (OC4J)
Forms Services
Enterprise Manager
Oracle Internet Directory
OC4J is Oracles lightweight Java 2 Enterprise
Edition (J2EE) container that executes on any
Java Virtual Machine.

2-29 Copyright Oracle Corporation, 2002. All rights reserved.

Summary
Oracle9iAS is a layered middle-tier architecture for developing and deploying Internet
applications. It contains several services that are used for deployment of Forms
applications:
Oracle9iAS Containers for J2EE (OC4J): A lightweight container for J2EE applications.
URL requests for Forms Services applications are redirected by mod_oc4j to OC4J.
OC4J can also function as a lightweight Web listener for testing Forms applications.

Oracle9i Forms Developer: New Features 2-29


Summary

Oracle9iAS Forms Services runs within the OC4J


Servlet container.
Oracle9iAS Forms Services consists of:
Forms Servlet: Dynamically constructs the start
HTML file
Forms Client: Generic Java applet downloaded to
and cached on the client that can run any form
Forms Listener Servlet: Initiates and maintains
communication through the HTTP Server between
the Forms Client and the Forms Runtime Engine
Forms Runtime Engine: Runs the application code
and maintains communication with the application
and the database

2-30 Copyright Oracle Corporation, 2002. All rights reserved.

Summary (continued)
Forms Services:
Forms Servlet: Constructs the HTML file that starts the applet
Forms Client: A Java applet that displays the user interface on the client
Forms Listener Servlet: Maintains a connection between the client and the Runtime
Engine, through the HTTP Server
Forms Runtime Engine: Handles all the application logic and Forms functionality;
communicates with the Forms client and the database

Oracle9i Forms Developer: New Features 2-30


Practice 2 Overview

This practice covers the following topics:


Setting Forms Builder preferences
Using a named configuration
Using a different Forms Servlet configuration file
Customizing environment variables
Running a form from Forms Builder with OC4J

2-31 Copyright Oracle Corporation, 2002. All rights reserved.

Practice 2 Overview
In this practice, you set Runtime preferences in Forms Builder to use OC4J. You also set
an applet parameter in the Runtime preferences. You define some applet parameters in a
named configuration, then set the Runtime preferences to use the named configuration.
You configure the Forms Servlet to use a different configuration file, and you set
environment variables in the environment configuration file. You use the Run Form
button to test the settings.
Note: The correct way to exit a Forms session is to exit the form (File > Exit, or click
Exit), then close the browser. If you close the browser without first exiting the form, your
session may hang. You will notice this because you will not be able to recompile the same
form, but will receive the error: FRM-30087: Unable to create form file.
If this happens, you will need to open Task Manager and kill the ifweb90 process
manually.
Instructor Note
Please emphasize to students the correct way to exit a Forms session.

Oracle9i Forms Developer: New Features 2-31


Practice 2
1. Make note of information you will need to complete these practices. Your instructor
will supply you with the following:

Item Example Your specific information


Lab directory e:\labs
<ids_home> e:\oracle\ids
User ID ora1
Password oracle
Database iasdb
Solutions e:\labs\soln
directory
Group number 1 (number portion
of your user id)
Machine name Right-click
Network
Neighborhood and
view properties

2. Start an instance of OC4J. Run the form to test the setting.


3. Open the Customers form in Forms Builder. Set the Run-Time preferences for
Forms Builder to use OC4J to test your applications. Set the Application Server
URL by pressing Set Default, which will enter the following settings:

URL Component Value


M achine nam e <local machine>
OC4J Port 8888 (This is the default port for
OC4J, which m ay be different on
your m achine.)
Pointer to Form s Servlet forms90/f90servlet

4. Add a parameter to the Run-Time preferences. Specify that the Forms application
should open in a separate browser window by setting the separateFrame
parameter to True.
5. Define a named configuration called [summit] that specifies the form to run, the
connect string, and the separateFrame parameter set to True. Set the Forms
Builder preferences to use the named configuration. Run the form to test the setting.
Hint: You should stop OC4J before modifying the Forms Web configuration file.

Oracle9i Forms Developer: New Features 2-32


Practice 2 (continued)
6. Create a separate Forms Servlet configuration file called Summit.cfg by copying
the formsweb.cfg file. Delete the named [summit] configuration in
Summit.cfg, and instead, specify those values in the main portion of the file. For
example, modify the line that specifies form=test.fmx to
form=e:\Labs\SUMMIT.fmx. Change the HTML body background color to
red so that you can easily see whether the new configuration is being used.

Modify the web.xml configuration file for OC4J so that the new Forms Servlet
configuration file (Summit.cfg) is used.

Set your Forms Builder Run-Time preferences back to the default. Run the form to
test the setting. Do not close the browser because it must be open for the next
exercise.
Hint: You should stop OC4J before modifying the OC4J configuration file.

7. Edit the URL in the browser by deleting all parameters. Open the new URL.

8. Prepare for subsequent exercises by setting configFileName back to the default.

9. From Forms Builder, run the Customers form normally. Click Orders. The Orders
form should display. Exit the forms and the browser.

10. Move the Orders form (Orders.fmx) from the lab directory to a temporary
directory, such as e:\temp. You can first create this directory if it does not already
exist. From Forms Builder, run the Customers form again and click Orders. What
happens and why? Exit the Customers form and the browser.

__________________________________________________________________

__________________________________________________________________

11. Modify the Forms environment to add e:\temp to the search path. Do not use the
Windows Registry to set the environment. Run the Customers form again and click
Orders to test that the Orders form is successfully located. Exit the forms and the
browser.

Oracle9i Forms Developer: New Features 2-33


Oracle9i Forms Developer: New Features 2-34
Migrating Existing Applications
to Oracle9i Forms

Copyright Oracle Corporation, 2002. All rights reserved.

Schedule: Timing Topic


60 minutes Lecture
30 minutes Practice
90 minutes Total
Instructor Note
Because of its length, this lesson is divided into two parts, with a practice after each:
Part One:
Migration path
Migration utility/PL/SQL Migration Assistant
Converting from Forms Listener deployment
Converting from client/server deployment
Converting from character mode deployment
Part Two:
Integrating Graphics (from previous development)
Integrating Reports using RUN_REPORT_OBJECT

Oracle9i Forms Developer: New Features 3-1


Objectives

After completing this lesson, you should be able to do


the following:
Describe the migration path for applications written
in previous versions of Forms
Use the Oracle9i Forms Migration Assistant to
upgrade a Forms6i application
List issues that can be encountered when
upgrading from Forms versions prior to 6i
Describe design and upgrade issues with
applications previously deployed by other means
Explain how to integrate graphs from Forms6i
applications
Run Reports from Oracle9i Forms

3-2 Copyright Oracle Corporation, 2002. All rights reserved.

Lesson Aim
This lesson describes the migration path, method, and issues in upgrading to Oracle9i
Forms. You learn how to successfully migrate to Oracle9i Forms from previous versions.

Oracle9i Forms Developer: New Features 3-2


Migration Path

Forms
Forms 4.0
2.0

f45gen32 ifcmp60
Forms Forms Oracle9i
Forms
4.5 6i Forms
2.3

Forms Forms
3.0 5.0

3-3 Copyright Oracle Corporation, 2002. All rights reserved.

Migration Path
The only supported way to upgrade directly to Oracle9i Forms is from Forms6i or 6.0.
Older versions of Forms applications will need one or more interim upgrades:
Forms 4.0, 4.5, or 5.0 applications will first need to be upgraded to Forms6i.
Although it should work to upgrade directly from 6.0, it is not supported to do so.
Forms 2.0, 2.3, or 3.0 applications will first need to be upgraded to Forms 4.5, then
to Forms6i.
For instructions for upgrading older versions, refer to the following white papers,
available on OTN:
Upgrade Developer Forms 4.5 to Oracle Forms 6
Migrating SQL*Forms 3.0 Applications to Internet Computing

Oracle9i Forms Developer: New Features 3-3


Upgrading from Older Versions

Issues:
V2-style triggers
V2.3-style LOVs
Windows and canvases
SQL*Menu 5.0 (with SQL*Forms 3.0)
Runtime Compatibility Mode
PL/SQL conversion issues v.1 to v.2, v.8, and v.9
(for example, CHAR to VARCHAR2)
Item data types
Obsolete item types

3-4 Copyright Oracle Corporation, 2002. All rights reserved.

Issues When Upgrading from Older Versions


V2-Style Triggers
If you have V2-style triggers in your application, you must convert these to PL/SQL
triggers in Forms 4.5 prior to upgrading to 6i. Forms 4.5 is the last version in which V2-
style triggers can be edited, and they are unsupported in Oracle9i Forms.
LOVs
If you have V2.3-style Lists of Values in your application, the upgrade process FKDQJHV
them into new-style LOVs. Old-style LOVs have a property called Old LOV Text that
refers to a table and a column, such as EMPLOYEES.LAST_NAME. The upgrade uses that
value to create a record group based on a query, then converts the old-style LOV into one
based on that new record group
Instructor Note
Mention these issues briefly, but do not go into detail unless students have specific
questions.

Oracle9i Forms Developer: New Features 3-4


Issues When Upgrading from Older Versions (continued)
Windows and Canvases
By default, migration from Forms 3.0 to Forms 4.5 using the Generator creates an MDI
window called ROOT_WINDOW. Because this can cause unpredictable behavior, you should
rename ROOT_WINDOW to some other name.
The upgrade process converts pop-up pages to windows; you may want to change these to
stacked canvases, pop-up lists, or some other GUI element.
Menus
With SQL*Forms 3.0, menus were built with a separate tool, SQL*Menu 5.0. In the current
build environment, both forms and menus are created within the same executable. Using
ifcmp60 extracts the menu from the database (requires that Forms 3.0 and 4.0 database
tables be installed) and creates an .MMB file. If the menu has significant levels of security,
you can direct the security structure to use the database role support that is now available.
Runtime Compatibility Mode
Run-time behavior of forms created with versions 5.0 and later differs from run-time
behavior for Forms Builder 4.5. Forms Builder 5.0 and later enabled you to revert to 4.5
behavior by setting the form property Runtime Compatibility Mode to a value of 4.5. In
Oracle9i Forms, setting this property has no effect at run time.
If you are upgrading a form that has Forms Runtime Compatibility set to a value of 4.5, you
should change the setting to 5.0 and test your application in this mode before upgrading to
Oracle9i Forms.
Note: You are still able to specify that the When-Validate-Item trigger should fire for NULL
items by setting the DEFER_REQUIRED_ENFORCEMENT property to 4.5.
Item Data Types
You should manually change all obsolete data types, such as JDate, to one of the Forms data
types: CHAR, LONG, NUMBER, DATE, DATETIME.
Obsolete Item Types
If your application contains items of a type no longer supported in Oracle9i Forms (OLE
containers, OCXs, VBXs, or sound items), these items are not removed by the migration
process. However, any modules that contain them will not compile. Use JavaBeans and
Pluggable Java Components for equivalent functionality.
Other Issues
For migration issues when upgrading from Forms 3.0, see the white paper Migrating
SQL*Forms 3.0 Applications to Internet Computing, available on OTN at
http://otn.oracle.com/products/forms/pdf/264850.pdf.
For migration issues when upgrading from Forms 4.5 to 6i, see the Upgrade Developer
Forms 4.5 to Oracle Forms 6 white paper, available on OTN at:
http://otn.oracle.com/products/forms/pdf/275195.pdf.

Oracle9i Forms Developer: New Features 3-5


Upgrading from
Forms Listener Deployment

Architecture and Configuration Issues:


OC4J
Servlet
Configuration files
Java-related issues:
Classes needed by Forms6i JavaBeans and PJCs
Fonts in JDK 1.3

3-6 Copyright Oracle Corporation, 2002. All rights reserved.

Upgrading from Forms Listener Deployment


Architecture/Configuration Issues
If you are currently using the Forms Listener to deploy Forms applications, you have
already resolved issues about the differences between Web deployment versus
client/server and character mode deployment. However, there are some issues to consider
in order to begin deploying with the Forms Listener Servlet.
You must understand how to work with Oracle Containers for J2EE (OC4J), and how to
use Servlet technology. You might want to modify certain configuration files in order to
control the environment. These issues were discussed in the previous lesson.
Issues with Class Files
If the application you are upgrading uses PJCs or JavaBeans, the application may fail at
run time because the necessary classes cannot be located. This is because the Oracle9i
Forms JAR files contain only the classes needed by the Forms Client; the missing classes
are contained in the ewt3_3_18.jar file in <iDS_HOME>\jlib). If you encounter a
problem with locating class files for your Forms6i JavaBeans or PJCs, you may need to
add ewt3_3_18.jar (and possibly share-1_1_9.jar as well) to your
CLASSPATH.

Oracle9i Forms Developer: New Features 3-6


Upgrading from Forms Listener Deployment (continued)
Because of security constraints related to Java 1.3, which is used by Oracle9i Forms, you
must sign again all of the classes (including the Forms classes) with your own certificate.
Java 1.3 requires that all classes from the same package be signed with the same certificate.
Therefore, if you need to use extra classes from ewt.jar in combination with
f90all.jar, you must sign all of the classes again with your own certificate.
Java Font Issues
When migrating Forms applications from JDK 1.1 to JDK 1.3 or higher, you might
encounter font height changes. This is because the code that renders fonts significantly
changed from JDK 1.1 to JDK 1.3. As a result of these changes, the font height for logical
fonts of the same size increased in JDK 1.3. For example, a dialog font of size 12 points has
a height of 15 points in JDK 1.1, and a height of 17 points in JDK 1.3.
In Forms applications, the font size changes might affect labels, which can overlap text
fields. One possible workaround is to set the mapFonts applet parameter to Yes:
<PARAM NAME = "mapFonts" VALUE = "yes" >
After making this change, check the appearance of the font size to be sure it is acceptable.
You may still need to modify the form if this workaround does not provide acceptable font
sizes.
Note: For additional information about the differences between Forms Listener deployment
and Forms Listener Servlet deployment, refer to the following white paper available on
OTN:
Oracle9iAS Forms Services Release 6i Patch 10
Instructor Note
Mention these issues briefly, but do not go into detail unless students have specific
questions.

Oracle9i Forms Developer: New Features 3-7


Upgrading from Client-Server Deployment

Issues:
Client support
Images
Icons
JAR files
Key mappings
Mouse enter/leave/move triggers
OS-specific item types
Fonts
Access to client machine
Program calls (HOST, user exits, OLE automation)
run on middle tier

3-8 Copyright Oracle Corporation, 2002. All rights reserved.

Upgrading from Client-Server Deployment


Issues with Web deployment include:
Client Support: JInitiator plug-in must be used for Netscape and can be used for IE
5.0.
Images: Must be GIF or JPG files located in FORMS90_PATH on application server
Icons: Must be GIF files; you can place them into Java ARchive (JAR) files (see
next bullet). To place your icons in a JAR file:
jar -cvf myicons.jar icon1.gif icon2.gif
This requires that jdk\bin is in your PATH, because that is the location of
jar.exe.
Use JAR files: You can cache JAR files on the client use for icons:
- Add JAR file to ARCHIVE parameter in formsweb.cfg
- Change imageBase in formsweb.cfg: imageBase=codeBase
- Put JAR files in forms90\java on middle tier; they will be downloaded and
cached when using JInitiator.
Key mappings: Oracle Terminal is no longer used. Edit FMRWEB.res with a text
editor.

Oracle9i Forms Developer: New Features 3-8


Upgrading from Client-Server Deployment (continued)
Mouse triggers: To reduce network traffic, the When-Mouse-Enter, When-Mouse-
Leave, and When-Mouse-Move triggers are disabled.
OS-Specific Items: Replace OCX/VBX items with JavaBeans or Pluggable Java
Components. A variety of such components is available for free download from OTN.
There is more information about this in Lesson 7.
Fonts: Java fonts are used; font mappings are performed in the
forms90/java/oracle/forms/registry/registry.dat file. The
following table lists the Java fonts and their equivalents on the major deployment
platforms:
Java Font Windows Font X Windows Font Macintosh Font
Courier Courier New adobe-courier Courier
Dialog MS Sans Serif b&h-lucidatypewriter Geneva
Helvetica Arial adobe-helvetica Helvetica
Symbol WingDings itc-zapfdingbats Symbol
TimesRoman Times New Roman adobe-times Times Roman

Access to client machine: The Java applet for the user interface does not allow access
to the client machine for such operations as file upload/download or printing. To
accomplish these tasks, use a JavaBean; see Lesson 7 for more information.
Program calls: Programs such as the HOST command, user exits, and OLE
automation run on the middle tier. You can use them as long as there is no UI
component, necessary files are on the middle tier machine, and any OS-specific
commands used are for the middle tier platform.
Note: For additional information see the Oracle9i Forms: Migrating Client/Server to the
Web white paper, available on OTN.
Instructor Note
Mention these issues briefly, but do not go into detail unless students have specific
questions.

Oracle9i Forms Developer: New Features 3-9


Upgrading from
Character Mode Deployment

Issues:
Application logic
Item length (WIDEN_FIELDS=YES)
Navigation
Fonts

3-10 Copyright Oracle Corporation, 2002. All rights reserved.

Upgrading from Character Mode Deployment


For migration issues when upgrading from character mode to Web deployment, see the
Migrating SQL*Forms 3.0 Applications to Internet Computing white paper, available on
OTN at http://otn.oracle.com/products/forms/pdf/264850.pdf.
Issues include:
Application logic: Applications are now deployed over the Internet or Intranet,
typically at a lower bandwidth than the one between the application server and the
database. Consider moving data intensive application logic to the database server as
a stored procedure, database trigger, or integrity constraint. Consider using
JavaBeans or Pluggable Java Components to perform client-side logic.
Item length: Items might not be wide enough to display completely because of
proportional fonts and GUI effects, such as beveling. Solution: Use
WIDEN_FIELDS=YES upgrade option.
Navigation: Users can use the mouse instead of function keys to navigate, so you
have much less control. Move some of the logic from key triggers to When-New-
<object>-Instance or When-Validate-<object> triggers, and use calculated items.
You can use navigational aids such as tree controls, tab canvases, or buttons.
Fonts: You can now use proportional fonts.

Oracle9i Forms Developer: New Features 3-10


Upgrading to Oracle9i Forms

You can upgrade


using:
Forms
Builder
Batch
compiler
Migration
Assistant

3-11 Copyright Oracle Corporation, 2002. All rights reserved.

Upgrading to Oracle9i Forms


As with previous Forms versions, you can upgrade your Forms applications from Forms6i
by opening and generating them in Oracle9i Forms Builder, or by running the Forms
Compiler ifcmp90.exe executable.
However, because of the streamlining of the Forms product, you might encounter
compilation problems. For this reason, Oracle provides the Oracle9i Forms Migration
Assistant tool to help you upgrade your Forms6i applications.
Upgrading Modules Saved to the Database
In Oracle9i Forms, there is no longer an option to save or access modules from the
database. If your modules exist on the database and not on the file system, you must use
the Forms6i compiler to first extract the module from the database to the file system prior
to upgrading it to Oracle9i Forms.

Oracle9i Forms Developer: New Features 3-11


Using the Oracle9i Forms
Migration Assistant

Command:
ifplsqlconv90 (Windows) or ifplsqlconv (UNIX)
Arguments:
module (required)
userid (optional)
log (optional)

3-12 Copyright Oracle Corporation, 2002. All rights reserved.

Using the Oracle9i Forms Migration Assistant


Oracle9i Forms provides a Migration Assistant tool that updates obsolete usage in your
PL/SQL code in order to migrate your Forms6i applications to Oracle9i Forms. The tool
issues warnings when it cannot make the required changes automatically.
You run the Migration Assistant in batch mode. You can reenter the utility as needed to
run the migration process on a Forms application more than once. First, migrate common
modules on which other modules depend, such as libraries, menus, or referenced forms.
Starting the Migration Assistant
To start the Oracle9i Forms Migration Assistant on Windows, type:
ifplsqlconv90 module=<modulename> userid=<userid> log=<log>
To start the Oracle9i Forms Migration Assistant on UNIX, type:
f90plsqlconv module=<modulename> userid=<userid> log=<log>
The forms90\rp2rro.pll file should be in the FORMS90_PATH in order to convert
RUN_PRODUCT to RUN_REPORT_OBJECT. You must also run first the script
ORACLE_HOME/reports/admin/sql/rw_server.sql to create a reports server
queue table in the database under the schema of the user who starts the reports server.
Note: For UNIX, an xterm display is required to run the Forms Migration Assistant.

Oracle9i Forms Developer: New Features 3-12


Using the Oracle9i Forms Migration Assistant (continued)
Migrating Multiple Files
On Windows NT, create a batch file (for example, upgrade.bat) that contains the
following (you can also specify userid and log if desired):
for %%f in (%1) do call ifplsqlconv90 module=%%f
Then run the batch file as follows:
upgrade *.fmb or upgrade foo*.mmb
On UNIX, create a shell script (for example upgrade.sh) that contains the following:
for file in $*
do
f90plsqlconv.sh module=$file
done
Then run the shell script as follows:
upgrade.sh *.fmb or upgrade.sh foo*.mmb
Note: If you are running the Migration Assistant on several modules at once, the same log
file will be overwritten each time unless you specify a different log file for each module.
The following batch file for Windows accomplishes this:
for %%f in (%1) do call ifplsqlconv90 module=%%f userid=%2
log=%%f.log
Assuming the above code is in a batch file called upgrade.bat, you would run it as
follows:
upgrade *.fmb <username>/<password>@<db>
This would create a separate log file for each form that is upgraded.

Oracle9i Forms Developer: New Features 3-13


Functions of the Migration Assistant

The Oracle9i Migration Assistant:


Updates PL/SQL code whenever possible
Provides a list of obsolete code
Provides warnings of obsolete built-ins
Displays
messages
Writes
messages
to log file

3-14 Copyright Oracle Corporation, 2002. All rights reserved.

Functions of the Oracle9i Forms Migration Assistant


The Oracle9i Forms Migration Assistant performs the following actions for all Forms
module types (including object libraries and PL/SQL libraries):
Updates PL/SQL code if there is a direct replacement. For example:
- Updates RUN_PRODUCT to the RUN_REPORT_OBJECT built-in when used
to call Reports, utilizing procedures in the rp2rro library, which it
automatically attaches to the form; also creates a report object node in the
form.
- Updates CHANGE_ALERT_MESSAGE to SET_ALERT_PROPERTY
Provides a list of obsolete code usage, including code that the tool cannot change
when there is not a straightforward equivalent for migration.
Provides warnings when specific obsolete built-ins are used at run time, such as
DISABLE_ITEM, ENABLE_ITEM, and ITEM_ENABLED.
Information about the progress of the migration process is displayed on the screen. It is
also saved to the log file that you specify.

Oracle9i Forms Developer: New Features 3-14


Configuring the Migration Assistant

Configuration files for the Migration Assistant:


converter.properties
search_replace.properties

3-15 Copyright Oracle Corporation, 2002. All rights reserved.

Using the Oracle9i Forms Migration Assistant (continued)


Configuration Files
There are two files in the ORACLE_HOME\forms90 directory that you can edit to
modify the behavior of the Migration Assistant:
converter.properties: Contains migration options, such as default log file,
database connection options, Reports options, and whether to generate an .fmx
file. For example, you can establish a database connection by setting
default.connecttodb=true, then defining the connect string either in
converter.properties or on the command line.
search_replace.properties: Contains the strings that the Migration
Assistant searches for and replaces, along with a list of obsolete built-ins that
generates warnings. You can edit this file to add your own search-and-replace
strings to the end or to customize warnings for obsolete built-ins.
For details, see Migrating Forms Applications from Forms6i, Part Number A92183-01,
available on OTN.

Oracle9i Forms Developer: New Features 3-15


Practice 3a Overview

This practice covers the following topics:


Upgrading a Forms6i application to Oracle9i
Forms
Using the Oracle9i Forms Migration Assistant:
On individual modules
On multiple modules at one time, using a batch file
Modifying the configuration for the Oracle9i Forms
Migration Assistant

3-16 Copyright Oracle Corporation, 2002. All rights reserved.

Practice 3a Overview
In this practice you use the Oracle9i Forms Migration Assistant:
On a single form
On multiple forms using a batch file
You will modify the settings for the Migration Assistant so that it automatically connects
to the database and generates the executables.
You will upgrade the Summit Office Supply application from Forms6i.

Oracle9i Forms Developer: New Features 3-16


Practice 3a
1. Make a new subdirectory of your lab directory called 9iApp to contain applications
to upgrade. Copy the Summit.fmb file from the 6iApp directory to your 9iApp
directory, keeping a copy in 6iApp as a backup. Use the Oracle9i Forms Migration
Assistant to upgrade Summit.fmb to Oracle9i Forms.
2. Copy the Orders.fmb and Customers.fmb files in the 6iApp directory to
your 9iApp directory, keeping a copy of each in 6iApp as a backup. Use the
Oracle9i Forms Migration Assistant to upgrade all the .fmb files in your lab
directory to Oracle9i Forms.
Hint: Create a batch file to perform the upgrade.
3. Examine the feedback from the upgrade script that is displayed on the screen. You
can also see the feedback in ORDERS.fmb.log. Were any special actions taken by
the Migration Assistant?
Note: The 6i form that you upgraded used RUN_PRODUCT to call a report.
4. If you run the migration utility on the Summit form without specifying a log file
name, a log file called converter.log is generated. Change the default log file
name to my_log.log. Run the utility on the Summit form without specifying a
log file name, as you did in 1b but without the log= parameter. Then check to see
what log file is created.
5. Type exit in the DOS window to close it.

Oracle9i Forms Developer: New Features 3-17


Integrating Graphics
Graphics not included with Oracle9iDS Release 2
You can:
Use RUN_PRODUCT to call existing charts
Display Graphics6i chart object in a form
Edit properties of existing chart items
Create new chart items
Populate a chart item with existing OGD
Replace functionality with a JavaBean
Requirements:
Install Graphics6i on Forms Services machine
Set ORACLE_GRAPHICS6I_HOME to directory on
which Graphics6i is installed
Set path for Forms Servlet to include Graphics
If using OG.PLL, compile it in Oracle9i Forms

3-18 Copyright Oracle Corporation, 2002. All rights reserved.

Integrating Graphics
Oracle Graphics is not shipped with Oracle9i Forms, and the charting wizard has been
removed from Forms Builder. For new applications, use a JavaBean, such as one written
with the Chart User Interface Component of Oracle9iDS JDeveloper.
Using chart objects or RUN_PRODUCT calls, you can upgrade and deploy existing
Forms applications that contain embedded Oracle Graphics displays. You can also edit
chart item properties, create new chart items, and populate chart items with existing OGD
files that were created in 6i. This requires the following actions:
Install Oracle Graphics 6i in a separate ORACLE_HOME on the same machine as
Oracle9iAS Forms Services.
Set the ORACLE_GRAPHICS6I_HOME environment variable to the directory
where you installed Graphics 6i.
Set the path for the Forms servlet environment (in default.env or equivalent) to
include the Graphics executable:
PATH=%FORMS9I_HOME%\bin;%ORACLE_GRAPHICS6I_HOME%\bin;
If you use the OG.PLL library in your application, compile it in Oracle9i Forms.
Note: For additional information see the February 2002 Oracle white paper, Deploying
Oracle Graphics in Oracle9iAS V2 Forms Services, available on OTN.

Oracle9i Forms Developer: New Features 3-18


Integrating Reports

Replace RUN_PRODUCT with


RUN_REPORT_OBJECT:
RUN_PRODUCT in 6i called Reports run
time, which you cannot directly call in
9iAS v2
RUN_REPORT_OBJECT can invoke the report with the
Reports Server
Call WEB.SHOW_DOCUMENT to display the report
Migration Assistant converts RUN_PRODUCT calls
to RUN_REPORT_OBJECT

3-19 Copyright Oracle Corporation, 2002. All rights reserved.

Integrating Reports
You should use RUN_PRODUCT in Oracle9i Forms only for integration with Oracle
Graphics. RUN_PRODUCT calls being used to integrate Forms with Reports should be
replaced using the RUN_REPORT_OBJECT built-in, using Reports Server to run the
report. The Reports Server must be configured and running when you invoke the report
from Forms.
The following slides present detailed information about using RUN_REPORT_OBJECT to
run a report. This is not a new feature of Oracle9i Forms; however, previous Forms
versions allowed the use of RUN_PRODUCT, so it is possible that you may not have used
RUN_REPORT_OBJECT. If you have experience with running reports this way, the
remainder of this lesson will be a review of this topic.
Instructor Note
This lesson uses the Reports Server to run reports. Students will use the Reports Server on
the instructor machine. You will need to start the Reports Server on your machine by
running the batch file RepSRV.bat, located in your demo directory.

Oracle9i Forms Developer: New Features 3-19


Using RUN_REPORT_OBJECT

1. Create a report object in Object


Navigator.
2. Set properties at design time or programmatically
(SET_REPORT_OBJECT_PROPERTY).
3. Define data to pass to the report.
4. Call RUN_REPORT_OBJECT to use Reports Server
to run the report.
5. Use WEB.SHOW_DOCUMENT to display the report.

3-20 Copyright Oracle Corporation, 2002. All rights reserved.

Integrating Reports (continued)


To use RUN_REPORT_OBJECT, assuming that the Reports Server is configured and is
running, perform the following:
1. Define a report object under the Reports node in the Object Navigator.
2. Set properties:
- At design time in the Property Palette
- At run time with the SET_REPORT_OBJECT_PROPERTY built-in
3. Define any data to pass to the report from the form.
4. Run the report with the RUN_REPORT_OBJECT built-in.
5. Display the report using the WEB.SHOW_DOCUMENT built-in.
The slides that follow explain these steps.

Oracle9i Forms Developer: New Features 3-20


Step 1: Create a Report Object

3-21 Copyright Oracle Corporation, 2002. All rights reserved.

Step 1: Create a Report Object


You create a report object as a node in the object navigator. With the Reports node
selected, click the Create icon to invoke a New Report dialog. With this dialog, you can
either indicate that the report object will use an existing report, or you can create a new
report and base it on one of the blocks in your form.
Choosing to create a new report invokes Reports Builder, where you can design the report.
If you are designing a new report, the first page of the Report Wizard asks you to select
the type of layout to generate. Select the Create both Web and Paper Layout option.
Continue completing the pages in the Reports Wizard to define your report.
To use the report object at run time, you obtain the report object ID with
FIND_REPORT_OBJECT:
DECLARE
v_repid REPORT_OBJECT;
BEGIN
v_repid := FIND_REPORT_OBJECT(report5);
....
You then pass the report object ID to other built-ins to manipulate report object properties
and to run the report. You can reuse the same report object to run any report.

Oracle9i Forms Developer: New Features 3-21


Step 2: Set Properties of the Report Object
Design Time Run Time
v_repid :=
FIND_REPORT_OBJECT(report5);
SET_REPORT_OBJECT_PROPERTY(v_repid,
REPORT_EXECUTION_MODE, BATCH);

SET_REPORT_OBJECT_PROPERTY(v_repid,
REPORT_COMM_MODE, SYNCHRONOUS);

SET_REPORT_OBJECT_PROPERTY(v_repid,
REPORT_DESTYPE, CACHE);

SET_REPORT_OBJECT_PROPERTY(v_repid,
REPORT_DESFORMAT, html);

SET_REPORT_OBJECT_PROPERTY(v_repid,
REPORT_SERVER, RepSRV);

3-22 Copyright Oracle Corporation, 2002. All rights reserved.

Step 2: Set Properties on the Report Object


After you have created a report object under the Reports node, you can set properties
using the Property Palette window. If desired, you can override any of these properties at
run time by using the SET_REPORT_OBJECT_PROPERTY built-in. You pass to this
built-in the report ID or name, a property name, and a value.
Property Name Value
REPORT_FILENAME <report file> as VARCHAR2
REPORT_EXECUTION_MODE RUNTIME | BATCH
REPORT_COMM_MODE SYNCHRONOUS | ASYNCHRONOUS
REPORT_SOURCE_BLOCK <block name> as VARCHAR2
REPORT_QUERY_NAME <report query name> as VARCHAR2
REPORT_DESTYPE CACHE | SCREEN | FILE | PREVIEW |
PRINTER | MAIL
REPORT_DESNAME <Name> as VARCHAR2
REPORT_DESFORMAT html | pdf
REPORT_SERVER <report server name>
REPORT_OTHER Additional Reports parameters such as user-
defined variables

Oracle9i Forms Developer: New Features 3-22


Step 3: Define Data to Pass to the Report
Use parameter list, Other Reports Parameters property,
or Data Block Data Source property to pass data to the report.

Example: Setting Other Reports Parameters:

Set at run time:

SET_REPORT_OBJECT_PROPERTY(v_repid,
REPORT_OTHER, ordno=||:orders.order_id);

Parameter name
matches parameter
defined in Reports
Builder
Set at design time:

3-23 Copyright Oracle Corporation, 2002. All rights reserved.

Step 3: Define Data to Pass to the Report


In previous versions of Forms, when you used RUN_PRODUCT to run a report, you had to
create a parameter list if you wanted to pass data to the report. Programmatically, you first
checked to see if the list already existed, destroyed it if it did exist, created the parameter
list, added each parameter to it individually, then passed the parameter list as an argument
to RUN_PRODUCT.
Although you can use such a parameter list with RUN_REPORT_OBJECT, you might find
it easier to pass data to the report by setting the REPORT_OTHER property:
SET_REPORT_OBJECT_PROPERTY(v_repid, REPORT_OTHER, custno= ||
:orders.cust_id || orddate= || :orders.order_date);
You can string together multiple parameters separated with a blank space. The name of
each parameter must match the name of a parameter defined in the report.
If you want to base the report on a block of the form, use the Data Source Data Block
property (REPORT_SOURCE_BLOCK) of the report object.
Note: Using RUN_REPORT_OBJECT, it is not possible to use a data parameter to pass a
record group to the report. If you need to pass tabular data to a report from a form, you
can create and populate a temporary database table, then query its data in the report.

Oracle9i Forms Developer: New Features 3-23


Step 4: Run the Report

RUN_REPORT_OBJECT:
Function that returns VARCHAR2 value to
uniquely identify the report
Overloaded to take the following combinations of
arguments:
Report name
Report ID
Report name, parameter list
Report ID, parameter list
Use REPORT_OBJECT_STATUS to determine when
report has finished

3-24 Copyright Oracle Corporation, 2002. All rights reserved.

Step 4: Run the Report


Now that you have set all the properties on the report object, you are ready to run the
report. You can use either the report name or report ID as the first argument to the
RUN_REPORT_OBJECT built-in, and optionally pass a parameter list.
You assign the return value of RUN_REPORT_OBJECT to a VARCHAR2 variable that
you can then use to obtain information about the report job:
vc_rep := RUN_REPORT_OBJECT(v_repid);
vc_rep_status := REPORT_OBJECT_STATUS(vc_rep);
WHILE vc_rep_status in (RUNNING, OPENING_REPORT,
ENQUEUED) LOOP
vc_rep_status := report_object_status(vc_rep);
END LOOP;
if vc_rep_status = FINISHED then
message(Report Completed);
else
message(Error when running report.);
end if;

Oracle9i Forms Developer: New Features 3-24


Step 5: Display the Report

WEB.SHOW_DOCUMENT:
Used to display any Web page from Forms
Use to display a report in the browser
Not necessary when just printing
Takes 2 arguments:
URL: VARCHAR2
Target: _self | _parent | _top | _blank
Use getjobid to retrieve the report from the
Reports Server
Can be used as alternative to
RUN_REPORT_OBJECT to run a report

3-25 Copyright Oracle Corporation, 2002. All rights reserved.

Step 5: Display the Report


The WEB.SHOW_DOCUMENT built-in, used to display a Web page, takes as arguments a
URL and optionally a target (lowercase and enclosed in quotes) that specifies how the
page should display:
_self: Load into the same window or frame
_parent: Load into the parent window or frame; if at top level, load into same
window or frame
_top: Load into window or frame containing hypertext link
_blank: Load into a new, unnamed top-level window
In the URL, you can use the getjobid function to specify the report to display. You use
a substring of vc_rep that contains the value returned by RUN_REPORT_OBJECT. This
variable contains the report server name followed by an underscore and the job ID. In the
following example, vc_rep contains the value RepSRV_, followed by the job ID, so you
want the value that begins at the eighth character:
vc_URL := /reports/rwservlet/getjobid
||substr(vc_rep,8)||?server=RepSRV;
Web.show_document(vc_URL,_blank);

Oracle9i Forms Developer: New Features 3-25


Using WEB.SHOW_DOCUMENT to
Run a Report

Alternative to RUN_REPORT_OBJECT
Construct the URL to be the same as you would
use to run a report in a browser with the Reports
Servlet:
http://pgamer-wah.us.oracle.com:8888/
reports/rwservlet?report=emps.jsp&destype=cache
&desformat=html&userid=ora1/oracle@iasdb

3-26 Copyright Oracle Corporation, 2002. All rights reserved.

Using WEB.SHOW_DOCUMENT to Run a Report


You can also use the WEB.SHOW_DOCUMENT built-in as an alternative to
RUN_REPORT_OBJECT for running a report. You construct the URL to be the same as
the one you use to run a report from a browser, as in the following example:
vc_un := Get_Application_Property(USERNAME);
vc_pw := Get_Application_Property(PASSWORD);
vc_cs := Get_Application_Property(CONNECT_STRING);
vc_URL := /reports/rwservlet?report=emps.jsp;
vc_URL := vc_URL || &destype=cache&desformat=html&userid=;
vc_URL := vc_URL || vc_un || / || vc_pw || @ || vc_cs;
Web.show_document(vc_URL,_blank);
This example assumes that the report has been saved as a .jsp.

Oracle9i Forms Developer: New Features 3-26


Summary

In this lesson, you should have learned that:


You can migrate Forms applications directly from
6i to 9i. Applications written in earlier versions
must first be migrated to Forms6i.
The Oracle9i Forms Migration Assistant
automatically handles some obsolete features by
converting or logging information about it.
Although Graphics is not included with Release 2
of Oracle9i Developer Suite, you can configure the
Forms application to use Graphics developed in
Forms6i.

3-27 Copyright Oracle Corporation, 2002. All rights reserved.

Summary
You can directly upgrade applications written in Forms6i to Oracle9i Forms. Applications
written in versions between 4.0 and 5.0 (including 4.5) must first be upgraded to 6i. If
your application was written in 2.0, 2.3, or 3.0, you must first upgrade it to 4.5, then 6i,
then 9i. You may need to perform some manual steps in 4.5 to rewrite obsolete triggers or
resolve some user interface issues.
The Oracle9i Forms Migration Assistant facilitates the task of migrating applications. It
provides feedback and error messages, and its functions are customizable.
Although Oracle9i Developer Suite does not have a graphics component, you can use
graphics from Oracle Developer 6i that have been installed into a separate
ORACLE_HOME. You can embed a graphics object into a form, or use RUN_PRODUCT.

Oracle9i Forms Developer: New Features 3-27


Summary

You must use the RUN_REPORT_OBJECT built-in to


run reports from Oracle9i Forms; RUN_PRODUCT to
run reports is no longer supported.
You may need to perform some manual steps to
overcome design and upgrade issues with
applications previously deployed by other means.

3-28 Copyright Oracle Corporation, 2002. All rights reserved.

Summary (continued)
The RUN_PRODUCT built-in no longer works to integrate reports. You can use
RUN_REPORT_OBJECT to achieve a high degree of control and flexibility in running
reports from forms. You can use WEB.SHOW_DOCUMENT to display or to run a report.
You might need to perform many manual tasks to resolve issues when upgrading
applications. These issues vary depending on whether you are upgrading from client-
server, character mode, or Forms Listener deployment.

Oracle9i Forms Developer: New Features 3-28


Practice 3b Overview

This practice covers the following topics:


Examining how the Migration Assistant converted
RUN_PRODUCT calls to RUN_REPORT_OBJECT
Creating and using a report object to run a report
Using WEB.SHOW_DOCUMENT to display the report

3-29 Copyright Oracle Corporation, 2002. All rights reserved.

Practice 3b Overview
In this practice, you examine the method used by the Migration Assistant to convert
RUN_PRODUCT calls to RUN_REPORT_OBJECT. You then perform this conversion
directly and display the report with WEB.SHOW_DOCUMENT.
Instructor Note
This practice uses the Reports Server to run reports. Students will use the Reports Server
on the instructor machine. If you have not already done so, you will need to start the
Reports Server on your machine by running the batch file RepSRV.bat, located in your
demo directory.

Oracle9i Forms Developer: New Features 3-29


Practice 3b
1. Move the three upgraded forms and the menu from the 9iApp directory to your lab
directory, overwriting any existing files of the same name. If you do not place these
files in the lab directory, Forms will be unable to find some of the files it needs to
run the practice forms. In Forms Builder, open the Orders form from the lab
directory. Examine the code in the When-Button-Pressed trigger of the
Control.Invoice_Button item. Now expand the nodes for Attached Libraries,
Parameters, and Reports. What has been added to the form module?
2. In Forms Builder, open the RP2RRO library, located in the
<ids_home>\forms90 directory, and examine the package body. The
RP2RRO_RUN_PRODUCT procedure calls the Handle_rp2rro_run_product
procedure. What does this procedure do?
3. With the Orders form selected in the Forms Builder Object Navigator, click Run
Form to run the Orders form. Click Invoice. If you receive FRM-40735 and ORA-
6508 errors or an ORA-907 error, this might indicate that the library needs to be
compiled. Compile the RP2RRO library, save it, then run the form again.
Note: The RP2RRO library included in this course has been slightly modified from
the library installed with Oracle9iDS. The line:
web.show_document(rp2rroVirtualDir||rp2rroReportsInterface
||/getjobid=||rp2rro_jobidFull||?server=||
rp2rroReportServer,_blank);
has been changed to:
web.show_document(rp2rroVirtualDir||rp2rroReportsInterface
||/getjobid||rp2rro_jobidPartial||?server=||
rp2rroReportServer,_blank);
4. Convert the code in the Invoice button of the Orders form to use a direct call to
RUN_REPORT_OBJECT. Display a message when the report completes. Use the
report object that was created by the Migration Assistant. Detach the RP2RRO
library from the form and delete all the parameters. Run the form from Forms
Builder to test your changes.
5. Add code to the When-Button-Pressed trigger for the Invoice button to display the
completed report. The name of the Reports Server that you will use is RepSRV.
Run the report by clicking Run Form, then click Invoice when the form is displayed.
The report should appear in a separate browser window.

Oracle9i Forms Developer: New Features 3-30


Designing Forms Outside the Builder

Copyright Oracle Corporation, 2002. All rights reserved.

Schedule: Timing Topic


75 minutes Lecture
45 minutes Practice
120 minutes Total
Instructor Note
Because of its length, this lesson is divided into two parts, with a practice after each:
Part One: The Java Design Time API (JDAPI)
Part Two: XML Conversion Tools
As part of the practice for this lesson, students will install and examine the javadoc for
JDAPI and the XML converter. In order to demonstrate the use of javadoc , you should
install it on your machine prior to presenting this lesson. To install javadoc , follow the
instructions given to students in Exercise 1 of the Practice 4a.
Objectives

After completing this lesson, you should be able to do


the following:
List the batch methods of modifying Forms
modules
Describe the benefits of modifying Forms with a
batch method
Use the Java API to modify Forms modules
Use the Forms to XML conversion utility to modify
Forms modules

4-2 Copyright Oracle Corporation, 2002. All rights reserved.

Lesson Aim
This lesson describe methods of modifying Forms applications without making manual
modifications in Forms Builder.

Oracle9i Forms Developer: New Features 4-2


How to Design Forms
without Forms Builder

You can design a form without opening it in Forms


Builder by:
Using the C Forms API (CFAPI)
Using the Java Design-Time API (JDAPI)
XML conversion

4-3 Copyright Oracle Corporation, 2002. All rights reserved.

Ways to Modify Forms


Of course you can use Forms Builder to create and modify Forms modules. In addition,
Forms 5.0 and later versions contain the C Forms API (CFAPI) that enable you to write C
programs to create, load, edit, save, and compile Forms, menus, object libraries, and
PL/SQL libraries. The CFAPI, still available in Oracle9i Forms, provides developers
access to almost all the functionality of Forms Builder. However, because it is not an
interactive tool, it is ideal for writing scripts to perform repetitive tasks on large numbers
of form module files.
New with Oracle9i Forms is the Java Design-time API (JDAPI), which is built on top of
the C Forms API and gives Java programmers a way to work with Forms outside the
Builder without the need to learn C programming. JDAPI can be used to
programmatically accomplish anything which can be achieved visually using Forms
Builder.

Oracle9i Forms Developer: New Features 4-3


What Can You Do with an API?

Build a form from scratch


Modify an existing form, such as:
Change color, name, size, and weight of boilerplate
fonts
Change background color of canvases
Generate forms
Enforce standards
Create documentation: Report on form
characteristics, such as:
Names of all graphic objects on all canvases
Labels of all tabs on all tabbed canvases
Work around bugs encountered when upgrading

4-4 Copyright Oracle Corporation, 2002. All rights reserved.

Typical Tasks for an API


There are many reasons why you might need to use an API. Some typical tasks that can be
performed are:
Form creation: After the program is written, you can parameterize some of the
requirements to rapidly build similar forms.
Form modification: With an API, making the same modification to multiple forms
becomes less tedious and error-prone.
Form generation: An API can be used to compile a set of forms.
Standards enforcement: An API can be used on existing forms, or when creating
new forms, to make them comply with corporate standards.
Form documentation: You can write a program to output information about the
structure of the form.
Bug workarounds: Upgrade problems encountered due to changes between versions
can be fixed on all upgraded forms at once.

Oracle9i Forms Developer: New Features 4-4


Advantages of Using an API
Time spent per form

API
Forms Builder
Speed

Number of modules
API

Errors per form


Forms Builder

Accuracy

Number of modules

4-5 Copyright Oracle Corporation, 2002. All rights reserved.

Why Use an API?


The main advantages of an API are realized when a program can be written once, but
executed on a number of modules.
When a program can be used on many modules, the time in writing the program is offset
by the time saved in avoiding the action of opening each module in Forms Builder and
manually performing the same task. With Forms Builder, the amount of time spent
performing a task on each module stays fairly constant. However, with an API, the greater
the number of modules, the lower the amount of time per module, because the time spent
writing the program gets distributed over a larger number of modules.
In addition to time saved, an API offers the advantage of being less error-prone. After the
program is working correctly, it can be executed multiple times without the errors that
would likely result from the same operations being performed manually. After you run the
program on a few modules and debug the code, it will run virtually error-free on
subsequent modules. This contrasts with performing the same task in Forms Builder,
where tedium and fatigue contribute to more errors as more modules are modified.
Although the graphs above do not depict actual numbers, they illustrate the advantages of
using an API and thereby increasing the number of modules on which a program is used.

Oracle9i Forms Developer: New Features 4-5


Using the Java API to Modify Modules

Forms
CFAPI JDAPI
Module

Use for:
Form modules
Menu modules
Object libraries
PL/SQL libraries
(load & inspect)

4-6 Copyright Oracle Corporation, 2002. All rights reserved.

Using JDAPI
The Java Design-time API acts upon Forms objects by using the Java Native Interface
(JNI) to call the Forms stack. You cannot use JDAPI at run time to control or interact with
running Forms modules.
You can manipulate all types of Forms modules: Forms, menus, object libraries, and
PL/SQL libraries. However, as with the C API, there is only limited functionality for
PL/SQL libraries. You can load them and inspect the contents, but cannot modify or save
them. Because PL/SQL libraries have a text-format alternative (with a .pld extension),
you can generate a text file of PL/SQL code without the JDAPI, save it as a pld file, and
compile it using the Forms command-line compiler. You can use the JDAPI to create and
modify library attachments on form and menu modules, as with any other Forms object.
Note: You can download the JDAPI javadoc from:
http://otn.oracle.com/docs/ products/forms/content.html. Scroll to the
section labeled Javadoc.
Instructor Note
As you present JDAPI constructs in the following slides, demonstrate the pertinent
javadoc to the students.

Oracle9i Forms Developer: New Features 4-6


Advantages of JDAPI

Provides object-oriented interface to


Forms modules
Enables you to perform some tasks
not possible in Forms Builder
Metadata classes enable generic
programming
Leverages Java knowledge

4-7 Copyright Oracle Corporation, 2002. All rights reserved.

Why Use the Java Design-time API?


JDAPI offers all the advantages of the Java 2 platform and APIs for writing high-level,
object-oriented programs that process Forms modules. In addition, there are some utility
features and constructs not available elsewhere. For example, it is possible to construct
Forms objects directly on Object Library Tabs, and thus build Object Libraries without
using intermediate Forms Modules. This feature is not available either in the C API or in
Forms Builder.
JDAPI is a higher-level API than the C API. It gives the user an object-oriented interface
to Forms, including abstract types and interfaces, generic objects with polymorphic
behavior, iterators for lists, memory management, object constructors that support
subclassing, typed exceptions, and Java-style naming conventions. Forms metadata is
encapsulated in a set of JDAPI metadata classes. The metadata allows powerful and
generic programming to be achieved easily; for example, obtaining the full set of string
properties for any given object as an iterator.
With JDAPI, you can leverage your knowledge of the popular Java language to affect the
design of Forms modules. The javadoc and extensive online help in Forms Builder
enable you to write simple JDAPI programs with little Java knowledge. However, to
realize the full advantages of JDAPI requires experience in Java programming.

Oracle9i Forms Developer: New Features 4-7


JDAPI Architecture

r
ja
api.
d
0j
\f9
va
ja
0\
s9
rm
fo

4-8 Copyright Oracle Corporation, 2002. All rights reserved.

JDAPI Architecture
JDAPI consists of a single oracle.forms.jdapi package contained in f90jdapi.jar
in the forms90\java subdirectory of ORACLE_HOME. To use JDAPI, you must set your
CLASSPATH to include this JAR file.
The package contains interfaces, abstract types, utility classes, and classes that represent
all Forms objects. The above diagram, taken from Forms online help, depicts the
architecture of JDAPI. The diagram is continued on the next slide.
Forms objects are sets of properties of Boolean, integer, string, and object types. The
Forms object classes implement the JdapiObject interface, which is the fundamental
type of all objects. The JdapiObject interface includes generic property accessors to get
and set properties by type, such as JdapiObject.getStringProperty(),
JdapiObject.setStringProperty(), JdapiObject.getIntegerProperty(),
and so on.
In addition to these generic methods, the Forms object classes have their own accessor
methods that are specific to the object. For example, the Font class has a
getFontSize() method that returns an integer, so you need not use the more generic
JdapiObject.getIntegerProperty().

Oracle9i Forms Developer: New Features 4-8


JDAPI Architecture

4-9 Copyright Oracle Corporation, 2002. All rights reserved.

JDAPI Architecture (continued)


JDAPI includes a JdapiIterator iterator interface that extends
java.util.Iterator. All methods returning iterator objects return this type,
regardless of the implementing subclass. Because it is a generic type of
java.lang.Object, you must cast to the appropriate return type or super type. For
example:
JdapiIterator blocks =
myForm.getObjectProperty(JdapiTypes.BLOCK_PTID);
Block myBlock = (Block)blocks.next();
The JdapiTypes class contains Property Type ID constants (*.PTID) and Object Type
ID constants (*.OTID) representing specific Forms object properties and Forms object
types.
Using the object-specific accessor method for the FormModule class (assuming that
myform has been instantiated as an instance of the FormModule class), the first statement
of the code above can be rewritten as:
JdapiIterator blocks = myForm.getBlocks();
Note: The diagram shown above is a continuation of the one on the previous slide.

Oracle9i Forms Developer: New Features 4-9


The JDAPI Session
Stop session
Session starts with first JDAPI call
import oracle.forms.jdapi.*;
Public class CreateForm
{
public static void main(String[] args)
{
// This line causes initialization
FormModule fmd = new FormModule("myform");
// Program code goes here
....
// Finally, free API resources
Jdapi.shutdown();
}
}

4-10 Copyright Oracle Corporation, 2002. All rights reserved.

The JDAPI Session


The JDAPI session is represented in the API by the oracle.forms.jdapi.Jdapi
class, which has several static methods for managing the session.
Starting the session: The underlying Forms API is automatically initialized as soon as
the first functional JDAPI call is made, as in the code sample above. You can explicitly
call Jdapi.startup() if you want to start the JDAPI in a mode other than its default
mode. (Currently, JDAPI can be started only in its default mode.)
Stopping the session: You stop a JDAPI session by calling Jadpi.shutdown().
Shutting down JDAPI destroys all the open JDAPI modules and objects.
Restarting the session: You can start, shut down, and restart JDAPI as often as required.
For example, you can temporarily free resources if processing Forms is only a part of your
running application. However, the API is single-threaded and multiple concurrent sessions
are not supported.

Oracle9i Forms Developer: New Features 4-10


Creating New Modules
Performing action in Forms Builder
Performing action with JDAPI
import oracle.forms.jdapi.*;
MYFORM
Public class CreateForm
{
public static void main(String[] args)
{
// This line causes initialization
FormModule fmd = new FormModule("myform");
// Program code goes here
....
// Finally, free API resources
Jdapi.shutdown();
}
}

4-11 Copyright Oracle Corporation, 2002. All rights reserved.

Creating Modules
To create a module, you simply call its constructor and instantiate it, as in the example
above. The example is equivalent to pressing the Create button in the Forms Builder
Object Navigator with the Forms node selected, then renaming the module to "myform."
You can create modules of the following types: FormModule, MenuModule, or
ObjectLibrary. You cannot create modules of the PlsqlModule type that has no
public constructor. As stated previously, the only JDAPI actions you can take with a
PL/SQL library module are to load it and inspect its contents.
Instructor Note
Show students the constructor for FormModule in javadoc. Note that there is also a
protected constructor (not shown above). Explain to students that this is for Forms internal
use only, and is not to be used in JDAPI programs. Scroll down to the Constructor Detail
section of the FormModule javadoc for further explanation of a protected constructor.
The slides show screenshots of performing equivalent actions in Forms Builder. Be sure
students make the connection between what they would do in Forms Builder and what
they can do with JDAPI.

Oracle9i Forms Developer: New Features 4-11


Adding Objects to Modules

....
FormModule fmd = new FormModule("myform");
Block blockA = new Block(fmd,"EMPLOYEES");
Item itemA = new Item(blockA,"employee_id");
Item itemB = new Item(blockA,"last_name");
Item itemC = new Item(blockA,"first_name");
....

4-12 Copyright Oracle Corporation, 2002. All rights reserved.

Adding Objects to Modules


After you create a module, you can add objects to it by calling the constructor for an
object and instantiating it. The constructors for Forms objects (other than modules)
specify the parent of the object and its name. These constructors are overloaded to take
other arguments as well, such as another object from which the new object is subclassed.
The code in the example is equivalent to the following actions in Forms Builder Object
Navigator:
Select the Block node under the MYFORM module, select Create, and select to
Build a new data block manually.
Select the item node under the EMPLOYEES block, select Create, and rename the
item to EMPLOYEE_ID. Do the same twice more to create the FIRST_NAME and
LAST_NAME items.
Instructor Note
Show students the javadoc for object constructors, such as Block and Canvas. Point out
how they are overloaded.

Oracle9i Forms Developer: New Features 4-12


Saving and Compiling Modules

....
FormModule fmd = new FormModule("myform");
Block blockA = new Block(fmd,"EMPLOYEES");
Item itemA = new Item(blockA,"employee_id");
Item itemB = new Item(blockA,"last_name");
Item itemC = new Item(blockA,"first_name");
fmd.save("EMPLOYEES_JDAPI.fmb");
fmd.compile();
....

4-13 Copyright Oracle Corporation, 2002. All rights reserved.

Saving and Compiling Modules


After you perform work on a module, save it before closing the JDAPI session. The
save() method takes a file name as an argument, along with a path if you are saving to
other than the current directory.
You can compile a module using the compile() method. If the form is unable to
compile, you receive a run-time exception and an error file (<filename>.err) is
created. The program in the example produces such an exception, and the error file shows:
FRM-30173: Module contains no canvases.
Form: MYFORM
FRM-30085: Unable to adjust form for output.
Instructor Note
Show students the javadoc on the save() and compile() methods for
FormModule.

Oracle9i Forms Developer: New Features 4-13


Saving and Compiling Modules (continued)
Example Code to Create a Form
The following code can be used to create a form in JDAPI:
import oracle.forms.jdapi.*;
public class CreateForm
{
public static void main(String[] args)
{
// This line will cause lazy initialization
// of the Jdapi session
FormModule fmd = new FormModule("myform");
Block blockA = new Block(fmd,"EMPLOYEES");
Item itemA = new Item(blockA,"EMPLOYEE_ID");
Item itemB = new Item(blockA,"LAST_NAME");
Item itemC = new Item(blockA,"FIRST_NAME");
fmd.save("EMPLOYEES_JDAPI.fmb");
fmd.destroy();
fmd.compile();
// Shut down the Jdapi session and free API resources
Jdapi.shutdown();
}
}

Instructor Note
Demonstration
Create a form using JDAPI and examine the new form in Forms Builder. Complete
instructions for this demonstration are in the JDAPI_CreateForm.txt file, located in
your demonstration directory. The Java code (as shown above) is in the
CreateForm.java file.

Oracle9i Forms Developer: New Features 4-14


Loading Existing Modules
import oracle.forms.jdapi.*;
public class ModifyForm
{
public static void main(String[] args)
{
Jdapi.setFailSubclassLoad(true);
Jdapi.setFailLibraryLoad(true);
FormModule fmd =
FormModule.open("EMPLOYEES_JDAPI.fmb");
....
fmd.save("EMPLOYEES_JDAPI.fmb");
fmd.destroy();
Jdapi.shutdown();
}
}

4-15 Copyright Oracle Corporation, 2002. All rights reserved.

Loading Existing Modules


You use the open() method for the module class to load a module in the JDAPI
program. In the example above, the form module is loaded from the file system. You can
also open a module from the session module list that stores all loaded and newly created
modules. The Jdapi.getModules() method obtains an iterator of the current set.
Suppressing Errors from Missing Subclassed Modules and Libraries
In setting up the JDAPI session, you can choose whether to suppress errors in the session
if subclassed modules or attached libraries cannot be located. You do so by calling
Jdapi.setFailSubclassLoad() and Jdapi.setFailLibraryLoad().
Passing a value of True to these methods causes JDAPI to ignore the errors. The default is
a value of False, which means that JDAPI will throw an exception if the referenced files
are missing. It is safe to ignore the errors and save the form, because the references will
not be lost; however, it may not be possible to compile the form.

Oracle9i Forms Developer: New Features 4-15


Using an Iterator
Forms Builder actions:
Expanding the list of
data blocks
Selecting a data block

....
Canvas cnv = new Canvas(fmd,"EMP_CV");
int xPos = 10; int yPos = 10;
JdapiIterator blocks = fmd.getBlocks();
while(blocks.hasNext())
{
Block myBlock = (Block)blocks.next();
// Code to process the block goes here
}
....

4-16 Copyright Oracle Corporation, 2002. All rights reserved.

Using an Iterator
To work with child objects of a Forms object, you must retrieve all such objects using an
iterator, which you declare to be of type JdapiIterator. You can think of an iterator
as an array, or list, of objects.
All of the classes for each Forms object that could have children have methods to access
those children. These methods, such as FormModule.getBlocks() shown in the
example above, return a JdapiIterator type.
After you have instantiated the iterator, as by assigning it to a variable such as blocks in
the example, you can traverse through the children by using the next() method of the
JdapiIterator interface. When the iterator is first instantiated, you must invoke the
next() method to get to the first object in the list. Note that the iterator returns the
generic type java.lang.Object, so you must cast it to the desired data type, which is
Block in the example.
You can use the hasNext() method, which returns Boolean, to test whether you are at
the end of the list.
Note: In the example above, prior to creating the iterator, a canvas is created and some
integer variables are initialized. These will be used to place items on a canvas.

Oracle9i Forms Developer: New Features 4-16


Modifying Forms Objects
....
{
Block myBlock = (Block)blocks.next();
myBlock.setQueryDataSourceName(myBlock.getName());
JdapiIterator items = myBlock.getItems();
while(items.hasNext())
{
Item myItem = (Item)items.next();
myItem.setCanvasObject(cnv);
myItem.setXPosition(xPos);
myItem.setYPosition(yPos);
yPos = yPos + 20;
}
}
....

4-17 Copyright Oracle Corporation, 2002. All rights reserved.

Modifying Forms Objects


After creating Forms objects, you will need to set some properties for them. Some of the
properties have default values; for example, the Query Data Source Type for a block is set
to Table when the block is created. However, the Query Data Source Name is not set. The
first statement highlighted above sets the Query Data Source Name property for the
EMPLOYEES block (the only block in the form) to be the same as the name of the block.
The code that follows creates an iterator for the blocks items. For each item, the Canvas is
set to be the new canvas, EMP_CV, that we created earlier in this program, assigned to the
variable cnv. The code also sets the X and Y Position for each item, placing each item 20
units below the previous one. The xPos and yPos variables were initialized to 10 in the
code on the previous slide.
Note: All of this code is part of the section that processes the blocks of the form.

Oracle9i Forms Developer: New Features 4-17


Deleting Forms Objects

....
while(items.hasNext())
{
Item myItem = (Item)items.next();
if (myItem.getName().equals("FIRST_NAME"))
{
myItem.destroy();
}
else
{
myItem.setCanvasObject(cnv);
myItem.setXPosition(xPos);
myItem.setYPosition(yPos);
yPos = yPos + 20;
}
}
....

4-18 Copyright Oracle Corporation, 2002. All rights reserved.

Deleting Forms Objects


Calling the destroy() method of a Forms object deletes it from the module. If it has
children, they are also deleted. For example, if you delete a block, all of its items and
triggers are deleted as well.
Calling the destroy() method on a Forms module (form, menu, object library, or
PL/SQL library) does not delete the module, but simply removes it from memory. This is
exactly the behavior of pressing the [Delete] key or clicking the Delete icon with an
object selected in the Forms Builder Object Navigator. If a module is selected, Delete
unloads it; but if any other object is selected, Delete removes it (with its children) from
the module.
For example, if you want to use JDAPI to delete the item called FIRST_NAME from the
EMPLOYEES block, you can check the name of each item within the item iterator for the
block, using the getName() method to obtain the name. If the name is equal to
FIRST_NAME, you can use the destroy() method to delete the item.

Oracle9i Forms Developer: New Features 4-18


Deleting Forms Objects (continued)
Example Code to Modify a Form
The following JDAPI code modifies the form that was created by the previous program:
import oracle.forms.jdapi.*;
public class ModifyForm
{
public static void main(String[] args)
{
// This line causes initialization of the Jdapi session
FormModule fmd = FormModule.open("EMPLOYEES_JDAPI.fmb");
Canvas cnv = new Canvas(fmd,"EMP_CV");
int xPos = 10; int yPos = 10;
JdapiIterator blocks = fmd.getBlocks();
while(blocks.hasNext())
{
Block myBlock = (Block)blocks.next();
myBlock.setQueryDataSourceName(myBlock.getName());
JdapiIterator items = myBlock.getItems();
while(items.hasNext())
{
Item myItem = (Item)items.next();
if (myItem.getName().equals("FIRST_NAME"))
{
myItem.destroy();
}
else
{
myItem.setCanvasObject(cnv);
myItem.setXPosition(xPos);
myItem.setYPosition(yPos);
yPos = yPos + 20;
}
}
}
fmd.save("EMPLOYEES_JDAPI.fmb");
fmd.compile();
fmd.destroy();
// Shut down the Jdapi session and free API resources
Jdapi.shutdown();
}
}

Instructor Note
Demonstration
Modify a form using JDAPI and examine the changed form in Forms Builder. Complete
instructions for this demo are in the JDAPI_ModifyForm.txt file.

Oracle9i Forms Developer: New Features 4-19


Copying and Subclassing

Copying: Use clone() method:

myblock.clone(fmd2,"EMPLOYEES");

Subclassing:
At object construction:

Block blockB = new Block(fmd1,"EMP2",blockA);

Post-construction:
blockB.setSubclassParent(blockA);

Using parent properties

4-20 Copyright Oracle Corporation, 2002. All rights reserved.

Copying and Subclassing


The JDAPI contains methods to copy and subclass objects:
Copy: Use the clone() method to copy an object.
In the example shown above, myblock is a block that you have created in an fmd1
form. You have also created another form,fmd2.
Subclass: You can use various methods to subclass an object:
- At object construction: Specify the object to be subclassed as the third
argument to the object constructor. In the example, you have created an fmd1
form and a blockA block, and are subclassing blockA within the same form.
- Post-construction: You can call high-level object methods:
JdapiObject.createSubclassedChild() and
JdapiObject.setSubclassParent(). If you have created an fmd1 form
and two blocks, blockA and blockB, you can use the code example above
to have blockB subclass from blockA.
- Using parent properties: Subclassing information is held at the object level in a
set of eleven string properties that you can set. See online help for further
information about this low-level kind of subclassing.

Oracle9i Forms Developer: New Features 4-20


Handling Exceptions

All exceptions extend


java.lang.RuntimeException.
Almost every method can throw an exception.
Trycatch is not required, but is recommended.
JDAPI exceptions:
JdapiException
JdapiIllegalStateException
JdapiUnsupportedOperationException

4-21 Copyright Oracle Corporation, 2002. All rights reserved.

Handling Exceptions
All exceptions thrown by JDAPI extend JdapiException, which in its turn extends
java.lang.RuntimeException. Although this means that almost every JDAPI
method can throw an exception, and that you are not required to specifically write
trycatch code for these exceptions, it is good practice to do this. As a suggestion, you
could follow each try... block with several catch... Block codes, catching
first the JDAPI exceptions and then more generic exceptions.
The JDAPI exceptions are:
JdapiException: The base type; thrown in many cases. May be thrown by the
underlying Forms code on failing to create Forms objects.
JdapiIllegalStateException: Thrown by any Forms object class when a
method is called and the class instance does not reference a valid Forms object (for
example, after the Forms object has been destroyed).
JdapiUnsupportedOperationException: Thrown by the remove()
method of JDAPI iterators, which do not support the functionality, and by the
compile() method of the PlsqlLibrary class.

Oracle9i Forms Developer: New Features 4-21


Writing Generic Code

You can write generic code to process multiple Forms


objects of different types using:
JdapiObject interface, JdapiModule abstract
type
Metadata objects:
JdapiMetadata
JdapiMetaObject
JadapiMetaProperty

4-22 Copyright Oracle Corporation, 2002. All rights reserved.

Writing Generic Code


The code shown in the previous examples used mostly object-specific code. However, if
you need to make JDAPI programs more generic so that they will work on multiple types
of objects, you can call the methods of JdapiObject for most objects, or when
referring to modules, you can use the methods of JdapiModule, which extends
JdapiObject.
There are also JDAPI classes dealing with Forms model metadata:
JdapiMetadata: Holds all metadata for Forms objects; used to determine the
properties of a given Forms object.
JdapiMetaObject: Represents the metadata for a Forms object, describing the
object in terms of its properties.
JdapiMetaProperty: Represents metadata for a given property, and has utility
methods for inspecting any property.
Online help shows several examples of writing generic code and using metadata. There is
also a metadata browser included with the Forms demos that shows information about
properties of any given Forms object. You can download the Forms demos from OTN:
http://otn.oracle.com/sample_code/products/forms/content.html.

Oracle9i Forms Developer: New Features 4-22


Special Cases in JDAPI Programming

JDAPI has specific support for managing:


Property classes
List items
Font objects
Coordinate objects
LOV and record objects
Menu roles

4-23 Copyright Oracle Corporation, 2002. All rights reserved.

Special Cases in JDAPI Programming


Most Forms objects can be handled using the generic approach or object-specific
constructors and property accessors that are intuitive once you understand the Forms
model. However, there are idiosyncrasies requiring special support for managing:
Property classes: Adding and retrieving custom properties
List items: Adding, retrieving, and deleting list elements
Font objects: Convenience objects encapsulating all the font properties of an object
Coordinate objects: Convenience objects encapsulating the coordinate system
attributes of a Forms module
LOVs and record group objects: Column mappings and record group columns
Menu roles: Adding or removing roles and retrieving role information
You can find information and case examples in online help.

Oracle9i Forms Developer: New Features 4-23


Practice 4a Overview

This practice covers the following topics:


Installing javadoc for JDAPI
Examining javadoc for JDAPI
Modifying the Orders form using a JDAPI program

4-24 Copyright Oracle Corporation, 2002. All rights reserved.

Practice 4a Overview
In this practice, you install javadoc for the JDAPI and XML conversion tools and use
the javadoc to answer some questions about JDAPI. You modify the Orders form by
writing, compiling, and executing a JDAPI program.
Instructor Note
Students unfamiliar with Java might have trouble writing the JDAPI program from
scratch. If this is the case, have them copy the ModifyOrders.java file from their
solutions directory to the lab directory. They should then be able to follow the instructions
to compile and run the ModifyOrders class.

Oracle9i Forms Developer: New Features 4-24


Practice 4a

1. Install the javadoc for JDAPI and XML tools. The javadoc file that was
downloaded from OTN is called javadocJDAPIXML.zip. Unzip the file into a
new labs\javadocJDAPIXML directory.

2. Navigate to the javadocJDAPIXML directory and double-click the index.html


file to open javadoc in Internet Explorer. Navigate through the documentation for
both the JDAPI and the XMLTOOLS packages.

3. Use the javadoc for JDAPI to answer the following questions, then close the
javadoc browser window:

a. What class would you use to access an Attached Library in a Forms module?

_____________________________________________________________

b. What method of that class would you use to find out the location of the
library?

_____________________________________________________________

c. What data type does that method return?

_____________________________________________________________

4. In Notepad, write a JDAPI program (a .java file) to modify the Orders form by
changing the X position and the width of the Order_Date item. The new X
position should be 340 and the width should be 95. Save and compile the modified
form.
Note: To compile this form, you must connect the JDAPI session to the database.
Look at the javadoc for the JDAPI class to discover the methods to call in order to
connect to the database prior to compiling the form. Disconnect from the database
after the compilation.
Hint: If you are familiar with Java, try to write this code yourself. However, if you
need help, the ModifyOrders.java file in your solutions directory contains the
required code.

5. Compile and run the ModifyOrders class that you have written. You can run the
SetCP.bat batch file to set your CLASSPATH so that the JDAPI classes can be
located.

Oracle9i Forms Developer: New Features 4-25


Practice 4a (continued)

6. Check to see that the Orders form compiled successfully. If an Orders.err file
was created, open it to examine the output. Open the Orders form in Forms Builder
to make sure that the X position and Width properties of Orders.Order_Items
have been modified. Then close all forms in Forms Builder.

Oracle9i Forms Developer: New Features 4-26


Why Convert Forms to XML?

XML is:
Simple
Easy to read
Platform-independent
XML files can be used by other tools.
Conversion utilities can be used from command line or
Java.
XML documents can be used for:
Programmatic manipulation of Forms modules
Custom documentation
Operations such as diffing and merging

4-27 Copyright Oracle Corporation, 2002. All rights reserved.

Benefits of XML Conversion


Forms modules that have been converted to text files (.fmt, .olt, and .mmt) are not
easily readable. In contrast, it is easy to read the simple hierarchical structure of the files
created by converting Forms modules to XML. The XML files are easily transportable to
different platforms, and can be used by other tools, such as XML parsers and text
manipulation tools.
The Forms XML conversion utilities are easy to use and can be started from the command
line or called in a Java program. After a module has been converted to XML with these
tools, you can modify them to manipulate Forms modules or produce custom
documentation. You can even perform operations not possible any other way, such as
reporting the differences between two files (diffing) or merging two XML documents and
converting back to a Forms module.

Oracle9i Forms Developer: New Features 4-27


XML Conversion Utilities

Oracle9i Forms offers tools to:


Convert a module to XML:
Forms
Forms2XML
XML
Convert XML to a Forms module: tools
XML2Forms
Generate the Forms XML schema file:
SchemaGenerator
Validate XML against Forms XML
schema: XMLValidator
Classes needed (under ORACLE_HOME):
\forms90\java\f90xmltools.jar
Also need JDAPI
\lib\xmlparserv2.jar
classes!
\lib\xschema.jar

4-28 Copyright Oracle Corporation, 2002. All rights reserved.

Forms XML Tools


Oracle9i Forms includes the oracle.forms.util.xmltools package:
Forms2XML: Takes a module (Form Module, Object Library or Menu Module) and
uses the JDAPI to convert it to XML
XML2Forms: Takes an XML Form representation and uses the JDAPI to convert it
back to a module
SchemaGenerator: Generates an XML Schema for the Forms model from the
JDAPI metadata
XMLValidator: Validates XML against the internal Forms XML Schema
You must set your CLASSPATH to include f90jdapi.jar, f90xmltools.jar,
xmlparserv2.jar, and xschema.jar. As an alternative, you can use from the
command line the following convenience scripts that set CLASSPATH for you:

For NT/2000/XP For UNIX Function


iff2xml90.bat iff2xml90.sh Converts Forms modules to XML
ifxml2f90.bat ifxml2f90.sh Converts XML to Forms modules
ifxmlsg90.bat ifxmlsg90.sh Generates Forms XML Schema
ifxmlv90.bat ifxmlv90.sh Validates structure of Forms XML file

Oracle9i Forms Developer: New Features 4-28


Converting a Forms Module to XML
Forms
XML
tools

Converts Form, Menu, or Object Library modules


Creates file with name formatted as:
<file name>_<file type>.xml
Example: EMPLOYEES_FMB.xml
Forms2XML does the following:
Queries all objects in the module for properties and
child objects
Creates a corresponding XML element for each
Forms object and an element attribute for each
property (overridden properties only)
Writes boilerplate images to separate image files:
<form>_<canvas>_IMAGEn.tif

4-29 Copyright Oracle Corporation, 2002. All rights reserved.

Converting a Forms Module to XML


The Forms2XML utility or its corresponding iff2xml90 convenience script operates
on Form, Menu, or Object Library modules. None of the XML conversion tools will
handle PL/SQL Library modules because they have no structure that can be usefully
represented in an XML format. The existing text format (.pld) of a PL/SQL library is
sufficient for browsing and editing needs.
You can use the Forms to XML utility as follows:
From the command line: java oracle.forms.util.xmltools.Forms2XML
[OVERWRITE=YES] <filename>.fmb
Set OVERWRITE if the XML file already exists
From the command line using the convenience script, which sets the CLASSPATH
for you: iff2xml90 [OVERWRITE=YES] <filename>.fmb
From a Java program: Call the dumpmodule() method of Forms2XML to create an
XMLDocument object that you can manipulate with classes from the XML
Developers Kit (XDK):
Forms2XML converter = new Forms2XML(mod);
XMLDocument doc = converter.dumpModule();

Oracle9i Forms Developer: New Features 4-29


Converting XML to a Forms Module:
Forms
XML
tools

Converts XML to Form, Menu, or Object Library


modules
Creates file with name formatted as:
<file name>.<type>
Example: EMPLOYEES_FMB.xml is converted to
EMPLOYEES.fmb
XML2Forms does the following:
Parses the XML using Oracle XDK SAXParser
Validates the XML against the Forms XML Schema
Creates a corresponding Forms object for each
XML element and sets the properties for attributes

4-30 Copyright Oracle Corporation, 2002. All rights reserved.

Converting XML to a Forms Module


The XML2Forms utility or its corresponding ifxml2f90 convenience script converts
XML to corresponding Form, Menu, or Object Library modules. It automatically validates
the XML against the internal Forms XML Schema.
You can use the XML to Forms utility as follows:
From the command line: java oracle.forms.util.xmltools.XML2Forms
[OVERWRITE=YES] [PRINTTREE=YES] [USERID=<connect string>]
<filename>.xml
Set OVERWRITE if the Forms module already exists; set PRINTTREE if you wish to
display a tree during conversion; set USERID if you are using a record group query.
From the command line using the convenience script, which sets the CLASSPATH
for you: ifxml2f90 [OVERWRITE=YES] [PRINTTREE=YES]
[USERID=<connect string>] <filename>.xml
From Java: You can pass an XMLDocument object (doc in the example) to
XML2Forms to convert it to the corresponding module:
XML2Forms converter = new XML2Forms(doc);
JdapiModule newModule = converter.createModule();

Oracle9i Forms Developer: New Features 4-30


Generating the Forms XML Schema File
Forms
XML form90.xsd
tools

Why use Schema Generator?


Generate forms90.xsd file for use with XML
software or parser
Not needed with Forms XML conversion tools,
which generate the schema internally for
validation

4-31 Copyright Oracle Corporation, 2002. All rights reserved.

Generating the Forms XML Schema File


The Forms XML conversion tools generate a schema internally at validation from the
Forms metadata in the JDAPI, so it is not required that you manually use the Schema
Generator tool. You would only need to generate a schema if you are using your own
XML software or parser. In this case, the Schema Generator produces a forms90.xsd
file that can be used with such software.
The Schema Generator utility command takes no arguments, and can be used as follows:
From the command line:
java oracle.forms.util.xmltools.SchemaGenerator
From the command line using the convenience script, which sets the CLASSPATH
for you: ifxmlsg90
From Java: You can use the generateSchema() method of the
SchemaGenerator class to return an oracle.xml.parser.v2.XMLDocument
representing the Forms XML Schema:
SchemaGenerator sgen = new SchemaGenerator();
XMLDocument formSchema = sgen.generateSchema();

Oracle9i Forms Developer: New Features 4-31


Validating XML
Forms
XML
tools

Why validate XML?


You have created XML from scratch.
OR
You have manually modified generated XML.
You want to check if XML is correct before
converting back to a Forms module or using in Java
program.
The XML validator:
Generates an internal Forms XML schema
Uses it to check correctness of specified XML file

4-32 Copyright Oracle Corporation, 2002. All rights reserved.

Validating XML
The rules for XML files are strict. A forgotten tag or an attribute without quotes makes an
XML file unusable.
In many cases, you do not need to explicitly validate the XML because the XML to Forms
tools performs such validation internally. However, if you have either created new XML
or modified the generated XML, you may want to explicitly validate it before converting
it to a Forms module or using it in a Java program.
You can use the XML Validator as follows:
From the command line:
java oracle.forms.util.xmltools.XMLValidator <filename>.xml
From the command line using the convenience script, which sets the CLASSPATH
for you: ifxmlv90 <filename>.xml
From Java: You can define an object of type XMLValidator and use it in a
try/catch block to validate an XML file, represented by doc in the example:
XMLValidator validator = new XMLValidator();
try { validator.validateXML(doc); }
catch(Exception e) { //code to handle exception }

Oracle9i Forms Developer: New Features 4-32


XML Conversion Utilities Example

Convert Form to XML

>iff2xml90 EMPLOYEES_JDAPI.fmb
Oracle9i Forms to XML Tool
Copyright(c) Oracle Corporation 2001. All rights reserved.
Processing module EMPLOYEES_JDAPI.fmb
XML Module saved as EMPLOYEES_JDAPI_fmb.xml

4-33 Copyright Oracle Corporation, 2002. All rights reserved.

XML Conversion Utilities Example


The following example shows how the convenience scripts are used to perform the
designated actions. The convenience scripts automatically set CLASSPATH for you, so
there is no need to set CLASSPATH before running them.
Example: Convert a form module to XML:
>iff2xml90 EMPLOYEES_JDAPI.fmb
Oracle9i Forms to XML Tool
Copyright(c) Oracle Corporation 2001. All rights
reserved.
Processing module EMPLOYEES_JDAPI.fmb
XML Module saved as EMPLOYEES_JDAPI_fmb.xml

Instructor Note
Demonstration
Show students how to run the convenience scripts. Complete instructions for this demo
are in the file are in the file XMLexample.txt, located in your demo directory.

Oracle9i Forms Developer: New Features 4-33


XML Conversion Utilities Example

>del EMPLOYEES_JDAPI.fmb

Convert XML to Form


>ifxml2f90 PRINTTREE=YES EMPLOYEES_JDAPI_fmb.xml
Oracle9i XML to Forms Tool
Copyright(c) Oracle Corporation 2001. All rights reserved.
Processing XML module EMPLOYEES_JDAPI_fmb.xml
FormModule: MYFORM
|-Coordinate: null
|-Block: EMPLOYEES
| |-Item: EMPLOYEE_ID In some cases (such as
| |-Item: LAST_NAME verifying that a record
|-Canvas: EMP_CV group query is correct)
|-Window: WINDOW1 you might need to
Module saved as EMPLOYEES_JDAPI.fmb
connect to a database
when converting XML
to a form module.

4-34 Copyright Oracle Corporation, 2002. All rights reserved.

XML Conversion Utilities Example (continued)


Delete the form module:
>del EMPLOYEES_JDAPI.fmb
Convert the XML file to a form module:
>ifxml2f90 PRINTTREE=YES EMPLOYEES_JDAPI_fmb.xml
Oracle9i XML to Forms Tool
Copyright(c) Oracle Corporation 2001. All rights
reserved.
Processing XML module EMPLOYEES_JDAPI_fmb.xml
FormModule: MYFORM
|-Coordinate: null
|-Block: EMPLOYEES
| |-Item: EMPLOYEE_ID
| |-Item: LAST_NAME
|-Canvas: EMP_CV
|-Window: WINDOW1
Module saved as EMPLOYEES_JDAPI.fmb

Oracle9i Forms Developer: New Features 4-34


XML Conversion Utilities Example

Validate XML

>ifxmlv90 EMPLOYEES_JDAPI_fmb.xml
Oracle9i Forms XML Validator
Copyright(c) Oracle Corporation 2001. All rights reserved.
EMPLOYEES_JDAPI_fmb.xml validated against the Forms XML Schema.

Generate XML Schema

>ifxmlsg90
Oracle9i Forms XML Schema Generator
Copyright(c) Oracle Corporation 2001. All rights reserved.
Forms XML Schema saved as forms90.xsd

4-35 Copyright Oracle Corporation, 2002. All rights reserved.

XML Conversion Utilities Example (continued)


Generate a file of the Forms XML schema:
>ifxmlsg90
Oracle9i Forms XML Schema Generator
Copyright(c) Oracle Corporation 2001. All rights
reserved.
Forms XML Schema saved as forms90.xsd
Operating on Multiple Files
For the conversion utilities that operate on files, you can write a batch file to perform the
operation on multiple files at one time. For example, you can place the following code
into a batch file called f2xml.bat:
for %%f in (%1) do call iff2xml90 %%f overwrite=yes
You can then run the conversion against all .fmb files in the directory as follows:
f2xml *.fmb
This produces an XML file for each .fmb file in the directory.

Oracle9i Forms Developer: New Features 4-35


Summary

In this lesson, you should have learned that:


You can modify forms modules outside the
Builder using:
The Forms C API (CFAPI)
The Java Design-Time API (JDAPI)
XML Conversion tools
By using a batch method to modify forms:
Accuracy is improved
Productivity is increased
} on larger numbers of forms

4-36 Copyright Oracle Corporation, 2002. All rights reserved.

Summary
There are three ways to modify Forms modules without opening Forms Builder:
The Forms C API (CFAPI)
The Java Design-Time API (JDAPI)
XML conversion tools
JDAPI and the XML conversion tools are new with Oracle9i Forms.
Using these tools to modify a larger number of forms results in greater accuracy and
productivity than with opening each form individually in Forms Builder to modify it.

Oracle9i Forms Developer: New Features 4-36


Summary

JDAPI contains classes and methods for:


Creating and modifying Forms, Menus, and Object
Libraries
Performing programmatically almost any action you
can perform manually with Forms Builder
The XML conversion utility enables you to:
Convert Forms modules to XML
Convert XML to Forms modules
Generate a Forms XML Schema
Validate XML against the Forms XML Schema
Perform any of the above operations from the
command line or within a Java program

4-37 Copyright Oracle Corporation, 2002. All rights reserved.

Summary (continued)
JDAPI provides Java classes that enable you to create and modify Forms modules,
including forms, menus, and object libraries. You can programmatically accomplish
almost anything that you can do manually with Forms Builder.
With the XML conversion tools, you can convert Forms modules to XML and vice versa.
You can generate an XML file of the internal Forms Schema or validate XML against the
internal Forms Schema. You can use the XML tools from the command line or from a
Java program.
JDAPI and XML conversion tools provide developers with the flexibility to employ
various methods to modify and document Forms modules accurately and efficiently.

Oracle9i Forms Developer: New Features 4-37


Practice 4b Overview

This practice covers the following topics:


Converting a Forms module to XML
Making modifications in the XML file
Converting the XML file back to an FMB
Validating XML
Producing the Forms XML Schema document

4-38 Copyright Oracle Corporation, 2002. All rights reserved.

Practice 4b Overview
In this practice, you use the XML conversion tools to convert a form module to XML,
modify the XML file, and convert it back to an .fmb file. You then open the .fmb file in
Forms Builder to test that the modification was made. You also validate XML after
deliberately introducing an error into the file, and you generate the Forms Schema XML
document.

Oracle9i Forms Developer: New Features 4-38


Practice 4b

1. Convert the Customers form to XML. Examine the structure of the XML file. In
WordPad, open xml_structure.txt to help you examine the tree structure of
the XML.

2. In the XML file, change the background color of the Account_Mgr_Name item to
red and the foreground color of that item to white.

3. Validate the modified XML file, using the convenience script.

4. Using the convenience script, convert the XML file back to a .fmb, then open the
form in Forms Builder and run it to test the change. Then close the form in Forms
Builder.
Hint: You will need to connect to the database when you convert this XML to an
.fmb file.

5. The prompt of the Account_Mgr_Name item appears as white because by default


it uses the foreground color for the item. Add a PromptForegroundColor
attribute (after the prompt name) in the XML file to change the color of the prompt
to black. Convert the .xml file to an .fmb file. Open the Customers form in
Forms Builder and click Run Form to test the changes, then close the form in Forms
Builder.

6. Change the three colors (Foreground Color, Background Color, and Prompt Color)
back to their default values without opening Forms Builder. Then open the form in
Forms Builder to verify that the changes have been made.

7. Create an error in the customers_fmb.xml file by deleting any of the end tags.
For example, delete the final ">" in the section for one of the items. Then validate
the XML to see the errors that appear.

8. Would you usually need to generate an external Forms Schema file? Under what
conditions would such a file be required?

__________________________________________________________________

__________________________________________________________________

__________________________________________________________________

Oracle9i Forms Developer: New Features 4-39


Practice 4b (continued)

9. Create a file that represents the Forms Schema. Open that file (forms90.xsd) in
WordPad to examine the structure of the Forms Schema, consisting of all the
possible tags that can be used for Forms elements and attributes. Examine the
attributes defined for the Item element. You should see the attributes that you
modified in earlier exercises.

Oracle9i Forms Developer: New Features 4-40


Troubleshooting Forms Applications

Copyright Oracle Corporation, 2002. All rights reserved.

Schedule: Timing Topic


80 minutes Lecture
60 minutes Practice
140 minutes Total
Instructor Note
Because of its length, this lesson is divided into two parts, with a practice after each part:
Part One: The Forms Debugger
Part Two: Tracing and Logging

Oracle9i Forms Developer: New Features 5-1


Objectives

After completing this lesson, you should be able to do


the following:
Describe the components of the Forms Debugger
Use the Debugger to diagnose problems with a
Forms module
Debug an application remotely
Enable tracing and logging to help troubleshoot
problems

5-2 Copyright Oracle Corporation, 2002. All rights reserved.

Lesson Aim
This lesson describes the new Forms facilities for debugging, tracing, and logging.

Oracle9i Forms Developer: New Features 5-2


Debugging Tips

To correct trigger problems, you can:


Connect to the database for SQL compilation.
Remember that the line that fails is not always
responsible.
Watch for missing semicolons and quotation
marks.
Define triggers at the correct level.
Place triggers where the event will happen.

5-3 Copyright Oracle Corporation, 2002. All rights reserved.

General Tips to Solve Trigger Problems


Make sure you are connected to the (correct) database when you compile triggers
that contain SQL. Error messages can be deceiving.
Although the PL/SQL Editor reports the line that fails, the error might be due to a
dependency on an earlier line of code.
Missing semicolons (;) and mismatched quotes are a common cause of compile
errors. Check for this if a compile error does not give an obvious indication to the
problem.
If a trigger seems to fire too often, or on the wrong block or item in the form, check
whether it is defined at the required level. For example, a form-level When-
Validate-Item trigger fires for every changed item in the form. To check this, you
can run the form with Debug Messages on.
For triggers that populate other items, make sure that the trigger belongs to the
object where the firing event will occur, not on the items to be populated.

Oracle9i Forms Developer: New Features 5-3


The Debugging Process

Monitor and debug triggers by:


Compiling and
correcting errors in
the PL/SQL Editor

Displaying debug
messages at run
time

Invoking the
PL/SQL Debugger

5-4 Copyright Oracle Corporation, 2002. All rights reserved.

The Debugging Process


With Forms Builder you can monitor and debug client-side and stored program units in a
number of ways:
Compiling: Syntax errors and object reference errors (including references to
database objects) are reported when you compile a trigger or generate the form
module. This enables you to correct these problems before run time.
Running a form with run time parameter debug_messages=Yes: In Debug
mode, you can request messages to be displayed to indicate when triggers fire. This
helps you see whether certain triggers are firing, their origin and level, and the time
at which they fire. If an error occurs, you can look at the last trigger that fired to
narrow the scope of the source of the error.
Invoking the PL/SQL Debugger: You invoke the debugger from Forms Builder by
clicking the Run Form Debug button on the toolbar. There is no longer a Help >
Debug menu item as there was in Forms6i Runtime.
With the Debugger you can monitor the execution of PL/SQL code. You can step through
the code on a line-by-line basis, and you can monitor called subprograms and variables as
you do so. You can also modify variables as the form is running to test how various
changes in form item values and variable values will affect your application.

Oracle9i Forms Developer: New Features 5-4


Setting Breakpoints
Breakpoints: Before setting breakpoint:
Suspend form
execution
Return control
to the debugger
Remain in effect
for the Forms
After setting breakpoint:
Builder session
May be enabled
or disabled
Are set in the
PL/SQL Editor
on executable
lines of code
5-5 Copyright Oracle Corporation, 2002. All rights reserved.

Setting Breakpoints in Client Code


You set breakpoints in code so that the form running in debug mode will be suspended
when a breakpoint is encountered and control will return to the Forms Builder debugger,
allowing you to monitor or change the environment at that point. When you set a
breakpoint, it remains set until you exit the Forms Builder session. However, you can
disable and enable breakpoints as needed by unchecking and rechecking the check box in
the Breakpoints panel of the Debug Console. The Debug Console is presented later in this
lesson.
You can set breakpoints only on executable lines of code, such as assignments or
subprogram calls. There are three ways to set a breakpoint:
By double-clicking to the left of a line of code in the PL/SQL Editor
By right-clicking a line of code and selecting Insert/Remove Breakpoint.
By choosing Debug > Insert/Remove breakpoint from the main menu
Performing the same action again unsets the breakpoint. You can also remove one or all
breakpoints from the pop-up menu in the Breakpoint panel, as described previously.

Oracle9i Forms Developer: New Features 5-5


Setting Breakpoints: Stored Code

Can set on stored program units:


Expand Database Objects node
Expand <schema> node
Expand PL/SQL Stored Program Units node
Double-click program unit
Set breakpoint in PL/SQL Editor
Cannot set on database triggers or stored PL/SQL
libraries
Compile with debug information

5-6 Copyright Oracle Corporation, 2002. All rights reserved.

Setting Breakpoints in Stored Code


If you are connected to the database, you can set breakpoints in stored packages,
procedures, and functions just as you do in client-side programs. To do so:
1. Expand the Database Objects node.
2. Navigate to the stored subprogram.
3. Open it in the PL/SQL Editor.
You cannot set breakpoints in database triggers or stored PL/SQL libraries.
If the program unit does not appear in a stack frame, or if you are not able to see it as you
step through its code, it has not been compiled with debug information included. There
are three methods to compile the stored program unit with debug information:
Create the stored procedure in Forms Builder, which creates it with debugging
information.
Use ALTER SESSION SET PLSQL_DEBUG=TRUE before creating the stored
procedure.
Manually recompile an existing PL/SQL program unit using:
ALTER PROCEDURE <schema.procedure> COMPILE DEBUG
(To reverse this and recompile without debug information, use the command:
ALTER PROCEDURE <schema.procedure> COMPILE).

Oracle9i Forms Developer: New Features 5-6


The Debug Console

Stack
Variables
Watch
Form Values
Loaded PL/SQL
Packages
Global and Dock/
System Variables Undock
Breakpoints
Click
bar for
pop-up
menu

5-7 Copyright Oracle Corporation, 2002. All rights reserved.

The Debug Console


The debug console is a workspace in Forms Builder that enables you to see various
aspects of the running form and its environment. You display the debug console by
selecting Debug > Debug Console from the menu. It displays automatically when you
encounter a breakpoint in a form that is running in debug mode.
Within the console, you can display several types of panels: Stack, Variables, Watch,
Form Values, Breakpoints, Loaded PL/SQL Packages, and Global/System Variables. You
can resize the debug console and any of the panels displayed within it.
You choose which panels to display or close by clicking the toggle buttons on the toolbar
of the debug console, or by selecting Debug > Debug Windows from the menu. As you
show and hide panels within the console, the panels automatically expand and contract to
fill the console.
You can undock any of the panels to display them outside the debug console by clicking
the upward pointing arrow in the top right of the panel; you redock the panel by clicking
its downward pointing arrow.
If you right-click the area beside the dock/undock arrow, you will see a pop-up menu that
enables hiding, docking, or undocking the panel.

Oracle9i Forms Developer: New Features 5-7


The Debug Console

Stack
Variables
Watch
Form Values
Loaded PL/SQL
Packages
Global and
System Variables
Breakpoints

5-8 Copyright Oracle Corporation, 2002. All rights reserved.

The Debug Console: Stack Panel


The call stack represents the chain of subprograms starting from the initial entry point
down to the currently executing subprogram. The program currently executing in the
example above is EMPLOYEES.SAL.CHECK_PCT, which was called by
EMPLOYEES.SAL.GET_SAL. This program was called from a When-Button-Pressed
trigger, the initial entry point of the current call stack. As you can see, frames are listed in
the reverse order in which the subprograms were executed. The earliest frame is at the
bottom of the stack, while the latest frame is at the top of the stack.
A stack frame contains information about the corresponding subprogram, including the
module name, the package name if any, the subprogram name, and the next statement to
be executed. For example, EMPLOYEES.SAL.GET_SAL::19 indicates that line 19 of
subprogram GET_SAL in the SAL package contained in the EMPLOYEES module will
be executed when the application returns to that subprogram. When that occurs, which
happens after EMPLOYEES.SAL.CHECK_PCT executes, the
EMPLOYEES.SAL.CHECK_PCT frame will get pushed off the stack.

Oracle9i Forms Developer: New Features 5-8


The Debug Console

Stack
Variables
Watch
Form Values
Loaded PL/SQL
Packages
Global and
System Variables
Breakpoints
Read-only:
Modifiable:

5-9 Copyright Oracle Corporation, 2002. All rights reserved.

The Debug Console: Variables Panel


The variables panel displays the variables of the current stack frame, along with their
values. There is a pop-up list from which you can select the stack frame whose variables
you want to view. You can also switch the variables shown in the variable panel by
clicking a different stack frame in the stack panel if it is open as well. This does not
change the order of execution of program statements, but only the information that is
displayed in the debug console.
A feature of the debugger is that when the form is suspended you can change the variable
values by clicking into the value column and entering a new value. When the program
continues, it will use the new value that you have entered, so that you can test the affect of
changing a value on the final result.
Some variables, such as parameters, cannot be modified. When you click into a read-only
variable, the entire cell is highlighted. Clicking into a modifiable variable will highlight
only the value, not the entire cell.

Oracle9i Forms Developer: New Features 5-9


The Debug Console

Stack
Variables
Watch
Form Values
Loaded PL/SQL
Packages
Global and
System Variables
Breakpoints

5-10 Copyright Oracle Corporation, 2002. All rights reserved.

The Debug Console: Watch Panel


A running application might have dozens of variables that can be displayed in various
panels in the debug console, but there may be very few that you need to monitor. The
watch panel provides a central place where you can keep track of any valid variables you
specify. Only variables that resolve to a scalar value are valid. Stored package variables
are not valid.
After a variable is displayed in your watch list, when execution is next suspended at a
different location, the variable values in the list are updated as needed if they are available
in the current execution context. If a variable is not defined in the currently executing
subprogram, #### appears in the cell instead of a value.
To add a variable to the watch list, open the window where the variable is displayed.
Select the variable you wish to add to the Watch list. When the variable is highlighted,
right-click and choose Add to Watch from the pop-up menu.
To delete an item from the watch list, select it in the watch window, right-click, and
choose Remove from the pop-up menu. If you choose Remove All, you will clear the
entire watch list.

Oracle9i Forms Developer: New Features 5-10


The Debug Console

Stack
Variables
Watch
Form Values
Loaded PL/SQL
Packages
Global and
System Variables
Breakpoints

5-11 Copyright Oracle Corporation, 2002. All rights reserved.

Debug Console: Form Values Panel


You can use the form values panel to display the values of all items and parameters in
modules that are currently running. You switch between a view of items and a view of
parameters by clicking the corresponding tabs in the panel.
You can change the values of modifiable items to test the effects of such changes. If the
value is read-only, such as display item values, the entire cell is highlighted when you try
to edit it. If the value is modifiable, only the value in the cell is highlighted when you
select it.

Oracle9i Forms Developer: New Features 5-11


The Debug Console

Stack
Variables
Watch
Form Values
Loaded PL/SQL
Packages
Global and
System Variables
Breakpoints

5-12 Copyright Oracle Corporation, 2002. All rights reserved.

The Debug Console: PL/SQL Packages Panel


Use the PL/SQL Packages panel to browse and examine PL/SQL packages that have been
instantiated. Both package specification and package body global variables are listed. You
can view packages only while the run-time process is currently executing PL/SQL. You
can also select an option button to determine which packages are displayed: Client,
Server, or All.

Oracle9i Forms Developer: New Features 5-12


The Debug Console

Stack
Variables
Watch
Form Values
Loaded PL/SQL
Packages
Global and
System Variables
Breakpoints

5-13 Copyright Oracle Corporation, 2002. All rights reserved.

Debug Console: Global/System Variables Panel


Use the Global/System Variables panel to display the current system, global, and
command line variables and their values. You can switch among these types of variables
by clicking the corresponding tabs in the panel.
Command line variables and most system variables are read-only. The only modifiable
system variables are DATE_THRESHOLD, EFFECTIVE_DATE, MESSAGE_LEVEL, and
SUPPRESS_WORKING. You can modify global variables, and the new values will be
used subsequently by the running application.

Oracle9i Forms Developer: New Features 5-13


The Debug Console

Stack
Variables
Watch
Form Values
Loaded PL/SQL
Packages
Global and
System Variables
Breakpoints

5-14 Copyright Oracle Corporation, 2002. All rights reserved.

The Debug Console: Breakpoints Panel


The breakpoints panel consists of two tabs:
Breakpoints tab displays any breakpoints set in the code during the current Forms
Builder session, in order of breakpoint creation.
Display includes:
- Name of trigger or program unit
- Line number where breakpoint is set
- A check box to temporarily enable or disable the breakpoint
Enables navigation to source code where breakpoint is set:
- By double-clicking the breakpoint name
- By highlighting (single-clicking) it, then choosing View Source Code from the
pop-up menu (right-click in Windows). From this pop-up menu, you can also
remove the breakpoint or remove all breakpoints.

Oracle9i Forms Developer: New Features 5-14


The Debug Console

Stack
Variables
Watch
Form Values
Loaded PL/SQL
Packages
Global and
System Variables
Breakpoints

5-15 Copyright Oracle Corporation, 2002. All rights reserved.

The Debug Console: Breakpoints Window


The Break On Exceptions tab displays a list of frequently used system exceptions
that you can use during debugging. The display includes:
- Exception name
- Associated ORA- error number
- Check box in which you set or unset the breakpoint
Instructor Note
Bug 2514146 describes a problem with setting Break on Exception in the initial version of
Oracle9i Forms. Do not attempt to demo this feature, or you may cause the debugger to
hang. If this happens, you will need to shut down and restart Forms Builder in order to use
the debugger again.

Oracle9i Forms Developer: New Features 5-15


Running a Form in Debug Mode

Run Form (Compiles automatically)


Debug

Contains source
code and .FMX (Runs automatically)
executable run file

Runs Form in
Debug Mode on
Server specified
in Runtime
Preferences

5-16 Copyright Oracle Corporation, 2002. All rights reserved.

Running a Form in Debug Mode


The Run Form Debug button in Forms Builder runs the form in debug mode. When a
breakpoint is encountered and control passes to the Debugger in Forms Builder, you can
use the debug commands to resume execution or step through the code in a variety of
ways to see how each line affects the application and the environment, as you will see
shortly.
As when you run a form from Forms Builder with the Run Form button, the Run Form
Debug button runs the form in a three-tier environment. It takes its settings from the
Preferences window that you access by choosing Edit > Preferences from the main menu
and clicking the Runtime tab.
You enter the URL for the application server that you want to run the form, which runs in
your default browser unless you specify a different browser in the Web Browser Location
text box. You can use a named configuration, if desired, with the config parameter.
Example of Application Server URL:
http://mymachine:8888/forms90/f90servlet?config=test
where test is a named section in the Forms Web configuration file (formsweb.cfg by
default) that specifies settings to use.

Oracle9i Forms Developer: New Features 5-16


Stepping through Code

Step over Pause

Stop

Step Step
into out

GO

5-17 Copyright Oracle Corporation, 2002. All rights reserved.

Stepping through Code


After the program encounters a breakpoint, the PL/SQL Debugger enables you to step
through program units in various ways in order to examine the environment as the
program progresses, using the following buttons:
Step Into: Execute the next statement
Step Over: Execute the next statement without stepping into a nested subprogram
Step Out: Complete nested subprogram and step to the next executable statement in
the calling program
Go: Resume execution until the program terminates normally or is interrupted by
the next breakpoint
Pause: Pauses execution of running PL/SQL code to enable you to examine the
environment. For example, you could check variable values. You can use the Pause
button to bring up the debugger at any time.
Stop: Terminates debugging and program execution completely. The Debug
Console and any opened debug panels close and application execution terminates.
Another command, available from the Debug menu, is Run to Cursor. When you select a
line of code in the PL/SQL Editor, the Run to Cursor command executes all code up to
that line, then stops and marks that line as the next executable line of code.

Oracle9i Forms Developer: New Features 5-17


Debugging a Forms Module

Debug Example

WHEN-BUTTON- The results are: ??


PRESSED
calls...
1 5

Procedure XYZ;

2 4
Function ABC; 3

5-18 Copyright Oracle Corporation, 2002. All rights reserved.

Debugging a Forms Module


Example
This example demonstrates some of the basic features available in the debugger. The
example form consists of a single button with trigger code for the When-Button-Pressed
event. The code works as follows:
1. The trigger calls the XYZ procedure, passing it a value for the xyz_param input
parameter.
2. The XYZ procedure calls the ABC function passing it a value for the abc_param
input parameter.
PROCEDURE xyz(xyz_param IN NUMBER) IS
v_results NUMBER;
BEGIN
v_results := ABC(10);
v_results := v_results + xyz_param;
MESSAGE(The results are: || TO_CHAR(v_results));
END xyz;

Oracle9i Forms Developer: New Features 5-18


Debugging a Forms Module (continued)

3. The ABC function multiplies two variables and adds the result to the abc_param
input parameter.
4. The ABC function returns the result to the XYZ procedure.
5. The XYZ procedure adds the result to the xyz_param and displays it in the
console at the bottom of the form window.
FUNCTION abc (abc_param IN NUMBER) RETURN NUMBER IS
v_total NUMBER := 0;
v_num3 NUMBER := 3;
v_num6 NUMBER := 8;
/*-- wrong value should be 6 */
BEGIN
v_total := v_num3 * v_num6;
v_total := v_total + abc_param;
RETURN v_total;
END abc;
Note: In previous versions of Forms, you could change PL/SQL code on the fly in the
debugger. However, now that the debugger is integrated into Forms Builder, and the form
itself is running in a three-tier environment, this is no longer possible.
Instructor Note
Demonstration
Open the form DebugDemo.fmb in Forms Builder to show the students how to use the
debugger. Instructions for this demo are in DebugDemo.txt.
If a more complex demo is desired, open and run EMPLOYEES.fmb:
The various buttons in this form enable you to demonstrate the Package and Break
on Exceptions windows.
The Cause Exception button in the form causes a 1422 exception, so select that as
the exception on which to break.
The code error in the form is that the Update Salary button does not seem to change
the salary. Set a breakpoint in the When-Button-Pressed trigger for that button. The
actual error occurs in the sal.get_sal package procedure, which is called by the
When-Button-Pressed trigger of the Update Salary button. The lines:
IF p_action = UPDATE THEN
v_new_sal := p_old_sal;
END IF;
should be corrected to:
IF p_action = UPDATE THEN
v_new_sal := p_old_sal + v_new_sal;
END IF;

Oracle9i Forms Developer: New Features 5-19


Remotely Debugging a Running Form

I need help with


the Orders form.

Click Remote Debug


and tell me what it says.

OK, Ill use that host


Application Application
and port to attach to
user your process. developer

5-20 Copyright Oracle Corporation, 2002. All rights reserved.

Remote Debugging
Oracle9i Forms enables the application developer to debug an application that is running
remotely within the Intranet. The application that is being debugged makes a call to the
built-in procedure Debug.Attach. This pops up a dialog containing machine and port
information, which the developer can then use from Forms Builder to attach to the
problem session in order to debug it. A direct socket connection is needed, so remote
debugging is usually not possible over the Internet unless the firewall allows a direct
socket connection.
This ability provides developers with a great head start in resolving problems. Rather than
having to obtain a list of instructions from an end user on how to reproduce the problem,
they can watch the problem happen as the user carries out the actions. If you want to
enable remote debugging, consider adding a hook into Debug.Attach within all your
application screens for activation by the user as required.
In the example illustrated above, the application developer has created a button that calls
Debug.Attach. With such a button or menu option, the user can find out the host and
port to convey that information to the developer who is debugging the problem.

Oracle9i Forms Developer: New Features 5-20


Remotely Debugging a Running Form
Debug

Attach Debug
Attach Debug to

pgamer-wah OK, Ive attached to


1784
your process and Ive
opened the Orders form.
What is the problem?

When I press the


Exit button,
nothing happens.

All right, Ive set a break-


point in the code. Now
press the Exit button.

5-21 Copyright Oracle Corporation, 2002. All rights reserved.

Remote Debugging (continued)


With information about the host and port of the running application, the developer can
attach to that process by invoking the Debug > Attach menu option in Forms Builder. This
invokes a window in which to enter the host and port information.
After it is successfully attached, the developer can open the .fmb file from which the
running .fmx was generated and set any breakpoints in the code that will assist in
debugging the problem described by the user.
In the example illustrated above, the user describes a non-functioning Exit button. The
developer opens the When-Button-Pressed trigger for that button and sets a breakpoint in
the first line of code, then instructs the user to click Exit to invoke the code.

Oracle9i Forms Developer: New Features 5-21


Remotely Debugging a Running Form
What the user sees: What the developer sees:

Help! My form
just disappeared!

Thats OK I've got


control of it now, and
I'm going to step
through the code to
find out what's wrong.

5-22 Copyright Oracle Corporation, 2002. All rights reserved.

Remote Debugging (continued)


When the process encounters a breakpoint in the code, control passes to the debugger.
This can cause confusion for the user because the browsers applet window blanks out,
just as it does when running in debug mode to test a form in Forms Builder.
The developer can view the Debug Console and its panels and step through the code as
needed to debug the problem. The developer does not see the running application. If user
interaction is needed (such as responding to an alert), the form reappears in the client
browser and the user regains control until the response is given, at which point control
passes back to the debugger.

Oracle9i Forms Developer: New Features 5-22


Practice 5a Overview

This practice covers the following topics:


Running a form in debug mode from within Forms
Builder
Setting breakpoints
Viewing information about the running form in the
Debug Console panes
Stepping through code
Remotely debugging an application

5-23 Copyright Oracle Corporation, 2002. All rights reserved.

Practice 5a Overview
In this practice, you run a form in debug mode and set a breakpoint. You examine various
aspects of the running form using the panes of the Debug Console, and you step through
the code to discover the coding error. Finally, you remotely debug an application that is
running on another machine.

Oracle9i Forms Developer: New Features 5-23


Practice 5a
1. Open the Customers form. In this form, there is a procedure that is called
List_Of_Values, which is called by the When-Button-Pressed trigger of
CONTROL.Account_Mgr_LOV_Button. Modify this trigger to misspell the
parameter that passes the LOV name, changing the parameter name to
ACCOUNT_MGR_LO.

2. Click Run Form to run the Customer form. Select the Account Information tab.
Click the LOV button that is to the right of the Account Manager ID. Notice that the
LOV does not display, and you receive a message that You have just cancelled the
List of Values. Exit the run-time form and close the browser window.

3. Click Run Form Debug to run the form in debug mode. In Forms Builder, set a
breakpoint in your When-Button-Pressed trigger for the
CONTROL.Account_Mgr_LOV_Button. In the running form, click the Account
Manager LOV button to invoke the debugger. Investigate the call stack. Try
stepping through the code to monitor its progress. Look at the Variables panel to see
the value of the parameters you passed to the procedure, and the value of the p_lov
variable in the procedure. How would this information help you to figure out where
the code was in error?

4. Add a button to the Control block of the Orders form. Place the button on the
CV_Order canvas. Set properties as follows (note that the Icon Filename property is
case sensitive):
Property Value
Name Check_Total_Button
Iconic Yes
Icon Filename check
Keyboard Navigable No
Mouse Navigate No
X Position 295
Y Position 220
Height 17
Width 17

The function of this button is to recheck the Order Total. Write a When-Button-
Pressed Trigger to loop through the records in the Order_Items block and
accumulate the calculated total (price * quantity) in a numeric variable. You should
intentionally make an error when initializing this variable (the intent is to initialize it
to zero, but you type 9 "by mistake").

Oracle9i Forms Developer: New Features 5-24


Practice 5a (continued)
You can import the code for the trigger from pr5a_4.pls in your solutions
directory.

Run the form, click the Check_Total_Button, and notice that the results are off by
$9.00 when compared with the calculated item labeled Order Total.

5. Set a breakpoint at the variable declaration of the When-Button-Pressed trigger for


Control.Check_Total_Button.

Run the form in Debug mode and click the button. When the Debug Console is
invoked, Look at the variable value in the Variables panel of the Debug Console.

As soon as the variable is initialized at 9, change the value of the variable to zero in
the Variables panel of the Debug Console before stepping into subsequent code.

The code should use the corrected value and the correct result should be displayed
on the message line. This indicates that the variable initialization is what should be
corrected in the code.

Stop the debug session. Correct the code and run the form normally to test.

6. Sales representative Janette King is using a query form to find out what
commissions she has earned. She calls the Help Desk because the form is under
calculating her commissions. Pair up with someone using another PC. Designate one
PC as the Help Desk PC and the other as Janettes PC. Perform the following:
Janettes PC:
A. Run the query form using the Help Desk PC as the middle tier. In your
browser, enter the URL:
http://<machine>:<port>/forms90/f90servlet?form=
e:\labs\debug_practice\practice6a_6.fmx&userid= <connect
string>
where <machine> and <port> are the machine and OC4J port of the Help
Desk PC, and <connect string> is your own connect string.
B. When the form displays, click Calculate Commission. The commission for the
displayed employee calculates correctly.
C. Press [Down Arrow] until the employee Janette King is displayed. Click
Calculate Commission. The commission is calculated incorrectly.
D. Scroll down and click Debug. The host and port to which the Help Desk must
attach is displayed.

Oracle9i Forms Developer: New Features 5-25


Practice 5a Overview (continued)
Help Desk PC:
A. In Forms Builder, open the form:
e:\labs\debug_practice\practice6a_6.fmb.
B. From the menu, select Debug > Attach Debug. The Attach Debug dialog
displays
C. Enter the Host and Port information that is displayed on the User PC.
D. Set a breakpoint on the When-Button-Pressed trigger for the Calc_Comm
button. Set the breakpoint on the first line after the BEGIN statement.
Janettes PC:
A. Click OK to dismiss the display of Host and Port information.
B. Recalculate Janette Kings commission by pressing Calculate Commission.
The execution of your form is suspended while control passes to the debugger.
The applet may go blank at this point.
Help Desk PC:
A. The Debug Console displays. Open the PL/SQL Packages and the Form
Values panels. Expand the Employees block in the Form Values panel so that
you can see the value of items in the Employees block.
B. Click Step Into to step into the code until you execute the line:
:orders.commission := :comm.get_comm;
This steps into the Comm package to execute the Get_Comm function.
C. Look at the PL/SQL Packages panel to take note of the value of the package
variable vn_emp_comm, which will be used in the calculation. Note that it is
still set to the value of the commission of the employee displayed when the
button was first pressed.
D. Click Go to execute the rest of the code.
E. In the PL/SQL Packages panel, change the value of the package variable
vn_emp_comm to the value of the current employees commission percent:
.35.
Janettes PC: Click Calculate Commission again.
Help Desk PC:
A. Click Go to execute all the code. The correct commission should now display
on Janettes PC.
B. Click Stop to end the debugging session.
C. The problem with the form is that the PL/SQL package variable
vn_emp_comm is set when the package is first instantiated. This variable was
set to the commission percent for the employee displayed the very first time
Janette clicked Calculate Commission. In order for the value to change with
each execution of the package, the variable should be set in the package body,
not the package specification.

Oracle9i Forms Developer: New Features 5-26


Practice 5a Overview (continued)
D. Open the PL/SQL Editor for the package specification and change the variable
declaration for vn_emp_comm to initialize the value to 0.
E. Open package body and add the following line right after the BEGIN
statement:
vn_emp_comm := :employees.commission_pct;
F. Generate the form by pressing [Ctrl-T].
Janettes PC:
A. Edit the URL in the browser to delete &debug and the host and port
information at the end of the URL. Run the form again by pressing Enter.
B. Test that the problem has been fixed by pressing Calculate Commission for the
first employee that displays, and again for Janette King. Verify that Janettes
commission is now calculated correctly.

Oracle9i Forms Developer: New Features 5-27


Tracing and Logging Tools

Tools available for tracing and logging:


Forms Trace
Servlet Logging

5-28 Copyright Oracle Corporation, 2002. All rights reserved.

Tracing and Logging Tools


The following tools are available to collect trace information for Oracle9i Forms:
Forms Trace: Enables you to trace the execution path through a form
Servlet Logging Tools: Enables site administrators to keep a record of all Oracle9i
Forms sessions, monitor Forms-related network traffic, and debug site configuration
problems.
The new Forms Trace feature in Oracle9i Forms replaces Forms Runtime Diagnostics
(FRD) and Performance Event Collection System (PECS), which were available in
Forms6i.
Servlet logging tools enable you to monitor Forms sessions, network traffic, and
performance, and also provide information for debugging site configuration problems.
Instructor Note
As documented in the Release Notes, Oracle Trace has been desupported for Oracle9i
Forms (2296258). If you specify record=otrace, the Form will fail to start. This issue will
be resolved in the next patch set to Oracle9i Forms.

Oracle9i Forms Developer: New Features 5-28


Using Forms Trace

To use Forms Trace, you must understand the


following topics:
Configuring Forms Trace
Starting the trace
Traceable events
Event details
Viewing Forms Trace output

5-29 Copyright Oracle Corporation, 2002. All rights reserved.

Using Forms Trace


Forms Trace provides a framework that enables you to record information about a
precisely defined part of forms functionality or a class of user actions. This is
accomplished by specifying the events for which you want to collect trace information.
An event is something that happens inside Oracle9i Forms as a direct or indirect result of
a user action. For example, you can record information about trigger execution, mouse-
clicks, or both.
The Forms Trace interface enables a great degree of user control, and the output is easy to
read and understand. To use Forms Trace, you need to know:
How to configure Forms Trace
How to start a trace
What events are traceable
What details are obtainable about events
How to view trace output

Oracle9i Forms Developer: New Features 5-29


Configuring Forms Trace

# example ftrace.cfg file ftrace.cfg


# This file is used to specify event groups
# for use with Forms Trace
# *******************************************
debug: 0-199
errors: 0-3
custom1: 32-46,65,66,96,194

default.env

5-30 Copyright Oracle Corporation, 2002. All rights reserved.

Configuring Forms Trace


The following two files are involved in configuring Forms Trace:
ftrace.cfg: An event set defines a set of events that you can trace by specifying
the event set name rather than each event number individually when you start the
trace. You can define named sets of events in the ftrace.cfg file, located by
default in the forms90/trace directory of your iDS installation.
Note that there must be a blank line between keyword (event set name) entries and a
comma between each event number or range of numbers. Keywords can be any
name as long as they do not contain spaces. For example, a_b_c is an acceptable
keyword.
default.env: The FORMS90_TRACE_PATH environment variable specifies the
location of trace output files. This variable is set in the environment configuration
file, (<ORACLE_HOME>\forms90\server\default.env unless otherwise
specified). There is a stub entry in the file; uncomment the entry and change it to a
valid path. Example: FORMS90_TRACE_PATH=c:\formsdata\tracefiles
If you do not set this variable, the trace files are written by default to the current
working directory.

Oracle9i Forms Developer: New Features 5-30


Starting the Trace

Parameters:
Type of trace to perform
record=forms
tracegroup=
Types of events to trace
Individual event
Event set
Named event set
Combination
log=<filename>
What to call the log file

5-31 Copyright Oracle Corporation, 2002. All rights reserved.

Starting the Trace


You can specify parameters for tracing in the URL or in the formsweb.cfg file:
record=forms: Enables Forms Trace
tracegroup= Indicates which events should be recorded and logged. From the
example of the ftrace.cfg file on the previous slide, using tracegroup=custom1
is equivalent to tracegroup=32-46,65,66,96,194. You can use a combination, such as
tracegroup=1-5,7,custom1. If tracegroup is not specified, only error messages are
collected. Tracegroup is ignored if Forms Trace is not enabled with record=forms.
log=<filename> Specifies what to name the log file. If a directory is not
specified, the file is saved in the directory specified by the
FORMS90_TRACE_PATH environment variable or to the current working directory.
If a log file is not specified, the process id (pid) of the user process is used as the
name of the trace file, for example, forms_<pid>.trc.
Note: To prevent users from overwriting files on the application server, this
parameter must be defined in formsweb.cfg; if specified in the URL, it is
ignored.
A future version of Forms will include built-ins to start and stop the trace dynamically.

Oracle9i Forms Developer: New Features 5-31


Starting the Trace

In formsweb.cfg:

[mytrace]
otherparams=record=forms tracegroup=custom1 log=mytrace.trc

5-32 Copyright Oracle Corporation, 2002. All rights reserved.

Starting the Trace (continued)


When you specify parameters for tracing in the formsweb.cfg file, you define them as
part of the otherparams parameter. Under a named configuration, include the
following all on one line:
otherparams=record=forms tracegroup=<events> log=<filename>.trc
You then start the form with the config parameter set to the named configuration, as
shown in the example in the slide.
It is intended that future version of Forms will merge ftrace.cfg into
formsweb.cfg.

Oracle9i Forms Developer: New Features 5-32


Traceable Events

Event types:
Lets see I want to
trace information Point event
about triggers.. Duration event
Built-in event

&tracegroup=66

5-33 Copyright Oracle Corporation, 2002. All rights reserved.

Traceable Events
With Forms Trace you can collect information about certain events without the need to
trace every Forms action. This enables you to see only the specific information that is of
interest to you. In future versions of Forms, it is planned that you will be able to define
your own custom events.
Event types are as follows:
Point event: An event that is the result of a user action or internal signal for which
there is no discernible duration, such as displaying an error message on the status
line; creates one entry in the log file
Duration event: An event with a start and end, such as a trigger; creates a pair of
entries in the log file for the start and end event
Built-in event: An event associated with a built-in; creates varied information about
the event, such as argument values
In the example, the developer is having a problem with triggers in a form. It would help to
find out the order in which triggers are firing. The developer could turn on Debug
Messages, which would display a message each time a trigger fires, but this would be
disruptive to the tester of the form. Instead, the developer instructs the tester to use the
following parameters in the URL: record=form&tracegroup=66 (trigger events).

Oracle9i Forms Developer: New Features 5-33


Traceable Events (continued)
Traceable events are as follows:

Event Definition Type


Number
0 Abnormal Error Point
1 Error during open form Point
2 Forms died error Point
3 Error messages on the status bar Point
4-31 Reserved for more error events to be defined
32 Forms startup Point
33 Menu Point
34 Key Point
35 Click Point
36 Double-click Point
37 Value Point
38 Scroll Point
39 LOV Selection Point
40 Not used
41 Window Close Point
42 Window Activate Point
43 Window Deactivate Point
44 Window Resize Point
45 Tab Page Point
46 Timer Point
47-48 Reserved for future use for asynchronous events
49-63 Reserved for more Actions to be defined
64 Form (Start and End) Duration
65 Procedure (Start and End) Duration
66 Trigger (Start and End) Duration
67 LOV (Start and End) Duration
68 Opening an Editor Point
69 Canvas Point
70 Alert Duration
71 GetFile Point
72-95 Reserved for more Events to be defined
96 Builtin (Start and End) Builtin
97 User Exit (Start and End) Duration
98 SQL (Start and End) Duration

Oracle9i Forms Developer: New Features 5-34


Traceable Events (continued)

Event Number Definition Type


99 MenuCreate (Start and End) Duration
100 PLSQL (Start and End) Duration
101 Execute Query Duration
102-127 Reserved for more Events to be defined
128 Client Connect Point
129 Client Handshake Point
130 Heartbeat Point
131 HTTP Reconnect Point
132 Socket (Start and End) Duration
133 HTTP (Start and End) Duration
134 SSL (Start and End) Duration
135 DB Processing (Start and End) Duration
136 DB Logon (Start and End) Duration
137 DB Logoff (Start and End) Duration
138-191 Reserved for more Events to be defined
192* Environment Dump n/a
193* State Delta
194* Builtin Arguments
195* UserExit Arguments
196* Procedure Arguments
197* Function Arguments
256 and higher User defined
1024 and higher Reserved for internal use

* These event numbers do not have a TYPE because they are not really events, but rather
details for events. For example, the State Delta is something you can choose to see, but it
is triggered by a real action or event.
Note: Event 132 (Socket start and end) is effectively desupported, because socket mode is
no longer used for connection. The Forms Listener Servlet communicates using HTTP or
HTTPS.

Oracle9i Forms Developer: New Features 5-35


Obtaining Event Details

Details are recorded about events.


Details vary depending on the event.

What information
will Forms Trace
give me about
triggers?
mylog.trc
TriggerName
BlockName
ItemName
FormID

5-36 Copyright Oracle Corporation, 2002. All rights reserved.

Obtaining Event Details


Forms Trace log files provide details about Events that vary according to the event:
Errors: Error type and a detailed message describing the error.
User Actions:

Action Details Number


Menu Selection Menu Name, Selection 33
Key Key Pressed, Form, Block, Item 34
Click Mouse/Key, Form, Block, Item 35
Double-click Form, Block, Item 36
Value Form, Block, Item 37
Scroll Form, Up, Down, Page, Row 38
LOV Selection LOV Name, Selection Item 39
Alert Alert Name, Selection 40
Tab Form 45
Window Activate, Window Name, Form Name, Size 41, 42, 43,
Deactivate, Close, Resize 44

Oracle9i Forms Developer: New Features 5-36


Obtaining Event Details (continued)

Forms Server Events:

E vent N ame D etails N umber


Form Form ID , N am e, Path, Attached 64
Libraries, Attached M enus
Procedure Procedure N am e, Form ID 65
T rigger Trigger N am e, Block N am e, Item 66
N am e, Form ID (Form N am e w ill be
included in a later enhancem ent)
LO V LO V nam e, Form ID 67
E ditor Form ID , E ditor N am e 68
C anvas Form ID , C anvas N am e 69
Detailed Events:

Event Name Details Number


Builtin Builtin Name, Form ID 96
User Exit User Exit Name, Form ID 97
Menu Create Menu Name, Form ID 99
PLSQL PLSQL Statement, Form ID 100
ExecQuery Block Name 101

Three-Tier Events:

Event Name Details Number


Client Connect, Client Timestamp 128, 129, 130
Handshake, Heartbeat
HTTP Reconnect 131
Socket, HTTP, HTTPS Form ID, Packets, Bytes 132, 133, 134
DB Processing Form ID, Statement 135
DB Logon, DB Logoff Form ID 136, 137
Miscellaneous:

Event Name Details Number


Environment Dump Selected environment information 192
State Delta Changes to internal state caused by the 193
last action/event
Builtin Args Argument values passed to a builtin 194
User Exit Args Argument values passed to a user exit 195
Procedure Args Arguments (in/out) passed to a 196
procedure
Function Args Arguments (in/out) passed to a function 197

Oracle9i Forms Developer: New Features 5-37


Viewing Forms Trace Output

Set CLASSPATH

Xlate Version 1.0


Run Translate utility
Usage:
Xlate DataFile=filename XMLFile=filename URL=host:port:sid
UserName=user_id Password=user_pwd CollectionID=collection_id
Regression=true|false

DataFile -
binary file produced by Forms server
XMLFile -
XML output file name
URL -
database URL e.g. mymachine:1521:my_sid
UserName -
user name to access database
Password -
password to access database
-
You must specify URL, UserName and Password
to upload to database
CollectionID - user supplied id uniquely identifying the
collection after uploading to database
Regression - boolean controlling inclusion of time stamps in output
- if true (i.e. output will be used for regression testing)
then time stamps are not included in output

5-38 Copyright Oracle Corporation, 2002. All rights reserved.

Viewing Forms Trace Output


To reduce the size of the trace file and to increase performance while tracing, the data is
stored in a binary file. This file is not readable, but must be processed in order to extract
the information. There is a Java utility called Xlate that can either upload the data to the
database (you must first create tables to contain it) or translate the file to XML, the
preferred method unless you have a need to develop customized reports.
Setting the CLASSPATH
This utility is contained in forms90\java\f90xlate.jar, so you must set your
CLASSPATH to include that JAR file. You need some JDBC classes as well. You can use
the following command to set your CLASSPATH prior to running the Xlate utility:
set CLASSPATH=<iDS_HOME>\forms90\java\f90xlate.jar;
<iDS_HOME>\jdbc\lib\classes12.jar;%CLASSPATH%
If you run the command for Xlate with no arguments, its usage will be displayed as above.
Creating the Tables
The script frmtrc.sql, located in <IDS_HOME>\tools\dbtab90\forms90, creates
database tables to contain the data that you upload using the Xlate utility. If you decide to
upload the data to the database, you must create these tables first.

Oracle9i Forms Developer: New Features 5-38


Viewing Forms Trace Output (continued)
Writing the Qutput of Forms Trace to the Database:
java oracle.forms.diagnostics.Xlate datafile=<filename>.trc
URL=machine.domain:port:SID username=<user>
password=<password> collectionid=<n>
Example:
java oracle.forms.diagnostics.Xlate datafile=forms_499.trc
URL=pgamer-wah.us.oracle.com:1521:iasdb username=ora1
password=oracle collectionid=2
Writing the output of Forms Trace to XML:
java oracle.forms.diagnostics.Xlate datafile=<filename>.trc
xmlfile=<filename>.xml
Example:
java oracle.forms.diagnostics.Xlate datafile=forms_499.trc
xmlfile=trace_triggers.xml
Note: You will not find it useful to write output to database tables unless you create
customized reports to interpret the data. If you need to create such reports, you will find
the structure of the Forms Trace tables documented in Oracle9iAS Forms Services
Deployment Guide Release 9.0.2, Part Number A92175-01. It is simpler, and therefore the
preferred method, to write the output to XML.

Oracle9i Forms Developer: New Features 5-39


Viewing Forms Trace Output

Use other tools, such as Oracle9iDS Reports, to


produce meaningful output.
Future plans include a sample XSL file and sample
reports.

Oracle9iDS
Reports

5-40 Copyright Oracle Corporation, 2002. All rights reserved.

Viewing Forms Trace Output (continued)


After you have translated the trace file into either XML or database records, you can use
other tools, such as Oracle9iDS Reports, to display meaningful data about the running
application. Plans for future enhancements for the Forms Trace tool include:
A sample XSL file to use as a template
Sample Oracle9iDS reports
These enhancements will appear on OTN and will be included in future patch sets.
Instructor Note
Explain to students that the Forms Trace utility is a new tool that is still under
development.

Oracle9i Forms Developer: New Features 5-40


Servlet Logging

To turn on logging for Forms


Four levels: Listener Servlet, add to
serverURL parameter:
Session /session
Session-performance /sessionperf
Request-performance /perf
Debug /debug

You can also perform debug level logging for Forms Servlet:
http://<machine>:<port>/forms90/f90servlet/debug?config=summit

5-41 Copyright Oracle Corporation, 2002. All rights reserved.

Servlet Logging
Because Oracle9iAS Forms Services deployment uses the Forms Listener Servlet, you can
obtain performance and other information using servlet logging. The servlet logging tool
available with Oracle9iAS Forms Services provides the following:
A record of all Forms sessions, including session start and end times, the user's IP
address, and host name (session-level logging)
Monitoring of Forms-related network traffic and performance (session-performance
and request-performance-level logging)
Verbose information for debugging site configuration problems (debug-level
logging)

Oracle9i Forms Developer: New Features 5-41


Servlet Logging (continued)
You can turn on logging by appending a string from the following table to the serverURL
parameter, either in formsweb.cfg or in the URL that starts the form.

String Description of Logging


(none) No log messages are produced, but during Forms Servlet initialization,
logs the name and path of the configuration file being used
/session When a Forms session starts or ends, logs host name, client IP address,
runtime process ID, and a unique internal session ID number
/sessionperf Includes performance summary statistics with the session end message
/perf Writes a performance message for every request from the client
/debug Full debug messages; very verbose and intended mainly for debugging
and support purposes

Examples:
To start a performance-level trace using a parameter in the URL:
http://machine:port/forms90/f90servlet
?serverURL=/forms90/l90servlet/perf

To start session-level logging for all users, you would change the serverURL entry in the
default section of the formsweb.cfg file to the following:
serverURL=/forms90/l90servlet/session
Note: You can also perform debug level logging on the Forms Servlet, rather than the
Forms Listener Servlet, simply by appending /debug to the URL used to start the
application.
Example:
http://machine:port/forms90/f90servlet/debug?form=orders
In addition to recording information in the application log file, the same information is
displayed in the DOS window where OC4J was started.
Instructor Note
Demonstration:
You can show students some results of Forms Servlet logging and Forms Listener Servlet
logging by opening the application.log file that is in your demo directory. This
shows information logged when no servlet logging is specified, as well as session,
perf, and debug level logging for both the Forms Servlet and the Forms Listener
Servlet. You can see that session and perf logging for the Forms Servlet do not
produce any more information than when logging was not performed, because these
logging levels are applicable only to the Forms Listener Servlet.

Oracle9i Forms Developer: New Features 5-42


Viewing the Log

Log file name: application.log


Log file location:
For iDS:
<iDS_HOME>\j2ee\Oracle9iDS\
application-deployments\forms
For iAS:
<iAS_HOME/j2ee/<Product Group>/
application-deployments/forms90app

5-43 Copyright Oracle Corporation, 2002. All rights reserved.

Viewing the Log


The servlet log file, called application.log is located in the Forms deployment
directory for OC4J:
For iDS (on NT; you must shut down the OC4J instance to view this log file):
<iDS_HOME>\j2ee\Oracle9iDS\application-deployments\forms
Example:
d:\oracle\iDSv2\j2ee\Oracle9iDS\application-
deployments\forms.
For iAS (on UNIX):
<iDS_HOME>/j2ee/<Product Group>/application-deployments/
forms90app
Example:
/oracle/ias902/j2ee/OC4J_BI_Forms/application-
deployments/
forms90app

Oracle9i Forms Developer: New Features 5-43


Viewing the Log (continued)
Example: What follows is a portion of an application.log, with some of the repetitive
information deleted. The actions shown are:
5:50 AM: Started an OC4J instance, which started servlet logging
7:24 AM: Ran a form, which initialized the Forms Servlet and the Forms Listener
Servlet
9:01 AM: Ran a form with performance-level logging, then exited the form and shut
down the browser
9:06 AM: Shut down the OC4J instance
6/12/02 5:50 AM Started
6/12/02 7:24 AM forms90web: oracle.jsp.runtimev2.JspServlet: init
6/12/02 7:24 AM forms90web: 9.0.2.0.0 Started
6/12/02 7:24 AM forms90web: oracle.forms.servlet.FormsServlet:
init
6/12/02 7:24 AM forms90web: FormsServlet init():
configFileName: d:\oracle\iDSv2/forms90/server/formsweb.cfg
testMode: false
6/12/02 7:25 AM forms90web: oracle.forms.servlet.ListenerServlet:
init
6/12/02 7:25 AM forms90web: ListenerServlet init()
6/12/02 9:01 AM forms90web: Forms session <4> started for pgamer-
wah ( 141.144.1.60 )
6/12/02 9:01 AM forms90web: Forms session <4> runtime process id
= 373
6/12/02 9:01 AM forms90web: Forms session <4>: request processed
in 0.010 sec. Received 8 bytes, returned 8 bytes.
.... (Several lines similar to the above)
6/12/02 9:01 AM forms90web: Forms session <4> ended Total
duration of network exchanges: 4.807 Total number of network
exchanges: 22 (1 "long" ones over 1.000 sec) Average time for one
network exchange (excluding long ones): 0.062 Total bytes: sent
16,335, received 698
6/12/02 9:06 AM forms90web: oracle.forms.servlet.ListenerServlet:
destroy
6/12/02 9:06 AM forms90web: oracle.forms.servlet.FormsServlet:
destroy
6/12/02 9:06 AM forms90web: 9.0.2.0.0 Stopped
6/12/02 9:06 AM Stopped (Shutdown executed by jazn.com/admin from
127.0.0.1 (localhost))

Oracle9i Forms Developer: New Features 5-44


Summary

In this lesson, you should have learned that:


The Forms Debugger is integrated into Forms
Builder, and includes:
A Debug Console with several panes to view
aspects of the running form
A Toolbar and menu items
You can run a form in debug mode from Forms
Builder with the Run Form Debug button.
You can set breakpoints, step through code, and
see the effects of each line of code if needed.

5-45 Copyright Oracle Corporation, 2002. All rights reserved.

Summary
The Oracle9i Forms Builder has an integrated debugger that enables you to set
breakpoints in any PL/SQL code and view various aspects of the running form in the
Debug Console. You can use the Run Form Debug button to run a form in debug mode,
and you can step through the code in a variety of ways.

Oracle9i Forms Developer: New Features 5-45


Summary

You can attach to a form running remotely on the


Intranet in order to debug it:
Call Debug.Attach from the running form to get
host and port information.
In Forms Builder, use the Debug menu to attach to
the host and port.
Debug as usual.

5-46 Copyright Oracle Corporation, 2002. All rights reserved.

Summary (continued)
With the Oracle9i Forms debugger, you can perform remote debugging within the Intranet
if you provide a way for the user running the application to call Debug.Attach from
the running form. This displays host and port information to which the developer can
attach from within Forms Builder. The developer can load the module and set
breakpoints; when a breakpoint is encountered in the running form, control switches to the
developers Forms Builder session. All the functionality of the debugger is then available
to troubleshoot the application.

Oracle9i Forms Developer: New Features 5-46


Summary

You can use Forms Trace to create a log of


specific Forms events.
The Xlate utility translates the Forms Trace file
into XML or database records that you can use
with other tools to produce meaningful output.
You can use four different levels of Servlet logging
to obtain session, network, performance, and
debug information.

5-47 Copyright Oracle Corporation, 2002. All rights reserved.

Summary (continued)
Forms Trace is a new tool in Oracle9i Forms that enables you to create a log that contains
information about the events you specify. The trace file is not readable, but you can
translate it into XML. You can even save the information to the database in order to create
custom reports.
Servlet logging is another tool to help troubleshoot your applications. You can log
information about the session, the network, or performance, or you can record verbose
debug information. This can be done on a per-user basis, or for all users of the application.
The new debugging, tracing, and logging tools in Oracle9i Forms make it easier than ever
to troubleshoot your Forms applications.

Oracle9i Forms Developer: New Features 5-47


Practice 5b Overview

This practice covers the following topics:


Configuring Forms Trace
Logging specific user actions in a running form
Translating the trace file to XML
Using Servlet logging to record information about
Forms sessions

5-48 Copyright Oracle Corporation, 2002. All rights reserved.

Practice 5b Overview
In this practice, you configure Forms Trace and use it to record information about specific
events. You translate the trace file to XML to view information about triggers that fire and
tab pages that are accessed in a form. You then user Servlet logging to record information
about a Forms run-time session.

Oracle9i Forms Developer: New Features 5-48


Practice 5b
1. Configure Forms to enable Forms Trace:

a. Define an event set called info that will record information about triggers
and tab pages.

b. Set the logging path for Forms Trace to the directory where ftrace.cfg is
located.

2. Define a named configuration called info where you specify that a Forms Trace
should occur, using the info event set and logging the information to a file called
info.log.

3. In Forms Builder, set run-time preferences to use the named configuration.

4. In Forms Builder, open the Customers form and click Run Form to run it. Click the
tabs to display all the items in the running form. Exit the form run-time session and
close the browser.

5. Move the trace file to your lab directory and convert it into XML. You can run the
batch file SETCP_xlate.bat to set the CLASSPATH for the translate utility.

6. Examine the XML file to see the triggers that executed and the tab pages that you
clicked in the running form.

7. From Forms Builder, enable Servlet session logging. Click Run Form to run the
Customers form. Shut down OC4J and examine the Servlet log to see what
information is recorded with session logging.

8. To disable Servlet logging, set your preferences back to default. Restart OC4J.

Oracle9i Forms Developer: New Features 5-49


Oracle9i Forms Developer: New Features 5-50
Integrating Java into Forms Applications

Copyright Oracle Corporation, 2002. All rights reserved.

Schedule: Timing Topic


50 minutes Lecture
50 minutes Practice
100 minutes Total
Objectives

After completing this lesson, you should be able to do


the following:
List the methods for using Java in Forms
applications
Explain the significance of using JDK 1.3
Use the improved support for JavaBeans
Use Pluggable Java Components (PJCs)

6-2 Copyright Oracle Corporation, 2002. All rights reserved.

Lesson Aim
This lesson describes the enhanced support in Oracle9i Forms for integrating Java into
your applications.

Oracle9i Forms Developer: New Features 6-2


Using Java in Forms

Client: Middle Tier: Database:


JavaBeans, PJCs Java Importer Java Stored
Procedures

6-3 Copyright Oracle Corporation, 2002. All rights reserved.

Using Java in Forms


Beginning with Forms, release 6, you can extend the Forms client using JavaBeans and
Pluggable Java Components (PJCs):
JavaBeans enables you to easily extend and customize the functionality of a form by
embedding a Java component.
Pluggable Java Components (PJCs) enable you to change the function or appearance
of Forms items. PJCs make it possible to extend the standard Forms user interface
and provide a varied experience for application users. PJCs offer the additional
possibility of being able to perform client-side validation on an item, thus reducing
network traffic.
You can integrate Java code from the middle tier and from external Web services using
the Java Importer introduced in Forms6i. This tool automatically generates PL/SQL
packages and procedures that enable you to create and use Java objects directly in your
Forms applications. For more information about the Java Importer, see the white paper
The Oracle Forms Java Importer, available on OTN.
Forms can also make use of Java code stored in the database by calling a Java stored
procedure from within PL/SQL.

Oracle9i Forms Developer: New Features 6-3


Support for Java 1.3

Client Tier
Enables integration with 1.3 JavaBeans and PJCs
Simpler to integrate Forms and other Applets on
the same page
JInitiator based on 1.3 JDK
Middle Tier
The Java Importer supports use
of JDK 1.2.2 and above.
Enables you to integrate the
latest technologies
Separate JDK installation not needed

6-4 Copyright Oracle Corporation, 2002. All rights reserved.

Support for Java 1.3


Forms Java Client
In Forms9i, the Forms Java Client is upgraded to be able to use 1.3 of the Java Runtime
Environment (JRE). Developers who are writing Pluggable Java Components or
integrating the Forms Java Client with other Java applets or JavaBeans can now use the
full power of the 1.3 Java APIs. In Forms6i, developers were restricted to the 1.1 APIs. In
line with this change, the JInitiator for Forms9i is based on a 1.3 JRE.
Middle Tier
The Java Importer feature continues to be a key part of the Forms integration strategy. It
provides simple-to-use Java integration from PL/SQL. Again, the Java Importer can be
used with 1.3 of the Java Runtime, making it possible to integrate Forms applications with
the latest external programs and services. In Forms6i, you had to manually install JDK
1.2.2 before using the Java Importer. This separate installation and configuration is no
longer necessary in Oracle9i Forms.

Oracle9i Forms Developer: New Features 6-4


Using Client-Side Code

JavaBeans
Pluggable Java
Components
FBean Package

6-5 Copyright Oracle Corporation, 2002. All rights reserved.

Using Client-Side Code


When you migrate from client-server to the Web, code that formerly operated within the
client environment now executes on the application server. For example, a call to the
HOST built-in no longer executes on the client and may need to be rewritten to use
commands available on the application server platform. If such code includes user
interaction, you can no longer use it because the display is to the application server
machine, so it will not be seen by the client.
JavaBeans and Pluggable Java Components (PJCs) provide a method to execute code on
the client. These features were available in Forms6i, but with the necessity in Oracle9i
Forms to migrate applications to the Web, their use may be more frequent than ever.
There is a new package called FBEAN in Oracle9i Forms that enables you to integrate
JavaBeans more easily.
Where do you obtain these components? If you are a Java developer, you can write them
yourself. If not, JavaBeans and PJCs are commercially available from a variety of sources,
and you can download many components from OTN for free. OTN also provides viewlets
showing you how to use the components. To download samples from OTN, open
http://otn.oracle.com/sample_code/products/forms/content.html and
download the Oracle9i Forms Demos.

Oracle9i Forms Developer: New Features 6-5


Using Client-Side Code (continued)
The Oracle9i Forms Demos include the following JavaBean and PJC components:

Component Description
Spell Checking with Enables text items to utilize the JSpell package from
JSpell 2.0 WallstreetWise; the JSpell software is not supplied with the
Forms demo suite and must be purchased separately if required
File Upload Utility Displays a file selection dialog on the browser machine and
transfers the selected file up to the middle tier
Calendar Enables selection of a date from a calendar widget, without
generating network traffic to display a Forms based calendar
Progress Bar Displays a progress meter
Hyperlink Provides a UI widget that looks and acts like an HTML
hyperlink
Get Client Info Provides information about the client browser machine,
including the Hostname, the IP address, and local O/S
Username; can also obtain the value of any of the Java system
properties on the client
Clock Displays a simple digital clock
Rollover Button Provides an enhanced version of a standard Forms button that
reacts to the mouse hovering over it by changing the displayed
image
Key Filter Customizes a normal text item to prevent unwanted characters
from being entered; filters keystrokes without generating
network traffic to the Application server
Modify Cursor Adds a single custom property to a text item that defines the
name of the mouse cursor that should be shown when the mouse
moves over the field; occurs on the client without any network
round trips when the mouse enters a field
Color Picker Enables client to change color properties of Forms objects by
selecting from a color picker
Info Button Enhances a Forms button so that when the mouse hovers over it,
information displays in a Forms text item that exists at a certain
point on the screen; ideal for menus or interactive help screens
Multi Select T-List Enhanced version of the Forms TList control that allows
multiple selections
Insert Replace Text Enables insert/replace functionality on Forms text items
Fields

In addition to the Forms Demos, you can obtain information on OTN about replacing
Outlook OLE integration with Java Mail and automating Word and Excel from Java.

Oracle9i Forms Developer: New Features 6-6


What Are JavaBeans?

JavaBeans:
Are components written in Java
Conform to standards
Can be integrated into applications
The Bean Area item enables you to:
Add JavaBean to a form
Extend Forms functionality
Interact with client machine
Reduce network traffic

6-7 Copyright Oracle Corporation, 2002. All rights reserved.

What Are JavaBeans?


A JavaBean is a component written in Java (a set of Java classes) that can plug into any
applet or Java application because it conforms to established standards. The Forms
Builder bean area item enables you to extend Forms functionality by adding a JavaBean to
your form.
With JavaBeans, you can interact with the client machine, performing such functions as:
Obtaining information about the client machine
Uploading client files to the server machine
Modifying the user interface on the client
Checking the spelling of a text item
Displaying a progress bar, clock, calendar, or color picker with which the operator
can interact and select values
Some of this functionality, such as a calendar, is possible using Forms native
functionality. However, using a JavaBean enables client interaction without generating
network traffic.

Oracle9i Forms Developer: New Features 6-7


What Are Pluggable Java Components?

Pluggable Java Components (PJCs) enable you to


replace an existing Form item type, such as:
Text item with client-side validation
Rounded buttons
Check boxes
Radio groups sible
n e
Ext UI
Radio Buttons:
Cash
Checkboxes: Credit Card
Y N Disabled Check

6-8 Copyright Oracle Corporation, 2002. All rights reserved.

What Are Pluggable Java Components?


Pluggable Java Components (PJCs) enable you to change the function or appearance of
Forms items. PJCs make it possible to extend the standard Forms user interface and
provide a varied experience for application users. PJCs offer the additional possibility of
being able to perform client-side validation on an item, thus reducing network traffic.
PJCs are similar to JavaBeans. However, there is a separate Bean Area Item to define a
JavaBean, whereas PJCs extend the following types of standard Forms items:
Check Box Radio Group
List Item Text Item
Push Button
The FBEAN package is designed to work with JavaBeans, whereas you implement PJCs
by setting item properties. If there are properties for the PJC other than those you can set
in the Property Palette, you set them with the SET_CUSTOM_PROPERTY built-in.
Instructor Note
Demonstration: Use the form PJC_Demo.fmb to demonstrate the use of a PJC to
augment the functionality of a button. Instructions for the demo are in PJC_Demo.txt.

Oracle9i Forms Developer: New Features 6-8


Interacting with JavaBeans

Tell Forms about the bean: Register


Communication from Forms to JavaBean:
Invoke Methods
Get/Set Properties
Communication from JavaBean to Forms: Events

Methods
Properties
Events

6-9 Copyright Oracle Corporation, 2002. All rights reserved.

Interacting with JavaBeans


You add a JavaBean to a form by creating a Bean Area item in Forms Builder. The bean
that you add to a form may have a visible component on the form itself, such as a calendar
bean that has its own button to invoke the bean. However, because JavaBeans do not
always have visible components, you might need to create a button or other mechanism to
invoke the bean.
Whether or not the bean is visible in the bean area, there must be some communication
between the run-time form and the Java classes that comprise the bean. First, the form
must be made aware of the bean, either by setting its Implementation Class property at
design time or by registering the bean and its events at run time. Once the form knows
about the bean, the form communicates to the bean by:
Invoking the beans methods
Getting and setting properties of the bean
The bean communicates to the form by:
Sending an event, such as the fact that the user selected a date or color
Sending a list containing information needed by the form, such as what date or color
was selected
Returning a value from an invoked method

Oracle9i Forms Developer: New Features 6-9


Introducing the FBean Package

The new PL/SQL FBean package:


Registers properties and methods of Java
components
Listens for specified events
Enables you to use these properties, methods,
and events in PL/SQL
Makes using Java components in Forms much
easier than with prior versions

FBean

6-10 Copyright Oracle Corporation, 2002. All rights reserved.

What Is the FBean Package?


In prior Forms versions, using JavaBeans in a Forms application required a special layer
of code to facilitate the communication between the Forms item and the JavaBean
component. Oracle9i Forms adds a new feature to provide enhanced JavaBean support. In
most cases, it is no longer necessary to develop Forms-specific Java layer code. In
addition, heavyweight JavaBeans (based on Abstract Windowing Toolkit classes), which
were not supported in Forms6i, can now be used.
The new FBean PL/SQL package is an integral part of this enhanced JavaBean support. It
provides a way to register the properties and methods of JavaBeans at run time and make
these available to you from PL/SQL in Forms. The properties and methods are discovered
using the standard Java reflection mechanism and are registered using a consistent naming
mechanism. Thus you no longer need to write Java wrapper classes to integrate JavaBeans
into Forms.
Technical Note
The Abstract Windowing Toolkit (AWT) was the first user interface development system
included in the Java Foundation Classes (JFC). It uses operating system specific code, and
is less flexible and has fewer capabilities than Swing classes, which are written entirely in
Java.
Oracle9i Forms Developer: New Features 6-10
The FBean Package

The FBEAN package provides built-ins to:

Register the bean


Invoke methods of the
bean
Get and set properties on
the bean
Subscribe to bean events

6-11 Copyright Oracle Corporation, 2002. All rights reserved.

The FBEAN package


The FBEAN package contains Forms built-ins that enable you to code interactions with
JavaBeans in PL/SQL, eliminating the need to know Java in order to communicate with
the bean.
Many of the built-ins take some of the same arguments:
Item Name or Item ID (obtained with the FIND_ITEM built-in): The first
argument for most of the FBEAN built-ins, referred to on the next page simply as
ITEM.
Item Instance: A reference to which instance of the item should contain the bean.
This is applicable where the Bean Area is part of a multi-row block and more than
one instance of the Bean Area is displayed. The item instance is referred to on the
next page simply as INSTANCE. You can use the value ALL_ROWS (or
FBEAN.ALL_ROWS) for the item instance value to indicate that the command
should apply to all of the instances of this Bean Area in the block.
Note: This refers to the UI instance of the Bean Area, not the row number in the
block. For example, in a block with 5 rows displayed and 100 rows queried, there
will be 5 instances of the bean numbered 1 through 5, not 100 instances.
Value: Can accept BOOLEAN, VARCHAR2, or NUMBER data types.

Oracle9i Forms Developer: New Features 6-11


The FBEAN package (continued)
Some of the built-ins in the FBEAN package are:
REGISTER_BEAN(ITEM,INSTANCE,BEAN_CLASS):
Registers the bean with the form at run time, making all its exposed attributes and
methods available for the forms bean item (The last argument is the full class name
of the bean, such as 'oracle.forms.demos.beans.ColorPicker'.
Remember that Java is case-sensitive, so be sure to use the exact case of the class.)
ENABLE_EVENT(ITEM,INSTANCE,EVENT_LISTENER_NAME,
SUBSCRIBE):
The last argument is a BOOLEAN indicating whether to subscribe (TRUE) or
unsubscribe (FALSE) to the event.
GET_PROPERTY(ITEM,INSTANCE,PROPERTY_NAME)(returns VARCHAR2):
Function that retrieves the value of the specified property
SET_PROPERTY(ITEM,INSTANCE,PROPERTY_NAME,VALUE):
Sets the specified property of the bean to the value indicated
INVOKE(ITEM,INSTANCE,METHOD_NAME[,ARGUMENTS]):
Invokes a method on the bean, optionally passing arguments to the method
Remember to precede calls to any of these built-ins with the package name and a dot, such
as FBEAN.GET_PROPERTY(). You can pass arguments to these built-ins as either a
delimited string or as an argument list.
Instructor Note
When the JavaBean is registered, its properties are given a name that is derived from the
JavaBean setters and getters for that property. For example, the Juggler JavaBean has a
rate property exposed through the bean methods getAnimationRate and
setAnimationRate. After the bean is registered with FBEAN.REGISTER_BEAN, the
custom property animationRate is made available for that Bean Area item in the form.
To see all the methods and properties of the JavaBean, you can use
FBEAN.SET_LOGGING_MODE to make the information appear on the Java Console.

Oracle9i Forms Developer: New Features 6-12


Registering the Bean

At design time

FBEAN.REGISTER_BEAN(:CONTROL.hyperlink,1,
At run time
oracle.forms.demos.beans.Hyperlink);

Typically called in When-New-Form-Instance


trigger
Makes bean properties and methods available to
Forms PL/SQL

6-13 Copyright Oracle Corporation, 2002. All rights reserved.

Registering the Bean


There are two possible ways to tell the form which bean to use in the bean area item:
At design time:
The Implementation Class property of the Bean Area Item can be used to specify the
fully qualified name of the Java class that the Bean Area item should instantiate. If
the JavaBean has a visible component, Forms Builder displays the JavaBean within
the Bean Area item in the Layout Editor after the Implementation Class is set.
Note: If you set the Implementation Class at design time, the path to the bean must
be included in the machine's CLASSPATH or FORMS90_BUILDER_CLASSPATH.
At run time:
With enhanced JavaBean support in Oracle9i Forms, it is not necessary to set the
Implementation Class at design time. Instead, you can programmatically register the
bean at run time using the FBEAN package.
You can use either of these methods, or both together. If you decide not to set the
Implementation Class at design time, the bean area will appear as a blank area in the
Layout Editor. However, if you do not use the FBEAN package to register the bean at run
time, you will not be able to use the FBEAN package to get or set properties on the bean
or invoke its methods.

Oracle9i Forms Developer: New Features 6-13


Setting Bean Area Item Properties

6-14 Copyright Oracle Corporation, 2002. All rights reserved.

Setting Properties for the Bean Area


You can set properties of the bean area item at design time. For example, the hyperlink
bean looks best without a bevel and with a background set to the same color as the canvas
on which the bean is positioned. You can set these bean area item properties in the
Property Palette, or use SET_ITEM_PROPERTY at run time.
Some JavaBeans have no visible component. To avoid the distraction of a large empty
rectangle on the form, you can set the bean area item properties so that the bean displays
as a tiny dot in the corner of the canvas, as shown on the slide above. Alternatively, you
can set the Visible property to No, which ensures that the Bean Area does not display at
run time, although you still see it in the Layout Editor.

Oracle9i Forms Developer: New Features 6-14


Setting JavaBean Properties

Bean area at run time

Bean area at design time

http://otn.oracle.com/products/forms

FBean.Invoke(hHyperlink,1,setURL,
http://otn.oracle.com/products/forms);
FBean.Invoke(hHyperlink,1,setLabel,
Forms on OTN);

6-15 Copyright Oracle Corporation, 2002. All rights reserved.

Setting JavaBean Properties


Properties that are specific to the JavaBean must be set at run time. The JavaBean
documentation should inform you of the properties and methods available for that bean.
In previous Forms versions, you used the GET/SET_CUSTOM_PROPERTY built-in to
code all programmatic interactions with JavaBeans. In Oracle9i Forms, you can code this
functionality using the FBEAN package.
If you used FBEAN to register the bean, you can set custom properties with
FBEAN.SET_PROPERTY, or you might invoke a method with FBEAN.INVOKE that
sets a property on the bean. For example, to set properties on the hyperlink bean, you can
place the following code in a When-New-Form-Instance trigger:
FBean.Invoke(hHyperlink,1,setURL,
http://otn.oracle.com/products/forms);
FBean.Invoke(hHyperlink,1,setLabel,Forms on OTN);
If you did not register the bean with FBEAN, you can set bean properties with the
SET_CUSTOM_PROPERTY built-in.

Oracle9i Forms Developer: New Features 6-15


Responding to Events

Register a listener for the event:


FBEAN.ENABLE_EVENT(MyBeanArea,1,
mouseListener, true);
When an event occurs on the bean:
The When-Custom-Item-Event trigger fires.
The name and information are sent to Forms in:
:SYSTEM.CUSTOM_ITEM_EVENT
:SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS

1 2 3
event parameters

6-16 Copyright Oracle Corporation, 2002. All rights reserved.

Responding to Events
When a user interacts with a JavaBean at run time, it usually causes an event to occur.
You can use FBEAN.ENABLE_EVENT to register a listener for the event, so that when
the event occurs, Forms will fire the When-Custom-Item-Event trigger. In this trigger, you
can code a response to the event. The :SYSTEM.CUSTOM_ITEM_EVENT and
:SYSTEM.CUSTOM_EVENT_PARAMETERS variables contain the name of the event
and information the bean is sending to the form.
A typical interaction that could occur includes the following steps:
1. The user clicks the bean area for a hyperlink bean. This bean area has a visible
component on the form consisting of hyperlinked text. The label is set to a
description of the hyperlink destination.
2. The Click event is initiated.
3. The beans listener recognizes the Click event, which automatically fires the When-
Custom-Event trigger.
4. The code in the When-Custom-Item-Event trigger obtains the URL from the
information sent to the form from the event, then invokes the URL.

Oracle9i Forms Developer: New Features 6-16


Responding to Events (continued)
Coding a When-Custom-Item-Event Trigger
In a When-Custom-Item-Event trigger that fires automatically to respond to JavaBeans
events, you code the action you want to take place when the listened-for event occurs.
For example, when a user clicks the hyperlink bean, the When-Custom-Item-Event trigger
fires because an action listener is enabled. In the code for the When-Custom-Item-Event
trigger on the hyperlink bean area item, you define the action to take in response to the
event. You can use the system variables containing the event and parameter information
in your code as needed. Since the hyperlink bean fires only the Click event, you do not
need to check for the event name, but you do need to obtain the URL. You can do this
either by extracting it from the event parameters, or by invoking a method of the bean:
declare
vcEventName VARCHAR2(256);
vcEventData VARCHAR2(256);
iParamType PLS_INTEGER;
begin
vcEventName := :SYSTEM.CUSTOM_ITEM_EVENT;

-- You can get the URL EITHER:


-- 1. from the event parameter list
GET_PARAMETER_ATTR(:SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS,
DATA,iParamType,vcEventData);
-- OR
-- 2. using FBean.Invoke_Char
-- vcEventData :=
-- Fbean.Invoke_Char(Control.hyperlink,1,getURL);

-- Show that url


Web.Show_Document(vcEventData,_blank);
end;
When you use the FBEAN package to integrate the bean, the name of the value passed
back to the form is always called DATA. For example:
GET_PARAMETER_ATTR(:SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS,
DATA,paramType,eventData);
(where paramType and eventData are PL/SQL variables you declare in the When-
Custom-Item-Event trigger, like iParamType and vcEventData in the example
above).
Instructor Note
Demonstration
The hyperlink bean is illustrated in Javabean_demo.fmx. You can run the form to
demonstrate how the bean works. The form displays a description of the code and triggers
involved. If you decide to create such a form yourself, you need to place at least one text
item on the form for navigation. The demo form contains a 1x1 text item.

Oracle9i Forms Developer: New Features 6-17


Interacting with Non-Event JavaBeans

The JavaBean may:


Not have a visible component
Not communicate via events
Return a value to the form when invoked (use like
a function)

2
1

51,255,255
4

6-18 Copyright Oracle Corporation, 2002. All rights reserved.

Interacting with Non-event JavaBeans


Not all information from JavaBeans is obtained via events. For example, a JavaBean
might return a value when one of its methods is invoked. This value might be assigned to
a PL/SQL variable or Forms item, similarly to the way a function returns a value.
An example of this is the ColorPicker bean. It contains a single method that returns a
value, and also has no visible component in the bean area of the form. To invoke the bean
and obtain a value from it, you can use a Forms push button and trigger with code similar
to the following:
vcNewColor := FBean.Invoke_char(hColorPicker,
1,showColorPicker,"Select color for canvas");
The INVOKE_CHAR built-in is used to call a method that returns a VARCHAR2 value:
1. User clicks button to invoke the bean.
2. Color Picker component displays.
3. User selects a color.
4. Color value (RGB values in comma-separated list: n,n,n) is returned to the
vcNewColor variable. The code can translate the n,n,n value to the value used by
PL/SQL (RnGnBn) and then use that value to set the canvas color.

Oracle9i Forms Developer: New Features 6-18


Deploying JavaBeans for
Forms Applications
Place the class files:
On middle-tier server in CODEBASE directory or
directory referenced in servers CLASSPATH
OR in a JAR file in CODEBASE directory AND
referenced in applets ARCHIVE parameter

formsweb.cfg file (deploying getclientinfo bean):


# 3) Values for the Forms applet parameters:
...
codebase=/forms90/java
...
archive_jini=f90all_jinit.jar,getclientinfo.jar
archive=f90all.jar,getclientinfo.jar

6-19 Copyright Oracle Corporation, 2002. All rights reserved.

Deploying the Bean


Because the bean itself is a Java class or set of Java class files separate from the form
module, you need to know where to put these files. You can locate these either:
On the middle-tier server, either in the directory structure referenced by the form
applets CODEBASE parameter or in the servers CLASSPATH. CODEBASE is by
default the forms90\java subdirectory of ORACLE_HOME.
Or, if using JInitiator, in a JAR file in the middle-tier servers CODEBASE directory.
Include the name of the JAR file in the ARCHIVE parameter so that the JAR file is
downloaded to and cached on the client. (The CODEBASE and ARCHIVE
parameters are set in the formsweb.cfg file.) For example:
archive_jini=f90all_jinit.jar,colorpicker.jar
If the JavaBean performs actions that a Java applet would normally not be permitted to
do, such as writing to client files, you must digitally sign the JAR file. If users of your
application know and trust your identity, you can use a self-signed certificate to sign your
files, as explained on the next page. If not, you can request a certificate from a recognized
certificate authority. For a detailed explanation, see the tutorial at
http://java.sun.com/docs/books/tutorial/security1.2/toolsign/index.html.

Oracle9i Forms Developer: New Features 6-19


Deploying the Bean (continued)
Creating and Signing JAR Files
There are Java tools that enable you to create and sign JAR files. To use these tools from
the command line, set your PATH to include the bin directory of the JDK 1.3 installation;
for example (on DOS): set PATH=d:\oracle\iDS\jdk\bin.
To create a JAR file from a set of class files contained in a single directory, navigate to
that directory and use the jar command: jar cvf mycode.jar *.class.
To sign the JAR file, perform the following steps:
1. Create a digital signature: keytool -genkey -dname "cn=Summit, ou=Dev
Tools, o=oracle, c=US" -alias mykey -keypass mykeypass -
keystore d:\temp\keystore -storepass manager -validity 360
2. Sign the JAR file with that identity: jarsigner -keystore
d:\temp\keystore storepass manager -keypass mykeypass
mycode.jar mykey
3. Export the signature to a certificate file: keytool -export -keystore
d:\temp\keystore -alias mykey -file mykey.cer storepass
manager
At this point, the client may be asked whether to accept your signature when attempting to
execute the code. To avoid this and get the client to recognize your signature, perform the
following steps:
1. Copy the exported certificate to a PC that is running JInitiator. In the example
below, mykey.cer has been copied to the c:\temp directory of the client PC.
2. Set the PATH on the client PC to include the bin directory of the JInitiator 1.3
installation; for example:
set PATH=c:\Program Files\oracle\JInitiator 1.3.1.9\bin
3. Import your certificate:
keytool import alias mykey file c:\temp\mykey.cer
keystore "c:\Program Files\oracle\JInitiator
1.3.1.9\lib\security\keystore" storepass jinitiator
4. Modify the java.policy file:
- Enter the command: policytool. The Policy Tool Java window opens.
- A warning displays that the default policy file cannot be found. Click OK.
- Select File > Open and open the java.policy file in the JInitiators
lib\security subdirectory.
- Click Add Policy Entry. The Policy Entry window displays.
- Enter the key alias (mykey in the example) in the SignedBy field.
- Click Add Permission. The Permissions window displays.
- Select AllPermission from the Permission drop-down list, enter the key alias
(mykey in the example) in the Signed By field, and click OK.
- Click Done.
- Select File > Save, then File > Exit.

Oracle9i Forms Developer: New Features 6-20


Summary

In this lesson, you should have learned:


Oracle9i Forms uses JDK 1.3 on both the middle
and client tier, enabling you to integrate with the
latest technologies.
You can use Pluggable Java Components to
change the appearance or functionality of Forms
items.
You can use the FBean package to integrate
JavaBeans without writing a wrapper class.

6-21 Copyright Oracle Corporation, 2002. All rights reserved.

Summary
You can integrate Oracle9i Forms applications with the latest Java technologies because
JDK 1.3 is used on both the middle and the client tier. You are no longer restricted to Java
code on the middle tier, or JavaBeans and PJCs on the client that were developed with
JDK 1.1.
You can use PJCs as the implementation class for Forms items such as text items, list
items, push buttons, radio groups, or check boxes. Using a PJC to implement these items
changes the functionality and the appearance of the item.
Support for JavaBeans is enhanced in Oracle9i Forms with the introduction of the FBean
package. You can now use JavaBeans without writing a wrapper class, and you can use
heavyweight beans, which was not possible in Forms6i.
The FBean package contains methods to register, invoke, get and set properties, and
enable an event listener on the bean. This makes it easy to code communication with the
bean.

Oracle9i Forms Developer: New Features 6-21


Practice 6 Overview

This practice covers the following topics:


Creating a bean area item
Implementing a hyperlink bean to invoke a URL
Implementing a color picker bean to allow users to
change the canvas color
Using the Rollover PJC to implement an
information button
Using the KeyFilter PJC to perform client-side
validation

6-22 Copyright Oracle Corporation, 2002. All rights reserved.

Practice 6 Overview
In this practice, you create bean area items to implement a hyperlink bean and a color
picker bean. You make calls to the FBean package to code interaction with the beans. You
also change the implementation class of a push button to utilize rollover button PJC, and
you implement client-side validation on a text item with a KeyFilter PJC.
Note: The JAR files used in these exercises are available in the Oracle9i Forms
demonstrations, downloadable from OTN.

Oracle9i Forms Developer: New Features 6-22


Practice 6
1. In the Layout Editor for the Customer_CV canvas, create a bean area called
Hyperlink in the Control block of the Customers form. Place the bean above the
Customer Information boilerplate text. The bean area should not have a bevel. Set its
background color to be the same as the background color of the canvas. At this
point, the bean should appear as a gray area on the canvas as shown in the following
screenshot:

2. Add code to the Customers form to register the bean at form start-up and to enable
an actionListener.
The class is oracle.forms.demos.beans.Hyperlink (this is case-sensitive).
The bean should be labeled "Forms on OTN" and should invoke the Forms Web
page (http://otn.oracle.com/products/forms).

3. Code the action you want to perform when the user clicks the bean, which is to
invoke the beans URL in a separate browser window. Click Run Form to run the
Form and test the function of the hyperlink..
Hint: You first need to get the URL from the bean, then use
web.show_document to invoke it.

4. In the Customers form, create a bean area in the CONTROL block and name it
Colorpicker. This bean has no visible component on the form, so set it to display as
a tiny dot in the upper left corner of the canvas. Make sure that users cannot
navigate to the bean area item with either the keyboard or mouse.

5. Create a button on the CV_CUSTOMER canvas to enable the user to change the
canvas color using the ColorPicker JavaBean. Place the button just above the Orders
button.
Set the following properties on the button:
Label: Canvas Color Mouse Navigate: No
Keyboard Navigable: No Background color: gray

The button should call a procedure named PickColor, which invokes the bean and
translates the comma-separated color values of the bean to the RGB values used by
PL/SQL. You can import the code from the the pr6_5.pls file in your solutions
directory.

Oracle9i Forms Developer: New Features 6-23


Practice 6 (continued)
6. In the Customers form, register the ColorPicker bean (making its methods available to
Forms) when the form first opens. The full path to the bean is:
oracle.forms.demos.beans.ColorPicker (this is case sensitive).

7. Click Run Form to run your form and test the Color button. You should be able to
invoke the ColorPicker bean from the Color button, now that the bean has been
registered at form startup.

8. In the Orders form, use the Rollover Button PJC to change the look of the buttons on
the Toolbar canvas to be rounded buttons. Set the Implementation Class property of
the toolbar buttons (Control block buttons Invoice_Button, Image_Button,
Stock_Button, Show_Help_Button, and Exit_Button) to:
oracle.forms.demos.enhancedItems.RolloverButton.
To implement the rounded button look, surround the label of the buttons with
parentheses, for example, (Invoice). Click Run Form to run the form and test the
changes. At run time, the buttons should have rounded ends as in the following
screenshot:

9. Change the Exit button in the Orders form to be a rollover button by setting its Label
property to [ROLLOVER]exit (note that this is case sensitive and must be typed
exactly as shown). Change the Height and Width properties of the button to 30. Set the
Height of the Toolbar_CV canvas to 40 to accommodate the larger button. Align the
centers of all the toolbar buttons. Click Run Form to run the form and test the changes.
At run time, the buttons should appear as in the following screenshot, and moving the
mouse over the Exit button should change its image.

Oracle9i Forms Developer: New Features 6-24


Practice 6 (continued)
10. In the Orders form, implement client-side validation on the ORDER_ITEMS.Quantity
item using a Pluggable Java Component to filter the keystrokes and allow only
numeric values.
The full path to the PJC class is oracle.forms.demos.KeyFilter (this is case
sensitive), to be used as the Implementation Class for the item. When the Orders form
first opens, set a filter on the ORDER_ITEMS.Quantity PJC.

11. Run the Orders form to test the changes. Try to enter alphabetic characters into the
Order_Items.Quantity item. You should be able to enter only numeric data.

Oracle9i Forms Developer: New Features 6-25


Oracle9i Forms Developer: New Features 6-26
Enhancing the User Experience

Copyright Oracle Corporation, 2002. All rights reserved.

Schedule: Timing Topic


20 minutes Lecture
20 minutes Practice
40 minutes Total
Objectives

After completing this lesson, you should be able to do


the following:
Design an LOV that can be canceled for long-
running queries
Write code that retrieves the Forms version
Write code to restrict a query only the first time it
is executed

7-2 Copyright Oracle Corporation, 2002. All rights reserved.

Lesson Aim
This lesson describes the new run-time enhancements for Oracle9i Forms.

Oracle9i Forms Developer: New Features 7-2


The Cancelable LOV

2 3 4
Incrementing
value

7-3 Copyright Oracle Corporation, 2002. All rights reserved.

The Cancelable LOV


In previous versions of Forms, if a query in a Long List LOV returned a large number of
rows, end users had to wait until Forms fetched all the records before they could continue.
For example, the user could make a mistake when specifying a condition and
inadvertently cause a large number of records to be fetched. It would not be possible to
continue working in the form until all the queried rows were fetched into the LOV.
To enable users to halt LOV population, you can make the LOV cancelable:
1. Set the LOVs Filter Before Display property to Yes (this is what makes it a Long
List LOV).
2. Set the Form modules Interaction Mode property to Non-Blocking.
3. When users run the LOV, the status bar displays how many records have been
fetched at any point in time.
4. Users can click Cancel to stop further retrieval of records.
After users have canceled the query, they can work with the set that has been fetched to
that point as if the query had run to completion. They can select a value, enter new query
criteria, or cancel out of the LOV completely.

Oracle9i Forms Developer: New Features 7-3


Retrieving the Forms Version

GET_APPLICATION_PROPERTY(VERSION)

7-4 Copyright Oracle Corporation, 2002. All rights reserved.

Retrieving the Forms Version


Large organizations may have applications running at various sites in the company,
possibly using different versions of Forms as well as other products. For supportability of
such applications, it is helpful to provide users with access to the version numbers of any
products that are used.
Oracle9i Forms includes a built-in to retrieve the version number of the Forms Runtime
that is running the application. This value, which is returned as a string, is obtained by
using GET_APPLICATION_PROPERTY(VERSION).
Instructor Note
The VERSION argument to GET_APPLICATION_PROPERTY worked in Forms6i as
well, but it was undocumented. See Bug 245852.

Oracle9i Forms Developer: New Features 7-4


The One Time Where Clause

Initially shows
restricted query
2nd Execute_Query
not restricted

7-5 Copyright Oracle Corporation, 2002. All rights reserved.

One Time Where Clause


ONETIME_WHERE Property
For applications where you want to temporarily restrict a query, you can
programmatically set the ONETIME_WHERE property on a block. This specifies a where
clause for the block that will be in effect only for the first query issued on the block after
setting that property. The one time where clause enables usage of bind variables,
promoting cursor reuse and database resource efficiency.
Example: In the Customers form, there is a button to invoke the Orders form. When the
Orders form initially appears, it presents information about the orders of the customer
displayed in the Customers form. However, after this initial information is displayed, you
want users to be able to query orders for any customer. You accomplish this by coding the
When-New-Form-Instance trigger of the Orders form to set the ONETIME_WHERE
property as shown in the slide.
Instructor Note
Demonstration: Run the Customers form, click the Orders button, and show students that
the Customer ID is restricted to the customer in the Customers form. Click Execute Query
and show that the query is no longer restricted.

Oracle9i Forms Developer: New Features 7-5


Summary

In this lesson, you should have learned that:


You can design a LOV that can be canceled for
long-running queries:
Set the modules Interaction Mode to Non-Blocking
Set LOVs Filter Before Display to Yes.
You can retrieve the Forms Runtime version with
GET_APPLICATION_PROPERTY(VERSION).
Defining a one time where clause restricts a query
only the first time it is executed.

7-6 Copyright Oracle Corporation, 2002. All rights reserved.

Summary
Oracle9i Forms introduces three features to enhance the usability of Forms applications:
The cancelable LOV, implemented by setting the form to non-blocking and setting
the LOV to filter before display
The ability to retrieve the Forms version with the GET_APPLICATION_PROPERTY
built-in
A one time where clause that enables you to restrict a query the first time a query is
executed, but perform subsequent queries that are not restricted

Oracle9i Forms Developer: New Features 7-6


Practice 7 Overview

This practice covers the following topics:


Creating a LOV that can be canceled by the user
Displaying a message with the Forms version
being used
Setting a one time WHERE clause to restrict the
query on a block only the first time it is executed

7-7 Copyright Oracle Corporation, 2002. All rights reserved.

Practice 7 Overview
In this practice, you create a LOV that shows the progress of a long-running record group
query and can be canceled at any point in the record retrieval. You also use
GET_APPLICATION_PROPERTY to retrieve the Forms version number. Finally, you set
up the Orders form so that the first query is restricted to the customer displayed on the
Customers form when Orders is called by the Customers form, but subsequent queries are
not restricted.

Oracle9i Forms Developer: New Features 7-7


Practice 7
1. Because there is no table in the sample data that returns a large number of rows,
create a LOV called Cartesian_LOV in the Customers form whose record group,
called Cartesian_RG, performs a Cartesian join of the CUSTOMERS and the
ORDERS tables. Define the query for the record group as follows (you can import
the query from pr8_1.sql in your solutions directory):
SELECT CUSTOMERS.CUST_LAST_NAME,
ORDERS.ORDER_ID
FROM CUSTOMERS, ORDERS
ORDER BY CUSTOMERS.CUST_LAST_NAME
Set the Filter Before Display property for the LOV to Yes and set Height to 200.

2. Create a Control block button on the Customer_CV canvas to display the LOV.
Name the button Long_LOV_Btn, with the Long LOV label. Place the button just to
the left of the Canvas Color button.

3. Click Run Form to run the form. Click Long LOV to invoke the LOV. Enter % in
the Find box so that all records will be retrieved, and click Find. What is the
behavior of the LOV?

4. In the Customers form, set the Interaction Mode property of the form to Non-
Blocking. Run the form again and click Long LOV to invoke the LOV. Enter % in
the Find box so that all records will be retrieved, and click Find. What is the
behavior of the LOV now?

5. In the Orders form, create a Control block button on the Toolbar canvas. Set the
name of the button to About_Btn and its label to About. The code for this button
should display the Forms version in a message. Run the form to test the button.

6. Users of the Customers form are complaining. They click the Orders button, and the
Orders form displays the orders for the customer in the Customers form. However,
after they are in the Orders form, they would like to be able to query orders for other
customers.
To make this possible, change the When-New-Form-Instance trigger in the Orders
form to enable users to execute a second query on the Orders block that is not
restricted to the current Customer_ID from the Customers form. You will also
need to delete or rename the Pre-Query trigger on the Orders block, where the
original functionality is implemented.

7. Run the Customers form to test the changes.

Oracle9i Forms Developer: New Features 7-8


Deploying Forms Applications Globally

Copyright Oracle Corporation, 2002. All rights reserved.

Schedule: Timing Topic


45 minutes Lecture
35 minutes Practice
80 minutes Total
Objectives

After completing this lesson, you should be able to do


the following:
Specify item length for single-byte, multi-byte, and
variable-byte character sets
Adjust functionality for different time zones
Publish one URL for applications that will be
displayed in different languages based on the
browser setting
Describe the TranslationHub tool to translate
Forms modules into different languages

8-2 Copyright Oracle Corporation, 2002. All rights reserved.

Lesson Aim
This lesson presents information to enable you to deploy multinational applications that
account for differences in language, time zone, and character set.

Oracle9i Forms Developer: New Features 8-2


Defining Item Length for Different
Character Sets
Forms6i used BYTE
semantics only.
Oracle9i Forms enables
you to use CHAR
semantics.
Specifies how Maximum
Length and Query Length
are enforced

US7ASCII
VARCHAR2(5 CHAR) 1 2 3 4 5
JA16SJIS
VARCHAR2(5 CHAR) 1 2 3 4 5
UTF8
VARCHAR2(5 CHAR) 1 2 3
8-3 Copyright Oracle Corporation, 2002. All rights reserved.

Defining Item Length for Different Character Sets


Character semantics is a new feature of the 9i database. This feature enables development
of applications that can be globally deployed in multiple character sets without changes.
You specify character semantics in PL/SQL by declaring a variable of
VARCHAR2(<n> CHAR)type, where <n> is the maximum number of characters.
In Oracle9i Forms, there is a new item property to take advantage of this feature. You can
set the Data Length Semantics property of many types of items to Null, BYTE, or CHAR
to be compatible with multiple character sets. If a null value is specified, then byte
semantics are used unless the environment variable NLS_LENGTH_SEMANTICS is set to
CHAR when the form is compiled. If Data Length Semantics is set to CHAR, the correct
amount of storage will be automatically allocated as required for the Maximum Length
and the Query Length, whether the character set is single-byte or multi-byte. This property
is effective only if the corresponding database column has a length declaration of CHAR.
Note: In the example above, whether the form operator is using a single-, double-, or
variable-byte character set, the right amount of storage is allocated. To hold the same
value if the Data Length Semantics property is set to BYTE, the Maximum Length would
have to be 5 for single-byte, 10 for double-byte, and 5 multiplied by the maximum
number of bytes per character for a variable-byte character set.

Oracle9i Forms Developer: New Features 8-3


Adjusting for Different Time Zones

What time is it?


Database server time?
Application server time?
Client machine time?
Important question for
time-sensitive applications

User1 User2

DB1 DB2

8-4 Copyright Oracle Corporation, 2002. All rights reserved.

Time Zone Support


Another problem experienced by applications that are widely deployed geographically is
the simple concept of time. When users record a time in a Forms field, what exactly do
they mean? The time where they are? The time where the Forms Server is running? Or the
time on the Database Server?
For example, suppose you have two users: User1, located in Colorado, and User2 in
Chicago. User1 connects to a database server in California, while User2s database server
is in New York. They are using the same application, which inserts the current date and
time into a DATETIME item in a form. If they both perform this operation at exactly the
same time, there could be as much as a four-hour time difference in the time that is
inserted, depending on whether client time or database time is used.
Oracle9i Forms supports the ability to define the time zones of both the Forms client and
the Database Server so that times are correctly stored in the database. Thus, if a time of
5:00 p.m. is recorded from a Forms client running in British Summer Time (BST) into a
database running in GMT (or Universal Coordinated [UTC] as it is more correctly called),
then the time will be recorded as 4:00 p.m. GMT. If the record is queried back, it is still
seen in the local time zone, for example, 5:00 p.m. BST.

Oracle9i Forms Developer: New Features 8-4


Time Zone Support (continued)
Likewise, if a colleague in San Francisco queries the same record with the local time zone
set to Pacific Daylight Time (PDT), the person will see the time as their correct time
9:00 a.m. PDT. (4:00 p.m. GMT == 5:00 p.m. BST == 9:00 a.m. PDT).
Time zone support is something that many customers have already implemented using a
variety of schemes, usually based on simple time offsets, such as PDT == GMT - 7.
However, time zones turn out to be much more complicated than they first appear. The
following issues must be considered:
Daylight Savings
When does daylight savings start and end (in some countries it differs from year to
year)?
What about the ambiguous time once a year when we switch back from summer
time/daylight savings, and we get one hour twice, once in summer time and once in
standard?
What about countries that have changed time zones in the past?

Oracle9i Forms Developer: New Features 8-5


The Time Zone Data File

The time zone data file (timezlrg.dat or


timezone.dat) file:
Cannot be created or modified by you
Is binary so not human-readable
Get correct time zone region strings by querying
v$timezone_names:
select tzname, tzabbrev from v$timezone_names;

The time zone region string to use for your Forms


settings is the tzname value.

8-6 Copyright Oracle Corporation, 2002. All rights reserved.

The Time Zone Data File


Oracle9i Forms uses a comprehensive knowledge base of time zones, based on
information maintained by the U.S. Navy Observatory, to handle any conversion. This
information is contained in a file called timezlrg.dat or its stripped-down version
timezone.dat that is sufficient for most applications. These are binary files.
The following SQL query provides a list of time zone regions:
SELECT TZNAME FROM v$timezone_names;
You use the time zone region value for many of the settings to implement time zone
support for Forms.

Oracle9i Forms Developer: New Features 8-6


Implementing Time Zone Support

To configure Forms for time zone support, set:


FORMS90_TZ_FILE: Specifies the time zone data file
that contains rules for conversion
FORMS90_DATETIME_SERVER_TZ: Specifies time
zone of database server (defaults to GMT)
FORMS90_DATETIME_LOCAL_TZ: (Optional)
Specifies time zone of local client; if not set, uses
client browser time zone or URL parameter
datetimeLocalTZ
Conversion in both directions is automatic.
Conversion applies to DATETIME items only.
Enter-Query mode requires special treatment.

8-7 Copyright Oracle Corporation, 2002. All rights reserved.

Implementing Time Zone Support


Forms is not automatically configured for time zone support. In order to set Forms up for
time zone support, you must set the following environment variables for your application:
Set FORMS90_DATETIME_SERVER_TZ to the time zone region where your
database server is located.
Set FORMS90_TZFILE to the location of your time zone data file.
Example settings added to default.env on the Forms Services machine:
FORMS90_DATETIME_SERVER_TZ=US/Pacific
FORMS90_TZFILE=/oracle/ias902/oracore/zoneinfo/timezone.dat
You can also optionally set FORMS90_DATETIME_LOCAL_TZ to the time zone region
of the browser client. The Forms client can also define the local time zone, either as an
explicit URL parameter (datetimeLocalTZ), or by simply using the current time zone
of the client.
With these settings in place, Forms automatically converts database time to local time for
display in text items that are of a DATETIME data type. Forms also converts the
displayed date back to the database time, using the specified
FORMS90_DATETIME_SERVER_TZ, prior to inserting into the database.

Oracle9i Forms Developer: New Features 8-7


Implementing Time Zone Support (continued)
Adjustment of Values in Enter-Query Mode
There are special considerations regarding the automatic conversion of DATETIME item
values in a block that is in Enter-Query mode. The following table indicates whether the
item value entered by the end user in Enter-Query mode will be time-zone adjusted to
produce the value used in the WHERE clause of the query:

Item Value Entered by User in Enter-Query Mode Adjusted?


Full DATETIME value Yes
Date-only portion of a DATETIME value Yes
DATETIME value preceded by relational operator Yes
DATETIME value containing wildcard character(s) (% or _ ) No
Value beginning with #, :, or & No
Item values set programmatically by the COPY built-in are time-zone adjusted only when
the value is:
A DATETIME value preceded by a relational operator. Note that the date portion of
such a value must be in the items input date format, not in built-in date format as
COPY values usually are.
A full DATETIME value or a date-only portion of a DATETIME value that is not
valid for the built-in date format but is valid for the items input date format. (COPY
will first attempt to convert such a value using the built-in date format with no time-
zone adjustment, and if that fails, will then attempt to convert it using the items
input date format - with time-zone adjustment.)
Full DATETIME item values set programmatically by a PL/SQL assignment are not time-
zone adjusted
Note: SYSTEM.LAST_QUERY always shows DATETIME values in the servers time
zone.
Instructor Note
Do not present these rules for Enter-Query mode in detail; they are here for the students
reference. Simply emphasize to the students that values entered by users in Enter-Query
mode are handled in a special way.

Oracle9i Forms Developer: New Features 8-8


Time Zone Properties and Built-in

New application properties (use with


[GET|SET]_APPLICATION_PROPERTY):
DATETIME_SERVER_TZ
DATETIME_LOCAL_TZ
New ADJUST_TZ built-in provides manual
conversion

8-9 Copyright Oracle Corporation, 2002. All rights reserved.

Time Zone Properties and Built-in


You can change the client time zone or database server time zone at run time:
SET_APPLICATION_PROPERTY(DATETIME_LOCAL_TZ,<timezone string>);
SET_APPLICATION_PROPERTY(DATETIME_SERVER_TZ,<timezone string>).
Note: Changing these settings does not affect the browser or the database, but simply tells
Forms how to treat time information received from the client and the database, and how to
convert dates being inserted into the database.
The automatic conversion of time zones only applies to items defined as DATETIME.
A new built-in, ADJUST_TZ(), can manually convert times between specified time
zones using the same rules.
Instructor Note
Demonstration
Run the form timezone_demo.fmx. Complete instructions for the demo are in the file
timezone_demo.txt.

Oracle9i Forms Developer: New Features 8-9


Time Zone Implementation Example

Create application-specific .env file:


Set FORMS90_TZ_FILE
Set FORMS90_DATETIME_SERVER_TZ so that the
same value is used by all clients
In formsweb.cfg, create named configuration
pointing to the .env file
Give users the URL with config=<named config>
User1 User2

DB1 DB2

8-10 Copyright Oracle Corporation, 2002. All rights reserved.

Time Zone Implementation Example


In the example discussed previously, where User1 in Colorado connects to a California
database and User 2 in Chicago connects to a New York database, a time-sensitive
application can benefit from implementing time zone support as follows:
The application developer decides that for consistency, all times inserted into the
database records should be in Pacific time, and so, creates an application-specific
environment file called myapp.env, with the following settings:
FORMS90_DATETIME_SERVER_TZ=US/Pacific
FORMS90_TZFILE=<ORACLE_HOME>/oracore/zoneinfo/timezone.dat
The application developer creates a section in formsweb.cfg:
[myapp]
envFile=myapp.env
Users can now connect to the application by appending ?config=myapp to the
URL. Forms will automatically display dates in the DATETIME items in the local
time, as determined by the client browser. Dates updated or inserted into the
database will be converted to the US/Pacific time zone, but when users query the
record, it is displayed in local time.

Oracle9i Forms Developer: New Features 8-10


Displaying Applications in
Multiple Languages

en 9iAS HTTP Listener

it OC4J Which application


should I use?
de Forms Servlet

Forms Listener
Servlet
Booking_en.fmx

fr
Booking_it.fmx

Booking_de.fmx
Forms Runtime
Booking_fr.fmx

8-11 Copyright Oracle Corporation, 2002. All rights reserved.

Displaying Applications in Multiple Languages


If your application is deployed multinationally, you may need to translate it into multiple
languages. If so, how does Forms Services know which version of the application to
display to the user?
One way is to give users different URLs pointing to the application that is specific to their
own languages. However, it would certainly be better if all users could access the
application with the same URL.
Oracle9i Forms provides the ability to deploy, with a single URL, multilanguage
applications to automatically display in the preferred language of the client browser.
Note: When installing Forms Services for multilanguage deployment, you must also
install the message and supplement files for each required language.

Oracle9i Forms Developer: New Features 8-11


Detecting Browser Language Settings
Tools Internet
Options

Change language
preferences

8-12 Copyright Oracle Corporation, 2002. All rights reserved.

Detecting Browser Language Settings


With every Web request, HTTP header information is passed to the middle tier server.
This information contains an accept_language parameter that is automatically set by
the users browser. The value of accept_language is the list of preferred languages as
defined in the Browser preference dialog. If, for example, a user prefers Web pages to be
displayed in American English, or if not available, in French, and finally in German, then
the request header contains the following information:
accept_language=en-us,fr,de.

Oracle9i Forms Developer: New Features 8-12


Translated Applications at Run Time
http://server/forms90/f90servlet?config=booking

accept_language=it formsweb.cfg

[booking]
envFile=default.env
en 9iAS HTTP Listener
[booking.it]
envFile=italian.env

[booking.en]
it OC4J envFile=english.env

[booking.french]
de Forms Servlet envFile=fr.env

italian.env
french.env
Forms Listener
Servlet english.env

german.env
fr
italian.env
NLS_LANG=Italian_Italy.
Forms Runtime WE8ISO8859P1
Forms90_PATH =

Booking_it.fmx

8-13 Copyright Oracle Corporation, 2002. All rights reserved.

Translated Applications at Run Time


The Oracle9i Forms Servlet reads the HTTP request header and filters out the sequence of
preferred languages, as specified in the users browser:
The Forms Servlet automatically looks for the first preferred version of the
application first (in the example on the previous page, that would be English).
If it cannot find a matching named configuration [en-us] in the formsweb.cfg
file, it then looks for the next preferred language.
If there is no named configuration to match any languages preferred by the user, the
default configuration is used.
If there is a language configuration for the requested application and language, then
the Forms Servlet looks for the environment file containing the NLS setting used to
start the run-time process on the server.
The information found in the language specific environment file is passed to the
Forms Listener Servlet that then starts up the Forms Runtime engine.
No matter how many languages your application supports, using this mechanism enables
you to deploy them all with one URL. The above example depicts several users
connecting to a booking application using the same URL. When the Italian user connects,
the Forms Servlet automatically displays the Italian translation of the form.

Oracle9i Forms Developer: New Features 8-13


Deploying Language-Specific Applications

Steps for deployment:


Booking_fr.fmx

Booking_en.fmx
1. Translate the application.
Booking_it.fmx

french.env
english.env 2. Define an environment file
italian.env
NLS_LANG=Italian_Italy.
for each language.
WE8ISO8859P1
Forms90_PATH = ...
... formsweb.cfg

[booking]
envFile=default.env

[booking.it]
3. Define a named configuration envFile=italian.env

for each environment. [booking.en]
envFile=english.env

[booking.fr]
envFile=french.env

8-14 Copyright Oracle Corporation, 2002. All rights reserved.

Deploying Language-Specific Applications


To deploy an application in multiple languages:
1. Translate the application into the languages in which it will be deployed. Oracle9i
TranslationHub, included as part of Oracle9iDS, is a tool that can help you with this
effort.
2. Define an environment file for each language in which you specify the character set
(NLS_LANG) and any other environment variables, such as path settings.
Example: NLS_LANG=Italian_Italy.WE8ISO8859P1
FORMS90_PATH=/oracle/forms/italian_forms
3. In your Forms Web configuration file, create a named configuration for each
language in which the application is being deployed. This configuration should
specify the language-specific environment file for that language.
Example: [booking.it]
envFile=italian.env
Users see the application in the first preferred language set in their browsers, in which the
application is deployed. If the application is not deployed in any of the preferred
languages, the default application is displayed.

Oracle9i Forms Developer: New Features 8-14


Translating an Application

What is Oracle9i TranslationHub?


Part of Oracle9i Developer Suite
Helps you translate Forms and Reports
application strings (UI, not data)
Proven technology
Available only on Windows platforms
Replaces Oracle Translation Manager and Oracle
Translation Builder

8-15 Copyright Oracle Corporation, 2002. All rights reserved.

Translating an Application
With browser language detection, deploying your translated applications is easy. But how
do you create the translations?
Oracle9iDS introduces a tool called TranslationHub for managing the translation of UI
strings in Forms and Reports applications. This is the same tool that Oracle has used for
several years for translation of Oracle products such as Oracle Applications, so it is
proven technology.
Oracle9i TranslationHub is available only on Windows platforms. It replaces Oracle
Translation Manager and Oracle Translation Builder, which are not supported with
Oracle9i Forms.
Instructor Note
This section presents TranslationHub concepts for the purpose of encouraging its use, but
it is not intended to be a complete tutorial.
The stated objective is that learners should be able to describe the TranslationHub tool,
but not necessarily that they would be able to use it. An eClass on this topic is currently
planned (Oracle9i Forms Developer: Using TranslationHub).

Oracle9i Forms Developer: New Features 8-15


Installing the TranslationHub Schema

TranslationHub is based on Oracle database


Uses many features of Oracle database
Must be in Administrator Mode to install schema

Creating the TranslationHub Schema in the database

8-16 Copyright Oracle Corporation, 2002. All rights reserved.

The TranslationHub Schema


TranslationHub is a database oriented translation tool that stores all translation strings,
with a reference to base strings, in database tables. The TranslationHub database schema
must be available in an Oracle database before starting a translation project.
You install the schema using TranslationHubs Schema Manager. You can access Schema
Manager from the menu: File > Schema Manager. This menu option is available when
you are in Administrator mode (Tools > User Mode).
Note: For additional information see the Oracle9i Forms TranslationHub Overview
white paper, available on OTN.

Oracle9i Forms Developer: New Features 8-16


Starting TranslationHub

Start > Programs Windows menu


Starting
TranslationHub

Forms Developer

TranslationHub
Oracle9i Developer Suite iDSv2

8-17 Copyright Oracle Corporation, 2002. All rights reserved.

Starting TranslationHub
You start the TranslationHub tool from the Windows menu: Start > Programs > Oracle9i
Developer Suite > Forms Developer > TranslationHub
Instructor Note
Demonstration
Open the TranslationHub tool. Customize the user interface to display the Navigator view,
the Attributes view, the Previewer view, and the Output view:
From the TranslationHub menu, choose View, and select the view to display if it is
not already shown.
Resize the views as needed by moving the cursor over a border until it changes to a
Resize pointer, then clicking and dragging the border to the desired position.
Make sure that the Attributes view displays the following columns: Item ID, Base String,
and Translation String.
Right-click one of the column headings in the Attributes view, and select Choose
Columns from the pop-up menu. The Choose Columns window displays.
Check the Item ID, Base String, and Translation String check boxes.
Click OK to close the Choose Columns window.

Oracle9i Forms Developer: New Features 8-17


The TranslationHub User Interface

1 2 3

8-18 Copyright Oracle Corporation, 2002. All rights reserved.

The TranslationHub User Interface


TranslationHub provides a customizable user interface containing the following views:
1. Navigator: Hierarchical structure enabling navigation between canvases and string
table
2. Attributes: Provides access to all strings and details about properties affecting the UI
3. Previewer: Lightweight live presentation of a canvas, showing either base or
translated strings as they will appear in the compiled application so that developers
can see the impact of the translation upon the user interface of the application
4. Output: Provides feedback when importing or exporting strings and running searches
or integrated report analyses
Terminology (not shown above): Displays base text strings sorted alphabetically, and
groups all identical text strings together
TranslationHub enables you to perform many translation tasks, including the following:
Extracting strings from software files
Organizing the translation strings
Organizing translation resources
Reusing translated strings automatically
Performing quality control

Oracle9i Forms Developer: New Features 8-18


Translating Applications

To translate an application:
1. Construct a translation project
2. Translate the text
3. Build the translated software
1
2
3

8-19 Copyright Oracle Corporation, 2002. All rights reserved.

Translating Applications
There are three basic steps to translating a Forms application:
1. Construct a translation project.
2. Translate the text.
3. Build the translated software.

Instructor Note
The purpose of this lesson is to introduce students to the capabilities of
TranslationHub, rather than to teach them to use the tool, so there is no formal
demonstration for translating an application.

Oracle9i Forms Developer: New Features 8-19


Constructing a Translation Project

A project is a logical container for strings.


Base project
stores base strings:
Starting point for a
translation project
Can contain one or
more imported Forms modules
Translation projects store translated strings:
Defines language and character settings
Can be updated with base strings

8-20 Copyright Oracle Corporation, 2002. All rights reserved.

The Translation Project


You can think of a project as a logical container for strings, with subcontainers called
applications and modules. TranslationHub projects are divided into two categories:
Base projects store all the original base language strings from the software files.
Translation projects store all the strings for a translation project. Translation projects
also store a copy of the base strings for reference.
From the File menu of TranslationHub, you can create a new project or open an existing
one. Only one project can be open at a time. If you have a project open, TranslationHub
saves and closes that project automatically when you open another one. You can open the
project in shared mode so that multiple translators can work on a project simultaneously.
The first step in translating an application is to create a base translation project in the
language in which the application was developed. You import the strings into the new
project from one or more Forms or Reports modules, which you can optionally group into
logical Application and Module units.
For example, the Summit system might contain many applications, such as Order Entry
and HR. Order Entry might consist of modules such as Customer Orders and Inventory
Management. Each of these modules may comprise several forms, menus, and reports
whose strings you must translate.

Oracle9i Forms Developer: New Features 8-20


Constructing a Translation Project

Create a translation project


from the base project.

8-21 Copyright Oracle Corporation, 2002. All rights reserved.

Constructing a Translation Project (continued)


To begin the translation process, you create a translation project from the base project.
You can do this the same way you created a base project, but there is a more efficient
way: Tools > Update Project. This copies objects from a base project to a translation
project, and you can create new translation projects at the same time by clicking New
Project, selecting the languages for the translation projects, and clicking Create.

Oracle9i Forms Developer: New Features 8-21


Translating the Text

Translate the strings:

*HVXQGKHLW

8-22 Copyright Oracle Corporation, 2002. All rights reserved.

Translating the Text (continued)


With the translation project open, you can use the Attributes view to translate the strings.
The illustration above shows that two strings have been translated (although not very
accurately). You also can use the Terminology view to translate strings.
You can customize the Attributes and the Terminology views by choosing columns to
display and by specifying color coding options.

Oracle9i Forms Developer: New Features 8-22


Building the Translated Software

*HVXQGKHLW

8-23 Copyright Oracle Corporation, 2002. All rights reserved.

Build the Translated Software


TranslationHub does not store all translated strings back into the original Forms module.
A new Forms definition file (.fmb or .mmb) is created for each translated language by
compiling the module in an environment that matches the target language.
Information related to a string label in Forms is kept in the internal string table of each
Forms module. With each new translation language, a new column is added to this string
table. Setting the NLS_LANG variable when compiling creates a .fmx or .mmx file that
is specific to the language. For example, to compile a German application, set
NLS_LANG=GERMAN_GERMANY.WE8ISO8859P1.
To create a translated Forms module from TranslationHub:
Open the translation project.
Select Tools > Build Translated File.
In the Build Translated Files window, choose the files for which to create translated
versions and the directories to use. Click OK.
You can open the translated .fmb or .mmb files in Forms Builder to see that the
translated strings are used.

Oracle9i Forms Developer: New Features 8-23


Summary

In this lesson, you should have learned that:


Oracle9i Forms provides character length semantics:
You can set the Data Length Semantics item
property to CHAR.
This allocates correct Maximum Length and Query
Length for single-byte, multi-byte, and variable-
byte character sets.

8-24 Copyright Oracle Corporation, 2002. All rights reserved.

Summary
Oracle9i Forms enables you to deploy your application globally in:
Any character set, using character length semantics
Any time zone, with automatic adjustment
Any language, using TranslationHub to translate your application and working with
browser language detection to deploy the correct translation
Character length semantics makes it possible to define Maximum Length or Query Length
without manually adjusting the length for single-byte, multi-byte, or variable-byte
character sets. Forms automatically adjusts the storage allocated for the item.

Oracle9i Forms Developer: New Features 8-24


Summary

Oracle9i Forms provides time zone support:


You can define consistent date/times to insert into
the database.
Users will see the date/times displayed for local time
zone.
Implement by setting environment variables for time
zone data file and database server time zone.
You can use [GET|SET]_APPLICATION_PROPERTY
to view or change time zone settings.
Conversion of DATETIME items is automatic.
You can perform manual conversion with
ADJUST_TZ .

8-25 Copyright Oracle Corporation, 2002. All rights reserved.

Summary (continued)
You can implement time zone support in Oracle9i Forms. Forms will automatically adjust
DATETIME items to the client time zone for display on the client, and to a defined
database time zone for insertion into the database.
You set the environment variable FORMS90_DATETIME_SERVER_TZ to specify the
time zone to use for DATETIME items for inserts and updates in the database. Forms uses
a time zone file to perform the conversion, and you specify the location of the file with the
FORMS90_TZFILE environment variable. You can programmatically set the time zone
to use for the client or the database with the SET_APPLICATION_PROPERTY built-in.
Although the time zone conversion is automatic, you can perform it manually if desired
with the ADJUST_TZ built-in.

Oracle9i Forms Developer: New Features 8-25


Summary

You can publish one URL for applications that is


displayed in different languages based on the
browser setting by:
Translating the application
Creating an environment file for each language
Defining named configuration in formsweb.cfg for
each language
Oracle9i TranslationHub enables you to manage
the translation of Forms and Reports modules into
different languages.

8-26 Copyright Oracle Corporation, 2002. All rights reserved.

Summary (continued)
Oracle9i Forms automatically detects the browser language settings on the client running
the application. You can use this feature to deploy applications in different languages
based on the browser setting. You define a named configuration for the application, with
additional configurations of the same name, but with a dot and the two-letter language
abbreviation appended. Each configuration can specify a different environment so that the
application displays in the desired language.
Of course, to deploy applications in different languages, you must first translate the
application into those languages. Oracle9iDS provides the TranslationHub tool to help
you manage such translations.

Oracle9i Forms Developer: New Features 8-26


Practice 8 Overview

This practice covers the following topics:


Implementing character length semantics
Implementing automatic time zone adjustment
Deploying different applications based on browser
preferences
Starting TranslationHub and customizing the UI

8-27 Copyright Oracle Corporation, 2002. All rights reserved.

Practice 8 Overview
In this practice, you implement character length semantics and time zone support for
Forms items. You deploy different applications depending on the language preferences set
in the browser, and you examine the TranslationHub tool.

Oracle9i Forms Developer: New Features 8-27


Practice 8
1. In the Orders form, change the Orders.Order_Mode item to a text item and
implement character length semantics for the Orders.Order_Mode item.

2. If this form runs with a double-byte character set, how many bytes of storage will
now be allocated for the Orders.Order_Mode item? How many characters will the
user be able to enter into the item?

3. Open the Property Palette for the Orders.Order_Date item and set the following
properties (the X Position and Width should have already been set if the JDAPI
program ModifyOrders ran correctly):
Datatype: Datetime
Maximum Length: 20
Initial value: $$dbdatetime$$
Format Mask: DD-MON-RRRR HH24:MI
Query Length: 25
X Position: 340
Width: 95
Click Run Form to run the Orders form and observe the time displayed in the item.
Click Insert and make note of the initial time displayed in the Order_Date item of a
new record. Choose Record > Clear, and click Exit.

Time displayed in first item: ____________________________

Time displayed in new record: ____________________________

4. Implement time zone support for Forms. Set the database time zone to US/Pacific.
Set the PC's time zone to Eastern Time (US & Canada). Click Run Form to run the
form and test the changes. Observe the time adjustment from the default time of
midnight for existing orders. Insert a new record and observe the time that is
displayed as the initial value. Save the new record and make note of the Order ID.

Time displayed in first item: ____________________________

Time displayed in new record: ____________________________

Order ID of new record: ____________________________

5. In SQL*Plus, issue a query to retrieve the Order_Date of the record you just entered.
Format the date as DD-MON-YYYY HH24:MI.

Oracle9i Forms Developer: New Features 8-28


Practice 8 (continued)
6. Add boilerplate text to the Orders form to identify it as the English version of the
form. Create a subdirectory called EN under your lab directory. Save the form to the
EN subdirectory. Generate the form.

7. Change the boilerplate text to read: German version. Create a subdirectory called
DE under your lab directory. Save the form to the DE subdirectory. Generate the
form.

8. Define named configurations [langsupport], [langsupport.en-us], and


[langsupport.de] with the form parameter set to the standard version, the
English version, and the German version, respectively.

9. Open Internet Explorer. Set the browser language to French. Enter the URL for the
Forms Servlet, with the ?config=langsupport parameter. The unmarked
version of the Orders form should appear.

10. Change the language preference to:


German (Germany) [de].
Use the same URL as before to run the form. The form marked German version
should appear.

11. Change the language preference to:


English (United States) [en-us].
Use the same URL as before to run the form. The form marked English version
should appear.

Oracle9i Forms Developer: New Features 8-29


Oracle9i Forms Developer: New Features 8-30
Practice Solutions

Copyright Oracle Corporation, 2002. All rights reserved.


Practice 2 Solutions
1. Make note of information you will need to complete these practices. Your instructor
will supply you with the following:
Item Example Your specific information
Lab directory e:\labs
<ids_home> e:\oracle\ids
User ID ora1
Password oracle
Database iasdb
Solutions e:\labs\soln
directory
Group number 1 (number portion
of your user id)
Machine name Right-click
Network
Neighborhood and
view properties

2. Start an instance of OC4J. Run the form to test the setting.

Start OC4J by double-clicking the startinst.bat desktop shortcut. When


you receive the message Oracle9iAS (9.0.2.0.0) Containers for
J2EE initialized, minimize the DOS window.

3. Open the Customers form in Forms Builder. Set the run-time preferences for Forms
Builder to use OC4J to test your applications. Set the Application Server URL by
pressing Set Default which will enter the following settings:

URL Component Value


M achine nam e <local machine>
OC4J Port 8888 (This is the default port for
OC4J, which m ay be different on
your m achine.)
Pointer to Form s Servlet forms90/f90servlet

Open Forms Builder. Open the Customers form.


From the menu, choose Edit > Preferences.
Select the Runtime tab.
Click Set Default.
Click OK.

Oracle9i Forms Developer: New Features A-2


Practice 2 Solutions (continued)
4. Add a parameter to the run-time preferences. Specify that the Forms application
should open in a separate browser window by setting the separateFrame
parameter to True. Run the form to test the settings.
From the menu, choose Edit > Preferences.
Select the Runtime tab.
Append to the end of the Application Server URL: ?separateFrame=True
Click OK.

Click Run Form to test. When the applet starts, it should open a separate
browser window to display the application.
Click Exit and close the browser windows.

5. Define a named configuration called [summit] that specifies to run the form
summit.fmx with a page title of Summit Application. You should also specify the
connect string and set the separateFrame parameter to True. You can also add
some HTML parameters, such as a background color
(HTMLbodyAttrs=bgcolor="yellow") and some text to appear before and
after the form (HTMLbeforeForm and HTMLafterForm).

Set the Forms Builder preferences to use the named configuration. Run the form to
test the setting.
Hint: You should stop OC4J before modifying the Forms Web configuration file.

Shut down OC4J by double-clicking the stopinst.bat desktop shortcut.

In Notepad, open formsweb.cfg from the


<ids_Home>\forms90\server directory. Scroll to the end of the file and
add the following lines (see formsweb2.cfg in your solutions directory):
[summit]
form=E:\Labs\SUMMIT.fmx
userid=<userid/password@db>
separateFrame=true
pageTitle=Summit Application
HTMLbodyAttrs=bgcolor="yellow"
HTMLbeforeForm=This is the Summit application:<P>
HTMLafterForm=<P>Thanks for using this application!
where <userid/password@db> is the connect string you are using to
connect to the database. For example: userid=ora1/oracle@iasdb
Save the file and close Notepad.

Oracle9i Forms Developer: New Features A-3


Practice 2 Solutions (continued)

Restart OC4J by double-clicking the startinst.bat desktop shortcut.


When you receive the message
Oracle9iAS (9.0.2.0.0) Containers for J2EE initialized,
minimize the DOS window.

In Forms Builder, choose Edit > Preferences.


Select the Runtime tab.

In the Application Server URL, delete the parameter separateFrame=True.


Append: config=summit. The Application Server URL should now read:
http://<machine>:8888/forms90/f90servlet?config=summit
Click OK.

Click Run Form to test that the application appears with the specified
attributes. It will run the Customers form rather than Summit because
Customers is the form that is open and selected in Forms Builder.

6. Create a separate Forms Servlet configuration file called Summit.cfg by copying


the formsweb.cfg file. Delete the named [summit] configuration in
Summit.cfg, and instead specify those values in the main portion of the file. For
example, modify the line that specifies form=test.fmx to
form=e:\Labs\SUMMIT.fmx. Change the HTML body background color to
red so that you can easily see whether the new configuration is being used.

Modify the web.xml configuration file for OC4J so that the new Forms Servlet
configuration file (Summit.cfg) is used.

Set your Forms Builder run-time preferences back to the default. Run the form to
test the setting. Do not close the browser because you will need it open for the next
exercise.
Hint: You should stop OC4J before modifying the OC4J configuration file.

Shut down OC4J by double-clicking the stopinst.bat desktop shortcut.

In Notepad, open formsweb.cfg from the


<ids_Home>\forms90\server directory. Save the file as Summit.cfg.

Oracle9i Forms Developer: New Features A-4


Practice 2 Solutions (continued)

Scroll to the end of the file and delete the following lines:
[summit]
form=E:\Labs\SUMMIT.fmx
userid=<userid/password@db>
separateFrame=false
pageTitle=Summit Application
HTMLbodyAttrs=bgcolor="yellow"
HTMLbeforeForm=This is the Summit application:<P>
HTMLafterForm=<P>Thanks for using this application!

In the main part of the file, edit the default values for form, userid,
separateFrame, pageTitle, HTMLbodyAttrs bgcolor,
HTMLbeforeForm, and HTMLafterForm to be the same as those previously
defined in the named [summit] portion of the file.

Save the file (as Summit.cfg) and close Notepad.

In Notepad, open web.xml from the


forms90/j2ee/forms90app/forms90web/WEB-INF directory.
Edit the following lines:
<!--
<init-param>
<param-name>configFileName</param-name>
<param-value><your configuration file name goes
here></param-value>
</init-param>
-->
Delete the comments lines (<!-- and -->) and substitute <your
configuration file name goes here> with
e:\orahome1\forms90\server\Summit.cfg.
Save the web.xml file and exit Notepad.

Restart OC4J by double-clicking the startinst.bat desktop shortcut.


When you receive the message
Oracle9iAS (9.0.2.0.0) Containers for J2EE initialized,
minimize the DOS window.

In Forms Builder, choose Edit > Preferences.


Select the Runtime tab. Click Set Default. Click OK.

Oracle9i Forms Developer: New Features A-5


Practice 2 Solutions (continued)

Click Run Form to test that the application appears with the specified
attributes. It will run the Customers form rather than Summit because
Customers is the form that is open and selected in Forms Builder.

Exit the form, but leave the browser open for the next exercise.

7. Edit the URL in the browser by deleting all parameters. Open the new URL.

Edit the URL: Delete the "?" and everything to the right of it. The URL should
now be: http://<machine name>:8888/forms90/f90servlet. Run
the URL (click Go or press Enter).

The Forms Servlet should now use all the default values specified in
Summit.cfg, so it should run the Summit form.

Exit the form and the browser.

8. Prepare for subsequent exercises by setting configFileName back to the default.

Shut down OC4J. In web.xml, add back the comments as they were originally
(<! at the beginning and --> at the end) to the section that specifies
configFileName.

Save the file and restart OC4J.

9. From Forms Builder, run the Customers form normally. Click Orders. The Orders
form should appear. Exit the forms and the browser.

No formal solution.

10. Move the Orders form (Orders.fmx) from the lab directory to a temporary directory,
such as e:\temp. You can first create this directory if it does not already exist.
From Forms Builder, run the Customers form again and click Orders. What happens
and why? Exit the Customers form and the browser.

___________________________________________________________________

___________________________________________________________________

You receive the error FRM-40010 Cannot read form orders. This is
because the .fmx file is no longer in the path (FORMS90_PATH) that Forms
Runtime searches to locate needed files.

Oracle9i Forms Developer: New Features A-6


Practice 2 Solutions (continued)
11. Modify the Forms environment to add e:\temp to the search path. Do not use the
Windows Registry to set the environment. Run the Customers form again and click
Orders to test that the Orders form is successfully located. Exit the forms and the
browser.

In Notepad, open <ids_home>\forms90\server\default.env. Append


to the FORMS90_PATH:
;e:\temp
Save the file and close Notepad.

Now when you run Customers from Forms Builder and click Orders, Forms
should successfully locate and run the Orders.fmx file.

Oracle9i Forms Developer: New Features A-7


Practice 3a Solutions
1. Make a new subdirectory of your lab directory called 9iApp to contain applications
to upgrade. Copy the Summit.fmb file from the 6iApp directory to your 9iApp
directory, keeping a copy in 6iApp as a backup. Use the Oracle9i Forms Migration
Assistant to upgrade Summit.fmb to Oracle9i Forms.

a. Copy the file:


Open Windows Explorer. With your lab directory selected, choose File > New >
Folder from the menu. Name the new folder 9iApp. Select the file
Summit.fmb in the 6iApp directory. Holding down the right mouse button,
drag the file to your 9iApp directory. Select Copy Here from the pop-up menu.

b. Run the Migration Assistant:


Open a DOS window. Navigate to your 9iApp directory. Enter the command:
ifplsqlconv90 module=summit.fmb userid=<connect string>
log=<log>
where <connect string> is your database login, such as
ora1/oracle@iasdb, and <log> is a file name of your own choosing.

2. Copy the Orders.fmb and Customers.fmb files in the 6iApp directory to


your 9iApp directory, keeping a copy of each in 6iApp as a backup. Use the
Oracle9i Forms Migration Assistant to upgrade all the .fmb files in your lab
directory to Oracle9i Forms.
Hint: Create a batch file to perform the upgrade.

a. Copy the files:


Open Windows Explorer. Select the files Customers.fmb and Orders.fmb
in the 6iApp directory. Holding down the right mouse button, drag the files to
your 9iApp directory. Select Copy Here from the pop-up menu.
b. Create a batch file to perform the upgrade:
Open your 9iApp directory in Windows Explorer. Right-click in a blank area
of the right pane and select New > Text Document from the pop-up window.
Name the document upgrade.bat. Right-click the document and select Edit
from the pop-up menu. Enter the following text into the document on one line:
for %%f in (%1) do call ifplsqlconv90 module=%%f userid=%2
log=%%f.log
Save the document.
c. Run the batch file:
Open a DOS window. Navigate to your lab directory. Enter the command:
upgrade *.fmb <connect string>, where <connect string> is
your database login, such as ora1/oracle@iasdb.

Oracle9i Forms Developer: New Features A-8


Practice 3a Solutions (continued)
3. Examine the feedback from the upgrade script that is displayed on the screen. You
can also see the feedback in ORDERS.fmb.log. Were any special actions taken by
the Migration Assistant?
Note: The 6i form that you upgraded used RUN_PRODUCT to call a report.

Yes. The feedback shows:


ORDERS.CONTROL.INVOICE_BUTTON.WHEN-BUTTON-PRESSED:
RUN_PRODUCT changed to RP2RRO.RP2RRO_RUN_PRODUCT

This indicates a change made to the When-Button-Pressed code for the


Invoice_Button in the Orders form.

4. If you run the migration utility on the Summit form without specifying a log file
name, a log file called converter.log is generated. Change the default log file
name to my_log.log. Run the utility on the Summit form without specifying a
log file name, as you did in 1b but without the log= parameter. Then check to see
what log file is created.

In WordPad, open the <ids_home>\forms90\converter.properties


file and change the following property:
default.logfilename=my_log.log
Save the file.
In the DOS window, enter the following command:
ifplsqlconv90 module=summit.fmb userid=<connect string>
where <connect string> is your database login.
Examine the directory to see that the file my_log.log was created.

5. Type exit in the DOS window to close it.

No formal solution.

Oracle9i Forms Developer: New Features A-9


Practice 3b Solutions
1. Move the three upgraded forms and the menu from the 9iApp directory to your lab
directory, overwriting any existing files of the same name. If you do not place these
files in the lab directory, Forms will be unable to find some of the files it needs to
run the practice forms. In Forms Builder, open the Orders form from the lab
directory. Examine the code in the When-Button-Pressed trigger of the
Control.Invoice_Button item. Now expand the nodes for Attached Libraries,
Parameters, and Reports. What has been added to the form module?

The upgrade process has attached the library RP2RRO to the form module and
has created a report object called RP2RRO. It has also added eleven
parameters.

2. In Forms Builder, open the RP2RRO library, located in the


<ids_home>\forms90 directory, and examine the package body. The
RP2RRO_RUN_PRODUCT procedure calls the procedure
Handle_rp2rro_run_product. What does this procedure do?

a. Open the library:


In Forms Builder, select File > Open. In the file dialog box, navigate to the
<ids_home>\forms90 directory and select rp2rro.pll to open.

b. Find the procedure:


Expand the Object Library node PL/SQL Libraries > RP2ROO > Program
Units. Double-click the package body to open it. Press [Ctrl-F] to open a
Find and Replace dialog. Enter the string to search for: procedure handle,
and click Find Next. Close the Find and Replace dialog box.

c. Examine the procedure:


The Handle_rp2rro_run_product procedure converts the RUN_PRODUCT
call from the 6i form to RUN_REPORT_OBJECT in the 9i form.

3. With the Orders form selected in the Forms Builder Object Navigator, click Run
Form to run the Orders form. Click Invoice. If you receive FRM-40735 and ORA-
6508 errors or an ORA-907 error, this might indicate that the library needs to be
compiled. Compile the RP2RRO library, save it, then run the form again.

Instructor Note
This practice uses the Reports Server to run reports. Students will use the Reports
Server on the instructor machine. If you have not already done so, you will need to
start the Reports Server on your machine by running the batch file RepSRV.bat,
located in your demo directory.

Oracle9i Forms Developer: New Features A-10


Practice 3b Solutions (continued)
Note: The RP2RRO library included in this course has been slightly modified from
the library installed with Oracle9iDS. The line:
web.show_document(rp2rroVirtualDir||rp2rroReportsInterface||
/getjobid=||rp2rro_jobidFull||?server=||
rp2rroReportServer,_blank);
has been changed to:
web.show_document(rp2rroVirtualDir||rp2rroReportsInterface||
/getjobid||rp2rro_jobidPartial||?server=||
rp2rroReportServer,_blank);

a. Run the form and report:


In Forms Builder with the Orders form selected, click Run Form. When the
form appears, click Invoice to run the report object.
b. Correct the run-time error (if received):
If you receive FRM-40735 and ORA-6508 errors, exit the form and the
browser. In Forms Builder, select the RP2RRO library, then select Program >
Compile Selection. Click Save, then try running the form again to test the
Invoice button. The report should appear in a separate browser window,
showing an invoice for the order in the Orders form.
c. Exit the application:
Close the reports browser window.
In the form , click Exit, then close the forms browser window. (You should do
this after each test in all subsequent practices.)

4. Convert the code in the Invoice button of the Orders form to use a direct call to
RUN_REPORT_OBJECT. A message appears when the report is completed. Use the
report object that was created by the Migration Assistant. Detach the RP2RRO
library from the form and delete all the parameters. Run the form from Forms
Builder to test your changes.

When-Button-Pressed on Control.Invoice_Button (you can import the code


from pr3b_4.pls in the solutions directory when using the PL/SQL Editor by
choosing File > Import PL/SQL Text from the menu):

Oracle9i Forms Developer: New Features A-11


Practice 3b Solutions (continued)

declare
v_repid REPORT_OBJECT;
vc_rep VARCHAR2(20);
vc_rep_status VARCHAR2(20);
BEGIN
v_repid := FIND_REPORT_OBJECT(RP2RRO);
SET_REPORT_OBJECT_PROPERTY(v_repid,REPORT_FILENAME,
order_invoice);
SET_REPORT_OBJECT_PROPERTY(v_repid, REPORT_OTHER,
porder_id= || :orders.order_id);
vc_rep := RUN_REPORT_OBJECT(v_repid);
vc_rep_status := REPORT_OBJECT_STATUS(vc_rep);
WHILE vc_rep_status in (RUNNING, OPENING_REPORT,
ENQUEUED) LOOP
vc_rep_status := report_object_status(vc_rep);
END LOOP;
if vc_rep_status = FINISHED then
message(Report Completed);
else
message(Error when running report.);
end if;
END;

5. Add code to the When-Button-Pressed trigger for the Invoice button to display the
completed report. The name of the Reports Server that you will use is RepSRV.

Run the report by clicking Run Form, then clicking Invoice when the form is
displayed. The report should appear in a separate browser window.

When-Button-Pressed on Invoice_Button (you can import the entire trigger


from pr3b_5.pls in your solutions directory) :

Add the following to the declaration section:


vc_URL VARCHAR2(100);

Add the following right after the message in the first part of the IF statement:
vc_URL := /reports/rwservlet/getjobid
||substr(vc_rep,8)||?server=RepSRV;
Web.show_document(vc_URL);

Oracle9i Forms Developer: New Features A-12


Practice 4a Solutions
1. Install the javadoc for JDAPI and XML tools. The javadoc file, which was
downloaded from OTN, is called javadocJDAPIXML.zip. Unzip the file into
a new labs\javadocJDAPIXML directory.

Open Windows Explorer. Open the Labs directory. Right-click the file
javadocJDAPIXML.zip and from the pop-up menu choose the option
Extract to folder \Labs\javadocJDAPIXML.

2. Navigate to the javadocJDAPIXML directory and double-click the index.html


file to open javadoc in Internet Explorer. Spend some time navigating around the
documentation for both the JDAPI and the XMLTOOLS packages.
No formal solution.

3. Use the javadoc for JDAPI to answer the following questions, then close the javadoc
browser window:

a. What class would you use to access an Attached Library in a Forms module?

_______________________________________________________________

Click the link for the oracle.forms.jdapi package and scroll down to the
Class Summary section of the documentation for that package. You will
see that the class name is AttachedLibrary.

b. What method of that class would you use to find out the location of the
library?

______________________________________________________________

Click the link for the AttachedLibrary. Scroll to the Method Summary
section of the documentation for that class. Scroll through the "get"
methods; you will find the method getLibraryLocation.

c. What data type does that method return?

______________________________________________________________

The left column of the Method Summary is the return data type, which in
this case is java.lang.String.

Close the javadoc browser window.

Oracle9i Forms Developer: New Features A-13


Practice 4a Solutions (continued)
4. In Notepad, write a JDAPI program (a .java file) to modify the Orders form by
changing the X position and the width of the Order_Date item. The new X position
should be 340 and the width should be 95. You should save and compile the
modified form.
Note: To compile this form, you will need to connect the JDAPI session to the
database. Look at the Javadoc for the Jdapi class to discover the methods to call in
order to connect to the database prior to compiling the form and disconnect from the
database after the compilation.
Hint: If you are familiar with Java, try to write this code yourself. However, if you
need help, the ModifyOrders.java file in your solutions directory contains the
code that is needed.

The following example, contained in ModifyOrders.java, will perform the


requested modifications (you will need to edit the database connect string):

import oracle.forms.jdapi.*;
public class ModifyOrders
{
public static void main(String[] args)
{
FormModule fmd = FormModule.open("Orders.fmb");
int xPos = 340; int itemWidth = 95;
JdapiIterator blocks = fmd.getBlocks();
while(blocks.hasNext())
{
Block myBlock = (Block)blocks.next();
if (myBlock.getName().equals("ORDERS"))
{
JdapiIterator items = myBlock.getItems();
while(items.hasNext())
{
Item myItem = (Item)items.next();
if (myItem.getName().equals("ORDER_DATE"))
{
myItem.setXPosition(xPos);
myItem.setWidth(itemWidth);
}}}}
fmd.save("Orders.fmb");
Jdapi.connectToDatabase("ora1/oracle@iasdb");
fmd.compile();
Jdapi.disconnectFromDatabase();
fmd.destroy();
Jdapi.shutdown();
}}

Oracle9i Forms Developer: New Features A-14


Practice 4a Solutions (continued)
5. Compile and run the ModifyOrders class that you have written. You can run the batch
file SetCP.bat to set your CLASSPATH so that the JDAPI classes can be located.

Open a DOS window and navigate to your lab directory.


Set your CLASSPATH by entering the command: SetCP
Compile the Java class by entering the command: javac ModifyOrders.java
Note that Java is case sensitive, so the file name is case sensitive.
Fix compilation errors, if any, and recompile if needed.
Run the program by entering the command: java ModifyOrders

6. Check to see that the Orders form compiled successfully. If an Orders.err file was
created, open it to examine the output. Open the Orders form in Forms Builder to
ensure that the X position and Width properties of Orders.Order_Items have been
modified. Then close all forms in Forms Builder.

No formal solution.

Oracle9i Forms Developer: New Features A-15


Practice 4b Solutions
1. Convert the Customers form to XML. Examine the structure of the XML file. In
WordPad, open xml_structure.txt to help you examine the tree structure of
the XML.

Open a DOS window and navigate to the labs directory. To perform the XML
conversion, do one of the following two choices:

a. Set the CLASSPATH by running the SETCP_xml.bat file (this assumes


that you ran SETCP.bat in the JDAPI exercises; if not, run it first).
Then run the command:
java oracle.forms.util.xmltools.Forms2XML
overwrite=yes customers.fmb
OR
b. Run the convenience script, which sets the CLASSPATH for you and also
calls the Java class to perform the conversion:
iff2xml90 OVERWRITE=YES customers.fmb

2. In the XML file, change the background color of the Account_Mgr_Name item to
red and the foreground color of that item to white.

Open customers_fmb.xml in WordPad. Search for the element:


<Item Name="ACCOUNT_MGR_NAME". Locate the BackColor attribute for
that element and change it to "red". Locate the ForegroundColor attribute for
that element and change it to "white". Save the file.

3. Validate the modified XML file, using the convenience script.

In the DOS window, run the convenience script:


ifxmlv90 customers_fmb.xml
You should receive a message that the form was validated against the Forms
XML Schema.

4. Using the convenience script, convert the XML file back to a .fmb, then open the
form in Forms Builder and run it to test the change. Then close the form in Forms
Builder.
Hint: You will need to connect to the database when you convert this XML to a
.fmb.

In the DOS window, run the convenience script:


ifxml2f90 overwrite=yes userid=ora1/oracle@iasdb
customers_fmb.xml

Oracle9i Forms Developer: New Features A-16


Practice 4b Solutions (continued)

Open the Customers form in Forms Builder. Examine the properties of the
Account_Mgr_Name item to see that the background color is now red. Run the
form and navigate to the Account Information tab to see that the Account
Manager Name item now has a red background and its text appears as white.
Notice that the prompt for the item also appears as white.

Close the Customers form in Forms Builder.

5. The prompt of the Account_Mgr_Name item appears as white because by default it


uses the foreground color for the item. Add a PromptForegroundColor attribute
(after the prompt name) in the XML file to change the color of the prompt to black.
Convert the .xml file to a .fmb. Open the Customers form in Forms Builder and
click Run Form to test the changes, then close the form in Forms Builder.

In the customers_fmb.xml file, add the PromptForegroundColor attribute


to the ACCOUNT_MGR_NAME item as follows:

<Item Name="ACCOUNT_MGR_NAME" ForegroundColor="white"


FontSpacing="Normal" YPosition="38"
FontWeight="Demilight" FontStyle="Plain" XPosition="186"
FontSize="800" FontName="MS Sans Serif" Width="145"
TabPageName="ACCOUNT" CanvasName="TAB_CUSTOMER"
DatabaseItem="false" BackColor="red" ItemType="Display
Item" DirtyInfo="true" PromptAttachmentOffset="5"
Prompt="Name" PromptForegroundColor="black"
Justification="Start" Height="14"/>

In the DOS window, run the convenience script to convert the .xml to a .fmb:
ifxml2f90 overwrite=yes userid=ora1/oracle@iasdb
customers_fmb.xml

Open the Customers form in Forms Builder. Click Run Form and navigate to
the Account Information tab. The prompt for the Account Manager Name
should now be black, while the foreground color (text color) in the item itself
remains white.

Oracle9i Forms Developer: New Features A-17


Practice 4b Solutions (continued)
6. Change the three colors (Foreground Color, Background Color, and Prompt Color)
back to their default values without opening Forms Builder. Then open the form in
Forms Builder to verify that the changes have been made.

You can change these colors back to their default values by deleting the entire
attribute from the item in the .xml file. Then, convert the .xml file to a .fmb,
open it in Forms Builder, and you will see that the values for these attributes
have been set back to <Unspecified> (the default).

7. Create an error in the customers_fmb.xml file by deleting any of the end tags.
For example, delete the final ">" in the section for one of the items. Then validate
the XML to see the errors that appear.

Delete an end tag and save the .xml file.


In the DOS window, enter the command to validate the .xml file:
ifxmlv90 customers_fmb.xml

Errors similar to the following should appear:

file:/E:/Labs/customers_fmb.xml<Line 22, Column 369>:


XML-0190: (Fatal Error) Whitespace required.
file:/E:/Labs/customers_fmb.xml<Line 22, Column 369>:
XML-0201: (Fatal Error) Expected name instead of /.
file:/E:/Labs/customers_fmb.xml<Line 22, Column 369>:
XML-0122: (Fatal Error) = missing in attribute.
file:/E:/Labs/customers_fmb.xml<Line 22, Column 370>:
XML-0125: (Fatal Error) Attribute value should start
with quote.
Invalid XML - file customers_fmb.xml does not validate
against Forms XML Schema: Whitespace required.

Oracle9i Forms Developer: New Features A-18


Practice 4b Solutions (continued)
8. Would you normally need to generate an external Forms Schema file? Under what
conditions would you need to generate such a file?

___________________________________________________________________

___________________________________________________________________

___________________________________________________________________

Forms XML Conversion Utilities use an internal Forms Schema to validate and
parse XML. You would need to generate an external Forms Schema file only if
you are using your own XML software or parser; in this case, the Schema
Generator produces a forms90.xsd file that can be used with such software.

9. Create a file that represents the Forms Schema. Open that file (forms90.xsd) in
WordPad to examine the structure of the Forms Schema, consisting of all the
possible tags that can be used for Forms elements and attributes. Examine the
attributes defined for the Item element. You should see the attributes that you
modified in earlier exercises.

From the DOS window, run the convenience script:


ifxmlsg90

This creates a file called forms90.xsd. Open this file in WordPad. Notice that
the top portion of the file lists all the elements that can be defined in a Form.

Below the list of elements is a list of complex types to provide further details
about the structure of the elements. To view the details about the Item element,
search the file for <complexType name="Item"> .

Look at the list of attributes for the Item element. You should see listed the
attributes that you modified in the customer_fmb.xml file for the
Account_Mgr_Name item: BackColor, ForegroundColor, and
PromptForegroundColor.

Oracle9i Forms Developer: New Features A-19


Practice 5a Solutions
1. Open the Customers form. In this form, there is a procedure that is called
List_Of_Values, which is called by the When-Button-Pressed trigger of
CONTROL.Account_Mgr_LOV_Button. Modify this trigger to misspell the
parameter that passes the LOV name, changing the parameter name to
ACCOUNT_MGR_LO.

When-Button-Pressed on CONTROL.Account_Mgr_LOV_Button:
LIST_OF_VALUES(ACCOUNT_MGR_LO, Account Manager);

2. Click Run Form to run the Customer form. Select the Account Information tab.
Click the LOV button that is to the right of the Account Manager ID. Notice that the
LOV does not appear, and you receive a message that You have just cancelled the
List of Values. Exit the run-time form and close the browser window.

No formal solution.

3. Click Run Form Debug to run the form in debug mode. In Forms Builder, set a
breakpoint in your When-Button-Pressed trigger for the
CONTROL.Account_Mgr_LOV_Button. In the running form, click the Account
Manager LOV button to invoke the debugger. Investigate the call stack. Try
stepping through the code to monitor its progress. Look at the Variables panel to see
the value of the parameters you passed to the procedure, and the value of the p_lov
variable in the procedure. How would this information help you to figure out where
the code was in error?
Hint: You may need to resize the PL/SQL Editor window to see the Debug Console.

In Forms Builder, open the PL/SQL Editor for the When-Button-Pressed


trigger on the CONTROL.Account_Mgr_LOV_Button. Create a breakpoint by
double-clicking the gray area just to the left of the line of code. Click Run Form
Debug.

In the running form, select the Account Information tab and click the
Account_Mgr_LOV_Button. The debugger takes control of the form because
the breakpoint is encountered. The running form now appears as a blank
applet.

In Forms Builder, the Debug Console is displayed. If the Stack panel and the
Variables panel are not shown, click the appropriate icons of the Debug
Console window to display them.

In the Forms Builder toolbar, click Step Into. This adds the List_Of_Values
procedure to the Stack panel. In addition, some variables now appear in the
Variables panel.

Oracle9i Forms Developer: New Features A-20


Practice 5a Solutions (continued)

Resize the Value column of the Variables panel so that you can see the entire
value of the variables. You can see that the p_lov value is incorrect, because as
the developer of the application you know that the list of values is named
ACCOUNT_MGR_LOV, not ACCOUNT_MGR_LO.

Having discovered the problem, you can click Go in the Forms Builder toolbar
to execute the remaining code. Control returns to the running form.

In Forms Builder, click Stop to dismiss the debugger and exit the form. Close
the browser window.

Correct the code in the When-Button-Pressed trigger. You can then run the
form again to retest it.

4. Add a button to the Control block of the Orders form. Place the button on the
CV_Order canvas. Set properties as follows (note that the Icon Filename property is
case sensitive):
Property Value
Name Check_Total_Button
Iconic Yes
Icon Filename check
Keyboard Navigable No
Mouse Navigate No
X Position 295
Y Position 220
Height 17
Width 17

The function of this button is to recheck the Order Total. Write a When-Button-
Pressed Trigger to loop through the records in the Order_Items block and
accumulate the calculated total (price * quantity) in a numeric variable. You should
intentionally make an error when initializing this variable (the intent is to initialize it
to zero, but you type 9 "by mistake").

You can import the code for the trigger from pr5a_4.pls in your solutions
directory.

Run the form, click the Check_Total_Button, and notice that the results are off by
$9.00 when compared with the calculated item labeled Order Total.

Oracle9i Forms Developer: New Features A-21


Practice 5a Solutions (continued)

When-Button-Pressed trigger for Control.Check_Total_Button:


declare
vn_total number(10,2) := 9;
this_block varchar2(20) := :system.cursor_block;
this_item varchar2(50) := :system.cursor_item;
begin
go_block(order_items);
while :order_items.product_id is not null loop
vn_total := vn_total +
nvl(:order_items.unit_price,0) *
nvl(:order_items.quantity,0);
next_record;
end loop;
go_block(this_block);
go_item(this_item);
message(The order total should be
||to_char(vn_total,$9,999,999.99));
end;

5. Set a breakpoint at the variable declaration of the When-Button-Pressed trigger for


Control.Check_Total_Button.

Run the form in Debug mode and click the button. When the Debug Console is
invoked, Look at the variable value in the Variables panel of the Debug Console.

As soon as the variable is initialized at 9, change the value of the variable to zero in
the Variables panel of the Debug Console before stepping into subsequent code.

The code should use the corrected value and the correct result should be displayed
on the message line. This indicates that the variable initialization is what should be
corrected in the code.

Stop the debug session. Correct the code and run the form normally to test.

Corrected code: vn_total number(10,2) := 0;

6. Sales representative Janette King is using a query form to find out what
commissions she has earned. She calls the Help Desk because the form is under
calculating her commissions. Pair up with someone using another PC. Designate one
PC as the Help Desk PC and the other as Janettes PC. Perform the following:

Oracle9i Forms Developer: New Features A-22


Practice 5a Solutions (continued)
Janettes PC:
A. Run the query form using the Help Desk PC as the middle tier. In your
browser, enter the URL:
http://<machine>:<port>/forms90/f90servlet?form=e:\labs\
debug_practice\practice6a_6.fmx&userid=<connect string>
where <machine> and <port> are the machine and OC4J port of the Help
Desk PC, and <connect string> is your own connect string.
B. When the form appears, click Calculate Commission. The commission for the
displayed employee calculates correctly.
C. Press [Down Arrow] until the employee Janette King is displayed. Click
Calculate Commission. The commission is calculated incorrectly.
D. Scroll down and click Debug. The host and port to which the Help Desk must
attach is displayed.
Help Desk PC:
A. In Forms Builder, open the form:
e:\labs\debug_practice\practice6a_6.fmb.
B. From the menu, select Debug > Attach Debug. The Attach Debug dialog
appears.
C. Enter the Host and Port information that is displayed on the User PC.
D. Set a breakpoint on the When-Button-Pressed trigger for the Calc_Comm
button. Set the breakpoint on the first line after the BEGIN statement.
Janettes PC:
A. Click OK to dismiss the display of Host and Port information.
B. Recalculate Janette Kings commission by pressing Calculate Commission.
The execution of your form is suspended while control passes to the debugger.
The applet may go blank at this point.
Help Desk PC:
A. The Debug Console appears. Open the PL/SQL Packages and the Form Values
panels. Expand the Employees block in the Form Values panel so that you can
see the value of items in the Employees block.
B. Click Step Into to step into the code until you execute the line:
:orders.commission := :comm.get_comm;
This steps into the Comm package to execute the Get_Comm function.
C. Look at the PL/SQL Packages panel to take note of the value of the package
variable vn_emp_comm, which will be used in the calculation. Note that it is
still set to the value of the commission of the employee displayed when the
button was first pressed.
D. Click Go to execute the rest of the code.
E. In the PL/SQL Packages panel, change the value of the package variable
vn_emp_comm to the value of the current employees commission percent:
.35.

Oracle9i Forms Developer: New Features A-23


Practice 5a Solutions (continued)
Janettes PC: Click Calculate Commission again.
Help Desk PC:
A. Click Go to execute all the code. The correct commission should now appear
on Janettes PC.
B. Click Stop to end the debugging session.

C. The problem with the form is that the PL/SQL package variable
vn_emp_comm is set when the package is first instantiated. This variable was
set to the commission percent for the employee displayed the very first time
Janette clicked Calculate Commission. In order for the value to change with
each execution of the package, the variable should be set in the package body,
not the package specification.
D. Open the PL/SQL Editor for the package specification and change the variable
declaration for vn_emp_comm to initialize the value to 0.
E. Open package body and add the following line right after the BEGIN
statement:
vn_emp_comm := :employees.commission_pct;
F. Generate the form by pressing [Ctrl-T].
Janettes PC:
A. Edit the URL in the browser to delete &debug and the host and port
information at the end of the URL. Run the form again by pressing Enter.
B. Test that the problem has been fixed by pressing Calculate Commission for the
first employee that appears, and again for Janette King. Verify that Janettes
commission is now calculated correctly.

Oracle9i Forms Developer: New Features A-24


Practice 5b Solutions
1. Configure Forms to enable Forms Trace:

a. Define an event set called info that will record information about triggers
and tabbed pages.

In WordPad, open <ids_HOME>\forms90\trace\ftrace.cfg.


At the end of the file, add the following line:
info: 45,66
Save and close the file

b. Set the logging path for Forms Trace to the directory where ftrace.cfg is
located.

In WordPad, open <ids_HOME>\forms90\server\default.env.


Uncomment the setting for FORMS90_TRACE_PATH and set it to the
directory where ftrace.cfg is located:
FORMS90_TRACE_PATH=<ids_HOME>\forms90\trace
For example:
FORMS90_TRACE_PATH=d:\oracle\iDS\forms90\trace
Save and close the file.

2. Define a named configuration called info where you specify that a Forms Trace
should occur, using the info event set and logging the information to a file called
info.log.

In WordPad, open <ids_HOME>\forms90\server\formsweb.cfg.


Scroll to the end of the file and add the following lines:
[info]
otherparams=record=forms tracegroup=info log=info.trc

3. In Forms Builder, set run-time preferences to use the named configuration.

From the Forms Builder menu, choose Edit > Preferences.


Click the Runtime tab.
Append the following to the end of the Application Server URL:
?config=info

4. In Forms Builder, open the Customers form and click Run Form to run it. Click the
tabs to display all the items in the running form. Exit the form run-time session and
close the browser.

No formal solution.

Oracle9i Forms Developer: New Features A-25


Practice 5b Solutions (continued)
5. Move the trace file to your lab directory and convert it into XML. You can run the
batch file SETCP_xlate.bat to set the CLASSPATH for the translate utility.
Ignore the error that appears about the collection ID.

Using Windows Explorer, drag info.trc from the forms90\trace


directory to your lab directory.
Open a DOS window and navigate to your lab directory.
To set the CLASSPATH, enter the command:
SETCP_xlate
To convert the trace file to XML, enter the command:
java oracle.forms.diagnostics.Xlate datafile=info.trc
xmlfile=info.xml
Exit the DOS window.

6. Examine the XML file to see the triggers that executed and the tabbed pages that
you clicked in the running form.

Open the info.xml file in WordPad.


Observe that the information between the tags <TRIGGER.START and
</TRIGGER.START> provides details about triggers that fired.
Observe that the information between the tags <TAB_PAGE_CHANGED and
</TAB_PAGE_CHANGED> provides details about tabbed pages that were
clicked.

7. From Forms Builder, enable Servlet session logging. Click Run Form to run the
Customers form. Shut down OC4J and examine the Servlet log to see what
information is recorded with session logging.

In the Forms Builder menu, choose Edit > Preferences, and click the Runtime
tab.
Modify the Application Server URL:
Delete the ?config=info parameter
Append the following:
?serverURL=/forms90/l90servlet/session
Click OK.
With the Customers form selected in the Object Navigator, click Run Form.
When the form appears, exit the form.
Shut down OC4J by double-clicking the shortcut to stopinst.bat.
In WordPad, open the file
<iDS_HOME>\j2ee\Oracle9iDS\application-deployments\
forms\application.log.

Scroll to the end of the file to view the server name, client IP address, and
process ID for the Forms Runtime process.
Oracle9i Forms Developer: New Features A-26
Practice 5b Solutions (continued)
8. To disable Servlet logging, set your preferences back to default. Restart OC4J.

In the Forms Builder menu, choose Edit > Preferences, and click the Runtime
tab. Click Set Default.
Start OC4J by double-clicking the shortcut to startinst.bat.

Oracle9i Forms Developer: New Features A-27


Practice 6 Solutions
1. In the Layout Editor for the Customer_CV canvas, create a bean area called
Hyperlink in the Control block of the Customers form. Place the bean above the
Customer Information boilerplate text. The bean area should not have a bevel. Set its
background color to be the same as the background color of the canvas. At this
point, the bean should appear as a gray area on the canvas as shown in the following
screenshot:

In the Object Navigator, double-click the Customer_CV canvas to open the


Layout Editor. Select the Control block from the Block pop-up list.
Select the Bean Area tool and drag out a rectangular area in the top center
portion of the canvas.

Double-click the bean area to invoke its Property Palette. Set the Name
property to HYPERLINK. Set the Bevel property to None. Set the Background
Color property to a color of your choosing. Copy to the clipboard the value of
the Background Color.

Right-click a blank area of the canvas and select Property Palette from the pop-
up menu. In the Property Palette for the canvas, set the Background Color to be
the same as the one you chose for the Bean Area by pasting the copied value.

2. Add code to the Customers form to register the bean at form start-up and to enable
an actionListener. The class is oracle.forms.demos.beans.Hyperlink (this is
case-sensitive). The bean should be labeled "Forms on OTN" and should invoke the
Forms Web page (http://otn.oracle.com/products/forms).

When-New-Form-Instance trigger on Customers form (you can import the code


from pr6_2.pls in your solutions directory):
declare
hHyperlink ITEM := FIND_ITEM(CONTROL.HYPERLINK);
begin
FBean.Register_Bean(hHyperlink,1,
oracle.forms.demos.beans.Hyperlink);
FBean.Invoke(hHyperlink,1,setURL,
http://otn.oracle.com/products/forms);
FBean.Invoke(hHyperlink,1,setLabel,Forms on OTN);
FBean.Enable_Event(hHyperlink,1,actionListener,true);
execute_query;
end;

Oracle9i Forms Developer: New Features A-28


Practice 6 Solutions (continued)
3. Code the action you want to perform when the user clicks the bean, which is to
invoke the beans URL in a separate browser window. Click Run Form to run the
Form and test the function of the hyperlink.
Hint: You first need to get the URL from the bean, then use
web.show_document to invoke it.

When-Custom-Item-Event trigger on Control.Hyperlink (you can import the


code from pr6_3.pls in your solutions directory):
declare
vcEventData VARCHAR2(256 char);
begin
vcEventData := Fbean.Invoke_Char(Control.hyperlink,
1,getURL);
Web.Show_Document(vcEventData,_blank);
end;
4. In the Customers form, create a bean area in the CONTROL block and name it
Colorpicker. This bean has no visible component on the form, so set it to display as
a tiny dot in the upper left corner of the canvas. Make sure that users cannot
navigate to the bean area item with either the keyboard or mouse.

Display the Layout Editor and make sure that the block is set to CONTROL.
Select the Bean Area tool and drag out a bean area on the canvas.
Set the NAME to COLORPICKER.
Set X Position and Y Position to 0.
Set Width and Height to 1.
Set Keyboard Navigable and Mouse Navigate to No.

5. Create a button on the CV_CUSTOMER canvas to enable the user to change the
canvas color using the ColorPicker JavaBean. Place the button just above the Orders
button.
Set the following properties on the button:
Label: Canvas Color Mouse Navigate: No
Keyboard Navigable: No Background color: gray

The button should call a procedure named PickColor, which invokes the bean and
translates the comma-separated color values of the bean to the RGB values used by
PL/SQL. You can import the code from the the pr6_5.pls file in your solutions
directory.

Oracle9i Forms Developer: New Features A-29


Practice 6 Solutions (continued)
Create a procedure under the Program Units node of the Object Navigator.
Name the procedure PickColor. With the PL/SQL Editor open, select File >
Import Text, and import pr6_5.pls from your solutions directory. The code
for the PickColor procedure is:

PROCEDURE PickColor(pvcTarget in VARCHAR2) IS


vcOldColor VARCHAR2(12 char);
vcNewColor VARCHAR2(12 char);
hCanvas CANVAS := FIND_CANVAS(CV_CUSTOMER);
hColorPicker ITEM := FIND_ITEM(CONTROL.COLORPICKER);
vnPos1 NUMBER;
vnPos2 NUMBER;
BEGIN
-- First get the current Color for this target
vcOldColor := get_canvas_property(hCanvas,background_color);
vnPos1 := instr(vcOldColor,g,1);
vnPos2 := instr(vcOldColor,b,vnPos1 + 1);
vcOldColor := substr(vcOldColor,2,vnPos1 - 2)||
||substr(vcOldColor,vnPos1+1,vnPos2 - vnPos1 -1)||
||substr(vcOldColor,vnPos2 + 1,length(vcOldColor)-
vnPos2);
-- now display the picker with that color as an initial value
vcNewColor := FBean.Invoke_char(hColorPicker,1,
showColorPicker, "Select color for ||pvcTarget||",
"||vcOldColor||");
-- finally if the selected color is not null
-- reset the Canvas property
if (vcNewColor is not null) then
vnPos1 := instr(vcNewColor, ,1);
vnPos2 := instr(vcNewColor, ,vnPos1 + 1);
vcNewColor := r||substr(vcNewColor,1,vnPos1 - 1)||
g||substr(vcNewColor,vnPos1+1,vnPos2 - vnPos1 -1)||
b||substr(vcNewColor,vnPos2 + 1,length(vcNewColor)-
vnPos2);
set_canvas_property(hCanvas,background_color,vcNewColor);
end if;
END;

Create a button in the CONTROL block called Color_Button on the


CV_CUSTOMER canvas, setting its properties as specified in the instructions.

Define a When-Button-Pressed trigger for the button:


PickColor(Canvas);

Oracle9i Forms Developer: New Features A-30


Practice 6 Solutions (continued)
6. In the Customers form, register the ColorPicker bean (making its methods available to
Forms) when the form first opens. The full path to the bean is:
oracle.forms.demos.beans.ColorPicker (this is case sensitive).

Add the following code to the When-New-Form-Instance trigger on the


Customers form:
FBean.Register_Bean(control.colorpicker,1,
oracle.forms.demos.beans.ColorPicker);

7. Click Run Form to run your form and test the Color button. You should be able to
invoke the ColorPicker bean from the Color button, now that the bean has been
registered at form startup.

No formal solution.

8. In the Orders form, use the Rollover Button PJC to change the look of the buttons on
the Toolbar canvas to be rounded buttons. Set the Implementation Class property of
the toolbar buttons (Control block buttons Invoice_Button, Image_Button,
Stock_Button, Show_Help_Button, and Exit_Button) to:
oracle.forms.demos.enhancedItems.RolloverButton.
To implement the rounded button look, surround the label of the buttons with
parentheses, for example, (Invoice). Click Run Form to run the form and test the
changes. At run time, the buttons should have rounded ends like the following
screenshot:

No formal solution.

Oracle9i Forms Developer: New Features A-31


Practice 6 Solutions (continued)
9. Change the Exit button in the Orders form to be a rollover button by setting its Label
property to [ROLLOVER]exit (note that this is case sensitive and must be typed
exactly as shown). Change the Height and Width properties of the button to 30. Set the
Height of the Toolbar_CV canvas to 40 to accommodate the larger button. Align the
centers of all the toolbar buttons. Click Run Form to run the form and test the changes.
At run time, the buttons should appear like the following screenshot, and moving the
mouse over the Exit button should change its image.

No formal solution.

10. In the Orders form, implement client-side validation on the ORDER_ITEMS.Quantity


item using a Pluggable Java Component to filter the keystrokes and allow only
numeric values.

The full path to the PJC class is oracle.forms.demos.KeyFilter (this is case


sensitive), to be used as the Implementation Class for the item. When the Orders form
first opens, set a filter on the ORDER_ITEMS.Quantity PJC.

Open the Property Palette for the :ORDER_ITEMS.Quantity item. Set the
Implementation Class property to: oracle.forms.demos.KeyFilter

When-New-Form-Instance at form level:


SET_CUSTOM_PROPERTY(order_items.quantity,1,
FILTER_TYPE,NUMERIC);
GO_BLOCK(ORDERS);
DO_KEY(EXECUTE_QUERY);

11. Run the Orders for to test the changes. Try to enter alphabetic characters into the
Order_Items.Quantity item. You should be able to enter only numeric data.

No formal solution.

Oracle9i Forms Developer: New Features A-32


Practice 7 Solutions
1. Because there is no table in the sample data that returns a large number of rows,
create an LOV called Cartesian_LOV in the Customers form whose record group,
called Cartesian_RG, performs a Cartesian join of the CUSTOMERS and the
ORDERS tables. Define the query for the record group as follows (you can import
the query from pr7_1.sql in your solutions directory):
SELECT CUSTOMERS.CUST_LAST_NAME,
ORDERS.ORDER_ID
FROM CUSTOMERS, ORDERS
ORDER BY CUSTOMERS.CUST_LAST_NAME
Set the Filter Before Display property for the LOV to Yes and set Height to 200.

In the Object Navigator, select LOVs and click Create. The New LOV window
appears. Click OK to use the LOV Wizard.
In the LOV Wizard, click Next to display the Record Group definition window.
Click Import SQL Query, and select pr8_1.sql from the soln directory.
Click Next.
Click >> to use both columns. Click Next twice to display the Window definition
window.
Give the LOV a title of Cartesian LOV. Click Finish.
In the Object Navigator, rename the LOV and the Record Group to
Cartesian_LOV and Cartesian_RG.
Open the Property Palette for the LOV. Set the Filter Before Display property
to Yes. Set the Height property to 200.

2. Create a Control block button on the Customer_CV canvas to display the LOV.
Name the button Long_LOV_Btn, with the label Long LOV. Place the button just to
the left of the Canvas Color button.

When-Button-Pressed trigger for Control.Long_LOV_Btn (you can import the


code from pr7_2.pls in your solutions directory) :
declare
v_lov BOOLEAN;
begin
v_lov := show_lov(cartesian_lov);
end;

Oracle9i Forms Developer: New Features A-33


Practice 7 Solutions (continued)
3. Click Run Form to run the form. Click Long LOV to invoke the LOV. Enter % in
the Find box so that all records will be retrieved, and click Find. What is the
behavior of the LOV?

The LOV returns all records. If you click Cancel because it is taking an
excessive amount of time, the LOV still returns all the records before it is
canceled. There is no feedback to the user about the process that is occurring,
so the user may think that the application is hanging.

4. In the Customers form, set the Interaction Mode property of the form to Non-
Blocking. Run the form again and click Long LOV to invoke the LOV. Enter % in
the Find box so that all records will be retrieved, and click Find. What is the
behavior of the LOV now?

After an initial pause, the LOV displays a message telling the user the number
of records being retrieved. Because this number is constantly updated, the user
realizes that processing is occurring and that the application is not hanging. If
the user clicks Cancel, record retrieval stops and the user can work with the set
of records that has been retrieved to that point.

5. In the Orders form, create a Control block button on the Toolbar canvas. Set the
name of the button to About_Btn, its label to (About), and its implementation class
to oracle.forms.demos.enhancedItems.RolloverButton. The code
for this button should display the Forms version in a message. Run the form to test
the button.

When-Button-Pressed trigger for Control.About_Btn (you can import the code


from pr7_5.pls in your solutions directory) :
message(The Forms version is: ||
GET_APPLICATION_PROPERTY(version));

Oracle9i Forms Developer: New Features A-34


Practice 7 Solutions (continued)
6. Users of the Customers form are complaining. They press the Orders button, and the
Orders form displays the orders for the customer in the Customers form. However,
after entering the Orders form, they would like to be able to query orders for other
customers.
To make this possible, change the When-New-Form-Instance trigger in the Orders
form to enable users to execute a second query on the Orders block that is not
restricted to the current Customer_ID from the Customers form. You must also
delete the Pre-Query trigger on the Orders block, where the original functionality is
implemented.

When-New-Form-Instance on Orders form (you can import the text from


pr7_6.pls in your solutions directory):
if :global.customer_id is not null then
set_block_property(orders,onetime_where,customer_id =
||:global.customer_id);
end if;
SET_CUSTOM_PROPERTY(order_items.quantity,1,
FILTER_TYPE,NUMERIC);
go_block(orders);
do_key(execute_query);

Delete the Pre-Query trigger on the Orders block.

With the Orders form selected, press [Ctrl-T] to generate it.

7. Run the Customers form to test the changes.

With the Customers form selected in the Object Navigator, click Run Form.

In the Customers form, click Orders. The Orders form should initially display
orders only for the customer whose record is displayed in the Customers form.

In the Orders form, press Execute Query. All orders should now be displayed.

Oracle9i Forms Developer: New Features A-35


Practice 8 Solutions
1. In the Orders form, change the Orders.Order_Mode item to a text item and
implement character length semantics for the Orders.Order_Mode item.
Invoke the Property Palette for the Orders.Order_Mode item. Set its Item
Type to Text Item and its Data Length Semantics property to CHAR.

2. If this form runs with a double-byte character set, how many bytes of storage will
now be allocated for the Orders.Order_Mode item? How many characters will the
user be able to enter into the item? Change Orders.Order_Mode back to a check
box when you are finished answering the question.

The Maximum Length property for Orders.Order_Mode is set to 8. Using


character length semantics with a double-byte character set, 16 bytes of
storage will be allocated for the item. The user will still be able to enter only 8
characters of data into the item.

Change the Item Type for Orders.Order_Mode back to Text Item.

3. Open the Property Palette for the Orders.Order_Date item and set the following
properties (the X Position and Width should have already been set if the JDAPI
program ModifyOrders ran correctly):
Datatype: Datetime
Maximum Length: 20
Initial value: $$dbdatetime$$
Format Mask: DD-MON-RRRR HH24:MI
Query Length: 25
X Position: 340
Width: 95
Click Run Form to run the Orders form and observe the time displayed in the
item. Click Insert and make note of the initial time displayed in the Order_Date
item of a new record. Choose Record > Clear, and click Exit.

Time displayed in first item: ____________________________

Time displayed in new record: ____________________________

No formal solution.

Oracle9i Forms Developer: New Features A-36


Practice 8 Solutions (continued)
4. Implement timezone support for Forms. Set the database time zone to US/Pacific.
Set the PCs time zone to Eastern Time (US & Canada). Click Run Form to run
the form and test the changes. Observe the time adjustment from the default time
of midnight for existing orders. Insert a new record and observe the time that
appears as the initial value. Save the new record and make note of the Order ID.

Time displayed in first item: ____________________________

Time displayed in new record: ____________________________

Order ID of new record: ____________________________

Implement timezone support:


In WordPad, open the <ids_HOME>\forms90\server\default.env file.
Scroll to the end of the file, and uncomment the following lines, which were
added for you during the setup for this course:
FORMS90_DATETIME_SERVER_TZ=US/Pacific
FORMS90_TZFILE=d:\oracle\iDSv2\oracore\zoneinfo\timezone.dat
If the path to the timezone file is different for your setup, adjust it in the
above line.

Set the PCs time zone to (GMT-5:00) Eastern Time (US & Canada):
Double-click the time displayed in the lower right corner of the Task Bar on
your PC desktop. The Date/Time Properties window appears. Click the Time
Zone tab.
If you have permission to change the browser settings, select from the drop-
down list:
(GMT-5:00) Eastern Time (US & Canada)
If you are not able to change the browser settings, you can add the
environment variable FORMS90_DATETIME_LOCAL_TZ to the
default.env file: FORMS90_DATETIME_LOCAL_TZ=US/Eastern

Run the form to test the changes:


When you specify that Forms should treat the database time as US/Pacific,
and the PC time zone is set to US/Eastern, Forms should add 3 hours to the
database time for the item to appear correctly in the time zone of the client
browser. Thus the default time of midnight in existing records should appear
as 3:00 AM. The time displayed as the initial value of the Order_Date item
should be 3 hours later than the current time in the US/Pacific time zone.

Oracle9i Forms Developer: New Features A-37


Practice 8 Solutions (continued)
5. In SQL*Plus, issue a query to retrieve the Order_Date of the record you just
entered. Format the date as DD-MON-YYYY HH24:MI.

Issue the following SQL*Plus query:


SELECT TO_CHAR(Order_Date,DD-MON-YYYY HH24:MI)
FROM Orders WHERE Order_ID = <n>;
(where <n> is the Order ID of the record you just inserted).

You should see that the record was saved to the database with the time in the
database time zone, 3 hours earlier than the time that appeared in your
browser. Note that it does not matter where the database is actually located;
it could be in any time zone, but the date is saved in the time zone defined by
FORMS90_DATETIME_SERVER_TZ in the default.env file.

6. Add boilerplate text to the Orders form to identify it as the English version of the
form. Create a subdirectory called EN under your lab directory. Save the form to
the EN subdirectory. Generate the form.

No formal solution.

7. Change the boilerplate text to read: German version. Create a subdirectory called
DE under your lab directory. Save the form to the DE subdirectory. Generate the
form.

8. Define named configurations [langsupport], [langsupport.en-us],


and [langsupport.de] with the form parameter set to the standard version,
the English version, and the German version respectively.

In WordPad, open formsweb.cfg. Scroll to the bottom of the file and add the
following lines:
[langsupport]
form=<lab directory>\orders.fmx
[langsupport.en-us]
form=<lab directory>\en\orders.fmx
[langsupport.de]
form=<lab directory>\de\orders.fmx
(where <lab directory> is the path to your lab directory.

Oracle9i Forms Developer: New Features A-38


Practice 8 Solutions (continued)
6. Add boilerplate text to the Orders form to identify it as the English version of the
form. Save the form to the EN subdirectory of your lab directory. Generate the
form.

No formal solution.

7. Change the boilerplate text to read: German version. Save the form to the DE
subdirectory of your lab directory. Generate the form.

8. Define named configurations [langsupport], [langsupport.en-us],


and [langsupport.de] with the form parameter set to the standard version,
the English version, and the German version respectively.

In WordPad, open formsweb.cfg. Scroll to the bottom of the file and add the
following lines:
[langsupport]
form=<lab directory>\orders.fmx
[langsupport.en-us]
form=<lab directory>\en\orders.fmx
[langsupport.de]
form=<lab directory>\de\orders.fmx
(where <lab directory> is the path to your lab directory.

9. Open Internet Explorer. Set the browser language to French. Enter the URL for
the Forms Servlet, with the ?config=langsupport parameter. The
unmarked version of the Orders form should appear.

To set the browser language in Internet Explorer, select Tools > Internet
Options from the menu. The Internet Options window appears. Click
Languages. The Language Preference window appears. If the French
(France) [fr] language is not listed, add it by clicking Add and selecting
it from the Add Language window, then click OK.

Oracle9i Forms Developer: New Features A-39


Practice 8 Solutions (continued)
In the Language Preference window, delete any other languages by selecting
each in turn and clicking Remove. Click OK to close the Language
Preferences window. Click OK to close the Internet Options window.

Enter the following URL in the address bar of the browser:


http://<machine name>:8888/forms90/f90servlet
?config=langsupport
The unmarked version of the Orders form should appear.

10. Change the language preference to:


German (Germany) [de].
Use the same URL as before to run the form. The form marked German version
should appear.

No formal solution.

11. Change the language preference to:


English (United States) [en-us].
Use the same URL as before to run the form. The form marked English version
should appear.

No formal solution.

Oracle9i Forms Developer: New Features A-40


Integrating Oracle9i Forms with
Oracle9i Application Server

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features B-1


Objectives

After reviewing this appendix, you should be able to


do the following:
Describe using Oracle Enterprise Manager to
manage Forms Services
Explain how to implement Single Sign-on for
Forms applications

B-2 Copyright Oracle Corporation, 2002. All rights reserved.

Appendix Aim
This appendix describes how to leverage the Oracle Enterprise Manager and Oracle
Internet Directory components of Oracle9i Application Server to manage Forms Services
and to enable single sign-on.

Oracle9i Forms Developer: New Features B-2


Managing Forms Services with OEM

OEM has two different UIs:


Enterprise Manager Web site: HTML-based tool
that enables viewing targets on a single node
Java-based console required for:
Registering events
Viewing discovered targets on multiple nodes
within a single navigator (OEM navigation list)
With OEM you can:
Monitor metrics for Forms Services and users
Stop user sessions
Add or edit named configurations in
formsweb.cfg

B-3 Copyright Oracle Corporation, 2002. All rights reserved.

Managing Forms Services with Oracle Enterprise Manager


Oracle9iAS supplies two user interfaces for the Enterprise Manager:
Enterprise Manager Web site, an HTML-based tool that you can access from any
browser and use for the following purposes:
- Monitoring metrics for a 9iAS Forms Services instance and user sessions, such
as CPU and memory usage
- Terminating user sessions
- Configuring parameters for a 9iAS Forms Services instance
A Java-based console that you install on a client and launch from the command line,
which is used to:
- Register events
- Monitor CPU usage and memory usage events for multiple 9iAS Forms
Services instances

Oracle9i Forms Developer: New Features B-3


OEM: System Components Page
1 3

4 5 6

B-4 Copyright Oracle Corporation, 2002. All rights reserved.

The Oracle Enterprise Manager System Component Page


When you drill down on a single 9iAS instance from the HTML-based tool, the System
Components page appears. From this page you can:
1. Start and restart the 9iAS instance.
2. View information about the host where 9iAS is running: Hardware platform,
operating system, number of users logged on to the machine, and so on.
3. View Application Server metrics: CPU and memory usage.
4. View a list of components that have been configured for OEM.
5. View the status of each displayed component. For Forms Services, the green check
means that Forms Services is installed and configured, and the Application Server is
up and running.
6. Start and stop a selected component. For Forms Services, these buttons have no
effect because the servlet container performs these functions automatically.

Oracle9i Forms Developer: New Features B-4


OEM: Forms Services Management Page
Status

B-5 Copyright Oracle Corporation, 2002. All rights reserved.

The Oracle Enterprise Manager Forms Services Management Page


From the OEM Forms Services page, you can see information about:
Status: Up means Application Server instance is running and Forms Services is
installed and configured.
Configuration: The URL and port for the servlet and the ORACLE_HOME where
Forms Services is installed
Load: CPU and memory usage and number of sessions for the Forms Services
instance
Response: Average time, in milliseconds, for the Forms sessions to connect to the
Forms Listener Servlet
Administration:
- Session details: View information about each Forms session, including process
ID of the run-time process, CPU and memory usage, IP address, database user
name, and date/time when the user connected; terminate individual sessions
- Forms Services Configuration: Ability to add new named configuration
sections to the formsweb.cfg file, delete existing named configurations, and
add or delete parameters to existing sections. Changes affect users connecting
after modification, not currently running sessions.

Oracle9i Forms Developer: New Features B-5


Integrating Forms with Single Sign-On

Why use SSO?


Web users access many applications; where is
their account information stored?
SSO capability comes with Oracle9iAS
Provides secure single entry to all applications
No additional coding required
A typical
users
password
store

Secure?

B-6 Copyright Oracle Corporation, 2002. All rights reserved.

Integrating Forms with Single Sign-On


Why Use Single Sign-On?
The Web provides users access to many more applications than are available to those
using just client/server. Often users must maintain a separate user name and password for
each application they access.
Where do they store information about these multiple accounts? Typically, users keep
their passwords stored on Post-It notes or in PDAs, often right next to their computers, or
in a file on the computer itself, like the Excel spreadsheet shown above. Maintaining
multiple accounts and passwords for each user is expensive, insecure, and most of all,
impractical.
Using Single Sign-On eliminates the need for users to remember multiple passwords
because they must only log in once. Moreover, no additional coding is required in your
Oracle9i Forms application modules.
Oracle9i Forms can use the authentication services provided by mod_osso included with
Oracle9iAS, which is integrated with the Oracle Internet Directory (OID) and is LDAP-
compatible. Everything that must be done to make Forms Services work with OID is
performed by the Oracle9iAS installer.

Oracle9i Forms Developer: New Features B-6


Oracle9i Forms SSO Architecture

Oracle 9iAS

1 Forms Runtime Engine


Oracle HTTP Server
powered by Apache
mod_osso Oracle9i DB
Forms Listener Servlet

Forms Servlet 5
2

Oracle9i
3 Oracle9i Single 4 Internet
SignOn Server
Directory

B-7 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms SSO Architecture


Forms Services uses the following 9iAS components when performing single sign-on:
1. The Oracle HTTP Server powered by Apache allows additional services components
to be linked in as modules.
2. The mod_osso is a new Oracle module that enables the Oracle HTTP Server for
Single Sign-On (SSO). Mod_osso is a partner application to Oracle9i Single
SignOn Server. Theoretically, any Web application can be SSO-enabled by using
mod_osso, which intercepts the HTTP requests and makes sure that users are
authenticated before they can access protected URLs.
3. The Oracle Single SignOn Server (SSO Server) is used to authenticate a user. It
checks the user credentials against those stored in the Oracle Internet Directory.
4. The Oracle Internet Directory (OID) provides a manageable password store for all
Oracle products to use. You create a lightweight user and password in OID (requires
that you have an OID administrator account), and map that to a list of all
applications and login information that you want to use with single sign-on.
5. The Forms Servlet knows how to handle decrypting the mod_osso authentication
cookie and retrieve the single sign-on name from it.

Oracle9i Forms Developer: New Features B-7


The Oracle9i Forms SSO Process

Oracle 9iAS
Forms Runtime Engine
Oracle HTTP Server
1
powered by Apache
2
mod_osso Oracle9i DB
Forms Listener Servlet

Forms Servlet

3
Oracle9i
Oracle9i Single
Internet
SignOn Server
Directory

B-8 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms SSO Process


The process of logging on to an SSO-enabled Forms application includes the following
steps:
1. The client requests the Forms application from a browser.
2. Oracle HTTP Server (OHS) decides that this call must be forwarded to mod_osso,
which checks for the existence of an OHS cookie for this user. If such a cookie
exists, mod_osso retrieves the users identity and credentials and redirects the user
to the Forms application.
3. If the cookie does not exist, mod_osso redirects the call to the SSO server. The
SSO server checks with the browser for its own cookie (ssocookie) for this user.
In other words, it checks to see whether it has authenticated this user before. If not, it
goes through the process of authenticating the user.

Oracle9i Forms Developer: New Features B-8


The Oracle9i Forms SSO Process

username Oracle 9iAS


FNIMPHIU
Forms Runtime Engine
Oracle HTTP Server
password

powered by Apache
IMGR8T

4 mod_osso Oracle9i DB
Forms Listener Servlet

Forms Servlet

5 Oracle9i
Oracle9i Single
Internet
SignOn Server
Directory

B-9 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms SSO Process (continued)


4. If the user started Oracle9i Forms Services in a new browser session, then the SSO
Server cannot find its authentication cookie, so it displays a logon dialog enabling
the user to connect. The user enters the lightweight SSO user ID and password,
which is not the same as the user ID and password required to connect the Forms
application with the database. In the example shown, the SSO user ID and password
are FNIMPHIU and IMGR8T.
5. The SSO Server verifies the provided user credentials against information stored in
OID for the user. If the information stored in OID matches the user provided
information, then the SSO Server sets an authentication cookie to the user browser
and redirects to the URL originally requested by the user. The SSO Server cookie is
not stored on the client side and lasts for the browser session only. It is encrypted
and contains the SSO user name, with no password or database connect information.
The cookie is passed with the client HTTP request only.

Oracle9i Forms Developer: New Features B-9


The Oracle9i Forms SSO Process

Oracle 9iAS
Forms Runtime Engine
Oracle HTTP Server
powered by Apache
mod_osso Oracle9i DB
Forms Listener Servlet

Forms Servlet
6

Oracle9i
Oracle9i Single
Internet
SignOn Server
Directory

B-10 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms SSO Process (continued)


6. Mod_osso receives the authentication from the SSO Server and sets its own
cookie, authenticating the Oracle9i Forms Services URL. The request is passed to
the Forms Servlet to render the application start HTML file.

Oracle9i Forms Developer: New Features B-10


The Oracle9i Forms SSO Process

Oracle 9iAS
Forms Runtime Engine
Oracle HTTP Server
powered by Apache
mod_osso Oracle9i DB
Forms Listener Servlet

Forms Servlet

7
Oracle9i
Oracle9i Single
Internet
SignOn Server
Directory

B-11 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms SSO Process (continued)


7. Before downloading the start HTML file, the Forms Servlet decrypts the cookie
passed from mod_osso to retrieve the SSO user name from it. The combination of
SSO user name and application name is a unique key that is used to retrieve the
database connect information stored in OID for a particular user and application.
For example, if the login SSO user name is FNIMPHIU and the application is
http://host:port/forms90/f90servlet?config=faq, then the
unique key to retrieve the database account information is "FNIMPHIU" and "faq."

Oracle9i Forms Developer: New Features B-11


The Oracle9i Forms SSO Process

Oracle 9iAS
Forms Runtime Engine
Oracle HTTP Server
powered by Apache
mod_osso Oracle9i DB
Forms Listener Servlet

Forms Servlet

8
Oracle9i
Oracle9i Single
Internet
SignOn Server
Directory

B-12 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms SSO Process (continued)


8. The Forms Servlet downloads the start HTML file containing the forms client applet
tags. This file contains the SSO user name as a serverArgs parameter, but does not
contain the database connect information. This might look like a security hole
because this page could be modified and replayed to the server, but the Forms
Servlet prohibits that by:
- Establishing a session that is used to store the database connect information on
the server. The actual database account information does not appear in the
page source that can be viewed in the browser.
- Ignoring the SSO user name if provided in the URL or the formsweb.cfg
file. It only accepts the SSO user name when it is provided by the
authentication cookie.

Oracle9i Forms Developer: New Features B-12


The Oracle9i Forms SSO Process
Whats the SSO user name? Use the function:
GET_APPLICATION_PROPERTY(SSO_USERID);

Oracle 9iAS 10
Forms Runtime Engine
Oracle HTTP Server
powered by Apache 9 Oracle9i DB
mod_osso
Forms Listener Servlet

Forms Servlet

Oracle9i
Oracle9i Single
Internet
SignOn Server
Directory

B-13 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms SSO Process (continued)


9. The Forms Listener Servlet starts a Forms Runtime Engine on the server for the
requesting user and reads the username/password for the database connect from the
servlet session.
10. The Forms Runtime Engine connects to the specified database, and the application is
ready for use. You can access single sign-on username in Forms with the
SSO_USERID application property.
Once authenticated, the user has access to other SSO-enabled applications, such as
Reports, Portal, or Discoverer, as well as other named Forms applications with a resource
in OID under that SSO user name.
Note: The Forms Services single sign-on architecture does not play a part in these final
steps, because the FormsListener Servlet is not part of the single sign-on protected path.
Registering the Forms Listener Servlet for SSO would dramatically decrease performance
without gaining any security benefit. The better way to protect the Forms client to server
communication is to use SSL on the application server.

Oracle9i Forms Developer: New Features B-13


Setting Up Single Sign-On

To work with single sign-on:


1. Register the application URL with mod_osso.
$ pwd
/oracle/ias902/forms90/server
$ vi forms90.conf
# forms90.conf
....
#Forms mod_osso authentication directive
<IfModule mod_osso.c>
<Location /forms90/f90servlet>
require valid-user
AuthType Basic
</Location>
</IfModule>

B-14 Copyright Oracle Corporation, 2002. All rights reserved.

Setting Up SSO
To use single sign-on with Forms applications, you perform the following steps:
1. Register the application with mod_osso: To SSO secure an application in
Oracle9iAS, the application URL must be registered with mod_osso. Note that the
SSO configuration is not the default when installing Oracle9i Forms Services. You
must add the URL to the forms90.conf file that is located in the
forms90/server directory. You do this by uncommenting the last entries in the
file. You must stop and restart the 9iAS instance for the new setting to take effect.
In this release, mod_osso registers the root URL, not providing a separate handling
for added query parameters (this feature will be implemented in a future patch set).
For Oracle9i Forms, protecting the static root URL means that the URL
http://hostname:port/forms90/f90servlet is protected by
mod_osso. All Forms applications started with this URL, no matter what parameters
are added, are protected by mod_osso.
Note: According to Oracle9i Forms Developer and Forms Services Release Notes
Addendum, you cannot run forms in both HTTP and HTTPS mode simultaneously
when using SSO, because you can register only one or the other with mod_osso.

Oracle9i Forms Developer: New Features B-14


Setting Up Single Sign-On

2. Register OID with Forms Services.


3. Create a single sign-on user account in OID for
each person using the system.
4. Create one or more application resources in OID
for each single sign-on account name.

--formsweb.cfg
.... Oracle9i
.... 9iDB
Internet
[faq] Directory connect string:
form=faq.fmx frankie/johnnie@9idb

URL: http://host:port/forms90/f90servlet?config=faq

B-15 Copyright Oracle Corporation, 2002. All rights reserved.

Setting Up SSO (continued)


2. Register the Oracle Internet Directory with Forms Services: This is done
automatically upon installation by adding the following section to formsweb.cfg:
# OID Config parameters (for Single Sign-On)
oid_formsid=formsApp
oracle_home=/oracle/ias902
This registration is used by the Forms Servlet to authenticate itself against OID, if you
are using SSO. If you are not using SSO, this registration has no effect.
3. Create one or more single sign-on user accounts: Use the OID Web administration
interface to create a lightweight SSO user account. This is called the Deliberate
Administration Service (DAS) Web interface. You access this interface by invoking
the URL: http://hostname:7777/oiddas/. To create a new account, you
must be an OID administrator (log into the Web interface with an OID administrator
account).

Oracle9i Forms Developer: New Features B-15


Setting Up SSO (continued)
4. Create one or more application resources for each SSO account: Define the
applications the user will access, with database connection information for each. For
Forms, the application name must match a named section of the formsweb.cfg file
that the URL references in the config=<application_name> parameter. The
application shown above is called "faq," but there may be more applications defined
for the SSO user.

Oracle9i Forms Developer: New Features B-16


Setting Up Single Sign-On

To use some Forms applications without SSO:


Create an alias for Forms Servlet and use the alias
in the URL.
Create an application-specific configuration file to
use instead of formsweb.cfg.

B-17 Copyright Oracle Corporation, 2002. All rights reserved.

Setting Up SSO (continued)


Using Some Forms Applications without SSO
If Forms Services is configured for SSO but there are some Forms applications that should
not run in SSO mode, you can create a new alias name for the Forms Servlet, changing the
root URL to http://host:port/forms90/<your alias>, which is not
protected. The required changes can be done in the web.xml file of the Forms OC4J
configuration.
Because it makes no sense to use the same formsweb.cfg file with a SSO-protected
and a non-SSO-protected URL, you should change the Servlet initialization parameter
configFile as well, pointing the new defined servlet alias to another configuration
file. This ensures security and enables you to run Forms applications outside of your SSO
environment, for example, over the Internet.

Oracle9i Forms Developer: New Features B-17


Relationship Between SSO Elements
Oracle
Internet SSO user
Directory Username: FormsUser
SSO password: ora1

formsweb.cfg
....
[hr_app]
form=hr.fmx
[order_entry]
form=orders.fmx
[expense]
form=
expense_report.fmx

B-18 Copyright Oracle Corporation, 2002. All rights reserved.

The Relationship Between SSO Elements


A user can have many resources assigned to his or her SSO user account, all identified by
the Forms application name. The resource name must match the config parameter
value, which is equivalent to the name the application has in the custom configuration
section of the formsweb.cfg file or other configuration file. This is because the
application name is part of the unique key.
The SSO user depicted above has three resources defined, each with a corresponding entry
in the formsweb.cfg file. If this user enters the URL with the
?config=order_entry parameter, after the user is authenticated with the SSO
username and password (FormsUser/ora1), the form orders.fmx will start, with a
connection to the database1 server as the user2 database user.

Oracle9i Forms Developer: New Features B-18


Summary

In this appendix, you should have learned that:


The OEM Web site is an HTML-based tool you can
use from any browser to access information and
modify the configuration for a Forms Services
instance on a single node.
The OEM Java console is required to register
events or to monitor Forms Services instances on
multiple nodes.
You can enable Single Sign-on for the Forms
Servlet so that users can have one user ID and
password to access multiple applications.

B-19 Copyright Oracle Corporation, 2002. All rights reserved.

Summary
Oracle Enterprise Manager: Provides a Web site where you can manage and view
information about Forms Services.
Oracle Internet Directory and Single-Sign-on Server: Enables you to implement
single sign-on for Forms applications without changing application code.

Oracle9i Forms Developer: New Features B-19


Managing the Team Development
of Forms Applications

Copyright Oracle Corporation, 2002. All rights reserved.


Objectives

After reviewing this appendix, you should be able to


do the following:
Describe Oracle9i Software Configuration Manager
(SCM)
Explain integration of SCM with Forms
Use SCM to check files in and out from the SCM
repository

C-2 Copyright Oracle Corporation, 2002. All rights reserved.

Appendix Aim
This appendix explains how integration with Oracle9i Software Configuration Manager
enables source code control of Forms applications.

Oracle9i Forms Developer: New Features C-2


Oracle9i Software Configuration
Manager Overview

Using Oracle9i SCM, development teams can improve


quality, while reducing risk.

Oracle9i SCM
Repository

Upload

Download

C-3 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Software Configuration Manager Overview


Oracle9i Software Configuration Manager (SCM) provides software developers with: a
repository for storing development objects, mechanisms for managing versioned objects,
controlling access to the repository, and policies that impose restrictions on versioning
operations. This repository is created in the Oracle9i database.
Oracle SCM manages structured and unstructured data, including Forms FMB files,
throughout the entire development life cycle. It supports multideveloper, multistream
software development projects of any size and complexity.
Key features of Oracle SCM include:
Version control and history
Configuration management for component based application architectures
Storage and management of all files, folders, relational data, and modeled metadata
objects
Ability to register and add new types of content
Ability to compare and merge all object types
Extensible dependency analysis

Oracle9i Forms Developer: New Features C-3


Oracle9i SCM Options in Forms Builder

File >
Administration
Check In
Check Out
Source
Control
Options

C-4 Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i SCM Options in Forms Builder


Oracle Forms Builder can directly interface with the SCM repository through the
File > Administration menu choices. From within Forms, you can check files in, check
files out, and specify with which repository you choose to work (Source Control Options).
You can provide notes when checking your source FMB file in or out, and you can place a
lock on your checked-out files. These files can be automatically versioned with each
operation.
As a safety precaution, write access is removed for any file that has been checked in, and
write access is restored if a file is successfully checked out.
Note: SCM has many capabilities that are not covered in this course, which discusses only
those functions that Forms developers will typically use. For more information about
SCM, see the OLN course Managing Development with Oracle Repository, or the Using
Oracle Repository for Software Configuration Management white paper available from
OTN (http://otn.oracle.com/products/repository/content.html).

Oracle9i Forms Developer: New Features C-4


Setting Up SCM to Work with Forms
Required administration tasks:
Repository Administration Utility:
Repository Administration Utility
Enable the repository Options

for versioning: Options >


Enable Version Support
Enable Version Support
Create repository users with default privileges
Specify SCM as source control for Forms and
Reports: Start > Programs > Oracle9iDS

Oracle9i Software Configuration Manager

Use as Source Control for Forms and Reports

C-5 Copyright Oracle Corporation, 2002. All rights reserved.

Setting Up SCM to Work with Forms


There are a few administrative tasks that the SCM administrator must perform so that you
can integrate Forms with SCM:
1. To enable the repository for versioning, use the Repository Administration Utility
(RAU). Choose Options > Enable Version Support.
2. Use RAU to create a user with default privileges for each Forms developer.
3. To enable Oracle SCM for checkin and checkout support:
- From the Windows Start menu, select Programs > Oracle9i Developer Suite >
Oracle9i Software Configuration Manager.
- Select Use as Source Control for Forms and Reports.
- A Windows registry file (<ORAHOME>\repadm61\drsc61.reg)
automatically sets the following keys in
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\HOMEx:
"FORMS90_PROJECT"=""
"FORMS90_SOURCECONTROL"="CUSTOM"
"FORMS90_SCDRIVER"="d2scrw32.dll"
- The Check In, Check Out, and Source Control Options will be enabled the next
time Forms Builder is started.

Oracle9i Forms Developer: New Features C-5


Creating SCM Containers

C-6 Copyright Oracle Corporation, 2002. All rights reserved.

Creating SCM Containers


You can use the Repository Object Navigator (RON) to define work areas and containers
in the SCM repository. You start RON from the Windows Start menu: Start > Programs >
Oracle9i Developer Suite > Oracle9i Software Configuration Manger > Repository Object
Navigator.
To create a new container:
When RON is first invoked, select Open Navigator.
Open the navigator for the work area in which you want to create a container.
With the work area selected, click the Create as Child icon.
The example above shows creating a new container in the Forms Developers work area.
After you have created the container, you can grant other users access to it. They must
first have access to the work area. Right-click the work area and select Grant Access from
the pop-up menu. You can grant access rights to a user on a work area and all its
subcontainers; if this is the case, the user will automatically have access on any new
containers created in that work area.
If you do not give the user access to all subcontainers, you can grant access to individual
containers. Right-click the container and select Grant Access from the pop-up menu.

Oracle9i Forms Developer: New Features C-6


Setting Up a Work Area

Change repository
connection

Change work area

Select container

C-7 Copyright Oracle Corporation, 2002. All rights reserved.

Setting Up a Work Area


Before you can check files in and out, you must set up your SCM work area and working
folder. To set up your work area:
In Forms Builder, select File > Administration > Source Control Options. Your SCM
repository connection and work area are displayed at the top of the dialog.
You can change your work area by clicking the Change button next to the Workarea
field. This invokes a window showing all of the work areas to which you have
access. From this window, you can select a different work area or create a new one.
After you have specified a work area, select a folder (container) in your work area.
Your files are checked in and out of the folder that you select in the current work
area.
Click OK. The selections that you make are stored in your Windows registry and
will be used the next time you open Forms Developer.

Oracle9i Forms Developer: New Features C-7


The Checkin and Checkout Process

Checked-in files are read-only in the file system.


Checked-out files can be written to.
To check in or out, you must first open and select
the file in Forms Builder.
Checking in or checking out synchronizes the file
system file with what is stored in SCM.
When you check out a form, close and reopen the
file in Forms Builder to make sure that the latest
version is loaded into Forms Builder.

C-8 Copyright Oracle Corporation, 2002. All rights reserved.

Checking In and Checking Out


When you check in a file, the file property is set to read-only in the file system. When you
check out a file, the file property is set back to write, so that you can modify it.
Checkin and checkout always acts on the active Form as it exists in the file system. To
check in and check out files, you must open the form in Forms Builder. For example, if
you open c:\work\myform.fmb in Forms Builder, make changes to the form, and
check it into SCM, it will check in the c:\work\myform.fmb file. It will not check
in the .fmb as it exists within Forms Builder. If you do not save the changes that you
made to your form, the changes will not be checked in.
If you try to save the changes after checking in the file, Forms Builder will throw an alert
saying that it could not create the file. This is because when you checked in the
myform.fmb file, its file system properties became read-only. In order to save the
changes, you must check out the myform.fmb file, save the changes in Forms Builder,
and check the file in again.
If you check out the form, the current version of myform.fmb in the SCM work area
will be downloaded from SCM to synchronize c:\work\myform.fmb. The
myform.fmb file is no longer read-only, so you can save your changes.

Oracle9i Forms Developer: New Features C-8


Checking Out a File

1. Open the file in Forms Builder (opens from the file


system).
2. From the menu, choose File > Administration >
Check Out.
3. Close and reopen the file in Forms Builder.
4. Make changes and save the file if desired, then
check back in.

C-9 Copyright Oracle Corporation, 2002. All rights reserved.

Checking Out a File


To check out a file:
Open the file in Forms Builder. Be sure that the work area and folder that you are
using contains the version of the file that you want to edit.
Select the File | Administration | Check Out.
- If prompted, log into SCM with your username, password, and connect string.
- Select any checkout options by selecting a check box for Lock, Check Out
Latest, or Version Dependencies.
- Provide Check Out notes. These notes describe why the Form is checked out
and for how long.
- Click the OK button. The .fmb file is downloaded from SCM to the file
system. It overwrites the currently active .fmb file in Forms Builder. An alert
states that the FMB file on the file system will be overwritten with the FMB
file from SCM. Click OK if the files are the same.
To ensure the correct FMB definition is loaded in Forms Developer, close the active
Form and reopen it. This will load the FMB file as it was downloaded from SCM.
Edit, compile, and test the form as needed. You can save changes to the local file
system, but be sure to check in the final version to SCM.

Oracle9i Forms Developer: New Features C-9


Checking In a File

1. Save file to file


system
2. File >
Administration >
Check In
3. Select options
4. Add notes

C-10 Copyright Oracle Corporation, 2002. All rights reserved.

Checking In a File
To check in a file:
The file that you want to check in must be selected in Forms Builder.
Save your changes to the file system.
Select the File | Administration | Check In.
If prompted, log into SCM. Forms Builder will connect with SCM, establish the
work area and folder, and upload the source file from the file system.
If the file already exists in SCM, an alert is displayed. Select whether to overwrite
the file in SCM. (If the file was never checked out, the operation will fail.)
After the file is uploaded, select any checkin options:
- Use Branch
- Version Label (This is available for editing only if automatic version labeling
switched off.)
- Use Checkout Notes
- Check Out after Check In
- Check in Even if Unchanged
Enter any checkin notes. At this point, you can cancel the checkin, if necessary.
Click OK. The checkin is complete, and the source file is set to Read-Only.

Oracle9i Forms Developer: New Features C-10


An Overwriting Scenario

User 1 User 2

1. In Forms Builder (FB), 2. In FB, opens myform.fmb,


opens myform.fmb checks it out from SCM,
from file system, makes closes and reopens, makes
changes, saves, checks changes, saves to file
in myform.fmb to SCM. system, checks back in to
SCM, closes form in FB.

3. With form still open, 4. Opens form from file


makes more changes in system, checks out from
Forms Builder, checks SCM, closes form and
form out from SCM, reopens to get latest
saves form to file version in FB, discovers
system, checks form in. previous changes are gone.

C-11 Copyright Oracle Corporation, 2002. All rights reserved.

Caution: Dont Overwrite Another Developers Changes


The scenario described above shows how easy it is to overwrite another developers
changes. In #3, the underlined actions overwrite the other developers changes. What step
did User 1 miss that would have prevented this overwrite from occurring?
The correct sequence that User 1 should have followed in #3:
With the form still open in Forms Builder, check the form out from SCM.
Close the form and reopen in Forms Builder to be sure the latest version is loaded.
Make changes.
Save the form to the file system.
Check the form back in to SCM.
When you check out a form in Forms Builder, you should always close it and then reopen
it to make sure that you have loaded the latest version. Checking out the form only
synchronizes it with the file system, but not with Forms Builder.

Oracle9i Forms Developer: New Features C-11


Deleting a File from the Repository

C-12 Copyright Oracle Corporation, 2002. All rights reserved.

Deleting a File from the Repository


If you no longer want to share work on a file, you can delete it from the SCM repository
using the Repository Object Navigator. You just select the file and click the Delete Object
icon, or select Edit > Delete from the menu. You will be asked to confirm that you want to
delete the file.
Note: Deleting a file from the repository does not delete it from the file system.

Oracle9i Forms Developer: New Features C-12


Summary

In this appendix, you should have learned that:


Oracle9i Software Configuration Manager provides
a repository in the Oracle9i database to manage
team development efforts.
Forms Builder can use SCM for source control if
the SCM administrator sets up the repository for
versioning and specifies that it should be used as
source control for Forms and Reports.
Forms developers who have been set up as SCM
users can share files by checking them in and out
of the SCM repository.
Checking in and out synchronizes the repository
with the file system, but not with Forms Builder.

C-13 Copyright Oracle Corporation, 2002. All rights reserved.

Summary
Oracle9i Software Configuration Manager is a component of Oracle9i Developer Suite. It
enables source control for team development of applications, using a repository in the
Oracle9i database. The SCM administrator can specify that the repository should be used
as source control for Forms and Reports applications.
Only after Forms developers have been set up as SCM users, can they, in Forms Builder,
select the SCM work area and folder to use for source control. They can check modules
out of the SCM repository and load them into Forms Builder, which synchronizes the file
with the developers file system and enables them to make changes to the file. When they
save the changes, they can check the module back in to the SCM repository, thus
synchronizing the latest file system file with the SCM repository. After it is checked in,
the file system file has a read-only attribute.
When developers check out modules from SCM, they should close the module in Forms
Builder and reopen it to ensure that they are working with the latest version of the module.
They should also save changes before checking a module back in. This is because
checking a module in or out synchronizes the repository with the file system, but does not
synchronize with the module loaded in Forms Builder.

Oracle9i Forms Developer: New Features C-13


Oracle9i Forms Developer: New Features C-14
Table Descriptions

Copyright Oracle Corporation, 2002. All rights reserved.


Summit Office Supply Database Diagram

ORDER_ID ORDER_ID
ORDER_ITEMS ORDERS
PRODUCT_ID SALES_REP_ID CUSTOMER_ID

CUSTOMER_ID

*
INVENTORIES CUSTOMERS
PRODUCT_ID ACCOUNT_MGR_ID

PRODUCT_ID PRODUCT_ID EMPLOYEE_ID EMPLOYEE_ID

PRODUCTS EMPLOYEES

DEPARTMENT_ID

DEPARTMENT_ID

DEPARTMENTS

*Unique occurrences are identified by PRODUCT_ID and WAREHOUSE_ID.


Note: What follows is not a complete list of schema objects, but only those relevant to the
Summit Office Supply application.

Oracle9i Forms Developer: New Features D-2


CUSTOMERS Description
SQL> desc customers
Name Null? Type
------------------ -------- -------------
CUSTOMER_ID NOT NULL NUMBER(6)
CUST_FIRST_NAME NOT NULL VARCHAR2(20)
CUST_LAST_NAME NOT NULL VARCHAR2(20)
CUST_ADDRESS CUST_ADDRESS_TYP
PHONE_NUMBERS VARCHAR2(30)
NLS_LANGUAGE VARCHAR2(3)
NLS_TERRITORY VARCHAR2(30)
CREDIT_LIMIT NUMBER(9,2)
CUST_EMAIL VARCHAR2(30)
ACCOUNT_MGR_ID NUMBER(6)

SQL> desc cust_address_typ


Name Null? Type
------------------ -------- ------------
STREET_ADDRESS VARCHAR2(40)
POSTAL_CODE VARCHAR2(10)
CITY VARCHAR2(30)
STATE_PROVINCE VARCHAR2(10)
COUNTRY_ID CHAR(2)

Related object creation statements

CREATE TYPE cust_address_typ


AS OBJECT
( street_address VARCHAR2(40)
, postal_code VARCHAR2(10)
, city VARCHAR2(30)
, state_province VARCHAR2(10)
, country_id CHAR(2)
);

CREATE TABLE customers


( customer_id NUMBER(6)
, cust_first_name VARCHAR2(20) CONSTRAINT
cust_fname_nn NOT NULL
, cust_last_name VARCHAR2(20) CONSTRAINT
cust_lname_nn NOT NULL
, cust_address cust_address_typ
, phone_numbers varchar2(30)
, nls_language VARCHAR2(3)

Oracle9i Forms Developer: New Features D-3


CUSTOMERS Description (continued)
, nls_territory VARCHAR2(30)
, credit_limit NUMBER(9,2)
, cust_email VARCHAR2(30)
, account_mgr_id NUMBER(6)
, CONSTRAINT customer_credit_limit_max
CHECK (credit_limit <= 5000)
, CONSTRAINT customer_id_min
CHECK (customer_id > 0)) ;

CREATE UNIQUE INDEX customers_pk


ON customers (customer_id) ;

ALTER TABLE customers


ADD ( CONSTRAINT customers_pk
PRIMARY KEY (customer_id)) ;

ALTER TABLE customers


ADD ( CONSTRAINT customers_account_manager_fk
FOREIGN KEY (account_mgr_id)
REFERENCES employees(employee_id)
ON DELETE SET NULL) ;

CREATE SEQUENCE customers_seq


START WITH 982
INCREMENT BY 1
NOCACHE
NOCYCLE;

Sample record (1 out of 319 customers)


CUSTOMER_ID CUST_FIRST_NAME CUST_LAST_NAME
----------- -------------------- --------------------
CUST_ADDRESS(STREET_ADDRESS, POSTAL_CODE, CITY, STATE_PROVINCE,
COUNTRY_ID)
----------------------------------------------------------------
----------------
PHONE_NUMBERS NLS NLS_TERRITORY
CREDIT_LIMIT
------------------------------ --- -----------------------------
- ------------
CUST_EMAIL ACCOUNT_MGR_ID
------------------------------ --------------
101 Constantin Welles
CUST_ADDRESS_TYP(514 W Superior St, 46901, Kokomo, IN,
US)
+1 317 123 4104 us AMERICA
100
Constantin.Welles@ANHINGA.COM

Oracle9i Forms Developer: New Features D-4


DEPARTMENTS Description
SQL> desc departments
Name Null? Type
------------------- -------- ------------
DEPARTMENT_ID NOT NULL NUMBER(4)
DEPARTMENT_NAME NOT NULL VARCHAR2(30)
MANAGER_ID NUMBER(6)
LOCATION_ID NUMBER(4)

Related object creation statements

CREATE TABLE departments


( department_id NUMBER(4)
, department_name VARCHAR2(30)
CONSTRAINT dept_name_nn NOT NULL
, manager_id NUMBER(6)
, location_id NUMBER(4)
) ;

CREATE UNIQUE INDEX dept_id_pk


ON departments (department_id) ;

ALTER TABLE departments


ADD ( CONSTRAINT dept_id_pk
PRIMARY KEY (department_id)
, CONSTRAINT dept_loc_fk
FOREIGN KEY (location_id)
REFERENCES locations (location_id)
) ;
Note: The Locations table is not documented here because it is not used in the Summit
Office Supply application.
Rem Useful for any subsequent addition of rows to
departments table
Rem Starts with 280

CREATE SEQUENCE departments_seq


START WITH 280
INCREMENT BY 10
MAXVALUE 9990
NOCACHE
NOCYCLE;

Oracle9i Forms Developer: New Features D-5


DEPARTMENTS Description (continued)
SQL> select * from departments;
DEPARTMENT_ID DEPARTMENT_NAME MANAGER_ID LOCATION_ID
------------- ----------------- ---------- ---------
10 Administration 200 1700
20 Marketing 201 1800
30 Purchasing 114 1700
40 Human Resources 203 2400
50 Shipping 121 1500
60 IT 103 1400
70 Public Relations 204 2700
80 Sales 145 2500
90 Executive 100 1700
100 Finance 108 1700
110 Accounting 205 1700
120 Treasury 1700
130 Corporate Tax 1700
140 Control And Credit 1700
150 Shareholder Services 1700
160 Benefits 1700
170 Manufacturing 1700
180 Construction 1700
190 Contracting 1700
200 Operations 1700
210 IT Support 1700
220 NOC 1700
230 IT Helpdesk 1700
240 Government Sales 1700
250 Retail Sales 1700
260 Recruiting 1700
270 Payroll 1700
27 rows selected.

Oracle9i Forms Developer: New Features D-6


EMPLOYEES Description
SQL> desc employees
Name Null? Type
------------------ -------- ------------
EMPLOYEE_ID NOT NULL NUMBER(6)
FIRST_NAME VARCHAR2(20)
LAST_NAME NOT NULL VARCHAR2(25)
EMAIL NOT NULL VARCHAR2(25)
PHONE_NUMBER VARCHAR2(20)
HIRE_DATE NOT NULL DATE
JOB_ID NOT NULL VARCHAR2(10)
SALARY NUMBER(8,2)
COMMISSION_PCT NUMBER(2,2)
MANAGER_ID NUMBER(6)
DEPARTMENT_ID NUMBER(4)
Related object creation statements
CREATE TABLE employees
( employee_id NUMBER(6)
, first_name VARCHAR2(20)
, last_name VARCHAR2(25)
CONSTRAINT emp_last_name_nn NOT NULL
, email VARCHAR2(25)
CONSTRAINT emp_email_nn NOT NULL
, phone_number VARCHAR2(20)
, hire_date DATE
CONSTRAINT emp_hire_date_nn NOT NULL
, job_id VARCHAR2(10)
CONSTRAINT emp_job_nn NOT NULL
, salary NUMBER(8,2)
, commission_pct NUMBER(2,2)
, manager_id NUMBER(6)
, department_id NUMBER(4)
, CONSTRAINT emp_salary_min
CHECK (salary > 0)
, CONSTRAINT emp_email_uk
UNIQUE (email)
) ;
Oracle9i Forms Developer: New Features D-7
EMPLOYEES Description (continued)
CREATE UNIQUE INDEX emp_emp_id_pk
ON employees (employee_id) ;
ALTER TABLE employees
ADD ( CONSTRAINT emp_emp_id_pk
PRIMARY KEY (employee_id)
, CONSTRAINT emp_dept_fk
FOREIGN KEY (department_id)
REFERENCES departments
, CONSTRAINT emp_job_fk
FOREIGN KEY (job_id)
REFERENCES jobs (job_id)
, CONSTRAINT emp_manager_fk
FOREIGN KEY (manager_id)
REFERENCES employees
) ;
ALTER TABLE departments
ADD ( CONSTRAINT dept_mgr_fk
FOREIGN KEY (manager_id)
REFERENCES employees (employee_id)
) ;
Rem Useful for any subsequent addition of rows to
employees table
Rem Starts with 207
CREATE SEQUENCE employees_seq
START WITH 207
INCREMENT BY 1
NOCACHE
NOCYCLE;
Sample records (2 out of 107 employees)
EMPLOYEE_ID FIRST_NAME LAST_NAME EMAIL PHONE_NUMBER HIRE_DATE
----------- ---------- --------- -------- ------------ ----------
JOB_ID SALARY COMMISSION_PCT MANAGER_ID DEPARTMENT_ID
-------- ------ -------------- ---------- -------------
100 Steven King SKING 515.123.4567 17-JUN-87
AD_PRES 24000 90
101 Neena Kochhar NKOCHHAR 515.123.4568 21-SEP-89
AD_VP 17000 100 90

Oracle9i Forms Developer: New Features D-8


INVENTORIES Description and Data
SQL> desc inventories
Name Null? Type
----------------------------------------- -------- ---------
PRODUCT_ID NOT NULL NUMBER(6)
WAREHOUSE_ID NOT NULL NUMBER(3)
QUANTITY_ON_HAND NOT NULL NUMBER(8)
Related object creation statements
CREATE TABLE inventories
( product_id NUMBER(6)
, warehouse_id NUMBER(3) CONSTRAINT
inventory_warehouse_id_nn NOT NULL
, quantity_on_hand NUMBER(8)
CONSTRAINT inventory_qoh_nn NOT NULL
, CONSTRAINT inventory_pk PRIMARY KEY (product_id,
warehouse_id)
) ;

ALTER TABLE inventories


ADD ( CONSTRAINT inventories_warehouses_fk
FOREIGN KEY (warehouse_id)
REFERENCES warehouses (warehouse_id)
ENABLE NOVALIDATE
) ;

ALTER TABLE inventories


ADD ( CONSTRAINT inventories_product_id_fk
FOREIGN KEY (product_id)
REFERENCES product_information (product_id)
) ;

Sample records (11 out of 1112 inventory items)


PRODUCT_ID WAREHOUSE_ID QUANTITY_ON_HAND
---------- ------------ ----------------
1733 1 106
1734 1 106
1737 1 106
1738 1 107
1745 1 108
1748 1 108
2278 1 125
2316 1 131
2319 1 117
2322 1 118
2323 1 118

Oracle9i Forms Developer: New Features D-9


PRODUCTS Description and Data
SQL> desc products
Name Null? Type
---------------------- -------- ---------------
PRODUCT_ID NOT NULL NUMBER(6)
LANGUAGE_ID VARCHAR2(3)
PRODUCT_NAME NVARCHAR2(250)
CATEGORY_ID NUMBER(2)
PRODUCT_DESCRIPTION NVARCHAR2(4000)
WEIGHT_CLASS NUMBER(1)
WARRANTY_PERIOD NUMBER(5)
SUPPLIER_ID NUMBER(6)
PRODUCT_STATUS VARCHAR2(20)
LIST_PRICE NUMBER(8,2)
MIN_PRICE NUMBER(8,2)
CATALOG_URL VARCHAR2(50)

Related object creation statements


CREATE OR REPLACE VIEW products
AS
SELECT i.product_id
, d.language_id
, CASE WHEN d.language_id IS NOT NULL
THEN d.translated_name
ELSE TRANSLATE(i.product_name USING NCHAR_CS)
END AS product_name
, i.category_id
, CASE WHEN d.language_id IS NOT NULL
THEN d.translated_description
ELSE TRANSLATE(i.product_description USING NCHAR_CS)
END AS product_description
, i.weight_class
, i.warranty_period
, i.supplier_id
, i.product_status
, i.list_price
, i.min_price
, i.catalog_url
FROM product_information i
, product_descriptions d
WHERE d.product_id (+) = i.product_id
AND d.language_id (+) = sys_context(USERENV,LANG);

Oracle9i Forms Developer: New Features D-10


PRODUCTS Description and Data (continued)
CREATE TABLE product_information
( product_id NUMBER(6)
, product_name VARCHAR2(50)
, product_description VARCHAR2(2000)
, category_id NUMBER(2)
, weight_class NUMBER(1)
, warranty_period NUMBER(5)
, supplier_id NUMBER(6)
, product_status VARCHAR2(20)
, list_price NUMBER(8,2)
, min_price NUMBER(8,2)
, catalog_url VARCHAR2(50)
, CONSTRAINT product_status_lov
CHECK (product_status in (orderable,
planned,development,obsolete))) ;

ALTER TABLE product_information


ADD ( CONSTRAINT product_information_pk PRIMARY KEY
(product_id));

CREATE TABLE product_descriptions


( product_id NUMBER(6)
, language_id VARCHAR2(3)
, translated_name NVARCHAR2(50)
CONSTRAINT translated_name_nn NOT NULL
, translated_description NVARCHAR2(2000)
CONSTRAINT translated_desc_nn NOT NULL);

CREATE UNIQUE INDEX prd_desc_pk


ON product_descriptions(product_id,language_id) ;

ALTER TABLE product_descriptions


ADD ( CONSTRAINT product_descriptions_pk
PRIMARY KEY (product_id, language_id));

Sample records (4 out of 288 products; only 3 columns shown)


PRODUCT_ID PRODUCT_NAME LIST_PRICE
---------- ------------------------------ ----------
1726 LCD Monitor 11/PM 259
2359 LCD Monitor 9/PM 249
3060 Monitor 17/HR 299
2243 Monitor 17/HR/F 350

Oracle9i Forms Developer: New Features D-11


ORDER_ITEMS Description
SQL> desc order_items;
Name Null? Type
-------------------- -------- -----------
ORDER_ID NOT NULL NUMBER(12)
LINE_ITEM_ID NOT NULL NUMBER(3)
PRODUCT_ID NOT NULL NUMBER(6)
UNIT_PRICE NUMBER(8,2)
QUANTITY NUMBER(8)

Related object creation statements


CREATE TABLE order_items
( order_id NUMBER(12)
, line_item_id NUMBER(3) NOT NULL
, product_id NUMBER(6) NOT NULL
, unit_price NUMBER(8,2)
, quantity NUMBER(8)
) ;

CREATE UNIQUE INDEX order_items_pk


ON order_items (order_id, line_item_id) ;

CREATE UNIQUE INDEX order_items_uk


ON order_items (order_id, product_id) ;

ALTER TABLE order_items


ADD ( CONSTRAINT order_items_pk PRIMARY KEY (order_id,
line_item_id)
);

ALTER TABLE order_items


ADD ( CONSTRAINT order_items_order_id_fk
FOREIGN KEY (order_id)
REFERENCES orders(order_id)
ON DELETE CASCADE enable novalidate) ;

ALTER TABLE order_items


ADD ( CONSTRAINT order_items_product_id_fk
FOREIGN KEY (product_id)
REFERENCES product_information(product_id)) ;

Oracle9i Forms Developer: New Features D-12


ORDER_ITEMS Description (continued)
CREATE OR REPLACE TRIGGER insert_ord_line
BEFORE INSERT ON order_items
FOR EACH ROW
DECLARE
new_line number;
BEGIN
SELECT (NVL(MAX(line_item_id),0)+1) INTO new_line
FROM order_items
WHERE order_id = :new.order_id;
:new.line_item_id := new_line;
END;

Sample records (11 out of 665 order items)


ORDER_ID LINE_ITEM_ID PRODUCT_ID UNIT_PRICE QUANTITY
--------- ------------ ---------- ---------- ----------
2355 1 2289 46 200
2356 1 2264 199.1 38
2357 1 2211 3.3 140
2358 1 1781 226.6 9
2359 1 2337 270.6 1
2360 1 2058 23 29
2361 1 2289 46 180
2362 1 2289 48 200
2363 1 2264 199.1 9
2364 1 1910 14 6
2365 1 2289 48 92

Oracle9i Forms Developer: New Features D-13


ORDERS Description and Data
SQL> desc orders
Name Null? Type
------------------ -------- -----------
ORDER_ID NOT NULL NUMBER(12)
ORDER_DATE NOT NULL DATE
ORDER_MODE VARCHAR2(8)
CUSTOMER_ID NOT NULL NUMBER(6)
ORDER_STATUS NUMBER(2)
ORDER_TOTAL NUMBER(8,2)
SALES_REP_ID NUMBER(6)
PROMOTION_ID NUMBER(6)

Related object creation statements

CREATE TABLE orders


( order_id NUMBER(12)
, order_date DATE
CONSTRAINT order_date_nn NOT NULL
, order_mode VARCHAR2(8)
, customer_id NUMBER(6)
CONSTRAINT order_customer_id_nn NOT
NULL
, order_status NUMBER(2)
, order_total NUMBER(8,2)
, sales_rep_id NUMBER(6)
, promotion_id NUMBER(6)
, CONSTRAINT order_mode_lov
CHECK (order_mode in
(direct,online))
, constraint order_total_min
check (order_total >= 0)) ;

CREATE UNIQUE INDEX order_pk


ON orders (order_id) ;

ALTER TABLE orders


ADD ( CONSTRAINT order_pk
PRIMARY KEY (order_id));

ALTER TABLE orders


ADD ( CONSTRAINT orders_sales_rep_fk
FOREIGN KEY (sales_rep_id)
REFERENCES employees(employee_id)
ON DELETE SET NULL) ;

Oracle9i Forms Developer: New Features D-14


ORDERS Description and Data (continued)
ALTER TABLE orders
ADD ( CONSTRAINT orders_customer_id_fk
FOREIGN KEY (customer_id)
REFERENCES customers(customer_id)
ON DELETE SET NULL) ;

Sample records (12 out of 105 orders)


ORDER_ID ORDER_DAT ORDER_MO CUSTOMER_ID ORDER_STATUS ORDER_TOTAL
--------- --------- -------- ----------- ------------ ----------
SALES_REP_ID PROMOTION_ID
------------ ------------
2458 16-AUG-99 direct 101 0 78279.6
153
2397 19-NOV-99 direct 102 1 42283.2
154
2454 02-OCT-99 direct 103 1 6653.4
154
2354 14-JUL-00 direct 104 0 46257
155
2358 08-JAN-00 direct 105 2 7826
155
2381 14-MAY-00 direct 106 3 23034.6
156
2440 31-AUG-99 direct 107 3 70576.9
156
2357 08-JAN-98 direct 108 5 59872.4
158
2394 10-FEB-00 direct 109 5 21863
158
2435 02-SEP-99 direct 144 6 62303
159
2455 20-SEP-99 direct 145 7 14087.5
160
2379 16-MAY-99 direct 146 8 17848.2
161

Oracle9i Forms Developer: New Features D-15


Oracle9i Forms Developer: New Features D-16