Oracle 9i Forms Developer

Oracle 9i Forms Developer: New Features
Instructor Guide
D14298GC10 Production 1.0 October 2002 D37333
Author
Pam Gamer
Copyright Oracle Corporation, 2002. All rights reserved. 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. 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 applicable: Restricted Rights Legend Use, duplication or disclosure by the Government is subject to restrictions for commercial computer software and shall be deemed to be Restricted Rights software under Federal law, as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013, Rights in Technical Data and Computer Software (October 1988). This material or any portion of it may not be copied in any form or by any means without the express prior written permission of Oracle Corporation. Any other copying is a violation of copyright law and may result in civil and/or criminal penalties. If this documentation is delivered to a U.S. Government Agency not within the Department of Defense, then it is delivered with Restricted Rights, as defined in FAR 52.227-14, Rights in Data-General, including Alternate III (June 1987). 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, Oracle Corporation, 500 Oracle Parkway, Box SB-6, Redwood Shores, CA 94065. Oracle Corporation does not warrant that this document is error-free. 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 may be trademarks of their respective owners.
Technical Contributors and Reviewers

Yanti Chang Laurent Dereac Ellen Gravina Jonas Jacobi Chris Lewis Chris Lowes Marcelo Manzano Duncan Mills Frank Nimphius Kavitha Prakash Jasmin Robayo Bryan Roberts Grant Ronald Raza Siddiqui Sarah Spicer Jack Walsh Ken Woolfe Robin Zimmerman
Publisher
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
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. iAS Overview on OLN or experience administering the Oracle9i Application Server 9.0.2. Prerequisites 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.
Related Publications Oracle Publications Title Oracle9iAS Forms Services Deployment Guide Release 9.0.2 Oracle9iDS Forms Developer Reference Guide Oracle9i Forms Developer and Forms Services 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
Part Number A92175-01 A97289-01 A92183-01
Release notes addendum:

http://otn.oracle.com/docs/products/forms/902docs/902formsaddendum.pdf
Typographic Conventions Typographic Conventions In Text

Convention Bold Element Example
Emphasized words and phrases To navigate within this application, do not in Web content only click the Back and Forward buttons. Glossary terms (if there is a glossary) Key names Buttons, check boxes, triggers, windows
The algorithm inserts the new key.
Bold italic
Brackets Caps and lowercase
Press [Enter]. Click the Executable button. Select the Registration Required check box. Assign a When-Validate-Item trigger. Open the Master Schedule window.
Carets Commas
Menu paths Key sequences
Select File > Save. Press and release these keys one at a time: [Alt], [F], [D]
Typographic Conventions (continued) Typographic Conventions In Text (continued)

Convention Courier New, case sensitive Object or Term Code output, SQL and PL/SQL code elements, Java code elements, directory names, filenames, passwords, pathnames, URLs, user input, usernames Example Code output: debug.seti (I,300); SQL code elements: Use the SELECT command to view information stored in the last_name column of the emp table. Java code elements: Java programming involves the String and StringBuffer classes. Directory names: bin (DOS), $FMHOME (UNIX) 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 (unless the term is a proper noun) Emphasized words and phrases in print publications, titles of books and courses, variables Key combinations Lesson and chapter titles in cross references, interface elements with long names that have only initial caps Customer address (but Oracle Payables)
Italic
Do not save changes to the database. For further information, see Oracle7 Server SQL Language Reference Manual. Enter user_id@us.oracle.com, where user_id is the name of the user. Press and hold these keys simultaneously: [Control] + [Alt] + [Delete] This subject is covered in Unit II, Lesson 3, Working with Objects. Select the Include a reusable module component and click Finish. Use the WHERE clause of query property.
Plus signs Quotation marks
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 (M) = Menu (T) = Tab (I) = Icon (H) = Hyperlink (B) = Button
Course Introduction
Copyright Oracle Corporation, 2002. All rights reserved.
Schedule:
Timing 20 minutes 20 minutes
Topic Lecture 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
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
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
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
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
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
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
Summit Office Supply Schema

Order Entry Application
I-7
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.
The Course Application
Customers form
I-8
Orders form
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.
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.
Why Upgrade to Oracle9i Forms?
Schedule:
Timing 30 minutes 30 minutes
Topic Lecture 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
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
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.
Oracle9iDS Application Development
1-4
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.
Oracle9iDS Business Intelligence
1-5
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.
Benefits of Oracle9i Developer Suite
Application Development
Discoverer OWB Reports
Designer Forms JDeveloper SCM
Business Intelligence
1-6
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 Overview
Optimized for the Web Productivity enhancements Globalization Integration Openness
1-7
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.
Optimized for the Web
No client-server run-time executable No character mode deployment Why?

Accessibility Cost effective Single Sign-on Openness with Java
Ease of maintenance
Run thru firewalls
Call Web services
1-8
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.
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.
Globalization
Improved translation facilities Browser language detection Support for character semantics Time zone support
1-10
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.
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
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.
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
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.
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
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.
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
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.
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.
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
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.
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
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.
Deploying Forms Applications on the Internet
Schedule:
Timing 60 minutes 40 minutes 100 minutes
Topic Lecture Practice 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
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.
Oracle 9iAS Architecture
2-3
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.
Oracle 9iAS Components
Oracle9iAS Containers for J2EE
Oracle9iAS Forms Services
2-4
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.
What Is OC4J?
A component of Oracle9i Application Server that deploys J2EE applications
Oracle9iAS containers for J2EE
2-5
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.
What Is Oracle Forms Services?
A component of Oracle9i Application Server that deploys Forms applications to Java clients in a Web environment
2-6
Oracle9iAS Forms Services
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.
Forms Services Architecture Overview

Client Tier Middle Tier: Application Server Forms Listener Servlet Forms Servlet
Incrementally downloaded
Database Tier
Forms Runtime User interface User interface layer Application logic layer
Net Services
DB
JRE Java applet
Data manager/ PL/SQL engine Files containing application code
2-7
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.
The Forms Servlet

URL Pointing to Forms Servlet
http://summit.com/forms90/f90servlet?form=customers.f
Desktop Client
Application Server Web Server
formsweb.cfg basejini.html
URL PARAMETERS:
?form=customers.fmx &userid=un/pw@db &buffer_records=NO ...
Static HTML files HTTP Server Forms Services Forms Client Base HTML files Forms Servlet Forms Listener Servlet Forms Runtime Engine
Dynamic HTML file is created
2-8
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.
The Forms Client

Desktop Client
Generic Java applet Responsibilities: Displays the forms user interface Processes user interaction back to Forms Services Processes incoming messages from Forms Services
Forms Client Generic Java applet
2-9
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
The Forms Listener Servlet

HTTP Server Forms Listener Servlet
HTTP/ HTTPS
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
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.
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
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 Formsspecific 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).
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
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.
Running a Form: Browser

How do I access this application? How do I access this new application?
http://summit.com:80/forms90/f90servlet?form=customers.fmx&userid=ora1/oracle@
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
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 Host Port for HTTP Server or OC4J Forms Servlet Alias or static HTML file Parameters: this section begins with ?; parameters separated by & (can be specified in the URL or taken from the Forms configuration file) http summit.com 80 default for HTTP Server OR 8888 default for OC4J (use only for testing) /forms90/f90servlet form=customers.fmx userid=username/password@database buffer_records=NO debug_messages=NO ....
Running a Form: Web Form Tester
2-14
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.
Starting a Run-Time Session

Client Tier Web Browser 1
URL
http://summit.com:80/forms90/f90se
Middle Tier: Application Server
Oracle9iAS HTTP Server

MOD_OC4J
OC4J Servlet Engine

Forms Servlet Forms Listener Servlet
Forms Runtime Engine
Forms Application Executables FMX files MMX files PLX files
2-15
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.
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).

Client Tier Web Browser 4
URL

MOD_OC4J
OC4J Servlet Engine

Forms Servlet Forms Listener Servlet Forms Runtime Engine
Applet started
6
6
DB
2-17
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.

Client Tier Web Browser
URL

MOD_OC4J
OC4J Servlet Engine

Forms Servlet Forms Listener Servlet Forms Runtime Engine
2-18
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.
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
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.
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
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.
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
Programs
Oracle9i Developer Suite
2-21
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.
Testing a Form: Starting OC4J

OC4J starts in DOS window: Minimize window Closing window aborts OC4J Run batch file to stop OC4J
2-22
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.
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
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 threetier 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.
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
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
default.env formsweb.cfg
Purpose
Environment control file for Forms Services: Set environment variables 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). 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
forms90.conf
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).
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 Settings in the # You can append your own Java code here) 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; d:\oracle\iDSv2\jlib\oracle_ice5.jar;d:\oracle\iDSv2\jlib\ewt3.jar; settings. d:\oracle\iDSv2\jlib\share.jar;d:\oracle\iDSv2\jlib\importer.jar
2-25
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.
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
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.
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
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.
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
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.
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
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.
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
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
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
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.
Practice 2 1. Make note of information you will need to complete these practices. Your instructor will supply you with the following:
Item Lab directory <ids_home> User ID Password Database Solutions directory Group number Machine name Example e:\labs e:\oracle\ids ora1 oracle iasdb e:\labs\soln 1 (number portion of your user id) Right-click Network Neighborhood and view properties Your specific information
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 M achine nam e OC4J Port Value <local machine> 8888 (This is the default port for OC4J, which m ay be different on your m achine.) forms90/f90servlet
Pointer to Form s Servlet
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.
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.
Migrating Existing Applications to Oracle9i Forms
Schedule:
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
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
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.
Migration Path
Forms 4.0
Forms 2.0
f45gen32
Forms 2.3
Forms 4.5
ifcmp60
Forms 6i
Oracle9i Forms
Forms 3.0
Forms 5.0
3-3
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
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
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 V2style 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.
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.
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
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.
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.
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
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.
Upgrading from Client-Server Deployment (continued) Mouse triggers: To reduce network traffic, the When-Mouse-Enter, When-MouseLeave, 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 Courier Dialog Helvetica Symbol TimesRoman Windows Font Courier New MS Sans Serif Arial WingDings Times New Roman X Windows Font adobe-courier b&h-lucidatypewriter adobe-helvetica itc-zapfdingbats adobe-times Macintosh Font Courier Geneva Helvetica Symbol 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.
Upgrading from Character Mode Deployment

Issues: Application logic Item length (WIDEN_FIELDS=YES) Navigation Fonts
3-10
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.
Upgrading to Oracle9i Forms
You can upgrade using: Forms Builder Batch compiler Migration Assistant
3-11
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.
Using the Oracle9i Forms Migration Assistant
Command: ifplsqlconv90 (Windows) or ifplsqlconv (UNIX) Arguments: module (required) userid (optional) log (optional)
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.
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.
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
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.
Configuring the Migration Assistant
Configuration files for the Migration Assistant: converter.properties search_replace.properties
3-15
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.
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
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.
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.
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
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.
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
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.
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
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.
Step 1: Create a Report Object
3-21
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.
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);
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 REPORT_FILENAME REPORT_EXECUTION_MODE REPORT_COMM_MODE REPORT_SOURCE_BLOCK REPORT_QUERY_NAME REPORT_DESTYPE REPORT_DESNAME REPORT_DESFORMAT REPORT_SERVER REPORT_OTHER Value <report file> as VARCHAR2 RUNTIME | BATCH SYNCHRONOUS | ASYNCHRONOUS <block name> as VARCHAR2 <report query name> as VARCHAR2 CACHE | SCREEN | FILE | PREVIEW | PRINTER | MAIL <Name> as VARCHAR2 html | pdf <report server name> Additional Reports parameters such as userdefined variables
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
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.
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
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;
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
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);
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
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.
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
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.
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
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 clientserver, character mode, or Forms Listener deployment.
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
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.
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 ORA6508 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.
Designing Forms Outside the Builder
Schedule:
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
Lesson Aim This lesson describe methods of modifying Forms applications without making manual modifications in Forms Builder.
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
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.
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
4-4
Work around bugs encountered when upgrading

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.
Advantages of Using an API

Time spent per form
API Forms Builder
Speed
Number of modules Errors per form

API Forms Builder
Accuracy
Number of modules
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.
Using the Java API to Modify Modules
Forms Module
CFAPI
JDAPI
Use for: Form modules Menu modules Object libraries PL/SQL libraries (load & inspect)
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.
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
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.
JDAPI Architecture
s9 rm fo
r ja i. ap d 0j f9 a\ v ja 0\
4-8
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().
JDAPI Architecture
4-9
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.
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
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.
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
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.
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
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.
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(); ....
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.
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.
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
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.
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
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.
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
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.
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
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.
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.
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
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.
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
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.
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
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.
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
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.
This practice covers the following topics: Installing javadoc for JDAPI Examining javadoc for JDAPI Modifying the Orders form using a JDAPI program
4-24
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.
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.
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.
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
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.
XML Conversion Utilities

Oracle9i Forms offers tools to:
Convert a module to XML: Forms2XML Convert XML to a Forms module: XML2Forms Generate the Forms XML schema file: SchemaGenerator Validate XML against Forms XML schema: XMLValidator
Forms XML tools
Classes needed (under ORACLE_HOME):

\forms90\java\f90xmltools.jar \lib\xmlparserv2.jar \lib\xschema.jar Also need JDAPI classes!
4-28
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 iff2xml90.bat ifxml2f90.bat ifxmlsg90.bat ifxmlv90.bat
For UNIX iff2xml90.sh ifxml2f90.sh ifxmlsg90.sh ifxmlv90.sh
Function Converts Forms modules to XML Converts XML to Forms modules Generates Forms XML Schema Validates structure of Forms XML file
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
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();
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
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();
Generating the Forms XML Schema File

Forms XML tools form90.xsd
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
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();
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
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 }
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
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.

>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
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

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
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.
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
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.
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
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.
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
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.
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? __________________________________________________________________ __________________________________________________________________ __________________________________________________________________
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.
Troubleshooting Forms Applications
Schedule:
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
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
Lesson Aim This lesson describes the new Forms facilities for debugging, tracing, and logging.
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
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 WhenValidate-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.
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
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.
Setting Breakpoints
Breakpoints: Suspend form execution Return control to the debugger Remain in effect for the Forms Builder session May be enabled or disabled Are set in the PL/SQL Editor on executable lines of code
5-5
Before setting breakpoint:
After setting breakpoint:
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.
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
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).
The Debug Console
Stack Variables Watch Form Values Loaded PL/SQL Packages Global and System Variables Breakpoints
Dock/ Undock Click bar for pop-up menu
5-7
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.
The Debug Console
5-8
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.
The Debug Console
Read-only: Modifiable:
5-9
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.
The Debug Console
5-10
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.
The Debug Console
5-11
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.
The Debug Console
5-12
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.
The Debug Console
5-13
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.
The Debug Console
5-14
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.
The Debug Console
5-15
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.
Running a Form in Debug Mode

Run Form Debug
(Compiles automatically)
Contains source code and .FMX executable run file
(Runs automatically)
Runs Form in Debug Mode on Server specified in Runtime Preferences
5-16
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.
Stepping through Code
Step over
Pause Stop
Step into
Step out
GO
5-17
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.
Debugging a Forms Module

Debug Example WHEN-BUTTONPRESSED The results are: ?? calls...
Procedure XYZ;
2
Function ABC;
4 3
5-18
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;
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;
Remotely Debugging a Running Form

I need help with the Orders form. Click Remote Debug and tell me what it says.
Application user
OK, Ill use that host and port to attach to your process.
Application developer
5-20
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.

Debug Attach Debug
Attach Debug to
pgamer-wah 1784
OK, Ive attached to 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 breakpoint in the code. Now press the Exit button.
5-21
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.

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.
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.
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
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.
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 Name Iconic Icon Filename Keyboard Navigable Mouse Navigate X Position Y Position Height Width Value Check_Total_Button Yes check No No 295 220 17 17
The function of this button is to recheck the Order Total. Write a When-ButtonPressed 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").
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.
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.
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.
Tracing and Logging Tools
Tools available for tracing and logging: Forms Trace Servlet Logging
5-28
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.
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
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, mouseclicks, 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
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
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.
Starting the Trace
Parameters:
Type of trace to perform
record=forms tracegroup=
Individual event Event set Named event set Combination
Types of events to trace
log=<filename>
What to call the log file
5-31
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.
Starting the Trace
In formsweb.cfg:
[mytrace] otherparams=record=forms tracegroup=custom1 log=mytrace.trc
5-32
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.
Traceable Events
Lets see I want to trace information about triggers..
Event types: Point event Duration event Built-in event
&tracegroup=66
5-33
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).
Traceable Events (continued) Traceable events are as follows:
Event Number 0 1 2 3 4-31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47-48 49-63 64 65 66 67 68 69 70 71 72-95 96 97 98
Definition Abnormal Error Error during open form Forms died error Error messages on the status bar Reserved for more error events to be defined Forms startup Menu Key Click Double-click Value Scroll LOV Selection Not used Window Close Window Activate Window Deactivate Window Resize Tab Page Timer Reserved for future use for asynchronous events Reserved for more Actions to be defined Form (Start and End) Procedure (Start and End) Trigger (Start and End) LOV (Start and End) Opening an Editor Canvas Alert GetFile Reserved for more Events to be defined Builtin (Start and End) User Exit (Start and End) SQL (Start and End)
Type Point Point Point Point Point Point Point Point Point Point Point Point Point Point Point Point Point Point
Duration Duration Duration Duration Point Point Duration Point Builtin Duration Duration
Traceable Events (continued)
Event Number 99 100 101 102-127 128 129 130 131 132 133 134 135 136 137 138-191 192* 193* 194* 195* 196* 197* 256 and higher 1024 and higher
Definition MenuCreate (Start and End) PLSQL (Start and End) Execute Query Reserved for more Events to be defined Client Connect Client Handshake Heartbeat HTTP Reconnect Socket (Start and End) HTTP (Start and End) SSL (Start and End) DB Processing (Start and End) DB Logon (Start and End) DB Logoff (Start and End) Reserved for more Events to be defined Environment Dump State Delta Builtin Arguments UserExit Arguments Procedure Arguments Function Arguments User defined Reserved for internal use
Type Duration Duration Duration Point Point Point Point Duration Duration Duration Duration Duration Duration n/a
* 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.
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
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 Menu Selection Key Click Double-click Value Scroll LOV Selection Alert Tab Window Activate, Deactivate, Close, Resize
Details Menu Name, Selection Key Pressed, Form, Block, Item Mouse/Key, Form, Block, Item Form, Block, Item Form, Block, Item Form, Up, Down, Page, Row LOV Name, Selection Item Alert Name, Selection Form Window Name, Form Name, Size
Number 33 34 35 36 37 38 39 40 45 41, 42, 43, 44
Obtaining Event Details (continued) Forms Server Events:

E vent N ame Form Procedure T rigger D etails Form ID , N am e, Path, Attached Libraries, Attached M enus Procedure N am e, Form ID Trigger N am e, Block N am e, Item N am e, Form ID (Form N am e w ill be included in a later enhancem ent) LO V nam e, Form ID Form ID , E ditor N am e Form ID , C anvas N am e N umber 64 65 66
LO V E ditor C anvas
67 68 69
Detailed Events:
Event Name Builtin User Exit Menu Create PLSQL ExecQuery Details Builtin Name, Form ID User Exit Name, Form ID Menu Name, Form ID PLSQL Statement, Form ID Block Name Number 96 97 99 100 101
Three-Tier Events:
Event Name Client Connect, Client Handshake, Heartbeat HTTP Reconnect Socket, HTTP, HTTPS DB Processing DB Logon, DB Logoff Details Timestamp Number 128, 129, 130 131 132, 133, 134 135 136, 137
Form ID, Packets, Bytes Form ID, Statement Form ID
Miscellaneous:
Event Name Environment Dump State Delta Builtin Args User Exit Args Procedure Args Function Args Details Selected environment information Changes to internal state caused by the last action/event Argument values passed to a builtin Argument values passed to a user exit Arguments (in/out) passed to a procedure Arguments (in/out) passed to a function Number 192 193 194 195 196 197
Viewing Forms Trace Output

Set CLASSPATH
Xlate Version 1.0 Usage: Xlate DataFile=filename XMLFile=filename URL=host:port:sid UserName=user_id Password=user_pwd CollectionID=collection_id Regression=true|false DataFile XMLFile URL UserName Password binary file produced by Forms server XML output file name database URL e.g. mymachine:1521:my_sid user name to access database 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 -
Run Translate utility
5-38
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.
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.
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
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.
Servlet Logging
Four levels: Session Session-performance Request-performance Debug To turn on logging for Forms Listener Servlet, add to serverURL parameter: /session /sessionperf /perf /debug
You can also perform debug level logging for Forms Servlet:
http://<machine>:<port>/forms90/f90servlet/debug?config=summit
5-41
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)
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 (none) /session /sessionperf /perf /debug Description of Logging No log messages are produced, but during Forms Servlet initialization, logs the name and path of the configuration file being used When a Forms session starts or ends, logs host name, client IP address, runtime process ID, and a unique internal session ID number Includes performance summary statistics with the session end message Writes a performance message for every request from the client 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.
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
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\applicationdeployments\forms. For iAS (on UNIX): <iDS_HOME>/j2ee/<Product Group>/application-deployments/ forms90app Example: /oracle/ias902/j2ee/OC4J_BI_Forms/applicationdeployments/ forms90app
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 pgamerwah ( 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))
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
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.
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
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.
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
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.
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
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.
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.
Integrating Java into Forms Applications
Schedule:
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
Lesson Aim This lesson describes the enhanced support in Oracle9i Forms for integrating Java into your applications.
Using Java in Forms
Client: JavaBeans, PJCs
Middle Tier: Java Importer
Database: Java Stored Procedures
6-3
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.
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
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.
Using Client-Side Code
JavaBeans Pluggable Java Components FBean Package
6-5
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.
Using Client-Side Code (continued) The Oracle9i Forms Demos include the following JavaBean and PJC components:
Component Spell Checking with JSpell 2.0 File Upload Utility Calendar Progress Bar Hyperlink Get Client Info
Clock Rollover Button
Key Filter
Modify Cursor
Color Picker Info Button
Multi Select T-List Insert Replace Text Fields
Description Enables text items to utilize the JSpell package from WallstreetWise; the JSpell software is not supplied with the Forms demo suite and must be purchased separately if required Displays a file selection dialog on the browser machine and transfers the selected file up to the middle tier Enables selection of a date from a calendar widget, without generating network traffic to display a Forms based calendar Displays a progress meter Provides a UI widget that looks and acts like an HTML hyperlink 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 Displays a simple digital clock Provides an enhanced version of a standard Forms button that reacts to the mouse hovering over it by changing the displayed image Customizes a normal text item to prevent unwanted characters from being entered; filters keystrokes without generating network traffic to the Application server 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 Enables client to change color properties of Forms objects by selecting from a color picker 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 Enhanced version of the Forms TList control that allows multiple selections Enables insert/replace functionality on Forms text items
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.
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
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.
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 le Radio groups sib n
e Ext UI
Radio Buttons: Cash Credit Card
Checkboxes: Y N Disabled
Check
6-8
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.
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
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
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
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.
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
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.
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.
Registering the Bean

At design time
At run time
FBEAN.REGISTER_BEAN(:CONTROL.hyperlink,1, 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
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.
Setting Bean Area Item Properties
6-14
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.
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
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.
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
2
event
3
parameters
6-16
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 WhenCustom-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.
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 WhenCustom-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.
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)
3 1 2
51,255,255
6-18
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.
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
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.
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.
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
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.
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
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.
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.
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.
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.
Enhancing the User Experience
Schedule:
Objectives
After completing this lesson, you should be able to do the following: Design an LOV that can be canceled for longrunning queries Write code that retrieves the Forms version Write code to restrict a query only the first time it is executed
7-2
Lesson Aim This lesson describes the new run-time enhancements for Oracle9i Forms.
The Cancelable LOV
Incrementing value
7-3
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.
Retrieving the Forms Version
GET_APPLICATION_PROPERTY(VERSION)
7-4
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.
The One Time Where Clause
Initially shows restricted query 2nd Execute_Query not restricted

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.
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
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
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
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.
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 NonBlocking. 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.
Deploying Forms Applications Globally
Schedule:
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
Lesson Aim This lesson presents information to enable you to deploy multinational applications that account for differences in language, time zone, and character set.
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 JA16SJIS UTF8
VARCHAR2(5 CHAR) VARCHAR2(5 CHAR) VARCHAR2(5 CHAR)

8-3
1 2 3 4 5 1 1 2 2 3 3 4 5
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.
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
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.
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?
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
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.
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
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.
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 Full DATETIME value Date-only portion of a DATETIME value DATETIME value preceded by relational operator DATETIME value containing wildcard character(s) (% or _ ) Value beginning with #, :, or &
Adjusted? Yes Yes Yes No 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 timezone 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 timezone 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.
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
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.
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
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.
Displaying Applications in Multiple Languages
en
9iAS HTTP Listener
it de
OC4J
Forms Servlet
Which application should I use?
Forms Listener Servlet Booking_en.fmx fr Booking_it.fmx Forms Runtime Booking_de.fmx Booking_fr.fmx
8-11
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.
Detecting Browser Language Settings

Tools Internet Options
Change language preferences

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.
Translated Applications at Run Time

http://server/forms90/f90servlet?config=booking accept_language=it
en
formsweb.cfg
[booking] envFile=default.env [booking.it] envFile=italian.env [booking.en] envFile=english.env [booking.french] envFile=fr.env
9iAS HTTP Listener
it de
OC4J
Forms Servlet italian.env
french.env
Forms Listener Servlet fr
english.env german.env italian.env
Forms Runtime
NLS_LANG=Italian_Italy. WE8ISO8859P1 Forms90_PATH =
Booking_it.fmx
8-13
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.
Deploying Language-Specific Applications

Steps for deployment:
Booking_fr.fmx
1. Translate the application.

french.env english.env italian.env
NLS_LANG=Italian_Italy. WE8ISO8859P1 Forms90_PATH = ...
...
Booking_en.fmx Booking_it.fmx
2. Define an environment file for each language.

formsweb.cfg
[booking] envFile=default.env [booking.it] envFile=italian.env [booking.en] envFile=english.env [booking.fr] envFile=french.env
3. Define a named configuration for each environment.
8-14
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.
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
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).
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
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.
Starting TranslationHub
Start > Programs Windows menu

Starting TranslationHub
Forms Developer
TranslationHub
Oracle9i Developer Suite iDSv2
8-17
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.
The TranslationHub User Interface
8-18
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
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
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.
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
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.
Constructing a Translation Project

Create a translation project from the base project.
8-21
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.
Translating the Text
Translate the strings:
*HVXQGKHLW
8-22
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.
Building the Translated Software
*HVXQGKHLW
8-23
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.
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 variablebyte character sets.
8-24
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.
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
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.
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
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.
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
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.
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.
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.
Practice Solutions
Practice 2 Solutions 1. Make note of information you will need to complete these practices. Your instructor will supply you with the following:
Item Lab directory <ids_home> User ID Password Database Solutions directory Group number Machine name Example e:\labs e:\oracle\ids ora1 oracle iasdb e:\labs\soln 1 (number portion of your user id) Right-click Network Neighborhood and view properties Your specific information
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 M achine nam e OC4J Port Value <local machine> 8888 (This is the default port for OC4J, which m ay be different on your m achine.) forms90/f90servlet
Pointer to Form s Servlet
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.
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.
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 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.
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.
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.
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.
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.
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 ORA6508 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.
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):
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);
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.
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(); }}
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.
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
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.
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.
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.
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.
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 Name Iconic Icon Filename Keyboard Navigable Mouse Navigate X Position Y Position Height Width
Value Check_Total_Button Yes check No No 295 220 17 17
The function of this button is to recheck the Order Total. Write a When-ButtonPressed 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.
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:
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.
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.
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.
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.
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.
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 popup 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;
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.
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);
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.
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.
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;
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 NonBlocking. 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));
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.
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. ____________________________ ____________________________
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 dropdown 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.
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.
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.
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.
Integrating Oracle9i Forms with Oracle9i Application Server
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
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.
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
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
OEM: System Components Page

1 3
4
B-4
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.
OEM: Forms Services Management Page

Status
B-5
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.
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
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 LDAPcompatible. Everything that must be done to make Forms Services work with OID is performed by the Oracle9iAS installer.
Oracle9i Forms SSO Architecture
Oracle 9iAS
Oracle HTTP Server
powered by Apache
1
mod_osso
Forms Listener Servlet Forms Servlet
Oracle9i DB
2 3
Oracle9i Single SignOn Server
Oracle9i Internet Directory
B-7
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.
The Oracle9i Forms SSO Process
Oracle 9iAS
powered by Apache
Oracle HTTP Server
2
mod_osso
Oracle9i DB
3
Oracle9i Single SignOn Server Oracle9i Internet Directory
B-8
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.
username
Oracle 9iAS
Oracle HTTP Server
powered by Apache
FNIMPHIU
password
IMGR8T
mod_osso
Oracle9i DB
B-9
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.
Oracle 9iAS
Oracle HTTP Server
powered by Apache
mod_osso
Oracle9i DB
6
B-10
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.
Oracle 9iAS
Oracle HTTP Server
powered by Apache
mod_osso
Oracle9i DB
7
B-11
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."
Oracle 9iAS
Oracle HTTP Server
powered by Apache
mod_osso
Oracle9i DB
8
B-12
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.

Whats the SSO user name? Use the function: GET_APPLICATION_PROPERTY(SSO_USERID); Oracle 9iAS
Oracle HTTP Server
powered by Apache
10 9
Oracle9i DB
mod_osso
B-13
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.
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
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.

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 .... .... [faq] form=faq.fmx
9iDB connect string:

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).
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.
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
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.
Relationship Between SSO Elements

Oracle Internet Directory SSO user Username: FormsUser SSO password: ora1
formsweb.cfg .... [hr_app] form=hr.fmx [order_entry] form=orders.fmx [expense] form= expense_report.fmx
B-18
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.
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
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.
Managing the Team Development of Forms Applications
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
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
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 SCM Options in Forms Builder
File > Administration Check In Check Out Source Control Options
C-4
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).
Setting Up SCM to Work with Forms

Required administration tasks: Repository Administration Utility:
Enable the repository Options for versioning: Options > Enable Version Support Enable Version Support Create repository users with default privileges
Repository Administration Utility
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
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.
Creating SCM Containers
C-6
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.
Setting Up a Work Area
Change repository connection Change work area Select container
C-7
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.
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
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.
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
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.
Checking In a File
1. 2.
3. 4.
Save file to file system File > Administration > Check In Select options Add notes
C-10
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.
An Overwriting Scenario
User 1
1. In Forms Builder (FB), opens myform.fmb from file system, makes changes, saves, checks in myform.fmb to SCM. 2.
User 2
In FB, opens myform.fmb, checks it out from SCM, closes and reopens, makes changes, saves to file system, checks back in to SCM, closes form in FB.
3.
With form still open, makes more changes in Forms Builder, checks form out from SCM, saves form to file system, checks form in.
4.
Opens form from file system, checks out from SCM, closes form and reopens to get latest version in FB, discovers previous changes are gone.
C-11
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.
Deleting a File from the Repository
C-12
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.
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
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.
Table Descriptions
Summit Office Supply Database Diagram
ORDER_ITEMS
PRODUCT_ID
ORDER_ID
ORDER_ID
ORDERS
SALES_REP_ID CUSTOMER_ID
CUSTOMER_ID
* INVENTORIES
PRODUCT_ID
CUSTOMERS
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 -----------------CUSTOMER_ID CUST_FIRST_NAME CUST_LAST_NAME CUST_ADDRESS PHONE_NUMBERS NLS_LANGUAGE NLS_TERRITORY CREDIT_LIMIT CUST_EMAIL ACCOUNT_MGR_ID Null? -------NOT NULL NOT NULL NOT NULL Type ------------NUMBER(6) VARCHAR2(20) VARCHAR2(20) CUST_ADDRESS_TYP VARCHAR2(30) VARCHAR2(3) VARCHAR2(30) NUMBER(9,2) VARCHAR2(30) NUMBER(6)
SQL> desc cust_address_typ Name Null? ------------------ -------STREET_ADDRESS POSTAL_CODE CITY STATE_PROVINCE COUNTRY_ID Related object creation statements
Type -----------VARCHAR2(40) VARCHAR2(10) VARCHAR2(30) VARCHAR2(10) CHAR(2)
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 , cust_first_name cust_fname_nn NOT NULL , cust_last_name cust_lname_nn NOT NULL , cust_address , phone_numbers , nls_language
NUMBER(6) VARCHAR2(20) CONSTRAINT VARCHAR2(20) CONSTRAINT cust_address_typ varchar2(30) VARCHAR2(3)
CUSTOMERS Description (continued)

, , , , , nls_territory credit_limit cust_email account_mgr_id CONSTRAINT VARCHAR2(30) NUMBER(9,2) VARCHAR2(30) NUMBER(6) customer_credit_limit_max CHECK (credit_limit <= 5000) customer_id_min CHECK (customer_id > 0)) ;
, CONSTRAINT
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
DEPARTMENTS Description
SQL> desc departments Name Null? ------------------- -------DEPARTMENT_ID NOT NULL DEPARTMENT_NAME NOT NULL MANAGER_ID LOCATION_ID Type -----------NUMBER(4) VARCHAR2(30) NUMBER(6) 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 START WITH INCREMENT BY MAXVALUE NOCACHE NOCYCLE; departments_seq 280 10 9990
DEPARTMENTS Description (continued) SQL> select * from departments; DEPARTMENT_ID DEPARTMENT_NAME MANAGER_ID LOCATION_ID ------------- ----------------- ---------- --------10 Administration 20 Marketing 30 Purchasing 40 Human Resources 50 Shipping 60 IT 70 Public Relations 80 Sales 90 Executive 100 Finance 110 Accounting 120 Treasury 130 Corporate Tax 140 Control And Credit 150 Shareholder Services 160 Benefits 170 Manufacturing 180 Construction 190 Contracting 200 Operations 210 IT Support 220 NOC 230 IT Helpdesk 240 Government Sales 250 Retail Sales 260 Recruiting 270 Payroll 27 rows selected. 200 201 114 203 121 103 204 145 100 108 205 1700 1800 1700 2400 1500 1400 2700 2500 1700 1700 1700 1700 1700 1700 1700 1700 1700 1700 1700 1700 1700 1700 1700 1700 1700 1700 1700
EMPLOYEES Description SQL> desc employees Name Null? Type ------------------ -------- -----------EMPLOYEE_ID FIRST_NAME LAST_NAME EMAIL PHONE_NUMBER HIRE_DATE JOB_ID SALARY COMMISSION_PCT MANAGER_ID DEPARTMENT_ID NOT NULL NUMBER(6) VARCHAR2(20) NOT NULL VARCHAR2(25) NOT NULL VARCHAR2(25) VARCHAR2(20) NOT NULL DATE NOT NULL VARCHAR2(10) NUMBER(8,2) NUMBER(2,2) NUMBER(6) 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) ) ;
EMPLOYEES Description (continued)

CREATE UNIQUE INDEX emp_emp_id_pk ON employees (employee_id) ; ALTER TABLE employees ADD ( CONSTRAINT , CONSTRAINT emp_emp_id_pk PRIMARY KEY (employee_id) 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 INCREMENT BY NOCACHE NOCYCLE; 207 1
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 AD_PRES 101 AD_VP Steven King 24000 Neena 17000 Kochhar SKING 515.123.4567 17-JUN-87 90
NKOCHHAR 515.123.4568 21-SEP-89 100 90
INVENTORIES Description and Data

SQL> desc inventories Name ----------------------------------------PRODUCT_ID WAREHOUSE_ID QUANTITY_ON_HAND Null? -------NOT NULL NOT NULL NOT NULL Type --------NUMBER(6) NUMBER(3) NUMBER(8)

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
PRODUCTS Description and Data

SQL> desc products Name Null? ---------------------- -------PRODUCT_ID NOT NULL LANGUAGE_ID PRODUCT_NAME CATEGORY_ID PRODUCT_DESCRIPTION WEIGHT_CLASS WARRANTY_PERIOD SUPPLIER_ID PRODUCT_STATUS LIST_PRICE MIN_PRICE CATALOG_URL Type --------------NUMBER(6) VARCHAR2(3) NVARCHAR2(250) NUMBER(2) NVARCHAR2(4000) NUMBER(1) NUMBER(5) NUMBER(6) VARCHAR2(20) NUMBER(8,2) NUMBER(8,2) VARCHAR2(50)

CREATE AS SELECT , , OR REPLACE VIEW products 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 product_information i product_descriptions d d.product_id (+) = i.product_id d.language_id (+) = sys_context(USERENV,LANG);
, ,
, , , , , , , FROM , WHERE AND
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
ORDER_ITEMS Description
SQL> desc order_items; Name Null? -------------------- -------ORDER_ID NOT NULL LINE_ITEM_ID NOT NULL PRODUCT_ID NOT NULL UNIT_PRICE QUANTITY Type ----------NUMBER(12) NUMBER(3) NUMBER(6) NUMBER(8,2) NUMBER(8)

CREATE TABLE order_items ( order_id , line_item_id , product_id , unit_price , quantity ) ; NUMBER(12) NUMBER(3) NOT NULL NUMBER(6) NOT NULL NUMBER(8,2) 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)) ;
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
ORDERS Description and Data

SQL> desc orders Name -----------------ORDER_ID ORDER_DATE ORDER_MODE CUSTOMER_ID ORDER_STATUS ORDER_TOTAL SALES_REP_ID PROMOTION_ID Null? -------NOT NULL NOT NULL Type ----------NUMBER(12) DATE VARCHAR2(8) NOT NULL NUMBER(6) NUMBER(2) NUMBER(8,2) NUMBER(6) NUMBER(6)

CREATE TABLE orders ( order_id , order_date , order_mode , customer_id NULL , order_status , order_total , sales_rep_id , promotion_id , CONSTRAINT (direct,online)) , constraint NUMBER(12) DATE CONSTRAINT order_date_nn NOT NULL VARCHAR2(8) NUMBER(6) CONSTRAINT order_customer_id_nn NOT NUMBER(2) NUMBER(8,2) NUMBER(6) NUMBER(6) order_mode_lov CHECK (order_mode in 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) ;
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 102 1 42283.2 2397 19-NOV-99 direct 154 2454 02-OCT-99 direct 103 1 6653.4 154 2354 14-JUL-00 direct 104 0 46257 155 105 2 7826 2358 08-JAN-00 direct 155 106 3 23034.6 2381 14-MAY-00 direct 156 107 3 70576.9 2440 31-AUG-99 direct 156 108 5 59872.4 2357 08-JAN-98 direct 158 2394 10-FEB-00 direct 109 5 21863 158 2435 02-SEP-99 direct 144 6 62303 159 145 7 14087.5 2455 20-SEP-99 direct 160 146 8 17848.2 2379 16-MAY-99 direct 161

Oracle 9i Forms Developer

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Oracle 9i Forms Developer

Uploaded by

Copyright:

Available Formats

Oracle 9i Forms Developer: New Features

D14298GC10 Production 1.0 October 2002 D37333

Technical Contributors and Reviewers

Oracle9i Forms Developer: New Features Preface - 2

Oracle9i Forms Developer: New Features Preface - 3

Part Number A92175-01 A97289-01 A92183-01

Release notes addendum:

Oracle9i Forms Developer: New Features Preface - 4

Typographic Conventions Typographic Conventions In Text

Brackets Caps and lowercase

Menu paths Key sequences

Oracle9i Forms Developer: New Features Preface - 5

Typographic Conventions (continued) Typographic Conventions In Text (continued)

Plus signs Quotation marks

Oracle9i Forms Developer: New Features Preface - 6

Oracle9i Forms Developer: New Features Preface - 7

Oracle9i Forms Developer: New Features Preface - 8

Copyright Oracle Corporation, 2002. All rights reserved.

Timing 20 minutes 20 minutes

Topic Lecture Total

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features I-2

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features I-3

Oracle9i Forms Developer: New Features I-4

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features I-5

Oracle9i Forms Developer: New Features I-6

Summit Office Supply Schema

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features I-7

The Course Application

Copyright Oracle Corporation, 2002. All rights reserved.

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.

Timing 30 minutes 30 minutes

Topic Lecture Total

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features 1-2

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features 1-3

Oracle9iDS Application Development

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features 1-4

Oracle9iDS Business Intelligence

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features 1-5

Benefits of Oracle9i Developer Suite

Discoverer OWB Reports

Designer Forms JDeveloper SCM

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features 1-6

Oracle9i Forms Overview

Optimized for the Web Productivity enhancements Globalization Integration Openness

Copyright Oracle Corporation, 2002. All rights reserved.

Oracle9i Forms Developer: New Features 1-7

Optimized for the Web

No client-server run-time executable No character mode deployment Why?

Run thru firewalls

Call Web services

Copyright Oracle Corporation, 2002. All rights reserved.