Oracle iDS Forms: Build Internet Applications II Volume 1 • Student Guide .......................................................................................
l a n r e t n I e l c a r O 40034GC11
Production 1.1 June 2001 D33129
ly n O e s U I A O &
Author
Copyright Oracle Corporation, 2001. All rights reserved.
Ian Purvis
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:
Technical Contributors and Reviewers Cem Ayberkin Gunnar Bohrs Brian Boxx Libor Danek Laurent Dereac Brain Fry Pam Gamer Pascal Gibert Thierry Guibert Ellen Gravina Norris Gray Anthony Hargreaves Ali Hiemstra Barry Hiern Ursula Hovy Sarah Jones Jan Keuben Aija Lehtonen Regis Louis Kenji Makita Jayne Marlow Sergei Pechersky Milos Randak Jonas Reborg Bryan Roberts Candace Stover Hiroyuki Sugiyama Laura Tejero Jack Walsh
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 the Worldwide Education Services group 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 659806, Redwood Shores, CA 94065. Oracle Corporation does not warrant that this document is error-free. Oracle Developer, Oracle Server, and PL/SQL 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.
l a n r e t n I e l c a r O
Publisher
Shane Mattimoe
ly n O e s U I A O &
Contents .....................................................................................................................................................
Contents Preface Profile xv Related Publications xvi Typographic Conventions xvii Introduction Introduction I-2 Course Content I-3 Lesson 1: Creating a Menu Module Introduction 1-3 Components of the Menu Module 1-5 The Default Menu 1-7 The Menu Editor 1-9 Creating a Menu Module 1-11 Module Properties 1-13 Menu Properties 1-15 Menu Item Properties 1-17 Menu Item Types 1-19 Menu Item Command Types 1-21 Implementing Menu Toolbars 1-23 Storing the Menu Module 1-25 Attaching the Menu Module 1-27 Pop-up Menus 1-29 Summary 1-31 Practice Overview: Lesson 1 1-33 Practice 1 1-34
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 2: Managing Menu Modules Introduction 2-3 Using PL/SQL in Menu Item Code 2-5 Useful Built-in Menu Subprograms 2-7
..................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II iii
Contents .....................................................................................................................................................
Showing and Hiding the Current Menu 2-9 Managing Menu Security 2-11 Defining Security Roles 2-13 Assigning Access to Menu Items 2-15 Summary 2-17 Practice Overview: Lesson 2 2-19 Practice 2 2-20 Lesson 3: Programming Function Keys Introduction 3-3 Key Triggers 3-5 Defining Key Triggers 3-7 Characteristics of Key Triggers 3-9 Classification of Key Triggers 3-11 Using Key Triggers 3-15 Association with Other Interface Controls 3-17 Summary 3-19 Practice Overview: Lesson 3 3-21 Practice 3 3-22 Lesson 4: Responding to Mouse Events Introduction 4-3 What Are Mouse Events? 4-5 Responding to Mouse Movement 4-7 Responding to Mouse Button Actions 4-11 Summary 4-15 Practice Overview: Lesson 4 4-17 Practice 4 4-18
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 5: Controlling Windows and Canvases Programmatically Introduction 5-3 Using Window-Interaction Triggers 5-5 Built-ins for Manipulating Windows 5-7 Built-ins for Manipulating Canvases 5-9
..................................................................................................................................................... iv Oracle iDS Forms: Build Internet Applications II
Contents .....................................................................................................................................................
Working with Tab-Style Canvases 5-11 Windows and Blocks 5-15 Manipulating Window Properties Programmatically 5-17 Closing Windows 5-19 Manipulating Windows in Web-Deployed Forms 5-21 Sizing Windows for Web-Deployed Forms 5-23 Display Large Data Blocks in a Window 5-25 Managing Images for Web-Deployed Forms 5-27 Summary 5-29 Practice Overview: Lesson 5 5-31 Practice 5 5-32 Lesson 6: Defining Data Sources Introduction 6-3 Data Source Types 6-5 Basing a Data Block on a FROM Clause Query 6-7 Basing a Data Block on a Stored Procedure 6-9 Example of a Query Using a REF Cursor Procedure 6-11 Example of Query Using a Table of Records Procedure 6-13 Example of DML Using a Stored Procedure 6-15 Deciding Whether to Use a REF Cursor or a Table of Records 6-17 Data Block Wizard 6-19 Data Block Properties 6-21 Data Source Guidelines 6-23 Summary 6-27 Practice Overview: Lesson 6 6-29 Practice 6 6-30
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 7: Working with Oracle8i Objects in Form Builder Introduction 7-3 What Are Object Types? 7-5 Review of Objects 7-7 Object REFs 7-9
..................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II v
Contents .....................................................................................................................................................
Supported Oracle8i Features 7-11 How Oracle Forms Developer Treats Objects 7-13 Object Type Displays 7-15 Creating Data Blocks Based on Oracle8i Objects 7-17 Selecting Object Table Columns 7-19 Selecting Object Column Attributes 7-21 Blocks with REF Lookups 7-23 The REF Column Value 7-25 LOVs for REFs 7-27 Summary 7-29 Practice Overview: Lesson 7 7-31 Practice 7 7-32 Lesson 8: Controlling Data Block Relationships Introduction 8-3 Creating a Relation 8-5 Block Coordination 8-7 Coordinate Blocks Using REFs 8-9 Characteristics of Relation-Handling Triggers 8-11 Principles of Relation-Handling Code 8-13 Obtaining Relation-Handling Information 8-15 Implementing a Coordination-Type Toggle 8-17 Forcing a Commit Per Master 8-19 Summary 8-21 Practice Overview: Lesson 8 8-23 Practice 8 8-24
ly n O e s U I A O &
Lesson 9: Building Multiple Form Applications Introduction 9-3 OPEN_FORM to Invoke Additional Forms 9-5 Closing Forms 9-7 Navigating Between Forms 9-9 Transaction Processing for Opened Forms 9-11 CALL_FORM to Invoke Additional Forms 9-13
l a n r e t n I e l c a r O
..................................................................................................................................................... vi Oracle iDS Forms: Build Internet Applications II
Contents .....................................................................................................................................................
Transaction Processing for Called Forms 9-15 NEW_FORM to Invoke Additional Forms 9-19 Controlling Open Forms and Called Forms Together 9-21 Different Ways of Invoking Forms 9-23 Using Form Parameters 9-25 Parameter Lists 9-29 Creating and Manipulating Parameter Lists 9-31 Passing Data Between Forms 9-33 Summary 9-35 Practice Overview: Lesson 9 9-37 Practice 9 9-38 Lesson 10: Working with Record Groups Introduction 10-3 Record Groups 10-5 Using Record Groups 10-7 Defining Record Groups at Design Time 10-9 Built-in Functions for Controlling Record Groups 10-11 Defining Query Record Groups Programmatically 10-17 Defining Nonquery Record Groups Programmatically 10-19 Manipulating Record Group Rows 10-21 Manipulating Selected Record Group Rows 10-23 Defining Global Record Groups 10-25 Manipulating List Items Programmatically 10-27 Implementing Dynamic List Items 10-29 Adding Values to Combo Boxes 10-31 Summary 10-33 Practice Overview: Lesson 10 10-35 Practice 10 10-36
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 11: Using Reusable Components Introduction 11-3 Reusable Components 11-5 Reusable Components List 11-7
..................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II vii
Contents .....................................................................................................................................................
The Calendar Class 11-11 Calendar Object Group Content 11-13 Built-in for Manipulating the Calendar 11-15 Summary 11-17 Practice Overview: Lesson 11 11-19 Practice 11 11-20 Lesson 12: Using Java with Web-Deployed Forms Introduction 12-3 Java and Oracle Forms Developer 12-5 Java in Web-Deployed Forms 12-7 The Forms Applet 12-9 Defining Fonts for Web-Deployed Forms 12-11 Pluggable Java Components 12-13 What Is a Bean Area? 12-17 Hosting a JavaBean 12-19 How a JavaBean Communicates 12-21 Communicating with the JavaBean 12-23 Exploiting Oracle8i Features 12-25 How to Create JavaBeans 12-27 The Java Importer 12-29 The Java Importer Tool 12-31 Summary 12-33 Practice Overview: Lesson 12 12-35 Practice 12 12-36
ly n O e s U I A O &
Lesson 13: Using Server Features in Form Builder Introduction 13-3 Using Oracle Database Server Functionality in Forms 13-5 Dealing with PL/SQL Code 13-7 PL/SQL8 Support 13-9 PL/SQL8 Scalar Data Types 13-11 Unsupported Oracle Forms Developer PL/SQL8 Features 13-13 Handling Errors Raised by the Oracle Database Server 13-15
l a n r e t n I e l c a r O
..................................................................................................................................................... viii Oracle iDS Forms: Build Internet Applications II
Contents .....................................................................................................................................................
Performing DDL with FORMS_DDL 13-19 Using FORMS_DDL 13-21 Summary 13-23 Practice Overview: Lesson 13 13-25 Practice 13 13-26 Lesson 14: Applying Timers Introduction 14-3 Timers 14-5 Handling Timer Expiration 14-7 Creating a Timer 14-9 Modifying a Timer 14-11 Deleting a Timer 14-13 Summary 14-15 Practice Overview: Lesson 14 14-17 Practice 14 14-18 Lesson 15: Including Charts and Reports Introduction 15-3 Including Charts by Using the Chart Wizard Chart Item Properties 15-11 Reporting Within Form Builder 15-13 Report Object Properties 15-15 Working with Reports 15-17 Summary 15-23 Practice Overview: Lesson 15 15-25 Practice 15 15-26 Appendix A: Practice Solutions Practice 1 Solutions A-2 Practice 2 Solutions A-6 Practice 3 Solutions A-9 Practice 4 Solutions A-11 Practice 5 Solutions A-12
l a n r e t n I e l c a r O
15-5
ly n O e s U I A O &
..................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II ix
Contents .....................................................................................................................................................
Practice 6 Solutions Practice 7 Solutions Practice 8 Solutions Practice 9 Solutions Practice 10 Solutions Practice 11 Solutions Practice 12 Solutions Practice 13 Solutions Practice 14 Solutions Practice 15 Solutions
A-15 A-16 A-18 A-21 A-24 A-27 A-30 A-33 A-35 A-37
Appendix B: Table Descriptions and Data Summit Sporting Goods Database Diagram S_CUSTOMER Description B-3 S_CUSTOMER Data B-4 S_DEPT Description and Data B-8 S_EMP Description B-9 S_EMP Data B-10 S_ITEM Description B-13 S_ITEM Data B-14 S_ORD Description and Data B-16 S_PRODUCT Description B-17 S_PRODUCT Data B-18 S_REGION Description and Data B-22 S_TITLE Description and Data B-23 Oracle8i Objects: Types, Tables B-24 Appendix C: Mouse Movement Events Introduction C-2 Drag and Drop C-4 Summary C-6
l a n r e t n I e l c a r O
B-2
ly n O e s U I A O &
Appendix D: Introduction to Oracle8i Object Features Introduction D-3
..................................................................................................................................................... x Oracle iDS Forms: Build Internet Applications II
Contents .....................................................................................................................................................
New Oracle8i Data Types D-5 Object Types D-7 Creating Oracle8i Objects D-11 Object Columns D-13 Object Views D-15 INSTEAD-OF Triggers D-17 Referencing Objects D-19 Displaying Oracle8i Objects in the Object Navigator D-21 Summary D-29 Appendix E: Menu Run-Time Parameters Introduction E-3 Substitution Parameters E-5 Defining a User-Named Substitution Parameter E-7 Substitution Parameter Built-ins E-9 Validating a Substitution Parameter Value E-11 Summary E-13 Appendix F: Handling Server-Side Errors Introduction F-3 Obtaining the Cause of Declarative-Constraint Violations F-5 Customizing Oracle Server Error Messages F-7 Example Procedure for Handling Oracle Server Errors F-9 Summary F-13 Appendix G: EMP_PKG Package Package Specification G-2 Package Body G-4
l a n r e t n I e l c a r O
ly n O e s U I A O &
Appendix H: Working with ActiveX Controls Introduction H-3 What Are VBX, OCX, and ActiveX Controls? H-5 Comparison of VBX, OCX, and ActiveX Controls H-7 ActiveX in Form Builder H-9 Implementing an ActiveX Control H-11
..................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II xi
Contents .....................................................................................................................................................
Inserting an ActiveX Control in an ActiveX Control Item H-13 Importing ActiveX Control Methods and Events Packages H-15 Setting and Getting ActiveX Control Properties H-17 Invoking ActiveX Control Methods H-21 Responding to ActiveX Control Events H-23 Handling Exceptions H-25 Registering an ActiveX Control H-27 Summary H-29 Appendix I: Using Oracle Server Roles at Run Time Using Oracle Server Roles at Run Time I-3 Procedures for Managing Roles I-7
l a n r e t n I e l c a r O
ly n O e s U I A O &
..................................................................................................................................................... xii Oracle iDS Forms: Build Internet Applications II
Preface .................................
l a n r e t n I e l c a r O
ly n O e s U I A O &
Preface .....................................................................................................................................................
Notes Page
l a n r e t n I e l c a r O
ly n O e s U I A O &
..................................................................................................................................................... xiv Oracle iDS Forms: Build Internet Applications II
Profile .....................................................................................................................................................
Profile Before You Begin This Course Before you begin this course, you should have the following qualifications: • Thorough knowledge of: - Creating simple applications with Oracle Forms Developer Form Builder - Creating SQL query statements • Working experience of: - Creating PL/SQL constructs, including conditional statements, procedures, and functions - Creating PL/SQL stored (server) procedures and functions • Knowledge of using a graphical user interface (GUI) • Knowledge of using a Web browser, and downloading HTML pages with a Uniform Resource Locator (URL) Prerequisites The following instructor-led training (ILT) course: Oracle 9iDS Forms: Build Internet Applications I Suggested Follow-up Courses • Oracle 9iDS Reports: Build Internet Reports • Oracle 9iAS Forms Services: Deploy Internet Applications
ly n O e s U I A O &
How This Course Is Organized Oracle 9iDS Forms: Build Internet Applications II is an instructor-led course featuring lectures and hands-on exercises. Online demonstrations and written practices reinforce the concepts and skills introduced.
l a n r e t n I e l c a r O
..................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II xv
Preface .....................................................................................................................................................
Related Publications Oracle Publications Title
Part Number
Oracle Forms Developer and Oracle Reports Developer Guidelines for Building Applications, Release 6i
A73073-02
Oracle Forms Developer Getting Started, Release 6i
A73154-01
Oracle Forms Server Release 6i Patch 2: Deploying Forms Applications to the Web with the Oracle Internet Application Server
A86202-01
Additional Publications • read.me file • relnotes.pdf file
l a n r e t n I e l c a r O
ly n O e s U I A O &
..................................................................................................................................................... xvi Oracle iDS Forms: Build Internet Applications II
Typographic Conventions .....................................................................................................................................................
Typographic Conventions Typographic Conventions in Text Convention Bold italic Caps and lowercase
Element Glossary term (if there is a glossary) Buttons, check boxes, triggers, windows
Courier new, case sensitive (default is lowercase)
Code output, directory names, filenames, passwords, pathnames, URLs, user input, usernames
Initial cap
Graphics labels (unless the term is a proper noun) Emphasized words and phrases, titles of books and courses, variables
Italic
Quotation marks
Interface elements with long names that have only initial caps; lesson and chapter titles in cross-references SQL column names, commands, functions, schemas, table names
l a n r e t n I e l c a r O Uppercase
Example The algorithm inserts the new key. Click the Executable button. Select the Can’t Delete Card check box. Assign a When-Validate-Item trigger . . . Open the Master Schedule window. Code output: debug.seti(’I’,300); Directory: bin (DOS), $FMHOME (UNIX) Filename: Locate the init.ora file. Password: Use tiger as your password. Pathname: Open c:\my_docs\projects URL: Go to http://www.oracle.com User input: Enter 300 Username: Log on as scott Customer address (but Oracle Payables)
Do not save changes to the database. For further information, see Oracle7 Server SQL Language Reference Manual. Enter
[email protected], where user_id is the name of the user. Select “Include a reusable module component” and click Finish. This subject is covered in Unit II, Lesson 3, “Working with Objects.”
ly n O e s U I A O &
Use the SELECT command to view information stored in the LAST_NAME column of the EMP table.
..................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II xvii
Preface .....................................................................................................................................................
Convention Arrow Brackets Commas
Element Menu paths Key names Key sequences
Plus signs
Key combinations
Example Select File—>Save. Press [Enter]. Press and release these keys one at a time: [Alt], [F], [D] Press and hold these keys simultaneously: [Ctrl]+[Alt]+[Del]
Typographic Conventions in Code Convention Caps and lowercase Lowercase
Element Oracle Forms triggers Column names, table names Passwords PL/SQL objects
Lowercase italic Uppercase
Syntax variables SQL commands and functions
Example When-Validate-Item SELECT last_name FROM s_emp; DROP USER scott IDENTIFIED BY tiger; OG_ACTIVATE_LAYER (OG_GET_LAYER (’prod_pie_layer’)) CREATE ROLE role SELECT userid FROM emp;
Typographic Conventions in Navigation Paths This course uses simplified navigation paths, such as the following example, to direct you through Oracle Applications.
ly n O e s U I A O &
(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 bar, select Query—>Find. 3 (B) Click the Approve button.
l a n r e t n I e l c a r O
N = Navigator, M = Menu, B = Button
..................................................................................................................................................... xviii Oracle iDS Forms: Build Internet Applications II
................................
Introduction
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson I: ......................................................................................................................................................
Introduction Aim of the Course After completing this course, you should be able to do the following: • Create, modify and attach menu documents to Oracle Forms Developer Internet applications • Ensure application security with Oracle8i database roles • Code triggers that respond to function keys • Respond to mouse movement and mouse button actions • Manipulate windows and canvases • Choose appropriate data sources for data blocks • Work with Oracle8i objects in Form Builder • Create and manage multiple Internet form applications • Manage transaction processing in multiple Oracle Forms Developer Internet applications • Create and modify Record Groups programmatically • Build forms with Reusable Components • Enhance the User Interface with JavaBeans • Manage Server side features • Create Timers • Include charts and reports in Oracle Forms Developer Internet applications
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... I-2 Oracle iDS Forms: Build Internet Applications II
Course Content ......................................................................................................................................................
Course Content The lesson titles show the topics we cover in this course, and the usual sequence of lessons. However, the daily schedule is an estimate, and may vary for each class. Day 1 Lesson Number
Lesson Name
1
Creating a Menu Module
2
Managing Menu Modules
3
Programming Function Keys
4
Responding to Mouse Events
Day 2 Lesson Number
Lesson Name
5
Controlling Windows and Canvases Programmatically
6
Defining Data Sources
7
Working with Oracle8i Objects in Form Builder
8
Controlling Data Block Relationships
9
Building Multiple Form Applications
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II I-3
Lesson I: ......................................................................................................................................................
Day 3 Lesson Number
Lesson Name
10
Working with Record Groups
11
Using Reusable Components
12
Using Java with Web-Deployed Forms
13
Using Server Features in Form Builder
14
Applying Timers
15
Including Charts and Reports
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... I-4 Oracle iDS Forms: Build Internet Applications II
................................
Creating a Menu Module
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Objectives
After completing this lesson, you should be able to do the following:
• • •
Identify the components of a menu
• •
Create menu toolbars
Create, save, and attach menu modules Set menu properties by using the Property Palette Create pop-up menus
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 1-2 Oracle iDS Forms: Build Internet Applications II
Introduction ......................................................................................................................................................
Introduction Overview By default, each form module uses the same menu structure, called the Default menu. This lesson teaches you how to customize this menu and how to create your own menu modules. You will also learn how to enhance your application by including menu toolbars and pop-up menus. Objectives After completing this lesson, you should be able to do the following: • Identify the different components of a menu module • Create, save, and attach menu modules • Set menu properties by using the Property Palette • Create menu toolbars • Create pop-up menus
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-3
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Components of the Menu Module Menu item
Main menu
Individual menu Menu toolbar ®
Copyright Oracle Corporation, 2001. All rights reserved.
Hierarchical Structure of a Menu
Menu module
Individual menu
Menu item
Menu item
Menu items
ly n O e s U I A O & Individual menu
Submenu
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
Menu items
®
...................................................................................................................................................... 1-4 Oracle iDS Forms: Build Internet Applications II
Components of the Menu Module ......................................................................................................................................................
Components of the Menu Module What Is a Menu Module? A menu module is a hierarchically structured object that provides a quick and easy method for operating your Forms application. Like the form module, the menu module is one of the main components of an application. Each menu module displays as a pull-down menu. A pull-down menu comprises a set of options, displayed horizontally under the application window title. Each option can represent a submenu or an action. Selecting a submenu displays a vertical list. Selecting an action executes the action. What Is a Menu? A menu is a list of related options. Each option performs a different action. You can create three menu types in Forms: • Main menu: - Displays horizontally in the menu bar - Contains options (menu items) that are typically individual menus • Individual menu: Displays vertically • Submenu: Displays vertically and to the right of the menu item that calls it What Is a Menu Item? A menu item is an option that you can choose from a menu. Each menu item has an associated command that enables the user to perform an action.
ly n O e s U I A O &
What Is a Menu Toolbar? A menu toolbar is a toolbar of iconified buttons that represent individual items from your menu. For a menu module, you can have a vertical and a horizontal menu toolbar.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-5
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Default Menu
Action
Edit
Query
Block
Record
Save Clear All Print Print Setup Exit
Cut Copy Paste Edit Display List
Enter Execute Cancel Last Criteria Count Hits Fetch Next Set
Previous Previous Next Next Clear Scroll Up Scroll Down Insert Remove Lock Duplicate Clear
Field
Help
Previous Next Clear Duplicate
Help Keys List Display Error Debug
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 1-6 Oracle iDS Forms: Build Internet Applications II
The Default Menu ......................................................................................................................................................
The Default Menu What Is the Default Menu? The Default menu is not a separate menu module and is built in to every form module. The Default menu includes standard commands for editing, navigating, and database interaction, such as Action—>Save. When you build a form module, it automatically uses the Default menu. The Default menu is internal to Oracle Forms Developer. You can replace the Default menu with a custom menu. A custom menu is stored in a separate module that has a suffix of .mmb. A custom menu that is exactly the same as the Default menu, menudef.mmb, ships with Oracle Developer Forms. Examining the Default Menu You can look at the structure of the Default menu by opening the file called menudef.mmb. This file contains a menu module with an identical structure to that of the Default menu. Once you have opened the menudef.mmb module, you can see its objects in the Object Navigator. You can see that the menu module consists of a main menu (starting point), menus, and menu items.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-7
Lesson 1: Creating a Menu Module ......................................................................................................................................................
The Menu Editor Display menu
Menu tab
Create Down
Expanded menu
Create Right
Switch Orientation
Collapsed menu
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note By default, the Menu Editor displays a pull-down menu, with the top-level menu displayed horizontally. If you are developing a full-screen menu, you may want to display the top-level menu vertically, so that the display matches the way your menu will appear at run time. To change the orientation, click the Switch Orientation button.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 1-8 Oracle iDS Forms: Build Internet Applications II
The Menu Editor ......................................................................................................................................................
The Menu Editor What Is the Menu Editor? The Menu Editor is a graphical design facility for laying out, modifying, and viewing menu modules and their objects. Use the Menu Editor to carry out all of your menu design work. Two Ways to Display the Menu Editor • Double-click the icon to the left of the menu module entry in the Object Navigator. • Select Tools—>Menu Editor. Tools Specific to the Menu Editor Toolbar You have seen the majority of the tools from the Menu Editor toolbar in the Layout Editor; however, some are specific to the Menu Editor. Tool
Function
Display Menu
Determines the highest level menu that the Menu Editor displays. (Choose from all the menus in your menu module.)
Create Down
Creates a new menu item below the currently active one
Create Right
Creates a new menu item to the right of the currently active one
Switch Orientation
Allows display of the top-level menu vertically or horizontally
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-9
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Creating a Menu Module
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 1-10 Oracle iDS Forms: Build Internet Applications II
Creating a Menu Module ......................................................................................................................................................
Creating a Menu Module The first step when creating a menu is to define a new menu module by using the Object Navigator. Once the module is created, you need to create menus and menu items in the Menu Editor. When the Menu Editor is displayed, it shows a menu called MAIN_MENU, with one item labeled New Item. Creating a Main Menu from the Menu Editor To create menu items for the Main menu, select New Item from the Menu Editor (it is usually selected already). 1 Type a menu label to replace the default label. 2 Click the Create Right icon. 3 Type a new label to replace the default label. 4 Repeat steps 2 and 3 to add more items to the Main menu. Note: The label is the text that is displayed for the menu item at run time. The label may differ from the name, which you can use programmatically and which must follow PL/SQL naming conventions. Creating an Individual Menu 1 In the Main menu, select the parent item. 2 Click the Create Down icon. 3 Type a new label to replace the default label. 4 Repeat steps 2 and 3 to add more menu items to the current individual menu. Note: Forms places a shaded rectangle, or handle, to the left of the first menu item. You can use it to move the menu along with all its items.
ly n O e s U I A O &
Creating a Submenu 1 Select the parent item on the individual menu. 2 Click the Create Right icon. 3 Replace the default label. 4 Select Menu—>Create Down to add another item to the submenu. 5 Replace the default label. 6 Repeat steps 4 and 5 to add more submenu items.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-11
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Menu Module Properties
Main Menu Menu Directory Menu Filename Startup Code Share Library with Form
Use Security Module Roles Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 1-12 Oracle iDS Forms: Build Internet Applications II
Module Properties ......................................................................................................................................................
Module Properties Property
Description
Main Menu
Property that specifies the name of the individual menu in the module that is the main or starting menu at run time For a pull-down menu, the main menu is automatically set to the name of the first menu that you create. Users cannot navigate above this menu in the menu hierarchy.
Menu Directory
Path used by Forms as a pointer to the directory for the run-time .mmx file; only used by menu modules that are saved to the database
Menu Filename
Filename used by Forms as a pointer to the run-time .mmx file; only used by menu modules that are saved to the database
Startup Code
PL/SQL code executed when a menu module is loaded in memory
Share Library with Form
Property that enables the loading into memory of a single copy of a PL/ SQL library, if this is the library used by the form module and the menu module
Use Security
When set to Yes, this property enforces security at run time. (Set this property to No to test the menu module without having to be a member of any database role.)
Module Roles
Property that displays the Menu Module Roles dialog box, where you can list the roles assigned to the menu module. (Roles defined must be assigned to individual menu items in the Menu Editor.)
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-13
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Menu Properties
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 1-14 Oracle iDS Forms: Build Internet Applications II
Menu Properties ......................................................................................................................................................
Menu Properties Property
Description
Tear-Off Menu
Enables the menu to be dragged from the menu bar and repositioned elsewhere on the screen (available only if your window manager supports this feature)
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-15
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Menu Item Properties • • • • • •
Enabled Label Menu Item Type
• • •
Menu Item Code
• •
Icon in Menu
Magic Item Menu Item Radio Group
Submenu Name Keyboard Accelerator Icon Filename
Command Type
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note Radio menu items must belong to a radio group. All of the radio items for a radio group must be contiguous on the same menu. Radio group names are internal names that are not displayed at run time.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 1-16 Oracle iDS Forms: Build Internet Applications II
Menu Item Properties ......................................................................................................................................................
Menu Item Properties Properties Specific to Menu Item Menu Item Property Enabled Label Menu Item Type Magic Item Menu Item Radio Group Command Type Menu Item Code Submenu Name Keyboard Accelerator
Icon in Menu Icon Name
Function Specifies whether the menu item is an active and mouse manipulatable (Inactive menu items are displayed in grey.) Specifies the text that appears in the menu item Determines how this menu item displays (Choose from Plain, Check, Radio, Separator, and Magic.) Specifies that one of the predefined menu items for custom menus should be used Determines which radio group this menu item belongs to Determines the type of command that this menu item calls (Choose from Null, Menu, PL/SQL, or SQL*Plus.) Specifies the command that this menu item invokes Specifies the menu that this menu item invokes Determines which logical function key is associated with this menu item (Accelerator keys are named ACCELERATOR1 through ACCELERATOR5.) Specifies if an icon is displayed in the menu item Specifies the name of the icon to display
Defining Menu Access Keys Forms indicates an access key by underlining one special character in the menu item. Users can then issue the menu item command by pressing a key combination such as [Alt] + [character]. Specifying the Underline Character Development execute query eXecute query Exe&cute Query Execute &Query
ly n O e s U I A O &
Run Time execute query eXecute query Execute Query Execute Query
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-17
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Menu Item Types
Plain Check
Radio
Magic
Separator
Copyright Oracle Corporation, 2001. All rights reserved.
®
Magic Items • • • • •
About Undo Clear Copy
• • • •
Paste Help Quit Window
Cut
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 1-18 Oracle iDS Forms: Build Internet Applications II
Menu Item Types ......................................................................................................................................................
Menu Item Types You can customize a menu by using different item types. In addition to plain menu items, Form Builder supports four types of special menu items. Choosing a Menu Item Type Menu Item Type Plain Check Radio
Separator Magic
Description Creates a standard text menu item (This is the Default menu item type.) Creates a menu item that has two possible states (Check menu item functionality is defined using PL/SQL.) Creates a set of mutually exclusive buttons, each representing a different action (To assign a radio item to a group, enter the name of the group in the Menu Item Radio Group field in the Properties window.) Creates a separating horizontal line for grouping menu items Creates a menu item with predefined functionality
Magic Items Some Magic menu items include default functionality. Because a Magic item provides the standard actions of a graphical user interface (GUI), a copy or paste action is already defined at the menu level. All you need to do is set the item to the Magic type and define the desired action (standard or specific). Magic Item About Undo Clear Copy Paste Cut Help
Command Type Any except Menu Null
Menu
l a n r e t n I e l c a r O Quit
Null
Window
Null or Menu
Default Functionality? No. You must assign a command to these items to perform the desired function. Yes. These items perform the default operations indicated by their names.
ly n O e s U I A O & No. You must define a submenu to be called by the Magic Help item, and you must assign commands to the items on that submenu. Yes. The Quit command, by default, exits from the form after asking the user to save any changes. Yes. The window item invokes a default submenu that lists all open windows. Users can activate a window by selecting it from the submenu.
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-19
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Menu Item Command Types
Null
Does not issue a command
Menu
Invokes a submenu
PL/SQL
Executes a PL/SQL command
Plus
Spawns a process to SQL*Plus
Form
Backward compatibility
Macro
Backward compatibility
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 1-20 Oracle iDS Forms: Build Internet Applications II
Menu Item Command Types ......................................................................................................................................................
Menu Item Command Types Every menu item must have a valid command type. Most menu items execute PL/SQL commands, so their command type is PL/SQL. However, if a menu item is composed of submenus, the command type must be set to Menu. For example, all items on the Main menu must have the command type set to Menu. In this case, the Menu Item Code property is replaced by the Submenu Name property. Choosing a Command Type Command Type Null
Menu PL/SQL (default)
Plus
Description Specifies that the menu item does not issue a command (The NULL command is required for Separator menu items and optional for all other types of items.) Invokes a submenu (Valid submenu name is the name of the submenu to be invoked.) Executes a PL/SQL command (Valid menu item code is a PL/SQL block, including calls to built-in and user-named subprograms.) Specifies that the menu item code spawn a process to SQL*Plus.
Note: The command types of Form, Plus and Macro are available for backward compatibility only. Web Design Tip If you invoke the HOST command with Web-deployed forms, the required process will run on the Forms Services machine, not on the client. The client will not be able to view or participate in that process.
ly n O e s U I A O &
Viewing Menu Item Commands To view the menu item command associated with a menu item, you must take one of the following actions: • Double-click the icon to the left of the menu item entry in the Object Navigator. • Use the Menu Item Code or Submenu Name property in the Property Palette. • Right-click on the menu item in the Object Navigator or Menu Editor and select PL/SQL Editor from the pop-up menu.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-21
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Implementing Menu Toolbars Toolbar as part of menu module:
•
Contains only buttons corresponding to menu items
• • •
Is displayed above “normal” toolbars Executes the same code as menu items Is enabled and disabled, visible and hidden, in synchronization with corresponding menu item
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note For more flexible or complex requirements, use the existing Toolbar canvas in form modules.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 1-22 Oracle iDS Forms: Build Internet Applications II
Implementing Menu Toolbars ......................................................................................................................................................
Implementing Menu Toolbars What Is a Menu Toolbar? A menu toolbar is a set of iconic buttons that represent individual items from a menu. When you create a custom form menu, you can specify that some of its items appear on a menu toolbar. You need to provide icons to represent the associated buttons on the menu toolbar. If you use the default form menu, Form Builder attaches a default menu toolbar to your form automatically. Menu toolbars allow developers to easily provide toolbar shortcuts to menu commands without duplicating code or effort. Menu Toolbar Orientation You can assign menu items to a horizontal or a vertical menu toolbar. Form Builder locates a horizontal menu toolbar at the very top of a form (just beneath the pull-down form menu.) A vertical menu toolbar appears at the far left of a form (to the left of any existing toolbar canvas). Creating a Menu Toolbar To create a menu toolbar, you have to set up the following menu item properties. Property
Description
Visible in Horizontal Menu Toolbar
Specifies that the menu item should appear (represented by an icon) on the horizontal toolbar of a form
Visible in Vertical Menu Toolbar
Specifies that the menu item should appear (represented by an icon) on the vertical toolbar of a form
Icon Filename
Specifies the name of the icon resource that you want to represent the iconic button. For Web-deployed forms, this should be a GIF file, otherwise use an ICO file.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-23
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Menu Module Storage
Menu module definition:
• •
.mmb Stored in files or database tables
Menu module executable:
• •
.mmx Stored in files
Menu module text:
• •
.mmt Stored in files
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 1-24 Oracle iDS Forms: Build Internet Applications II
Storing the Menu Module ......................................................................................................................................................
Storing the Menu Module Saving the Menu Module Definition As with the form module, you can save your menu module definition to either of the following storage formats. Storage Format File with .mmb extension Database table
Description Menu module binary file, a binary representation of the menu structure that is portable between operating systems A table representation of the menu structure that is portable between databases
You can save your menu module definition by either of the following actions: • Clicking the Save icon in the Object Navigator • Selecting File—>Save Creating an Executable Version Before you can use your customized menu module, you must create an executable version. To do so, select File—>Administration—>Compile File. The resulting file that you create has the .mmx extension. A menu module executable file containing binary code is not portable between operating systems.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-25
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Form Module Properties
Menu module to use with this form module
Specify that menu module is stored in the file system
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note If you want to use the Default menu without the associated menu toolbar, replace the value DEFAULT&SMARTBAR in the Menu Module property with DEFAULT only.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 1-26 Oracle iDS Forms: Build Internet Applications II
Attaching the Menu Module ......................................................................................................................................................
Attaching the Menu Module To use your customized menu module, you must attach it to a form module. When you attach a customized menu module to a form module, you are effectively replacing the Default menu with your own menu module. Attaching the Menu Module to the Form Module 1 Ensure that the menu module has been generated. 2 Select the form module to which you want to attach your menu. 3 Invoke the Property Palette for the form module. 4 Replace the value DEFAULT&SMARTBAR in the Menu Module property with your menu module name. 5 Ensure that the Menu Source property has a value of: a File, if the menu module is stored in the file system b Database, if the menu module is stored in the database 6 Generate your form module.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-27
Lesson 1: Creating a Menu Module ......................................................................................................................................................
What Is a Pop-up Menu?
Menu that appears on the screen at the location it was invoked
•
Enables users to access commonly used functions easily
•
Is accessed by pressing the right mouse button (Microsoft Windows and Motif)
Copyright Oracle Corporation, 2001. All rights reserved.
®
Incorporating Pop-up Menus •
Pop-up menus are: – Top-level objects in the object navigator, such as alerts or Data Blocks
ly n O e s U I A O &
– Built through the Property Palette or Menu Editor – Defined in a form module
– Associated with items and canvases with a pop-up menu property
•
Pre-Popup-Menu trigger provides dynamic control
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 1-28 Oracle iDS Forms: Build Internet Applications II
Pop-up Menus ......................................................................................................................................................
Pop-up Menus Pop-up menus are context-sensitive menus. You attach pop-up menus to an item or canvas, and display them by right click on that item or canvas. Pop-up menus enable end users to quickly access common functions and commands. Pop-up menus are top-level objects in the Object Navigator (similar to alerts, blocks, canvases, and so on) and belong to a form module, as opposed to form menus, which belong to a separate menu module. Items on a pop-up menu should be contextual to the menu’s associated objects. For example, you would not include text-editing items on the pop-up menu for a two-digit numeric item. However, you might include such items on the pop-up menu for a multiline text item. Incorporating Pop-up Menus 1 In the Object Navigator of a form, click the Pop-up Menus node, and click the Create button on the toolbar. Form Builder creates a pop-up menu and gives it a default name, such as MENU1. 2 In the Object Navigator or Menu Editor, create a main pop-up menu, submenus (if any), and menu items. 3 Assign commands to the menu items. You can select plain text, separators, check boxes, and option boxes for Menu items. 4 Attach the menu to items and canvases with a new Pop-up Menu property. Rules for Incorporating Pop-up Menus • To show pop-up menus for a canvas, the mouse must be on the canvas only. • Pop-up menu items can be parents of submenus (if the platform allows it), magic menu items, or separators.
ly n O e s U I A O &
Pre-Popup-Menu Trigger You can use this trigger to add dynamic control at run time, prior to displaying the menu. For example, you can use the trigger to identify the cursor context and navigate to a different item if necessary.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-29
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Summary
In this lesson, you should have learned to:
•
Identify Menu module components – The Default menu – Menu properties
• • •
Create a Menu module Associate Menu and form modules Create a Pop-up menu
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 1-30 Oracle iDS Forms: Build Internet Applications II
Summary ......................................................................................................................................................
Summary In this lesson, you learned how to add, create, and customize menu modules. The Menu Module Components • Main menu • Menu • Menu item • Menu toolbar The Default Menu • Automatically used with every form module • Can be customized Creating a Menu Module Properties • Menu module properties • Menu properties • Menu item properties Implementing a Menu Toolbar Menu Module Storage • Database tables • .mmb file extension • .mmx file extension • .mmt file extension
ly n O e s U I A O &
Menu Module and Form Module Association Using the form module properties of Menu Module and Menu Source
l a n r e t n I e l c a r O Creating a Pop-up Menu • Incorporate pop-up menus • Rules to incorporate pop-up menus • Pre-Popup-Menu trigger
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-31
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Practice 1 Overview
This practice covers the following topics:
• •
Creating a simple menu module
•
Compiling and attaching the menu to the ORDERS form
•
Creating a pop-up menu
Incorporating some of the menu items in the menu toolbar
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 1-32 Oracle iDS Forms: Build Internet Applications II
Practice Overview: Lesson 1 ......................................................................................................................................................
Practice Overview: Lesson 1 This practice guides you through creating a custom menu, a menu toolbar and a pop-up menu. Practice Contents • Create a simple menu module • Incorporate menu items in the menu toolbar • Compile and attach a menu to a form • Create a pop-up menu
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-33
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Practice 1 1 Create a new menu module. a
•
Using the following screenshot as a guideline, create a new menu module called M_SUMMITXX where XX is your student course number.
File Menu Visible in Menu
Visible in Horiz. Menu Toolbar
Icon Filename
DO_KEY(’CO MMIT_FORM’ );
Yes
Yes
Save
DO_KEY(’ CLEAR_FORM ’);
Yes
Yes
Abort
Yes
Yes
Yes
Yes
No
Yes
Label
Menu Item Type
Command Type
Menu Item Code
Save
Plain
PL/SQL
Clear
Plain
PL/SQL
l a n r e t n I e l c a r O
Null1
Separator
Null
Exit
Plain
PL/SQL
Null2
Separator
Null
ly n O e s U I A O &
DO_KEY( ’EXIT_FORM ’);
Exit
...................................................................................................................................................... 1-34 Oracle iDS Forms: Build Internet Applications II
Practice 1 ......................................................................................................................................................
•
•
•
Edit Menu
Label
Menu Item Type
Magic Item
Command Type
Visible in Menu
Visible in Horiz. Menu Toolbar
Icon Filename
Cut
Magic
Cut
Null
Yes
Yes
Cut
Copy
Magic
Copy
Null
Yes
Yes
Copy
Paste
Magic
Paste
Null
Yes
Yes
Paste
Null3
Separator
Null
No
Yes
Sort By Menu
Menu Label
Menu Item Type
Menu Item Radio Group
Command Type
Order Id
Radio
Order_By
PL/SQL
SET_BLOCK_PROPERTY( ’s_ord’, order_by, ’id’ ) ;
Customer Id
Radio
Order_By
PL/SQL
SET_BLOCK_PROPERTY( ’s_ord’, order_by, ’customer_id’ ) ;
Sales Rep Id
Radio
Order_By
PL/SQL
SET_BLOCK_PROPERTY( ’s_ord’, order_by, ’sales_rep_id’ ) ;
Query Menu
Menu Item Code
ly n O e s U I A O & Visible in Horiz. Menu Toolbar
Icon Filename
Menu Item Type
Command Type
Enter Query
Plain
PL/SQL
DO_KEY(’ ENTER_QUERY’);
Yes
query
eXecute Query
Plain
PL/SQL
DO_KEY(’EXECUT E_QUERY’);
Yes
execute
l a n r e t n I e l c a r O Label
Menu Item Code
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 1-35
Lesson 1: Creating a Menu Module ......................................................................................................................................................
Save as M_SUMMIT and compile the menu module. c Attach the menu module to the ORDERS form. d Save and compile the form module as ORDGXX where XX is your student course number. e Run and test your ORDERS form. 2 Add pop-up menus to the CUSTOMERS form. a Open the CUSTOMERS form module. Save as CUSTGXX where XX is your student course number. b Copy the EDIT_MENU menu from your M_SUMMIT menu module to your CUSTOMERS form. Attach this pop-up menu to the Comments item. c Save and compile the form module. Deploy your form to the Web to test. b
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 1-36 Oracle iDS Forms: Build Internet Applications II
................................
Managing Menu Modules
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 2: Managing Menu Modules ......................................................................................................................................................
Objectives
After completing this lesson, you should be able to do the following:
• •
Control the menu programmatically
•
Implement application security through the menu
Manage the interaction between the menu and form documents
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 2-2 Oracle iDS Forms: Build Internet Applications II
Introduction ......................................................................................................................................................
Introduction Overview In this lesson, you will learn how to modify menus dynamically, as well as how to control application security through menu access. Objectives After completing this lesson, you should be able to do the following: • Control the menu programmatically by using menu built-ins • Implement menu security by using both database roles and the appropriate built-ins
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 2-3
Lesson 2: Managing Menu Modules ......................................................................................................................................................
Using PL/SQL in Menu Item Code • •
Similar to PL/SQL code in form triggers You can share code between a form module and a menu module by using the following: – Libraries – User-defined triggers – DO_KEY built-in
Copyright Oracle Corporation, 2001. All rights reserved.
®
Using PL/SQL in Menu Item Code • •
Menu modules generated independently Restrictions: – Cannot directly reference values of form objects
ly n O e s U I A O &
– Must use NAME_IN built-in function – Cannot use direct assignment for form objects
– Must use COPY built-in procedure
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 2-4 Oracle iDS Forms: Build Internet Applications II
Using PL/SQL in Menu Item Code ......................................................................................................................................................
Using PL/SQL in Menu Item Code Using PL/SQL in Menu Item Commands PL/SQL menu item commands are structurally similar to form triggers. In addition to standard application functions such as navigation, validation, and database interaction, you can use PL/SQL menu item commands to perform any actions. Sharing Code Between a Form Module and a Menu Module You can share code between form modules and menu modules in three ways: • Setting up libraries and attaching them to the modules • Creating user-defined triggers in the form module and calling them from a standard trigger in a form module, or calling them from a menu item in a menu module (Use EXECUTE_TRIGGER to fire the user-defined trigger.) • Using the DO_KEY built-in to fire the corresponding trigger or function from a menu item Restrictions Menu modules are generated independently of form modules. In PL/SQL command menu items: • You cannot directly reference the value of form module objects. • You must use the NAME_IN built-in function to determine the current value of the object. • You cannot use direct assignment to set the value of a form module object. • You must use the COPY built-in procedure. Example
ly n O e s U I A O &
IF :s_emp.title = ’MANAGER’ THEN ...-- INCORRECT IF NAME_IN(’s_emp.title’) = ’MANAGER’ THEN ... -- CORRECT :s_product.name := ’PUMP’; -- INCORRECT COPY(’PUMP’, ’s_product.name’); -- CORRECT
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 2-5
Lesson 2: Managing Menu Modules ......................................................................................................................................................
Built-ins for Setting and Getting Menu Item Properties • • • • •
FIND_MENU_ITEM GET_MENU_ITEM_PROPERTY SET_MENU_ITEM_PROPERTY ITEM_ENABLED MENU_SHOW_KEYS
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 2-6 Oracle iDS Forms: Build Internet Applications II
Useful Built-in Menu Subprograms ......................................................................................................................................................
Useful Built-in Menu Subprograms You can change certain menu characteristics dynamically at run time by using built-in subprograms. Using some of these subprograms, you can get or change menu item properties. Using others, you can hide, display, or replace the current menu. Setting and Getting Menu Item Properties Built-in FIND_MENU_ITEM
Description This function gets the ID of a menu item. The receiving variable must be declared as a menu item type. GET_MENU_ITEM_PROPERTY This function returns the current value of the given property for a specified menu item. SET_MENU_ITEM_PROPERTY This procedure modifies the state of a menu-itemspecific characteristic. ITEM_ENABLED This function returns the Boolean value TRUE when the menu item is enabled and FALSE when the menu item is disabled. MENU_SHOW_KEYS This procedure displays the Keys screen for the menu module at run time.
Example This procedure finds the ID of a menu item before setting multiple properties. DECLARE mi_id MenuItem; BEGIN
ly n O e s U I A O &
mi_id := Find_Menu_Item(’Preferences.AutoCommit’);
/* Determine the current checked state of the AutoCommit menu checkbox item and toggle the checked state */ IF Get_Menu_Item_Property(mi_id,CHECKED) = ’TRUE’ THEN
Set_Menu_Item_Property(mi_id,CHECKED,PROPERTY_FALSE); ELSE
l a n r e t n I e l c a r O
Set_Menu_Item_Property(mi_id,CHECKED,PROPERTY_TRUE);
END IF;
END;
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 2-7
Lesson 2: Managing Menu Modules ......................................................................................................................................................
Built-ins for Showing and Hiding the Current Menu REPLACE_MENU Character mode built-ins:
• • •
HIDE_MENU SHOW_MENU MENU_REDISPLAY
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note REPLACE_MENU replaces the menu for all windows in the application. If you are using CALL_FORM, REPLACE_MENU replaces the menu for both the calling form and the called form with the specified menu.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 2-8 Oracle iDS Forms: Build Internet Applications II
Showing and Hiding the Current Menu ......................................................................................................................................................
Showing and Hiding the Current Menu Built-in REPLACE_MENU
HIDE_MENU SHOW_MENU MENU_REDISPLAY
Description Replaces the current menu with a specific one, without making it active (Use this procedure to modify the display style and security.) Hides the current menu Displays the current menu without activating it Redraws the current menu on the screen
Example Use a standard procedure to change which root menu in the current menu application appears in the menu bar. A single menu application may have multiple root menus, which an application can set dynamically at run time. PROCEDURE Change_Root_To(root_menu_name VARCHAR2) IS BEGIN Replace_Menu(’MYAPPLSTD’, PULL_DOWN, root_menu_name); END;
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 2-9
Lesson 2: Managing Menu Modules ......................................................................................................................................................
Managing Menu Security • • • •
Defining security roles Choosing roles for the menu module Assigning access to menu items Setting the Use Security property
Copyright Oracle Corporation, 2001. All rights reserved.
®
What Is a Role? Users
Role
l a n r e t n I e l c a r O Privileges
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 2-10 Oracle iDS Forms: Build Internet Applications II
Managing Menu Security ......................................................................................................................................................
Managing Menu Security What Is Menu Security? Using menu security, you can set up access rights on menu items. You can choose between two security policies for the users: • Grant users access to all menu items in a module • Grant users access only to specific menu items When you want to deny a user access to a menu item, you can either hide the item or disable it. What Is a Role? A role is a group of users sharing the same privileges. With Form Builder, you can manage menu security through Oracle server roles. When you create a role, you can grant access privileges to each item individually. If access is granted only to some roles, only users belonging to those roles can access those items. Using this feature, you can deliver the same application for different kinds of users. Implementing Menu Security First, define the different types of users who will use the menus, their profiles, and their needs. Then follow the steps below: 1 Define security roles in the database. 2 Choose roles for the module in Form Builder. 3 Assign access to menu items. 4 Set the Use Security property.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 2-11
Lesson 2: Managing Menu Modules ......................................................................................................................................................
Menu Module Roles Window
Select Menu Module Roles:
Copyright Oracle Corporation, 2001. All rights reserved.
®
Use Security Property • •
Set to Yes to enforce security Set to No to ignore security: Enables the developer to test the application
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note If Use Security is modified, you must recompile the menu module.
...................................................................................................................................................... 2-12 Oracle iDS Forms: Build Internet Applications II
Defining Security Roles ......................................................................................................................................................
Defining Security Roles Defining New Roles Menu security is based on the Oracle server roles. You can create these using SQL statements. The following SQL commands implement roles. Command CREATE ROLE GRANT ALTER USER...DEFAULT ROLE
Action Creates a new role Assigns the role to a user (This command allows you to give a set of privileges to a user at one time.) Controls which role is assigned by default to users when they connect to the database
Assigning Roles to the Menu Module To associate a particular role with a menu item, you must define all the roles used in that menu module: 1 In the Object Navigator, select the menu module. 2 In the Properties window, select the Menu Module Roles property. 3 Click More... to open the Menu Module Roles dialog box. 4 Enter the names of the roles that you want to choose for this menu module. 5 Click OK to accept the roles list. Note: The role must exist in the database.
ly n O e s U I A O &
Setting the Use Security Property The Use Security property determines whether Form Builder should take account of the specified roles at run time. When Use Security is set to Yes, Forms enforces security. When Use Security is set to No: • Forms ignores security. • Your users can access all menu items. • You can test your application without being a member of all roles.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 2-13
Lesson 2: Managing Menu Modules ......................................................................................................................................................
Menu Item Roles Window
Select menu item roles:
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 2-14 Oracle iDS Forms: Build Internet Applications II
Assigning Access to Menu Items ......................................................................................................................................................
Assigning Access to Menu Items After defining roles to use for the current menu module, you must specify the role or the roles that will have access to each menu item. 1 Select the desired menu item in the Menu Editor or in the Object Navigator. 2 Select the Item Roles property in the Properties window. 3 Click More... in the Menu Item Roles dialog box, which contains the role names associated with the menu module. 4 Select the role in the list to assign a role to the selected menu item. 5 Set the Display without Privilege property to specify how Forms should display the item if the current user does not have access to the item. If set to Yes, the item is displayed disabled. If set to No, the item is hidden completely. Note: Roles assigned to an item are highlighted. All others are displayed as usual. To assign the same roles to many items, select the items first by “Shift-clicking” or “Control-clicking” in the Menu Editor or Object Navigator, then select the roles through the Menu Item Roles property. For additional information on how to manipulate Oracle server roles at run time, see Appendix I, “Using Oracle Server Roles at Run Time.”
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 2-15
Lesson 2: Managing Menu Modules ......................................................................................................................................................
Summary
In this lesson, you should have learned to:
• • •
Exploit Menu Built-ins Include PL/SQL in menu items Implement menu security
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 2-16 Oracle iDS Forms: Build Internet Applications II
Summary ......................................................................................................................................................
Summary PL/SQL in Menu Item Commands • Typical PL/SQL uses • Restrictions for PL/SQL in menu item commands Built-ins for Use with Menu Modules • Showing and hiding the current menu: - HIDE_MENU - REPLACE_MENU - SHOW_MENU - MENU_REDISPLAY • Getting and setting menu properties: - FIND_MENU_ITEM - GET_MENU_ITEM_PROPERTY - SET_MENU_ITEM_PROPERTY
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 2-17
Lesson 2: Managing Menu Modules ......................................................................................................................................................
Practice 2 Overview
This practice covers the following topics:
•
Enhancing the menu with a check menu item
•
Synchronizing the menu Display_Help item with the form Help button
•
Hiding irrelevant menu items according to form context
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 2-18 Oracle iDS Forms: Build Internet Applications II
Practice Overview: Lesson 2 ......................................................................................................................................................
Practice Overview: Lesson 2 This practice guides you through enhancing custom menus for the ORDERS and CUSTOMERS forms. Practice Contents • Add a check menu item. • Enhance the menu so that the Display Help menu item is synchronized with the ORDERS Help button. If the Help button is enabled, a checkmark should appear next to the Display Help menu item. • For the CUSTOMERS form, hide the menu items that are not relevant.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 2-19
Lesson 2: Managing Menu Modules ......................................................................................................................................................
Practice 2 1 Define a check menu item. a
Open your M_SUMMIT menu module and add a new menu item to the Sort By menu; name it Display_Help. Menu Label
Menu Item Type
Command Type
Display Help
Check
PL/SQL
If Display_Help is selected, enable the ORDERS form toolbar HELP button and set the toolbar canvas background color to grey. If Display_Help is not selected, disable the ORDERS form toolbar HELP button and set the toolbar canvas background color to red. You can import the code from the pr2_1.txt file. c Save and compile the menu module. d Deploy your ORDERS form on the Web to test your menu. b
2 Synchronize the menu module with the form.
Write startup code for your M_SUMMIT menu module that synchronizes the Display_Help menu item with the toolbar HELP button. You can import the code from the pr2_2.txt file. b Save and compile your menu module. c Deploy your ORDERS form on the Web to test your menu. a
ly n O e s U I A O &
3 Attach your M_SUMMIT menu to your CUSTOMERS form. The menu
item Sort_By is not relevant, and should not be visible to the user. a Attach the menu module to your CUSTOMERS form. b Modify the startup code of the M_SUMMIT menu module to hide the SORT_BY menu when the CUSTOMERS form is opened. You can import the code from the pr2_3.txt file to replace the existing code. You may need to change the code to conform to the exact names you gave to the Main Menu and its menu items. Also, be sure the When-Button-Pressed trigger on the Orders button refers to your Orders form. c Save and compile the menu module. d Deploy your CUSTOMERS form to the Web and test your application. Execute a Query and click the Orders button to move to the ORDERS form. Note that the Sort_By menu item is hidden when the CUSTOMERS form is current, and is visible when the ORDERS form is current. 4 With both the ORDERS and CUSTOMERS form modules, restore the default menu, (DEFAULT&SMARTBAR).
l a n r e t n I e l c a r O
...................................................................................................................................................... 2-20 Oracle iDS Forms: Build Internet Applications II
................................
Programming Function Keys
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 3: Programming Function Keys ......................................................................................................................................................
Objectives
After completing this lesson, you should be able to do the following:
• • • • •
Define key triggers and their uses Program function keys Describe the characteristics of key triggers Classify key triggers Associate function keys with interface controls
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 3-2 Oracle iDS Forms: Build Internet Applications II
Introduction ......................................................................................................................................................
Introduction Overview Form Builder enables you to redefine the actions of function keys. This lesson shows you how to create key triggers to either intercept, or supplement, the usual function key behavior with which your users navigate the Oracle Forms Developer application. Objectives After completing this lesson, you should be able to do the following: • Define key triggers and their uses • Program function keys • Classify key triggers • Associate function keys with interface controls
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 3-3
Lesson 3: Programming Function Keys ......................................................................................................................................................
Key Triggers
What is a key trigger? Example: Using Key-Exit, display an alert and exit the application if the user selects the “Yes” button. SET_ALERT_PROPERTY( SET_ALERT_PROPERTY(′question_alert ′question_alert′,′, ALERT_MESSAGE_TEXT, ALERT_MESSAGE_TEXT, ′Do you really want to leave the ′Do you really want to leave the form? form? ′); ′); IF IF SHOW_ALERT( SHOW_ALERT(′question_alert ′question_alert′)′) == ALERT_BUTTON1 ALERT_BUTTON1 THEN THEN EXIT_FORM; -default functionality EXIT_FORM; -- default functionality
END END IF; IF;
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 3-4 Oracle iDS Forms: Build Internet Applications II
Key Triggers ......................................................................................................................................................
Key Triggers If you press a function key, Forms usually performs the default function associated with that key. You can modify the standard functionality of a function key by defining a key trigger for that function key. What Is a Key Trigger? A key trigger, like any other trigger, is a subprogram that is executed when a certain event occurs. In the case of a key trigger, the event is pressing the function key for which the trigger is defined. The trigger is usually named after the event that causes it to fire. When the key trigger is defined for a function key, the usual functionality of the key is replaced by the PL/SQL text of the trigger. In this respect, key triggers resemble “on” triggers. Example The form level Key-Exit trigger below displays an alert asking the end user if he or she wants to leave the form. SET_ALERT_PROPERTY(’question_alert’, ALERT_MESSAGE_TEXT, ’Do you really want to leave the form?’); IF SHOW_ALERT(’question_alert’) = ALERT_BUTTON1 THEN EXIT_FORM; -- default functionality END IF;
Note: If you also want to execute the default functionality of the function key, you must ensure that the key trigger includes the built-in function associated with the key.
ly n O e s U I A O &
Example The following form-level Key-Menu trigger disables [Block Menu] for a form. BEGIN NULL; END;
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 3-5
Lesson 3: Programming Function Keys ......................................................................................................................................................
Key Trigger Properties and PL/SQL Editor
Display in “Keyboard Help” “Keyboard Help” Text
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 3-6 Oracle iDS Forms: Build Internet Applications II
Defining Key Triggers ......................................................................................................................................................
Defining Key Triggers You define key triggers in the same way that you define any other trigger. However, the following two properties in the Property Palette for triggers only apply to key triggers. Property Display in Keyboard Help Keyboard Help Text
Description Specifies whether a key trigger description is displayed in the run-time Keys Help window Specifies the text that is displayed in the run time Keys Help window if the display in the Keyboard Help property is set to Yes (If you want the default description to be displayed, leave this property blank.)
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 3-7
Lesson 3: Programming Function Keys ......................................................................................................................................................
Characteristics of Key Triggers •
You cannot redefine all function keys with key triggers.
• •
Key triggers are defined at all three levels.
•
Key triggers can fire in Enter Query mode.
A key trigger can contain SELECT statements and all built-ins.
®
Copyright Oracle Corporation, 2001. All rights reserved.
Characteristics of Key Triggers
Function Key
Built-in
[Accept]
COMMIT_FORM
[Clear Form]
CLEAR_FORM
[Create Record]
CREATE_RECORD
Key-Crerec
[Delete Record]
DELETE_RECORD
Key-Delrec
l a n r e t n I e l c a r O
Key Trigger
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
Key-Commit
Key-Clrfrm
®
...................................................................................................................................................... 3-8 Oracle iDS Forms: Build Internet Applications II
Characteristics of Key Triggers ......................................................................................................................................................
Characteristics of Key Triggers Rules of Key Triggers • You cannot redefine all function keys with key triggers. Some keys are handled by the terminal or window interface manager rather than by Forms. Examples of such static function keys are [Clear Item], [Left], [Right], and [Toggle Insert/Replace]. • You can define key triggers at all three levels: form, block, and item. • You can use SELECT statements, restricted built-in functions, and unrestricted built-ins. • Key triggers can fire in Enter Query mode. Note: You cannot use all built-ins in Enter Query mode. If you do not redefine a function key, a built-in function performs its default functionality when you press the key. Therefore, in most cases, a built-in function and a key trigger are associated with a function key. The following table gives some examples of this association. Function Keys, Their Associated Built-in Functions, and Key Triggers Function Key [Accept] [Create Record] [Delete Record] [Duplicate Record] [Enter Query] [Execute Query] [List] [Next Item] [Down] [Next Record] [Exit]
Built-in Function COMMIT_FORM CREATE_RECORD DELETE_RECORD DUPLICATE_RECORD ENTER_QUERY EXECUTE_QUERY LIST_VALUES NEXT_ITEM DOWN NEXT_RECORD EXIT_FORM
l a n r e t n I e l c a r O Note: This list is incomplete.
Key Trigger Key-Commit Key-Crerec Key-Delrec Key-Duprec Key-Entqry Key-Exeqry Key-Listval Key-Next-Item Key-Down Key-Nxtrec Key-Exit
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 3-9
Lesson 3: Programming Function Keys ......................................................................................................................................................
Classification of Key Triggers • •
Function key triggers
• •
Key-Others triggers
Key-Fn triggers and Oracle Terminal Key mapping for Web-deployed forms is different to Client Server
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note The function keys Fn do not necessarily map to F1, F2, F3, and so on.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 3-10 Oracle iDS Forms: Build Internet Applications II
Classification of Key Triggers ......................................................................................................................................................
Classification of Key Triggers You can distinguish among different types of key triggers. Learning these classifications will help you understand when to use key triggers. Types of Key Triggers Category Function key triggers Key-Fn triggers
Key-Others trigger
Description Key triggers that are associated with existing function keys (They fire when the associated function key is pressed.) Key triggers that are associated with the logical Runtime keys F0 through F9 (Before you can use these Key triggers, you or the DBA must map these logical keys to physical keys or key sequences. They fire when the associated physical key or key sequence is pressed.) A key trigger that is associated with all keys that can have key triggers associated with them, but are not currently redefined by a function key trigger at any level
Key Mapping Key mapping is defined by a platform specific resource file. The key definition file for the Microsoft Windows platform is FMRUSW.RES. You should use Oracle Terminal to edit Client Server resource files. For Web applications, you can edit the Java resource file, FMRWEB.RES, with any suitable operating system editor.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 3-11
Lesson 3: Programming Function Keys ......................................................................................................................................................
Classification of Key Triggers
Mouse-event key triggers:
• • • • •
Key-Next-Item Key-Prev-Item Key-Nxtrec Key-Prvrec Key-Up
• • • • •
Key-Down Key-Scrup Key-Scrdown Key-Nxtblk Key-Prvblk
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note Since mouse-event key triggers are not executed when the mouse is used to initiate window interaction, you should not place code that needs to be executed every time the window interaction occurs in a mouse-event key trigger.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 3-12 Oracle iDS Forms: Build Internet Applications II
Classification of Key Triggers ......................................................................................................................................................
What Are Mouse-Event Key Triggers? Mouse-event key triggers are function key triggers whose associated default functionality can also be activated directly with the mouse. Examples • The Key-Nxtblk trigger is a mouse-event key trigger, because the NEXT_BLOCK functionality can also be activated using the mouse by clicking in the next block. In this case, a possible Key-Nxtblk trigger will not fire. • The Key-Exeqry trigger is not a mouse-event key trigger, because the EXECUTE_QUERY functionality cannot be activated by simply clicking the mouse. It can be activated by the mouse only if a trigger is defined to fire as a result of the mouse action.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 3-13
Lesson 3: Programming Function Keys ......................................................................................................................................................
Using Key Triggers • • • • • •
Adjust user interface Disable a (set of) function keys Replace or extend functionality of function keys Add additional function keys Be careful with Key-Others Do not use for validation
Copyright Oracle Corporation, 2001. All rights reserved.
®
Specific Key Trigger Uses • •
Call an LOV form
• •
Prevent duplication of the primary key
Check for detail records before deleting a master record
ly n O e s U I A O &
Adjust toolbar buttons for Enter Query mode
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 3-14 Oracle iDS Forms: Build Internet Applications II
Using Key Triggers ......................................................................................................................................................
Using Key Triggers You should use key triggers sparingly. Often you must define many key triggers to trap a certain event completely. Mouse-event key triggers can be circumvented with the mouse. Use key triggers only if you want to adjust the default user interface. Common Uses • Disable function keys • Replace or extend the default functionality of function keys • Add additional keys for custom functions using Key-Fn triggers • Disable a set of function keys using Key-Others When Not to Use Key Triggers • To perform validation; use validation triggers instead • To amend navigation; use navigational triggers instead • To perform data manipulation; use transactional triggers instead Specific Key Trigger Uses • Call a list of values (LOV) form instead of the native Forms LOV, using Key-Listval • Check if detail records exist before deleting a master record if the master block and detail block are in separate forms, using Key-Delrec • Prevent duplication of the primary key when duplicating a record, using Key-Duprec • Adjust behavior of toolbar buttons when Enter Query mode is entered or left, using Key-Entqry
ly n O e s U I A O &
Technical Note To determine if a Key-Others trigger applies to a function key, Forms looks for associated key triggers at all levels. For example, if you define the Key-Others trigger at the block level, it will not fire for those function keys for which a key trigger is defined at the form level.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 3-15
Lesson 3: Programming Function Keys ......................................................................................................................................................
Association with Other Interface Controls Syntax: DO_KEY(built_in_name) Example: To customize actions when a user exits the form with [Exit Form], a button, or a menu item: 1. Key-Exit --- custom custom actions actions when when user user tries tries to to exit exit EXIT_FORM; EXIT_FORM; ... ...
Copyright Oracle Corporation, 2001. All rights reserved.
®
Association with Other Interface Controls 2. In When-Button-Pressed and Menu item code: DO_KEY(’EXIT_FORM’); DO_KEY(’EXIT_FORM’);
•
DO_KEY(’Key-Exit’) gives run-time error
•
Corresponding interface control descriptions
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 3-16 Oracle iDS Forms: Build Internet Applications II
Association with Other Interface Controls ......................................................................................................................................................
Association with Other Interface Controls You can often activate the same functionality in various ways, such as by pressing a function key, choosing a menu item, clicking a button, or performing direct manipulation with the mouse. In this case, you want to specify that the PL/SQL code be executed only once. You can use the builtin function DO_KEY to accomplish this. What Is DO_KEY? DO_KEY is a built-in function that executes the key trigger that corresponds to the built-in subprogram specified as its parameter. If no key trigger is defined, the specified built-in is executed. Syntax DO_KEY(built_in_name)
Example Exit a Form by clicking [Exit Form] or an Exit button, or by choosing a menu item. 1 Define a Key-Exit trigger at form level. 2 Call DO_KEY by using: a The When-Button-Pressed trigger on the associated Exit button b The menu-item code for the menu item that exits the form using DO_KEY(’EXIT_FORM’);
ly n O e s U I A O &
Interface Control Descriptions If the same functionality is activated by various interface controls, you should also make sure that the controls have the same descriptions. Interface Control Function key Menu item Button Mouse event
Property for Description Show keys description Menu-item label Button label Not applicable
l a n r e t n I e l c a r O
Changeable at Run Time? No Yes Yes Not applicable
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 3-17
Lesson 3: Programming Function Keys ......................................................................................................................................................
Summary
In this lesson, you should have learned to:
•
Define key triggers in order to: – Enhance keyboard functionality – Replace keyboard key
•
Provide consistent functionality between Function keys, buttons, menu items, and mouse events
• •
Display text in Keyboard Help Define Key-Fn, Key-Others, and mouse-event key triggers Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 3-18 Oracle iDS Forms: Build Internet Applications II
Summary ......................................................................................................................................................
Summary Understanding Key Triggers • They fire when the associated function key is pressed. • They are defined like any other trigger. • Special properties are Display in Keyboard Help and Keyboard Help Text. Classification of Key Triggers • Function key triggers • Key-Fn triggers • Key-Others • Mouse-event key triggers Uses of Key Triggers • Disable function keys • Replace or extend default behavior of function keys • Add function keys using Key-Fn triggers • Adjust set of function keys using Key-Others Association with Other Interface Controls • Function keys, buttons, menu items, mouse events • Keys description, button label, menu-item label
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 3-19
Lesson 3: Programming Function Keys ......................................................................................................................................................
Practice 3 Overview
This practice covers the following topics:
•
Enforcing consistent form run time functionality by redefining [Exit Form]
•
Changing the behavior of function keys by replacing [Enter Query] with a custom query form
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 3-20 Oracle iDS Forms: Build Internet Applications II
Practice Overview: Lesson 3 ......................................................................................................................................................
Practice Overview: Lesson 3 This practice guides you though redefining function keys with key triggers. Practice Contents • Use a key trigger to redefine [Exit Form] to provide consistent behavior between Menu and form modules. • Disable [Enter Query] mode, and replace with a custom query form.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 3-21
Lesson 3: Programming Function Keys ......................................................................................................................................................
Practice 3 1 Maintain consistent functionality in your form module by using key
triggers. Define a key trigger in your ORDERS form to give users consistent functionality whenever they exit the form, either using the menu or when the CONTROL.EXIT_BUTTON button is pressed. a Redefine [Exit Form] in your ORDERS form so that an alert message is displayed to users before allowing them to exit the form. b Amend the entry in Keyboard Help to “Exit Orders” for the key trigger. c Save and compile your form. Deploy your form to the Web to test. d Customize the Alert Text message in your key trigger and ensure that it is displayed whenever the user exits the form using the EXIT_BUTTON on the Control block. e Save and compile your form module. Deploy to the Web and test your form. If you have time 2 Disable [Enter query] in your CUSTOMERS form by creating an appropriate key trigger. Replace [Enter Query] functionality with a call to the customized query form CUSTQUERY. This form allows the user to select a CUSTOMER ID, a CUSTOMER NAME, or a SALES REP ID. The user selections are returned to your CUSTOMER form using global variables. a Add the following code to your key trigger:
ly n O e s U I A O &
call_form(’custquery’,no_hide); execute_query; b
The CUSTQUERY form will return three values, held in global variables. The contents should be passed to your CUSTOMERS form to allow the user to execute a restricted query. Use the following global variables:
l a n r e t n I e l c a r O :global.custid; :global.custname; :global.repid;
Define the global variables in your CUSTOMERS form to ensure that the user can perform unrestricted queries. d Save and compile your CUSTOMER form. Deploy your form to the Web to test.
c
...................................................................................................................................................... 3-22 Oracle iDS Forms: Build Internet Applications II
................................
Responding to Mouse Events
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 4: Responding to Mouse Events ......................................................................................................................................................
Objectives
After completing this lesson, you should be able do the following:
• •
Define mouse events
•
Cause a form module to respond to mouse button actions
Cause a form module to respond to mouse movement
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 4-2 Oracle iDS Forms: Build Internet Applications II
Introduction ......................................................................................................................................................
Introduction Overview The keyboard, menu, and mouse are the operator’s tools for interacting with the Forms application. This lesson demonstrates how to write an application that responds to mouse events. Objectives After completing this lesson, you should be able to do the following: • Define mouse events • Cause a form module to respond to mouse movement • Cause a form module to respond to mouse button actions
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 4-3
Lesson 4: Responding to Mouse Events ......................................................................................................................................................
Mouse Events • •
Point at which processing can be influenced Identified by: – Mouse movement – Mouse button action
Copyright Oracle Corporation, 2001. All rights reserved.
®
Mouse Cursor Style To change the cursor style dynamically: SET_APPLICATION_PROPERTY(CURSOR_STYLE, ′value′);
ly n O e s U I A O &
DEFAULT
GUI-specific arrow symbol
BUSY
GUI-specific busy symbol
CROSSHAIR
GUI-specific crosshair symbol
HELP
GUI-specific help symbol
INSERTION
GUI-specific insertion symbol
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 4-4 Oracle iDS Forms: Build Internet Applications II
What Are Mouse Events? ......................................................................................................................................................
What Are Mouse Events? An event is a point at which Forms processing can be influenced. Every object can have processing events with which you can associate PL/SQL code (triggers). A mouse event is an event that is identified by a mouse movement or a mouse button action. The Seven Mouse Events The Forms mouse events is divided in two groups: mouse movement events and mouse button action events. The mouse movement events are: • Entry into an item or canvas • Exit from an item or canvas • General movement The events that correspond to mouse button actions are: • Click • Double-click • Up • Down Mouse Cursor Style Form Builder allows you to change dynamically the cursor style. Use the following built-in to do it:
ly n O e s U I A O &
SET_APPLICATION_PROPERTY( CURSOR_STYLE, ’value’);
The valid settings for the cursor style property are: • BUSY • CROSSHAIR • DEFAULT • HELP • INSERTION
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 4-5
Lesson 4: Responding to Mouse Events ......................................................................................................................................................
Mouse Movement Triggers
When-Mouse-Enter
When-Mouse-Leave
When-Mouse-Move Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 4-6 Oracle iDS Forms: Build Internet Applications II
Responding to Mouse Movement ......................................................................................................................................................
Responding to Mouse Movement You can initiate an action whenever mouse movement occurs by defining the mouse movement triggers. The Three Mouse Movement Triggers Trigger When-Mouse-Enter When-Mouse-Leave When-Mouse-Move
Use Fires when the user moves the mouse into an item or canvas-view Fires when the user moves the mouse out of an item or canvas-view Fires when the user moves the mouse within an item or canvas-view
Uses of the Mouse Movement Triggers • Use When-Mouse-Move in conjunction with the SYSTEM.MOUSE_X_POS and SYSTEM.MOUSE_Y_POS system variables to return the exact position of the mouse within an item. • Use When-Mouse-Leave to update an item value without causing the cursor to navigate out of the current item Web Design Tip If you define mouse movement triggers in client server applications, this may adversely affect the performance of your form. This is because these triggers have the potential to fire frequently. For this reason, you should use them sparingly; in Web-deployed forms these triggers are disabled.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 4-7
Lesson 4: Responding to Mouse Events ......................................................................................................................................................
Mouse Position System Variables 1 2
7 6
3 4 5
Copyright Oracle Corporation, 2001. All rights reserved.
®
1
MOUSE_FORM
5
MOUSE_RECORD_OFFSET
2
MOUSE_CANVAS
6
MOUSE_X_POS
3
MOUSE_ITEM
7
MOUSE_Y_POS
4
MOUSE_RECORD
ly n O e s U I A O &
Technical Note The SYSTEM.MOUSE_FORM system variable is NULL if the platform is not a GUI platform.
l a n r e t n I e l c a r O
...................................................................................................................................................... 4-8 Oracle iDS Forms: Build Internet Applications II
Responding to Mouse Movement ......................................................................................................................................................
The Mouse Position System Variables Use the following system variables to determine when the mouse has moved, where it has moved from, and where it has moved to. Variable SYSTEM.MOUSE_FORM
Use Identifies the form module that the mouse is currently in SYSTEM.MOUSE_CANVAS Identifies the canvas that the mouse is currently on SYSTEM.MOUSE_ITEM Identifies the item that the mouse is currently in SYSTEM.MOUSE_RECORD Identifies the record number that the mouse is currently in SYSTEM.MOUSE_RECORD_OFFSET Identifies the number of the record that the mouse is currently in, relative to the first visible record; uses a 1-based index SYSTEM.MOUSE_X_POS Identifies the x coordinate of the mouse’s current position (If the mouse is positioned on a canvas, the x coordinate is measured relative to the top left corner of the canvas. If the mouse is in an item, the x coordinate is measured relative to the top left corner of the item.) SYSTEM.MOUSE_Y_POS Identifies the y coordinate of the mouse’s current position (If the mouse is positioned on a canvas, the y coordinate is measured relative to the top left corner of the canvas. If the mouse is in an item, the y coordinate is measured relative to the top left corner of the item.)
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 4-9
Lesson 4: Responding to Mouse Events ......................................................................................................................................................
Mouse Button Action Triggers When-Mouse-Down
When-Mouse-Up
When-Mouse-Click click
When-Mouse-Doubleclick click
click
Copyright Oracle Corporation, 2001. All rights reserved.
®
Mouse Event Trigger Sequence 1.
When-Mouse-Down
2.
When-Mouse-Up
3.
When-Mouse-Click
4.
When-Mouse-Down
5.
When-Mouse-Up
l a n r e t n I e l c a r O 6.
When-Mouse-Doubleclick
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note Click and double-click work only if the mouse stays on the item (or canvas) throughout the down-up action.
...................................................................................................................................................... 4-10 Oracle iDS Forms: Build Internet Applications II
Responding to Mouse Button Actions ......................................................................................................................................................
Responding to Mouse Button Actions You can initiate an action whenever a mouse button action occurs by defining the mouse button action triggers. The Mouse Button Action Triggers Trigger When-Mouse-Down
When-Mouse-Up
When-Mouse-Click When-Mouse-Doubleclick
Use Initiates an action when the user presses the mouse button down while the mouse is pointing to an item or a canvas Initiates an action when the user presses and releases the mouse button while the mouse is pointing to an item or a canvas Initiates an action when the user clicks on an item or canvas Initiates an action when the user double-clicks an item or canvas
Firing Sequence for Mouse Button Action Triggers When you double-click an item or canvas, you are potentially causing the following triggers to fire in the order in which they are listed. Similarly, when you click an item or canvas, the triggers that precede the When-Mouse-Click trigger will fire. • When-Mouse-Down • When-Mouse-Up • When-Mouse-Click • When-Mouse-Down • When-Mouse-Up • When-Mouse-Doubleclick
ly n O e s U I A O &
Web Design Tip When any mouse button action is initiated in a Web-deployed form, the Java user interface refers to Forms Services to identify the appropriate mouse button trigger. Even though you may not have defined the relevant mouse button trigger, the user interface will generate this event if you have defined at least one mouse button trigger in your form. You should therefore restrict use of mouse button triggers.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 4-11
Lesson 4: Responding to Mouse Events ......................................................................................................................................................
Mouse Button Action System Variables
SYSTEM.MOUSE_BUTTON_PRESSED
SYSTEM.MOUSE_BUTTON_MODIFIERS
Ctrl
Alt
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 4-12 Oracle iDS Forms: Build Internet Applications II
Responding to Mouse Button Actions ......................................................................................................................................................
The Mouse Button System Variables Use the following system variables to determine which mouse button was pressed and which special key, if any, was used. Variable SYSTEM.MOUSE_BUTTON_PRESSED
SYSTEM.MOUSE_BUTTON_MODIFIERS
Use Identifies which mouse button was pressed (values of 1–3, where 1 is the left mouse button) Identifies which special key was pressed to modify the usual mouse button action
(possible values are Shift+, Caps Lock+, Control+, Alt+, Command+, Super+, and Hyper+) If the operator holds down the [Ctrl] and [Shift] keys while pressing the mouse button, SYSTEM.MOUSE_BUTTON_MODIFIERS contains the value Shift+Control+.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 4-13
Lesson 4: Responding to Mouse Events ......................................................................................................................................................
Summary
In this lesson, you should have learned how to:
•
Respond to mouse movement – Mouse position system variables – Mouse movement triggers
•
Respond to mouse button actions – Mouse button system variables – Mouse button triggers
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 4-14 Oracle iDS Forms: Build Internet Applications II
Summary ......................................................................................................................................................
Summary In this lesson, you saw how to write an application that responds to mouse events. Mouse Events • Entry to a canvas or an item • Exit from a canvas or an item • Move the cursor • Click • Double-click • Up • Down • Responding to mouse movement • Mouse position system variables Mouse Movement Triggers • When-Mouse-Enter • When-Mouse-Leave • When-Mouse-Move Responding to Mouse Button Actions • Mouse button system variables • Mouse button triggers - When-Mouse-Click - When-Mouse-Doubleclick - When-Mouse-Up - When-Mouse-Down
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 4-15
Lesson 4: Responding to Mouse Events ......................................................................................................................................................
Practice 4 Overview
This practice covers the following topics:
•
Invoke an editor when the operator double-clicks an item
•
Redefine the mouse cursor style according to context
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 4-16 Oracle iDS Forms: Build Internet Applications II
Practice Overview: Lesson 4 ......................................................................................................................................................
Practice Overview: Lesson 4 This practice guides you through using mouse-event triggers and mouse system variables. Practice Contents • Define a mouse-event trigger to invoke an editor on the S_CUSTOMER.COMMENTS item. • Modify the mouse cursor style whenever the ORDERS Help canvas is displayed.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 4-17
Lesson 4: Responding to Mouse Events ......................................................................................................................................................
Practice 4 In this practice, you provide additional functionality in your forms by defining mouse event triggers. 1 In your CUSTOMERS form, define a mouse event trigger on
S_CUSTOMER.COMMENTS that invokes the item’s editor when the user double-clicks the item. 2 In your ORDERS form change the mouse cursor symbol to “busy” while the HELP canvas is displayed. a Ensure that the default symbol is restored whenever the user hides the HELP canvas. b The user can close the HELP canvas without pressing the HIDEHELP button, by navigating to an item in another block. How can you ensure that the mouse cursor is always restored? c Save and compile your form modules. Deploy your forms to the Web to test. You can call the ORDERS form from your CUSTOMERS form.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 4-18 Oracle iDS Forms: Build Internet Applications II
................................
Controlling Windows and Canvases Programmatically
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Objectives
After completing this lesson, you should be able to do the following:
•
Display a form document in multiple windows
• • • •
Write code to interact with windows
•
Display large data blocks in a window
Manipulate windows programmatically Manipulate canvas views programmatically Control windows and canvases with Web-deployed forms
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 5-2 Oracle iDS Forms: Build Internet Applications II
Introduction ......................................................................................................................................................
Introduction Overview You should already be familiar with setting window and canvas properties at design time. This lesson covers the triggers and built-ins that you can use to manage the properties and behavior of windows and canvases at run time. Objectives After completing this lesson, you should be able to do the following: • Display a form module in multiple windows • Write code to interact with windows • Manipulate windows programmatically • Manipulate canvas views programmatically • Control windows and canvases with Web-deployed forms • Display large data blocks in a window
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-3
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Using Window-Interaction Triggers
System Variable :SYSTEM.EVENT_WINDOW Trigger
Use
When-Window-Activated
Enforces navigation
When-Window-Deactivated Deactivates a window When-Window-Closed
Closes a window
When-Window-Resized
Maintains visual standards
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 5-4 Oracle iDS Forms: Build Internet Applications II
Using Window-Interaction Triggers ......................................................................................................................................................
Using Window-Interaction Triggers You can use four window-interaction triggers to provide extra functionality whenever a user interacts with a window. These triggers should be defined at the form level. Trigger When-Window-Activated
When-Window-Deactivated When-Window-Closed When-Window-Resized
Characteristic Fires when a window is made the active window (Note that window activation can occur independently of navigation.) Fires when a user deactivates a window by setting the input focus to another window Fires when a user closes a window by using a windowmanager-specific Close command Fires when a window is resized, either by the user or through a trigger (It also fires at form startup, but not when a window is made into an icon.)
The common uses for those triggers are the following: Trigger When-Window-Activated
When-Window-Deactivated When-Window-Closed When-Window-Resized
Use Captures initial settings of window properties; enforces navigation to a particular item whenever the window is activated Deactivates a window Closes a window programmatically Maintains visual standards; captures window properties
ly n O e s U I A O &
Keeping Track of the Triggered Window The SYSTEM.EVENT_WINDOW system variable contains the name of the last window for which a window-interaction trigger fired. You can use this system variable to perform different actions for different windows in your window-interaction triggers. Note: Help with triggers is available by pressing [Ctrl] + [H] and selecting PL/SQL Reference - Triggers.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-5
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Built-ins for Manipulating Windows • • • • • • •
FIND_WINDOW GET_WINDOW_PROPERTY SET_WINDOW_PROPERTY HIDE_WINDOW SHOW_WINDOW MOVE_WINDOW RESIZE_WINDOW
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note In Microsoft Windows, you can reference the multiple document interface (MDI) application window with the FORMS_MDI_WINDOW constant. FORMS_MDI_WINDOW is used with certain built-in functions and procedures that relate to windows. In Web-deployed forms, you can obtain similar functionality by setting the Forms Applet WIDTH and HEIGHT parameters in the base HTML page. Definition of these Form Applet parameters is covered later in this course.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 5-6 Oracle iDS Forms: Build Internet Applications II
Built-ins for Manipulating Windows ......................................................................................................................................................
Built-ins for Manipulating Windows Built-in
Description
FIND_WINDOW
Returns the internal window ID (of data type WINDOW) of a window with the given name
GET_WINDOW_PROPERTY
Returns the current value of the specified window property for the given window
SET_WINDOW_PROPERTY
Sets the specified window property for the given window to a specified value
HIDE_WINDOW
Hides the window
SHOW_WINDOW
Makes the window visible at the current or specified display position
MOVE_WINDOW
Moves the window to the location specified by the given coordinates
RESIZE_WINDOW
Changes the window to the specified width and height
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-7
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Built-ins for Manipulating Canvases • • • • • • • • • •
FIND_CANVAS GET_CANVAS_PROPERTY SET_CANVAS_PROPERTY FIND_VIEW GET_VIEW_PROPERTY SET_VIEW_PROPERTY HIDE_VIEW SHOW_VIEW REPLACE_CONTENT_VIEW SCROLL_VIEW Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note REPLACE_CONTENT_VIEW does not hide the stacked canvas already displayed in the window. In contrast SHOW_VIEW and SET_VIEW_PROPERTY will display the given canvas in front of any stacked canvas, if the canvas Visible property is set to true.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 5-8 Oracle iDS Forms: Build Internet Applications II
Built-ins for Manipulating Canvases ......................................................................................................................................................
Built-ins for Manipulating Canvases Built-in FIND_CANVAS GET_CANVAS_PROPERTY SET_CANVAS_PROPERTY FIND_VIEW GET_VIEW_PROPERTY SET_VIEW_PROPERTY HIDE_VIEW SHOW_VIEW REPLACE_CONTENT_VIEW SCROLL_VIEW
Description Returns the internal canvas ID (CANVAS data type) of a canvas with the given name Returns the current value of the specified canvas property for the given canvas Sets the specified canvas property for the given canvas to a specified value Returns the internal view ID (VIEWPORT data type) of a canvas with the given name Returns the current value of the specified view property for the canvas Sets the specified view property for the given canvas to a specified value Hides the canvas Makes the given canvas visible at the current display position Replaces the content canvas currently displayed in the window with the specified content canvas Moves the view of a given canvas to a different position on its canvas (does not move the window to a different position on the screen)
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-9
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Working with Tab-Style Canvases Page 1
click
Page 3
Page 2
The When-Tab-Page-Changed trigger fires when a user: • Clicks a tab
• Uses either function key • Next tab Page • Previous Tab page
Previous Next Tab Page Tab Page
Copyright Oracle Corporation, 2001. All rights reserved.
®
Working with Tab-Style Canvases
Tab canvas system variables:
• •
:SYSTEM.TAB_NEW_PAGE :SYSTEM.TAB_PREVIOUS_PAGE
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 5-10 Oracle iDS Forms: Build Internet Applications II
Working with Tab-Style Canvases ......................................................................................................................................................
Working with Tab-Style Canvases When-Tab-Page-Changed Trigger This form-level trigger fires when there is explicit item or mouse navigation from one tab page to another in a tab canvas; in other words, when the user clicks a tab or presses [Ctrl] + [PgUp] or [Ctrl] + [PgDown]. This trigger is very often used to perform actions when any tab page is changed during item or mouse navigation; for example, to enable or disable items or to set default or related item values. Be aware that this trigger does not fire when the tab page is changed programmatically and does not fire with implicit navigation. Tab Canvases System Variables Within the When-Tab-Page-Changed trigger, you can reference system variables to determine where you are coming from and going to. • :SYSTEM.TAB_NEW_PAGE returns the name of the tab page to which you are going. • :SYSTEM.TAB_PREVIOUS_PAGE returns the name of the tab page from which you are coming. These system variables return only the page name, not the canvas name, so you must name all tab pages uniquely across the form if you need to be able to identify them programmatically. Technical Note When you are changing to another tab page, the cursor does not automatically move to a different item. To move the cursor you must include a GO_ITEM statement in the When-Tab-Page-Changed trigger. This is intended functionality to allow users to view other tab pages without navigating the cursor and therefore causing item navigation and validation (as previously mentioned).
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-11
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Working with Tab-Style Canvases • •
FIND_TAB_PAGE: Returns the tab page ID
•
SET_TAB_PAGE_PROPERTY: Enables changing of the tab page label
GET_TAB_PAGE_PROPERTY: Returns the tab page label or the tab page canvas
Copyright Oracle Corporation, 2001. All rights reserved.
®
Other Arguments for Canvas Built-Ins • •
Identify the topmost tab page Bring a tab page to the top programmatically
ly n O e s U I A O &
If GET_CANVAS_PROPERTY(’custab’, TOPMOST_TAB_PAGE)= ’Billing’ then SET_CANVAS_PROPERTY(’custab’, TOPMOST_TAB_PAGE, ’Address’); end if;
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 5-12 Oracle iDS Forms: Build Internet Applications II
Working with Tab-Style Canvases ......................................................................................................................................................
Built-ins for Manipulating Tab-Style Canvases Built-in FIND_TAB_PAGE
GET_TAB_PAGE_PROPERTY
SET_TAB_PAGE_PROPERTY
Description Searches the list of tab pages in a given tab canvas and returns a tab page ID when it finds a valid tab page with the given name (You must define a variable of type TAB_PAGE to accept the return value.) Returns property values (CANVAS_NAME, ENABLED, LABEL, VISIBLE, VISUAL_ATTRIBUTE) for a specified tab page Sets the tab page properties (ENABLED, LABEL, VISIBLE, VISUAL_ATTRIBUTE) of the specified tab canvas page
Note: The tab page is named using the syntax “CanvasName.PageName.” Example DECLARE tp_id Tab_Page; BEGIN tp_id := Find_Tab_Page(’Canvas2.TabPage1’); IF Get_Tab_Page_Property(tp_id, enabled) =’FALSE’ THEN Set_Tab_Page_Property(tp_id, enabled, property_true); END IF; END;
Other Arguments for Canvas Built-Ins If you want to make a tab page the top-most on its underlying tab canvas, you can use the built-in procedure SET_CANVAS_PROPERTY and set the canvas property TOPMOST_TAB_PAGE. You can also get the top-most tab page by using the built-in function GET_CANVAS_PROPERTY.
ly n O e s U I A O &
GET_CANVAS_PROPERTY(‘canvas_name’, TOPMOST_TAB_PAGE) SET_CANVAS_PROPERTY(‘canvas_name’, TOPMOST_TAB_PAGE, page_name)
In the preceding syntax example, page_name is either a constant, in single quotes, or a variable.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-13
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Windows and Blocks Window 1
Active window
Nonactive window
Block 1 Window 2 Block 2
Block 3 Cursor location
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 5-14 Oracle iDS Forms: Build Internet Applications II
Windows and Blocks ......................................................................................................................................................
Windows and Blocks Form Builder processes many events based on blocks (and items), which can be completely independent of windows (and canvases). Keep in mind the following characteristics of windows and blocks. Connection Between Windows and Blocks • A window can contain multiple canvases, and multiple items can be located on a canvas. • A block can contain multiple items, and an item is located on one and only one canvas (except for null canvas items). • A window can contain multiple blocks, and a block can be located on several windows. Note: In general, put blocks in separate windows. If blocks are closely related (through a foreign-key relationship), put them in the same window. Window Activation and Block Navigation You can use the When-Window-Activated trigger to activate another window automatically (see the Closing Windows example later in this lesson). Transaction Management During commit processing, Forms processes all base table blocks in sequential order. Therefore, transaction management is block-based rather than window-based. However, the user expects to interact with a form in a window-based manner.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-15
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Manipulating Window Properties Programmatically Maximizing MDI application window SET_WINDOW_PROPERTY SET_WINDOW_PROPERTY (forms_mdi_window, (forms_mdi_window, window_state, window_state, maximize); maximize);
Locating the Cursor window GET_VIEW_PROPERTY GET_VIEW_PROPERTY (GET_ITEM_PROPERTY(NAME_IN (GET_ITEM_PROPERTY(NAME_IN (′system.cursor_item′), (′system.cursor_item′), item_canvas), item_canvas), window_name); window_name);
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note You can also maximize the client server MDI window application with the WINDOW_STATE command line parameter: ifrun60.exe module=customer.fmx userid=my_name/my_password@my_database window_state=maximize
You can switch from the MDI to the SDI window application by using the USESDI command line parameter:
ly n O e s U I A O &
ifrun60.exe module=customer.fmx userid=my_name/my_password@my_database usesdi=yes
With SDI window applications, you must size form module windows to allow for the menu, menu toolbar, and console bar to display.
l a n r e t n I e l c a r O
...................................................................................................................................................... 5-16 Oracle iDS Forms: Build Internet Applications II
Manipulating Window Properties Programmatically ......................................................................................................................................................
Manipulating Window Properties Programmatically You can use the window-interaction triggers and the built-ins for windows to manipulate your windows (and the MDI application window on Microsoft Windows) at run time. Manipulating the Client Server MDI Application Window at Form Startup The When-New-Form-Instance trigger below implements the following functionality: • Maximizing the MDI application window • Setting the window title of the MDI application window The When-New-Form-Instance Trigger at Form Level BEGIN SET_WINDOW_PROPERTY(forms_mdi_window, window_state, maximize); SET_WINDOW_PROPERTY(forms_mdi_window, title, ’Summit Sporting Goods.’); END;
Locating the Cursor Window The cursor may be located in a nonactive window. In this case, you can use the following GET_CURSOR_WINDOW function to find this window. FUNCTION get_cursor_window RETURN VARCHAR2 IS BEGIN RETURN (GET_VIEW_PROPERTY(GET_ITEM_PROPERTY( NAME_IN(’system.cursor_item’),item_canvas), window_name)); END;
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-17
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Window with Close Option on System Menu Box
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 5-18 Oracle iDS Forms: Build Internet Applications II
Closing Windows ......................................................................................................................................................
Closing Windows Use the Microsoft Windows close button, or system-menu box, to provide the user with a means for closing windows. There is no default behavior in Forms when a user clicks on the close button, therefore you must define a When-Window-Closed trigger. The following examples show a form based on departments and employees. The department block and the employee block are located in separate windows. The form level triggers When-Window-Closed and When-Window-Activated implement the following functionality: • Exiting from the form or hiding the window that is closed by the user (Forms automatically activates another window.) • Forcing navigation in the newly activated window Note: The function GET_CURSOR_WINDOW, discussed in an earlier example, is used here. The When-Window-Closed Trigger at Form Level BEGIN IF :SYSTEM.EVENT_WINDOW = ’WINDOW1’ THEN DO_KEY(’exit_form’); ELSIF :SYSTEM.EVENT_WINDOW = ’WINDOW2’ THEN HIDE_WINDOW(’window2’); END IF; END;
The When-Window-Activated Trigger at Form Level BEGIN IF :SYSTEM.EVENT_WINDOW = get_cursor_window THEN RETURN; ELSIF :SYSTEM.EVENT_WINDOW = ’WINDOW1’ THEN GO_BLOCK(’s_dept’); ELSIF :SYSTEM.EVENT_WINDOW = ’WINDOW2’ THEN GO_BLOCK(’s_emp’); END IF; END;
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-19
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Control Window Functionality with Web-Deployed Forms
WIDTH=650 HEIGHT=400 usesdi=no
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 5-20 Oracle iDS Forms: Build Internet Applications II
Manipulating Windows in Web-Deployed Forms ......................................................................................................................................................
Manipulating Windows in Web-Deployed Forms When you build Web-deployed forms, some run-time behavior is determined by Forms Applet parameters that you define in the base HTML file. The Forms Applet downloads and executes your application into an Applet area on the client browser. The parameters allow you to select either MDI or SDI options for your application and to define the size of the Applet area; this area is used as a frame for your forms windows. The following parameters affect the run time behavior of Web form windows: Parameter
Value
Description
usesdi
YES
Runs as a SDI Application
usesdi
NO
Runs as a MDI Application
width
integer
Width of the Applet area, in pixels
height
integer
Height of the Applet area, in pixels
The base HTML file is downloaded when a user requests your forms application from the Web server. It contains information that would otherwise be supplied with the client server RUNFORM command. Information on building the base HTML file is covered in the course Oracle 9iAS Forms Services: Deploy Internet Applications.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-21
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Running Web-Deployed Forms in the Applet Window
usesdi=yes separateFrame=true
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 5-22 Oracle iDS Forms: Build Internet Applications II
Sizing Windows for Web-Deployed Forms ......................................................................................................................................................
Sizing Windows for Web-Deployed Forms Sizing the Applet Area The size of the Applet area is determined by the WIDTH and HEIGHT parameters that were passed to the Forms Applet. If you run the Forms Applet within a browser HTML page, then the size of the Applet area cannot be changed at run time. If it is running outside a browser HTML page, the Applet area will have its own window; the user can resize this window. To run the Form Applet in a separate Applet window, you can set the separateFrame parameter: Parameter
Value
Description
separateFrame
false
Forms application runs in Applet area.
separateFrame
true
Forms application runs in a separate window outside the browser.
If your form module canvases must be larger than the Applet window, then you should either specify window scrollbars, or consider other Form Builder features such as Tab canvases, Tree objects, and scrollable Stacked canvases. With these you can extend the available canvas area within a form module without creating large canvases.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-23
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Display Large Data Blocks in a Window
Applet area WIDTH = 750 Customer Canvas WIDTH = 2000
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 5-24 Oracle iDS Forms: Build Internet Applications II
Display Large Data Blocks in a Window ......................................................................................................................................................
Display Large Data Blocks in a Window With stacked canvases, you can increase the canvas area within a form module, without defining large form windows. To allow the user to view the entire contents of large multiple records, you should place some of the text items on a scrollable canvas. At run time, users can use the canvas scrollbar, or functionality provided by using the SCROLL_VIEW built-in, to view their data. Web Design Tip When you design your base HTML file you can incorporate standard HTML features, such as lines, tables, and frames. By placing the Form Applet within a specific frame, you can give your Forms application a more integrated look and feel in your Web page. By deliberately sizing your form module window larger than the Applet area and by preventing the user from moving or resizing the window, you can hide the window title bar and frame from your Web users. This will enable you to present the form application as an integral part of the HTML page. For information on manipulating the base HTML file, attend the course Oracle 9iAS Forms Services: Deploy Internet Applications.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-25
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Managing Images for Web-Deployed Forms •
Application images are specified outside the form module – Splash screens – Background images
•
Form Module images are specified within the form – Image Items – Boilerplate Images
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 5-26 Oracle iDS Forms: Build Internet Applications II
Managing Images for Web-Deployed Forms ......................................................................................................................................................
Managing Images for Web-Deployed Forms You can display images with Form Builder in image items or as a boilerplate object on a canvas. With Web-deployed forms you can also specify Splash and Background images. The splash screen is only displayed while the Forms Applet is downloaded. You can customize the splash screen image by specifying the splashScreen parameter for the Forms Applet. Background images are displayed in the Applet area until the application is terminated. You can display a background image by specifying the backGround parameter for the Forms Applet. Parameter
Description
splashScreen
Identifies the file containing image to be displayed
backGround
Identifies the file containing image background
Web Design Tip Minimize the use of background objects on your canvases. There is an overhead in downloading images, boilerplate text, and graphics, which can adversely affect performance in Web-deployed forms. Therefore you should try to: • Use the Prompt item property instead of boilerplate text. • Define only common boilerplate graphics such as rectangles and lines. For further information on the performance of Web-deployed forms, see the course Oracle 9iAS Forms Services: Deploy Internet Applications.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-27
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Summary
In this lesson, you should have learned how to:
•
Manage Window-interaction with – SYSTEM.EVENT_WINDOW – Window triggers – Window Built-ins
•
Manipulate canvases and tab canvases with Built-ins
Copyright Oracle Corporation, 2001. All rights reserved.
®
Summary •
Relate Windows to Data Blocks – Multiple blocks correspond to multiple windows.
ly n O e s U I A O &
– Window activation does not induce navigation. – Transaction management is block-oriented.
•
Manage Windows in Web-deployed forms – MDI and SDI windows – Sizing the Applet area – Managing Images
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 5-28 Oracle iDS Forms: Build Internet Applications II
Summary ......................................................................................................................................................
Summary Window-Interaction Triggers • When-Window-Activated • When-Window-Deactivated • When-Window-Closed • When-Window-Resized Use the SYSTEM.EVENT_WINDOW system variable to keep track of the triggered window. Built-ins for Manipulating Windows • Manipulating Windows • Manipulating Canvases • Manipulating Views Windows and Blocks • Windows may contain multiple blocks and blocks may be located on several windows. • Forms will not automatically navigate to an item located in an activated window. • Transaction management is block-oriented rather than window-oriented.
ly n O e s U I A O &
Web-deployed Forms • MDI and SDI windows • Applet Areas • Separate frames • Display Large Data Blocks • Splash Screens and Background Images
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-29
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Practice 5 Overview
This practice covers the following topics:
•
Building a multiple-window form – Using window interaction triggers – Using window and canvas-view built-ins
•
Enhancing the tab canvas functionality by – Customizing tab page navigation – Disabling tab pages
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 5-30 Oracle iDS Forms: Build Internet Applications II
Practice Overview: Lesson 5 ......................................................................................................................................................
Practice Overview: Lesson 5 This practice guides you through managing a multiple-window form and tab canvases programmatically. Practice Contents • Build a multiple-window form and use the appropriate window interaction triggers and built-ins to: - Exit the form when in the primary content canvas window - Navigate to the primary content canvas window when closing another window in the form - Enforce navigation between form windows • Customize tab page navigation. • Disable the Customers comment tab page when there is no data to display.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 5-31
Lesson 5: Controlling Windows and Canvases Programmatically ......................................................................................................................................................
Practice 5 1 Manipulate a multiple-window form.
In your ORDERS form module, ensure that the form is exited when a user closes the Orders window using the window system menu box. An alert should be displayed to users asking them to confirm that they wish to leave the application. b If a user closes the Inventory window through the system menu box, ensure that the form remains open with the cursor positioned in the Orders window. c Whenever the user navigates between the Order and Inventory windows, place the cursor in the first navigable item within the current window. d Save and compile your form. Deploy your form to the Web to test. a
2 In your CUSTOMERS form module, define triggers to manage tab page
navigation. a Using an appropriate trigger, disable the COMMENTS tab page whenever the COMMENTS item contains no text. b The trigger should fire whenever the user navigates to another record. c Whenever the user moves from one tab page to another, ensure that the mouse cursor is placed in the first navigable field within the page. d Save and compile your form. Deploy your form to the Web to test.
ly n O e s U I A O &
If you have time 3 How can you ensure that the user is returned to the first navigable item within a tab page after navigating from the last navigable item? 4 How can you enforce item navigation dynamically within a tab page?
l a n r e t n I e l c a r O
...................................................................................................................................................... 5-32 Oracle iDS Forms: Build Internet Applications II
................................
Defining Data Sources
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 6: Defining Data Sources ......................................................................................................................................................
Objectives
After completing this lesson, you should be able to do the following:
• • •
Describe the various data source types Base a data block on a FROM clause query Describe the advantages of using a FROM clause query
Copyright Oracle Corporation, 2001. All rights reserved.
®
Objectives
After completing this lesson, you should be able to do the following:
• • • •
Base a data block on a stored procedure
ly n O e s U I A O &
Return a REF cursor from a stored procedure
Return a table of records from a stored procedure Select the appropriate data source for a data block
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 6-2 Oracle iDS Forms: Build Internet Applications II
Introduction ......................................................................................................................................................
Introduction Overview This lesson introduces you to the different data source types that you can use for data blocks. This lesson also provides you with some guidelines for choosing the best data source for the job. Objectives After completing this lesson, you should be able to do the following: • Describe the various data source types • Base a data block on a FROM clause query • Discuss the advantages of using a FROM clause query • Base a data block on a stored procedure that returns a REF cursor • Select the appropriate data source for a data block
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-3
Lesson 6: Defining Data Sources ......................................................................................................................................................
Data Source Types
Query
DML
Table FROM clause query Stored procedure
Table Company Name: Company Code: Balance:
Stored procedure Transactional trigger
Transactional trigger
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 6-4 Oracle iDS Forms: Build Internet Applications II
Data Source Types ......................................................................................................................................................
Data Source Types In the previous course, Oracle 9iDS Forms: Build Internet Applications I, you learned that a data block had a base table that served as the data source for both queries and DML operations. A base table is not the only source for a data block, however, and you can specify the data source for the query separately from DML. Data Sources for Query Operations For query operations, you can base your blocks on: • Database tables or views • Stored procedures • Transactional triggers • The FROM clause query (subquery) You can also change the base table of a block dynamically at run time. Data Sources for DML Operations For DML operations, you can base your blocks on: • Database tables or views • Stored procedures • Transactional triggers A data block based on a stored procedure can return data from a REF cursor or a PL/SQL table of records. If your data block has database-intensive multiple validation lookup or derived fields, this method of partitioning application logic onto the server can improve application performance.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-5
Lesson 6: Defining Data Sources ......................................................................................................................................................
Basing a Data Block on a FROM Clause Query SELECT... FROM...
(SELECT... FROM... WHERE...
WHERE...)
Copyright Oracle Corporation, 2001. All rights reserved.
®
Why Use a FROM Clause Query?
Perform joins, lookups, and calculations on the server (thus avoiding multiple network trips) without having to define a view every time
• • •
Improves developer productivity Reduces the burden on the DBA Improves performance
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 6-6 Oracle iDS Forms: Build Internet Applications II
Basing a Data Block on a FROM Clause Query ......................................................................................................................................................
Basing a Data Block on a FROM Clause Query You can use a FROM clause query as the data source for a data block. A FROM clause query is a feature of the Oracle Server that enables you to nest a SELECT statement in the FROM clause of a SELECT statement. A FROM clause query is a valid query block data source, but it is not a valid DML block data source. The value returned from a FROM clause query is a subset of records from the original query. Example SELECT deptno, sal_total FROM ( SELECT deptno, SUM(sal) sal_total FROM emp HAVING SUM(sal) > 5000 GROUP BY deptno ) ORDER BY deptno ;
Why Use a FROM Clause Query? FROM clause queries are used to perform: • Joins • Lookups • Calculations This is done without having to create a view on the server. FROM clauses queries can also be used to prototype views and to increase performance. Using a FROM clause query as a block data source is similar to using a view based on an updatable join as a block data source. However, a FROM clause query provides you with more control, because the presence of a DBA is not required to define the view. Note: The FROM clause query produces results that are identical to an updatable join-view from the client side, but for which there is no defined view on the server.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-7
Lesson 6: Defining Data Sources ......................................................................................................................................................
Basing a Data Block on a Stored Procedure for Query Operations Return data by way of:
• •
REF cursor A Table of records
Querying
Procedure Empno 1234 1235 1236 1237
Ename Jones Smith Adams Clark
Job Clerk Clerk Clerk Clerk
Data block Hire date 01-Jan-95 01-Jan-95 01-Jan-95 01-Jan-95
Company Name: Company Company Code: Name: Company Code: Balance: Balance:
®
Copyright Oracle Corporation, 2001. All rights reserved.
Basing a Data Block on a Stored Procedure for DML Operations •
Return data by way of a table of records
Updating
Procedure Empno 1234 1235 1236 1237
Ename Jones Smith Adams Clark
Job Clerk Clerk Clerk Clerk
ly n O e s U I A O & Data block
Hire date 01-Jan-95 01-Jan-95 01-Jan-95 01-Jan-95
Company Name: Company Company Code: Name: Company Code: Balance: Balance:
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 6-8 Oracle iDS Forms: Build Internet Applications II
Basing a Data Block on a Stored Procedure ......................................................................................................................................................
Basing a Data Block on a Stored Procedure You can base a data block on a stored procedure. A stored procedure returns data by using either a REF cursor or a table of records. What Is a REF Cursor? A REF cursor defines a SELECT statement that is the source of the records. You can use this cursor to perform array fetches of SELECT statements opened by a server-side procedure. A REF cursor is a pointer to a server-side cursor variable. It is analogous to a pointer in C in that it is an address to a location in memory. The stored procedure returns a reference to a cursor that is open and populated by a SELECT statement to be used as a block data source. A stored procedure that uses a REF cursor can be used only as a query block data source; it cannot be used as a DML block data source. Using a REF cursor is ideal for queries that depend only on variations in SQL SELECT statements and not PL/SQL. What Is a Table of Records? A table of records is a PL/SQL V2.3 variable that is essentially an array of rows. You can think of a table of records as an image of a table in memory. The server-side procedure constructs this array, usually based on parameters passed to it, and passes back the resulting “set” of records to a data block. Forms treats the resulting table of records exactly as if it were fetching a series of rows from a table. Unlike a view or a REF cursor, you are not limited to what you can express as a SQL SELECT statement. Anything you can code in PL/SQL is possible; for example, a tree-walk that includes a join. Using a table of records is extremely efficient in terms of the savings on network traffic because it takes a single round-trip (from client to server) to execute the stored procedure and a single round-trip to return the records.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-9
Lesson 6: Defining Data Sources ......................................................................................................................................................
Example of Query Using a REF Cursor Procedure Define a package specification with:
• • •
The objects returned by the REF cursor The REF cursor The query procedure: Data returned through the first argument (IN OUT)
Define a package body: Write the code for the query procedure
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 6-10 Oracle iDS Forms: Build Internet Applications II
Example of a Query Using a REF Cursor Procedure ......................................................................................................................................................
Example of a Query Using a REF Cursor Procedure This is an example of a stored procedure that returns a REF cursor as a block data source. A package is used to group the related data types and procedures logically. -- Define Package Specification PACKAGE emp_pkg IS -- Defines the objects returned by the REF Cursor TYPE emprec IS RECORD ( empno emp.empno%TYPE, ename emp.ename%TYPE ); -- Defines the Ref Cursor TYPE empcur IS REF CURSOR RETURN emprec; -- Defines the procedure used for querying records PROCEDURE empquery_refcur ( block_data IN OUT empcur, p_deptno IN NUMBER); END; -- Defines Package Body PACKAGE BODY emp_pkg IS PROCEDURE empquery_refcur ( block_data IN OUT empcur, p_deptno IN NUMBER) IS BEGIN OPEN block_data FOR SELECT empno, ename FROM emp WHERE deptno = NVL( p_deptno, deptno ) ORDER BY empno; END; END;
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-11
Lesson 6: Defining Data Sources ......................................................................................................................................................
Example of Query Using a REF Cursor Procedure Define a package specification with:
• • •
The objects returned by the REF cursor The REF cursor The query procedure: Data returned through the first argument (IN OUT)
Define a package body: Write the code for the query procedure
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 6-12 Oracle iDS Forms: Build Internet Applications II
Example of Query Using a Table of Records Procedure ......................................................................................................................................................
Example of Query Using a Table of Records Procedure This is an example of a stored procedure that returns a table of records as a block data source. A package is used to group the logically related data types and procedures. -- Define Package Specification PACKAGE emp_pkg IS -- Defines each row of the table TYPE emprec IS RECORD ( empno emp.empno%TYPE, ename emp.ename%TYPE ); -- Defines the Table of records TYPE emptab IS TABLE OF emprec INDEX BY BINARY_INTEGER; -- Defines the procedure
used for querying records
PROCEDURE empquery_tab ( block_data IN OUT emptab, p_deptno
IN
NUMBER );
END; -- Defines Package Body PACKAGE BODY emp_pkg IS PROCEDURE empquery_tab ( block_data IN OUT emptab, p_deptno
IN
NUMBER )
IS i NUMBER; CURSOR empsel IS SELECT empno, ename FROM emp
ly n O e s U I A O &
WHERE deptno = NVL( p_deptno, deptno ); BEGIN OPEN empsel; i := 1; LOOP
FETCH empsel INTO block_data(i).empno,
l a n r e t n I e l c a r O
block_data(i).ename;
EXIT WHEN empsel%NOTFOUND; i := i + 1;
END LOOP;
END;
END;
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-13
Lesson 6: Defining Data Sources ......................................................................................................................................................
Example of DML Using a Table of Records Procedure Define a package specification with:
• • • • • •
The structure of each row of the table The table of records A procedure to insert rows A procedure to update rows A procedure to delete rows A procedure to lock rows
Define a package body by writing the code for each DML procedure
Copyright Oracle Corporation, 2001. All rights reserved.
®
Note See Appendix F, “Handling Server-Side Errors” for code details.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 6-14 Oracle iDS Forms: Build Internet Applications II
Example of DML Using a Stored Procedure ......................................................................................................................................................
Example of DML Using a Stored Procedure This is an example of a stored procedure that inserts rows using a table of records as a block data source. A package is used to group the logically related data types and procedures. You should define procedures that update, delete, and lock rows also. -- Define Package Specification PACKAGE emp_pkg IS -- Defines each row of the table TYPE emprec IS RECORD ( empno emp.empno%TYPE, ename emp.ename%TYPE, mgr emp.mgr%TYPE, deptno emp.deptno%TYPE ); -- Defines the Table of records TYPE emptab IS TABLE OF emprec INDEX BY BINARY_INTEGER; -- Defines the procedure used for inserting records PROCEDURE empinsert ( block_data IN emptab ); END; -- Defines Package Body PACKAGE BODY emp_pkg IS PROCEDURE empinsert ( block_data IN emptab ) IS i NUMBER; cnt NUMBER; BEGIN cnt := block_data.count; FOR i IN 1..cnt LOOP INSERT INTO emp (empno, ename, mgr, deptno) VALUES (block_data(i).empno, block_data(i).ename, block_data(i).mgr, block_data(i).deptno); END LOOP; END; END;
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-15
Lesson 6: Defining Data Sources ......................................................................................................................................................
Returning a REF Cursor
SQL SELECT Procedure Query
1
2
REF cursor
REF cursor
3 Fetched rows
4 ®
Copyright Oracle Corporation, 2001. All rights reserved.
Returning a Table of Records
Any PL/SQL code Procedure Query
1
Cursor
3 Table of records
l a n r e t n I e l c a r O 4
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
2
Cursor
®
...................................................................................................................................................... 6-16 Oracle iDS Forms: Build Internet Applications II
Deciding Whether to Use a REF Cursor or a Table of Records ......................................................................................................................................................
Deciding Whether to Use a REF Cursor or a Table of Records When deciding whether to use a REF cursor or a table of records, take into account the following considerations. Queries or DML on a Table Executing queries or DML on a table takes one round trip per array size of rows returned. Queries with Stored Procedure Returning a REF Cursor Executing queries using a stored procedure that returns a REF cursor takes one round trip to execute the stored procedure(1, 2), plus one round trip (3, 4) per array size of rows returned. Queries or DML with Stored Procedure Using PL/SQL Tables of Records Executing queries or DML with stored procedures using PL/SQL tables of records takes one round trip to execute the stored procedure (1,2) plus one round trip (3,4) for all the rows. Performance Implications of REF Cursors or Table of Records If you are dealing with a large number of rows, the disadvantage of PL/SQL tables of records is that all the rows must be processed at once. For querying, this means you might retrieve rows that the user does not need and never displays. • REF cursor: The number of records fetched depends on the Array Fetch property value. • Table of records: All records are fetched. If you want to view all records, a table of records is more efficient. However, if the table of records returns 10,000 records and you look only at 3, it is not an efficient option. For querying and DML, you use an unnecessary amount of memory because all the rows must be in memory at the same time.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-17
Lesson 6: Defining Data Sources ......................................................................................................................................................
Data Block Wizard
Use the Data Block Wizard to specify the following:
• • • • • •
Data source type Query procedure Insert procedure Update procedure Delete procedure Lock procedure
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 6-18 Oracle iDS Forms: Build Internet Applications II
Data Block Wizard ......................................................................................................................................................
Data Block Wizard The Data Block Wizard simplifies and automates the process of creating blocks. You saw how to use it in the previous course, Oracle 9iDS Forms: Build Internet Applications I. Use the Data Block Wizard even if you want to create a data block based on stored procedure. You just have to specify the following: Property
Description
Data source type
Specifies if the data block is based on a table or a stored procedure
Query procedure
Name of the procedure used to query rows
Insert procedure
Name of the procedure used to insert rows
Update procedure
Name of the procedure used to update rows
Delete procedure
Name of the procedure used to delete rows
Lock procedure
Name of the procedure used to lock rows
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-19
Lesson 6: Defining Data Sources ......................................................................................................................................................
Data Block Properties for Queries
Copyright Oracle Corporation, 2001. All rights reserved.
®
Data Block Properties for DML
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 6-20 Oracle iDS Forms: Build Internet Applications II
Data Block Properties ......................................................................................................................................................
Data Block Properties Data Block Properties for Queries Property
Description
Query Data Source Type
Specifies the query data source type for the data block
Query Data Source Name
Specifies the name of the block query data source. (Used when the query data source type is Table, Subquery, or Procedure.)
Query Data Source Columns
Specifies the names and data types of columns associated with the query data source. (Used when the query data source type is Table, Subquery, or Procedure.)
Query Data Source Arguments
Specifies the names, data types, and values of the arguments that are to be passed to the procedure for querying data (Used only if the query data source type is Procedure.)
Data Block Properties for DML Property
Description
DML Data Target Type
Specifies the DML data source type for the data block
DML Data Target Name
Specifies the name of the DML data source for the data block (Used only if the DML data target type is Table.)
(Insert, Update, Delete, Lock) Procedure Name
Specifies the name of the procedure to be used (Used only if the DML data target type is Procedure.)
(Insert, Update, Delete, Lock) Procedure Result Set Columns
Specifies the names and data types of the result set columns associated with the procedure (Used only if the DML data target type is Procedure.)
(Insert, Update, Delete, Lock) Procedure Arguments
Specifies the names, data types, and values of the arguments that are to be passed to the procedure (Used only if DML data target type is Procedure.)
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-21
Lesson 6: Defining Data Sources ......................................................................................................................................................
Data Source Guidelines
Base a data block on a FROM clause query to:
• •
Create a “dynamic” view Perform validation and DML on the server side
Copyright Oracle Corporation, 2001. All rights reserved.
®
Data Source Guidelines
Base a data block on a stored procedure to:
• • • • •
Increase control and security Specify a SELECT statement at run time Query or update multiple tables Perform complex computations Perform validation and DML on the server side
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 6-22 Oracle iDS Forms: Build Internet Applications II
Data Source Guidelines ......................................................................................................................................................
Data Source Guidelines Using a FROM Clause Query You base a data block on a FROM clause query to: • Create a dynamic view • Perform validation and DML on the server side Using Stored Procedures You base a data block on a stored procedure when you want to: • Increase control and security Using a stored procedure, you do not have to grant select access on the table to the users, just EXECUTE privileges on the procedure. • Specify a SELECT statement at run time Using a REF cursor, if the logged-on user is a manager, open the cursor as SELECT last_name, salary FROM s_emp; otherwise open the cursor as SELECT last_name, null FROM s_emp. • Base a block on multiple tables Using a REF cursor and depending on some parameter to the procedure, you could open the cursor either as SELECT * FROM open_orders (current data) or as SELECT * FROM closed_orders (old data). • Perform complex computations and decisions Using a table of records, return the salary of all employees that you manage, but NULL for the salary of other employees. • Perform validation and DML on the server side If your data block has multiple validation lookup or derived fields that are database-intensive, this method of partitioning the application logic onto the server can vastly improve the performance of applications. • Encapsulate logic within a subprogram • Reduce traffic through array processing, using a REF cursor
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-23
Lesson 6: Defining Data Sources ......................................................................................................................................................
Data Source Guidelines
Data Source
Query
DML
Table
YES
YES
View
YES
YES
FROM Clause
YES
NO
Proc-Ref Cur
YES
NO
Proc-Table Rec
YES
YES
Transac. Trigger
YES
YES
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 6-24 Oracle iDS Forms: Build Internet Applications II
Data Source Guidelines ......................................................................................................................................................
Data Source Type Restrictions When deciding on a data block source, consider your requirements: • Will the block be used only to query records? • Will the block be used to perform inserts, updates, and deletes? • Will the block be used to perform both query and DML? To decide, you should also consider the functional restrictions for each data source type: Data Source
Allows Query
Allows DML
Table
Yes
Yes
View
Yes
Yes
FROM Clause
Yes
No
Procedure Using a REF Cursor
Yes
No
Procedure Using a Table of Records
Yes
Yes
Transactional Trigger
Yes
Yes
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-25
Lesson 6: Defining Data Sources ......................................................................................................................................................
Summary
In this lesson, you should have learned to:
•
Base data blocks on new data sources: – FROM clause query (query only) – Stored procedure (query and DML)
•
Exploit features of stored procedures: – REF cursors – Limited to a single SELECT statement
– Table of records – Can be a complex procedure
Copyright Oracle Corporation, 2001. All rights reserved.
®
Summary •
Use the Data Block Wizard to specify: – Data source type – Procedures for queries, updates, deletes, and locking
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 6-26 Oracle iDS Forms: Build Internet Applications II
Summary ......................................................................................................................................................
Summary New Data Sources • Stored procedure (query and DML) • FROM clause query (query only) Stored Procedures Return • REF cursors—limited to a single SELECT statement • Table of records—can be a complex procedure Using the Data Block Wizard • Specify data source type • Specify procedures for queries, updates, deletes, and locking
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-27
Lesson 6: Defining Data Sources ......................................................................................................................................................
Practice 6 Overview
This practice covers the following topics:
•
Creating a package containing a stored procedure to return a REF cursor
•
Creating a data block based on a REF cursor stored procedure
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 6-28 Oracle iDS Forms: Build Internet Applications II
Practice Overview: Lesson 6 ......................................................................................................................................................
Practice Overview: Lesson 6 This practice guides you through creating a data block based on stored procedures. Practice Contents • Create a package containing a stored procedure to return a REF Cursor • Create a data block based on a stored procedure
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 6-29
Lesson 6: Defining Data Sources ......................................................................................................................................................
Practice 6 1 Create a server-side package containing a procedure to return a REF
cursor. a Create the Orders_pkg package specification; you can import the code from the pr6_1.txt file. b Create the Orders_pkg package body; you can import the code from the pr6_2.txt file. c Examine the Orders_pkg package body to identify required parameter values. 2 Open the ORDERREFCURSOR.fmb file and save as ORDREFXX where
XX is your student course number. This form contains a control block, called CHOOSE, and a group of option buttons, which allows the user to specify a parameter value to be passed to the REF cursor. a Create a data block called SELECTION and base it on the REF cursor procedure that you have just created. b Pass the name of the radio group as the value for the P_VIEW argument: ‘:choose.view_type’. c In the layout editor, customize the canvas layout to ensure that SELECTION items are displayed to the left of the option buttons group. d Save and compile your form. Deploy your form to the Web to test.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 6-30 Oracle iDS Forms: Build Internet Applications II
................................
Working with Oracle8i Objects in Form Builder
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Objectives
After completing this lesson, you should be able to: • Recognize which object types are supported
•
Describe how object types are represented within Form Builder
• •
Create a block based on an object table
•
Populate a REF column with an LOV
Create a block based on a relation table with an object or an REF column
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-2 Oracle iDS Forms: Build Internet Applications II
Introduction ......................................................................................................................................................
Introduction Overview This lesson reviews certain object features of Oracle8i and explains how these objects are displayed in the Object Navigator. Objectives After completing this lesson, you should be able to do the following: • Recognize which Oracle8i object types are supported • Describe how Oracle8i objects are represented within Form Builder • Create a block based on an object table • Create a block based on a relational table with an object column or REF column • Populate a REF column with an LOV
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-3
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Object Types Attributes Ship
Check status
ORDER po_no custinfo line_items amount
Cancel
Hold Methods Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-4 Oracle iDS Forms: Build Internet Applications II
What Are Object Types? ......................................................................................................................................................
What Are Object Types? An object type is a user-defined composite data type. It is in some ways similar to a record type, and in some ways similar to a package. An object type is similar to a record type in that it is composed of one or more subparts that are of predefined data types. Record types call these subparts “fields,” but object types call these subparts “attributes.” Just as the fields of a record type can be of other record types, the attributes of an object type can be of other object types. Such an object type is called “nested.” Object types are like record types in another sense: both of them must be declared as types before the actual object or record can be declared. An object type is also similar to a package. After an object is declared, its attributes are similar to package variables. Like packages, object types can contain procedures and functions. In object types, these subprograms are known as “methods.” As with packages, object types can be declared in two parts: a specification and a body. Like package variables, attributes declared in the object type specification are public and those declared in the body are private, and as with package subprograms, all methods are defined in the package body, but only those whose specification appears in the object type specification are public methods.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-5
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Review of Objects • • • •
Object tables Object columns Object views INSTEAD-OF triggers
DECLARE BEGIN EXCEPTION END;
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-6 Oracle iDS Forms: Build Internet Applications II
Review of Objects ......................................................................................................................................................
Review of Objects With an object type, you can create object tables, object columns, object views, and INSTEAD-OF triggers. Object Tables After you have declared an object type, you can create objects based on the type. One way to do this is to create a table whose rows are objects of that object type. Rows in an object table are assigned object IDs (OIDs) and can be referenced using a REF type. Object Column Another construct that can be based on an object type is an object column in a relational table. In the object table, the rows of a table are objects. In a relational table with an object column, the column is an object. The table usually has standard columns, as well as one or more object columns. Object columns are not assigned OIDs, and thus cannot be referenced using object REF values. Object View An object view transforms the way a table appears to a user, without changing the actual structure of the table. Object views make relational tables look like object tables. Objects accessed through object views are assigned OIDs, and can be referenced using object REFs. INSTEAD OF Triggers INSTEAD OF triggers provide a transparent way of modifying views that cannot be modified directly through SQL DML statements (INSERT, UPDATE, and DELETE). These triggers are called INSTEAD-OF triggers because, unlike with other types of triggers, the Oracle server fires the trigger instead of executing the triggering statement. The trigger performs update, insert, or delete operations directly on the underlying tables.
l a n r e t n I e l c a r O
ly n O e s U I A O &
Technical Note The Database Trigger Editor includes the INSTEAD-OF triggering event.
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-7
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
References to Objects
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-8 Oracle iDS Forms: Build Internet Applications II
Object REFs ......................................................................................................................................................
Object REFs When a row in an object table or object view is created, it is automatically assigned a unique identifier called an object ID (OID). This OID value can be stored in attributes of other objects, or columns of other tables. The stored copy of the OID then becomes a pointer, or REF, to the original object. (Object columns are not assigned OIDs and cannot be pointed to by a REF.) In relational databases, primary key values are used to identify records uniquely. In object-relational databases, OIDs provide an alternate method. With relational tables, you can associate two records by storing the primary key of one record in one of the columns (the foreign key column) of another. In a similar way, you can associate two objects by storing the OID of one object in an attribute of another, you can associate a row in a relational table to an object by storing the OID of an object in a column of a relational table. The attribute or column that holds the OID is of data type REF. Remember, only the OID value for the object is stored in the table, not the object itself.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-9
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Oracle8i in Oracle Forms
Supported Oracle8i features
• •
Large Objects: BLOB, CLOB, NCLOB, BFILE User-defined objects – Object table – Column object – REF column
Unsupported Oracle8i features
• •
Collection types Stored procedures that return object values
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-10 Oracle iDS Forms: Build Internet Applications II
Supported Oracle8i Features ......................................................................................................................................................
Supported Oracle8i Features A number of features provided in the Oracle8i Server are available in Oracle Forms Developer. This allows greater scalability and performance in your application. Oracle adds support for the following Oracle8i data types: • Large objects (LOBs): BLOB, CLOB, NCLOB, BFILE • User-defined Oracle8i objects • An object table, where the entire table is based on a single object type (Oracle Forms Developer treats each column in an object table as an individual data item.) • A column object in an object or relational table, where the column is based on an object type definition • A REF column in an object or a relational table, where that column’s values are pointers to rows in a separate object table Unsupported Oracle8i Features Not all Oracle8i features are currently supported by Oracle Forms Developer. The major unsupported features are: • Collection types, including nested tables and varying arrays • Stored procedures that return object values
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-11
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
How Oracle Forms Treats Objects
Object_A
Object_A
Attr_A1
Attr_A1
Attr_A2 Object_B Attr_B1
Attr_A2_B1
Attr_B2
Attr_A2_B2
Attr_A3
Attr_A3
Nested Objects
Items in a Form
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-12 Oracle iDS Forms: Build Internet Applications II
How Oracle Forms Developer Treats Objects ......................................................................................................................................................
How Oracle Forms Developer Treats Objects As you have learned, Oracle8i tables can contain objects. In its support for the Oracle8i Server, Oracle Forms Developer allows you to access these objects in an application. A table itself can be based on an object (a table object), one or more of the table columns can be based on an object (a column object), or one or more of the tables’ columns can contain a reference to an object stored in another table (REF column). Each of these objects can itself contain objects. In these cases, the columns and attributes form a hierarchy among the Oracle8i data types. However, Oracle Forms Developer has no hierarchy of items. Each item lies directly below the block. Therefore, Oracle Forms Developer must collapse the hierarchy before the columns and attributes are mapped to items within a block. Both the hierarchy of the columns and attributes and the “flattened” nature of the resulting items are represented in Oracle Forms Developer’s displays and dialog boxes.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-13
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Object Display
Object Column Object Table
Object REF
Object Type
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-14 Oracle iDS Forms: Build Internet Applications II
Object Type Displays ......................................................................................................................................................
Object Type Displays The Object Navigator lists declared types under the Database Objects node, along with tables, views, and other Oracle objects. The objects in the screenshot are based on the following syntax: -- type declaration
CREATE TYPE dept_type AS OBJECT (id name region_id /
NUMBER, VARCHAR2(25), NUMBER(7) )
-- object table
CREATE TABLE oo_dept_table OF dept_type; -- object column
CREATE TABLE rel_emp_table_ObjCol ( id NUMBER(7), last_name VARCHAR2(25), first_name VARCHAR2(25), userid VARCHAR2(8), start_date DATE, NUMBER(7), title VARCHAR2(25), dept_id dept_type, salary NUMBER(11,2), commission_pct NUMBER(4,2) ); -- ref column
CREATE TABLE rel_emp_table_RefCol (
manager_id
ly n O e s U I A O &
id NUMBER(7), last_name VARCHAR2(25), first_name VARCHAR2(25), userid VARCHAR2(8), start_date DATE, manager_id NUMBER(7), title VARCHAR2(25), dept_id REF dept_type, salary NUMBER(11,2), commission_pct NUMBER(4,2) );
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-15
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Creating Data Blocks Based on Oracle8i Objects • • •
Blocks based on object tables Blocks based on object columns Blocks with REF Lookups
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-16 Oracle iDS Forms: Build Internet Applications II
Creating Data Blocks Based on Oracle8i Objects ......................................................................................................................................................
Creating Data Blocks Based on Oracle8i Objects Oracle Forms Developer enables you to create data blocks based on Oracle8i objects. The Data Block Wizard has been enhanced to support object tables. The fields of an object are displayed in a hierarchy underneath the object column in the wizard’s Table page. Like objects in the Object Navigator, you can expand or collapse the object columns in the display. You can base a data block on: • An object table • A column object • A REF column
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-17
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Blocks Based on Object Tables
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-18 Oracle iDS Forms: Build Internet Applications II
Selecting Object Table Columns ......................................................................................................................................................
Selecting Object Table Columns You can create a data block based on a user-defined object table. In the Data Block Wizard, you select object tables the same way you select relational tables. In the wizard’s Table page, when you select an object table as the data source, it is expanded and each of its components is displayed in the Available Columns window. An outline format with indenting is used to show each component of the object. You select the type attributes the same way you select relational table columns. Oracle Forms Developer treats each component in an object table as a separate column, and allows you to select these columns individually. The syntax below creates an object table based on an object type: CREATE TYPE dept_type AS OBJECT (id NUMBER, name VARCHAR2(25), region_id NUMBER(7) ) / CREATE TABLE oo_dept_table OF dept_type /
In the diagram, the wizard shows all the columns of the object table OO_DEPT_TABLE (ID, NAME, REGION_ID). Select any or all as data block items.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-19
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Blocks Based on Object Columns
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-20 Oracle iDS Forms: Build Internet Applications II
Selecting Object Column Attributes ......................................................................................................................................................
Selecting Object Column Attributes If you base a block on an object or relational table with an object column, the attributes of the object column appear indented beneath the name of the object column in the Data Block Wizard. Oracle Forms Developer treats each attribute as a separate column. You can select any combination of columns or object column attributes. Once selected, they all “collapse” to the same level as an item within the new block. Data items selected from an object are given the default name ColumnObjectName_ItemName. Selecting the object column name itself has the effect of selecting all of the attributes of the object column. The syntax below creates a table with an object column: CREATE TYPE dept_type AS OBJECT (id NUMBER, name VARCHAR2(25), region_id NUMBER(7) ) / CREATE TABLE rel_emp_table_ObjCol ( id NUMBER(7), last_name VARCHAR2(25), first_name VARCHAR2(25), userid VARCHAR2(8), start_date DATE, manager_id NUMBER(7), title VARCHAR2(25), dept_id dept_type, salary NUMBER(11,2), commission_pct NUMBER(4,2) );
ly n O e s U I A O &
In the diagram, the wizard displays ID, NAME, and REGION_ID as columns you can select as data block items.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-21
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Blocks with REF Lookups
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-22 Oracle iDS Forms: Build Internet Applications II
Blocks with REF Lookups ......................................................................................................................................................
Blocks with REF Lookups If you base a block on an object or relational table with a REF column, the attributes of the object being referenced appear below the REF column in the Available Columns window. Once selected, the attributes of the REF column are made into items, just like standard columns. However, the items based on REF column attributes are created with a QUERY ONLY property value of “YES,” and INSERT ALLOWED and UPDATE ALLOWED properties of “NO.” The syntax below creates a table with a REF data type: CREATE TYPE dept_type AS OBJECT (id NUMBER, name VARCHAR2(25), region_id NUMBER(7) ) / CREATE TABLE rel_emp_table_RefCol ( id NUMBER(7), last_name VARCHAR2(25), first_name VARCHAR2(25), userid VARCHAR2(8), start_date DATE, manager_id NUMBER(7), title VARCHAR2(25), dept_id REF dept_type, salary NUMBER(11,2), commission_pct NUMBER(4,2) );
ly n O e s U I A O &
As seen in the diagram, the REF column name (DEPT_ID) appears twice in the column selection list. It appears once as a heading for the referenced object’s attributes and then again as a pointer. The column is selectable.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-23
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Using the REF Lookup Value
Select REF attribute columns: This causes the columns to appear as data items at run-time. Select the REF item itself:
• • •
This causes the item to be placed on a Null canvas. The item does not appear at run time. The item is available for coding purposes.
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-24 Oracle iDS Forms: Build Internet Applications II
The REF Column Value ......................................................................................................................................................
The REF Column Value The double listing of the REF column name affords you different choices. As with a regular column object, you can select any or all of a REF’s attribute columns. Selecting the first instance of the REF name in the diagram on the previous page selects all its parts. When you select one or more of the REF’s attribute columns, they appear as normal data items in the data block at run time. You can also select the REF itself, which is the second entry in the diagram on the previous page. If the REF column itself is included in the block, it is created as a nondisplay item and placed by default on the Null canvas. Although the REF item does not appear on the canvas at run time, it is still available for coding purposes.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-25
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
LOVs for REFs
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-26 Oracle iDS Forms: Build Internet Applications II
LOVs for REFs ......................................................................................................................................................
LOVs for REFs Users may use an LOV to select appropriate referenced values. The Data Block Wizard presents the LOV for REF window, which enables you to define an LOV. How to Create the LOV 1 Select the REF desired. 2 For the REF selected, the wizard lists all the associated tables. Select the table of your choice. The wizard builds the LOV from the values in this table. Note: The same LOV gets attached to all the lookup items associated with a particular REF. REFs are defined on object types, not on specific tables. Therefore, a REF can point to multiple tables.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-27
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Summary
In this lesson, you should have learned how to:
• • •
Identify supported Oracle8i object types
•
Populate REF columns with an LOV
Define data blocks based on object tables Define data blocks based on tables with object columns or REF columns
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-28 Oracle iDS Forms: Build Internet Applications II
Summary ......................................................................................................................................................
Summary • • • • •
Oracle Forms Developer supports most, but not all, of the Oracle8i object types. In Forms Builder, object types are displayed like columns, where indentation shows the nesting of objects. Blocks can be based on object tables. Blocks based on object or relational tables can include object columns or REF columns. REF columns can be populated with an LOV.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-29
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Practice 7 Overview
This practice covers the following topics:
•
Creating a block based on a relational table with an object column
•
Creating a block based on a relational table with a REF column
•
Populating a REF column with an LOV
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 7-30 Oracle iDS Forms: Build Internet Applications II
Practice Overview: Lesson 7 ......................................................................................................................................................
Practice Overview: Lesson 7 This practice guides you through creating data blocks based on Oracle8i object tables. Practice Contents • Create a block based on a relational table with an object column • Create a block based on a relational table with a REF column • Populate a REF column with an LOV
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 7-31
Lesson 7: Working with Oracle8i Objects in Form Builder ......................................................................................................................................................
Practice 7 1 Create a data block based on a relational table with an object column. a b c d e
f
Create a form called OBJ_COLXX where XX is your student course number. Using the Data Block Wizard, create a block based on the REL_EMP_TABLE_OBJCOL relational table. Select the columns ID, FIRST_NAME, and LAST_NAME. Expand the object column DEPT_ID and select the attributes ID and NAME. Note the names that are given to the new items. In the Layout Wizard, select all available items for display. Change the prompt for item DEPT_ID to Department ID and DEPT_ID_NAME to Department Name. Use a form layout. Save, compile, and test your form.
If you have time 2 Create a block based on a relational table with an REF column, and specify an LOV to populate the REF column. a Create a form called REF_COLXX where XX is your student course number. b Create a block based on the REL_EMP_TABLE_REFCOL relational table. c Select the columns ID, FIRST_NAME, and LAST_NAME. d Select the DEPT_ID attributes ID and NAME. e Create an LOV for the REF item DEPT_ID. Select the check box, and select OO_DEPT_TABLE as the source for the LOV. f In the Layout Wizard, select all available items for display. g In the Object Navigator, identify the canvas with which item DEPT_ID is associated. h In the Object Navigator, check that an LOV and associated record group have been created. i Save, compile, and test the form.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 7-32 Oracle iDS Forms: Build Internet Applications II
................................
Controlling Data Block Relationships
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Objectives
After completing this lesson, you should be able to do the following:
• • •
Define block coordination
• •
Implement a coordination-type toggle
Coordinate data blocks by using REF relations Describe the characteristics and principles of relation-handling code Force one commit per master record
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 8-2 Oracle iDS Forms: Build Internet Applications II
Introduction ......................................................................................................................................................
Introduction Overview You have seen how form modules consist of data blocks based on related tables. This lesson shows how you can modify the relationship between two data blocks to affect the way in which deletes are handled and to what extent the data blocks are coordinated at query time. Also, it explains how to create relationships based on object REFs. Objectives After completing this lesson, you should be able to do the following: • Define block coordination • Coordinate data blocks by using REF relations • Describe the characteristics and principles of relation-handling code • Implement a coordination-type toggle • Force one commit per master record
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-3
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Relations •
Logical objects that handle the relationship between two blocks
• •
Created implicitly with a master-detail form module Created explicitly with the New Relation dialog box
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 8-4 Oracle iDS Forms: Build Internet Applications II
Creating a Relation ......................................................................................................................................................
Creating a Relation What Is a Relation? A relation is a Form Builder object that handles the relationship between two associated blocks. You can create a relation either: • Implicitly with a master-detail form module • Explicitly in the Object Navigator Implicit Relations When you create a master-detail form module, a relation is automatically created. This relation is named in the format masterblock_detailblock, for example, S_ORD_S_ITEM. Explicit Relations If a relation is not established when default blocks are created, you can create your own, either by setting the properties in the master block New Relation dialog box, or by calling the reentrant wizard for the detail data block. Like implicitly created relations, PL/SQL program units and triggers are created automatically when you explicitly create a relation.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-5
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Block Coordination • •
Coordination-causing event Block-coordination phases: – Clear phase executed before change of master record – Populate phase executed after change of master record
•
Implementation of block coordination: – The Copy Value from Item property – Relation-handling triggers – Relation-handling procedures Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 8-6 Oracle iDS Forms: Build Internet Applications II
Block Coordination ......................................................................................................................................................
Block Coordination To maintain a master-detail relationship, Forms coordinates the master and detail blocks to ensure that only the detail records that belong to the current master record are displayed. Coordination-Causing Events Any event that changes the master record is called a coordination-causing event or a coordination operation. Forms automatically coordinates the master and detail blocks again when you move to another master record. Block Coordination Phases Phase Clear
Populate
Description Forms clears all detail blocks before it navigates to the new master record. Unsaved changes in detail blocks are deleted. If the Clear phase fails, Forms stops coordination processing and does not navigate to the new master record. Forms queries all detail blocks after it has navigated to the new master record, unless the coordination type is Deferred.
Implementation of Block Coordination Forms implements block coordination through the following elements: • The Copy Value from Item property on the foreign-key item in the detail block, which specifies the corresponding primary-key item in the master block • Relation-handling triggers, which fire during the Clear and Populate phases of block coordination • Relation-handling procedures, which are called from relation-handling triggers Note: The elements above are controlled through the relation object.
ly n O e s U I A O &
Web Design Tip You can reduce potential network traffic within Web-deployed forms by specifying deferred coordination. By using relation-handling built-ins, you can give users the run-time option of selecting either immediate or deferred coordination.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-7
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Blocks with REF Relations
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 8-8 Oracle iDS Forms: Build Internet Applications II
Coordinate Blocks Using REFs ......................................................................................................................................................
Coordinate Blocks Using REFs Many object-oriented languages implement master-detail relations by storing in the detail data an internal identifier to the master data. This internal identifier is known as a reference (REF). To support object-oriented programming, the Data Block Wizard enables you to base the relation on a REF rather than on a foreign key. To create a master-detail relation based on a REF, the detail block must contain the REF column. Create a master-detail form using REFs by doing the following in the Data Block Wizard: 1 Create the master block and choose the columns you wish to include as items in the block. Complete the Layout Wizard steps to finish creating and laying out the master block. 2 Create the detail block. When you choose columns, you must choose the REF column, because this value will be used to establish the relationship. You should not choose the lookup columns, because doing so causes the detail block to duplicate items that are already displayed in the master block. 3 On the Master-Detail page of the wizard, click the Create Relationship button. A dialog box appears listing all possible master blocks for the relationship. Select the appropriate master block and click OK and then Finish. 4 Complete the Layout Wizard steps to finish creating and laying out the detail block.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-9
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Characteristics of Relation-Handling Triggers • •
On-Clear-Details: Implements the Clear phase
•
On-Check-Delete-Master: Implements the restricted-delete rule
•
Effect of trigger failure
On-Populate-Details: Implements the Populate phase
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note Relation-handling triggers fire only if you have defined a corresponding relation.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 8-10 Oracle iDS Forms: Build Internet Applications II
Characteristics of Relation-Handling Triggers ......................................................................................................................................................
Characteristics of Relation-Handling Triggers Forms automatically creates and maintains relation-handling triggers to implement block coordination and restricted-delete foreign-key rules. Trigger On-Clear-Details
On-Populate-Details
On-Check-Delete-Master
Description Fires when a coordination-causing event occurs in a master block, before Forms navigates to the new master record. This trigger implements the Clear phase and is defined at the form level. If it fails, the coordinationcausing event is aborted. Fires when a coordination-causing event occurs in a master block, after Forms has navigated to the new master record. However, this trigger fires only if an On-ClearDetails trigger is also defined. This trigger implements the Populate phase and is defined for each master block. If it fails, it can cause the wrong detail records to be displayed for the current master record. Fires when you attempt to delete the current master record, before Forms deletes the record. If it fails, the record deletion is aborted.
Note: If you specify a cascade-delete foreign-key rule for a relation, Form Builder uses a Pre-Delete trigger to implement this rule. However, this is a commit trigger, not a relation-handling trigger, and can also be used outside the context of relations.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-11
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Principles of Relation-Handling Code
Three relation-handling procedures:
• • •
CLEAR_ALL_MASTER_DETAILS QUERY_MASTER_DETAILS CHECK_PACKAGE_FAILURE
Adding your own code to relation-handling triggers:
• •
Forms adds comments around code. You add your own code before or after these comments.
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 8-12 Oracle iDS Forms: Build Internet Applications II
Principles of Relation-Handling Code ......................................................................................................................................................
Principles of Relation-Handling Code Forms automatically creates and maintains the PL/SQL code that is executed in the relation-handling triggers. You can add your own code to these triggers. Three Relation-Handling Procedures Procedure CLEAR_ALL_MASTER_DETAILS QUERY_MASTER_DETAILS CHECK_PACKAGE_FAILURE
Called From On-Clear-Details trigger defined on the form level On-Populate-Details trigger defined for each master block On-Populate-Details trigger and the previous procedures
Note: The CLEAR_ALL_MASTER_DETAILS procedure gives you an example of how to walk recursively through a hierarchical tree of blocks. Adding Your Own Code to Relation-Handling Triggers Forms adds comments around the PL/SQL code that it generates for relation handling, for example: --- Begin default relation program section -BEGIN CLEAR_ALL_MASTER_DETAILS; END; --- End default relation program section --
ly n O e s U I A O &
You can add PL/SQL code to relation-handling triggers before the “Begin default relation program section” comment or after the “End default relation program section” comment. Note: Forms will not delete a relation-handling trigger to which you have properly added PL/SQL code.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-13
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Obtaining Relation-Handling Information
System variables for relation handling:
• •
SYSTEM.MASTER_BLOCK SYSTEM.COORDINATION_OPERATION
Built-ins for relation handling:
• • •
GET_FORM_PROPERTY GET/SET_BLOCK_PROPERTY GET/SET _RELATION_PROPERTY
Copyright Oracle Corporation, 2001. All rights reserved.
®
Technical Note You can use these system variables in the On-Clear-Details trigger only. Assign their values to global variables to broaden the scope.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 8-14 Oracle iDS Forms: Build Internet Applications II
Obtaining Relation-Handling Information ......................................................................................................................................................
Obtaining Relation-Handling Information You can use system variables and built-ins to obtain more information about block coordination and relation properties. This is useful if you want to modify the default relation-handling triggers. System Variables for Relation Handling Name SYSTEM.MASTER_BLOCK SYSTEM.COORDINATION_OPERATION
Description Contains the name of the master block that drives the current block coordination Contains the name of a block coordination-causing event that occurred on the driving master block (Value examples of this system variable include NEXT_RECORD, SCROLL_DOWN, MOUSE, DELETE_RECORD, and EXECUTE_QUERY.)
Built-ins for Relation Handling Name GET_FORM_PROPERTY GET_BLOCK_PROPERTY
GET_RELATION_PROPERTY
l a n r e t n I e l c a r O
Properties Concerning Relations FIRST_BLOCK, LAST_BLOCK COORDINATION_STATUS(*), NEXTBLOCK, PREVIOUSBLOCK, FIRST_DETAIL_RELATION, FIRST_MASTER_RELATION AUTOQUERY(*), DEFERRED_COORDINATION(*), MASTER_DELETES(*), PREVENT_MASTERLESS_OPERATION(*), DETAIL_NAME, MASTER_NAME, NEXT_DETAIL_RELATION, NEXT_MASTER_RELATION
ly n O e s U I A O &
(*): You can also set those properties using the Set-Relation-Property builtin.
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-15
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Implementing a Coordination-Type Toggle Define a procedure that toggles between immediate and deferred coordination
•
Use GET_BLOCK_PROPERTY to obtain relation name.
•
Use GET_RELATION_PROPERTY to obtain current coordination type.
•
Use SET_RELATION_PROPERTY to switch to other coordination type.
Copyright Oracle Corporation, 2001. All rights reserved.
®
Implementing a Coordination-Type Toggle Call this procedure from:
• •
When-Checkbox-Changed trigger Menu item of type Check
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 8-16 Oracle iDS Forms: Build Internet Applications II
Implementing a Coordination-Type Toggle ......................................................................................................................................................
Implementing a Coordination-Type Toggle You can use relation-handling built-ins to offer users the choice between immediate and deferred coordination. You can use this example procedure in a simple master-detail form and can serve as a starting point for more complex situations; for example, you can call this procedure from a When-Checkbox-Changed trigger on a check box that represents the coordination type, or from a menu item of type Check. PROCEDURE toggle_query_sync (p_master_block in VARCHAR2) IS v_rel_name VARCHAR2(30); v_rel_id RELATION; BEGIN v_rel_name := GET_BLOCK_PROPERTY(p_master_block, first_master_relation); IF v_rel_name IS NOT NULL THEN v_rel_id := FIND_RELATION(v_rel_name); IF GET_RELATION_PROPERTY(v_rel_id, deferred_coordination) = ’FALSE’ THEN SET_RELATION_PROPERTY(v_rel_id,deferred_coordination, property_true); SET_RELATION_PROPERTY(v_rel_id,autoquery,property_true); MESSAGE(’Query-synchronization mode: deferred.’); ELSE SET_RELATION_PROPERTY(v_rel_id,deferred_coordination, property_false); MESSAGE(’Query-synchronization mode: immediate.’); END IF; END IF; END toggle_query_sync;
.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-17
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Forcing a Commit Per Master
Define a procedure that:
•
Updates the commit status by performing validation
• •
Checks the commit status of the master record Raises FORM_TRIGGER_FAILURE in case of changes
Copyright Oracle Corporation, 2001. All rights reserved.
®
Forcing a Commit Per Master
Call the procedure:
• •
In the On-Clear-Details trigger Before the “Begin default relation program section” comment
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 8-18 Oracle iDS Forms: Build Internet Applications II
Forcing a Commit Per Master ......................................................................................................................................................
Forcing a Commit Per Master In some cases, you must commit changes in master-detail forms before a change of master record takes place, for example, when checking databaselevel constraints, such as a mandatory relationship. You must call the procedure below from the On-Clear-Details trigger before the “Begin default relation program section” comment. Note that if the OnClear-Details trigger fails, the change of master record is aborted. PROCEDURE check_master_change IS v_master_record NUMBER; BEGIN -- Force update of record status. VALIDATE(record_scope); IF FORM_SUCCESS THEN -- Check if master record has been modified. v_master_record := GET_BLOCK_PROPERTY(NAME_IN(’system.master_block’), current_record); IF GET_RECORD_PROPERTY(v_master_record, NAME_IN(’system.master_block’),status) IN (’INSERT’, ’CHANGED’) THEN MESSAGE(’You must commit first before you go to another master record.’); RAISE form_trigger_failure; END IF; ELSE -- Validation error. RAISE form_trigger_failure; END IF; END check_master_change;
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-19
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Summary
In this lesson, you should have learned how to:
• •
Define Relation coordination properties Manage data block coordination – Coordination-causing events change the master record – Clear and populate
Copyright Oracle Corporation, 2001. All rights reserved.
®
Summary •
Obtain relation-handling information – Identify characteristics of relation-handling triggers
ly n O e s U I A O &
– Identify characteristics of relation-handling procedures
•
Coordinate data blocks with REF Elements
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 8-20 Oracle iDS Forms: Build Internet Applications II
Summary ......................................................................................................................................................
Summary Creating Relations • Implicitly, when you create a master-detail form module • Explicitly, by creating the relation after the blocks have been created Block Coordination • Coordination-causing events cause a change of the master record. • The two block-coordination phases are the Clear and Populate phases. • Base coordination of blocks on REF values. Elements Involved in the Implementation of Block Coordination • The Copy Value from Item property • Relation-handling triggers and procedures Characteristics of Relation-Handling Triggers • On-Clear-Details implements the Clear phase. • On-Populate-Details implements the Populate phase. • On-Check-Delete-Master implements restricted-delete rules. Principles of Relation-Handling Code • The three relation-handling procedures are CLEAR_ALL_MASTER_DETAILS, QUERY_MASTER_DETAILS, and CHECK_PACKAGE_FAILURE. • Add your own code to relation-handling triggers before or after comments generated by Forms.
ly n O e s U I A O &
Obtaining Relation-Handling Information • There are two system variables for relation handling. • You can use built-ins for relation handling to get relation names and to get or set relation properties.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-21
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Practice 8 Overview
This practice covers the following topics:
• •
Examining and changing relation properties
•
Synchronize coordination-type toggle at form startup
Implementing a coordination-type toggle for a master-detail form
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 8-22 Oracle iDS Forms: Build Internet Applications II
Practice Overview: Lesson 8 ......................................................................................................................................................
Practice Overview: Lesson 8 This practice guides you through choosing the appropriate user-initiated and forms event triggers to implement the desired data block relation functionality. Practice Contents • Examining and changing relation properties • Using check boxes to implement a coordination-type toggle for a masterdetail form. - The first check box should enable a user to toggle between immediate coordination and deferred coordination. - The second check box should enable a user to toggle between auto query and no auto query in the detail block. • Synchronizing the coordination-type toggle at form startup.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-23
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
Practice 8 1 Open your ORDERS form and examine the properties of the relation
called S_ORD_S_ITEM. a Note the deletion and coordination property values. b Run the ORDERS form and test the way deletes are handled. 2 Implement a query coordination-type toggle. a Add two check boxes to the control block with the following properties: Property
Check Box 1
Check Box 2
Name
IMMEDIATE
AUTO_QUERY
Enabled
Yes
No
Label
Immediate
Auto Query
Value When Checked
Y
Y
Value When Unchecked
N
N
Check Box Mapping of Other Value
CHECKED
UNCHECKED
Keyboard Navigable
No
No
Mouse Navigate
No
No
Data Type
CHAR
CHAR
Initial Value
Y
DataBase Item
No
Canvas
TOOLBAR
ly n O e s U I A O & Y
No
TOOLBAR
Use the Layout Editor to position the check boxes appropriately in the Toolbar canvas. c Make sure that the first check box enables a user to toggle between immediate coordination and deferred coordination. You can import the code from the pr8_1.txt file. d Make sure that the second check box enables a user to toggle between automatic query and no automatic query for the detail block. This check box should be disabled if the other check box indicates immediate coordination. You can import the code from the pr8_2.txt file. e Save, compile, and test your form. b
l a n r e t n I e l c a r O
...................................................................................................................................................... 8-24 Oracle iDS Forms: Build Internet Applications II
Practice 8 ......................................................................................................................................................
If you have time 3 Synchronize the check boxes at form startup. a Open your ORDERS form module b Create a procedure called SYNCHRONIZE_CHECKBOX. This procedure synchronizes the IMMEDIATE and AUTO_QUERY check boxes with the current default value. You can import the code from the pr8_3.txt file. c Call this procedure from the When-New-Form-Instance trigger. d Save, compile, and test your module.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 8-25
Lesson 8: Controlling Data Block Relationships ......................................................................................................................................................
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... 8-26 Oracle iDS Forms: Build Internet Applications II
................................
Building Multiple Form Applications
l a n r e t n I e l c a r O
ly n O e s U I A O &
Lesson 9: Building Multiple Form Applications ......................................................................................................................................................
Objectives
After completing this lesson, you should be able to do the following:
•
Describe the different ways of invoking additional forms
• •
Open, call, and close forms Navigate between Web-deployed form modules
Copyright Oracle Corporation, 2001. All rights reserved.
®
Objectives
After completing this lesson, you should be able to do the following:
• •
Control opened forms and called forms
•
Choose the most appropriate method for invoking forms
•
Pass form parameters
Manage transaction processing for opened forms and called forms
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 9-2 Oracle iDS Forms: Build Internet Applications II
Introduction ......................................................................................................................................................
Introduction Overview You have already seen that Oracle Forms Developer applications frequently consist of more than one form. This lesson revisits the topic of multiple form applications and takes a deeper look into the ways in which one form module can invoke another and the effects this has on transaction processing. Objectives After completing this lesson, you should be able to do the following: • Describe the various ways of invoking additional form modules • Open, call, and close form modules • Navigate between Web-deployed form modules • Control open form modules and called form modules • Manage transaction processing for open and called form modules • Choose the most appropriate method for invoking form modules • Pass form parameters
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 9-3
Lesson 9: Building Multiple Form Applications ......................................................................................................................................................
OPEN_FORM to Invoke Additional Forms • •
Modeless Different transaction scopes
A
B
OPEN_FORM(’form_name’, OPEN_FORM(’form_name’, activate_mode, activate_mode, session_mode, session_mode, data_mode, data_mode, paramlist); paramlist);
Copyright Oracle Corporation, 2001. All rights reserved.
®
Characteristics of OPEN_FORM • • • • •
Restricted Not valid in Enter Query mode No savepoint issued
ly n O e s U I A O &
Modeless with respect to other opened forms
Session run time option: FORMS60_SESSION
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 9-4 Oracle iDS Forms: Build Internet Applications II
OPEN_FORM to Invoke Additional Forms ......................................................................................................................................................
OPEN_FORM to Invoke Additional Forms This built-in procedure opens another form in a modeless fashion; that is, a user can freely switch between open forms. You can open a form within the same transaction scope or within a new transaction scope. Syntax OPEN_FORM(’form_name’, activate_mode, session_mode, data_mode, paramlist);
Parameter
Description
form_name
The file holding the executable module
activate_mode
Either ACTIVATE (the default) or NO_ACTIVATE
session_mode
Either NO_SESSION (the default) or SESSION
data_mode
Either NO_SHARE_LIBRARY_DATA (the default) or SHARE_LIBRARY_DATA
paramlist
Either the name (in quotes) or internal ID of a parameter list (This argument is optional.)
Characteristics of OPEN_FORM • Is a restricted procedure • Causes opened form to be modeless • Can start a new database session
ly n O e s U I A O &
Using Data Mode to Share PL/SQL Variable Data You can use the data mode parameter to share PL/SQL variable data between forms. Create a package that contains the PL/SQL variables to be shared, and place the package in a library. Attach the library to all the forms that are to share the data. In the OPEN_FORM command, set the data_mode parameter to SHARE_LIBRARY_CODE. Any changes made by one form are visible to the other forms. This method of sharing data between forms is preferable to global variables because the PL/SQL variables benefit from PL/SQL’s strong typing and because PL/ SQL variables are stored and accessed more efficiently than global variables.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 9-5
Lesson 9: Building Multiple Form Applications ......................................................................................................................................................
Closing Forms •
CLOSE_FORM: – form_name – form_id
•
Characteristics of CLOSE_FORM: – Restricted – Not valid in Enter-Query mode – CLOSE_FORM or EXIT_FORM – Cannot close a form that called another form
Copyright Oracle Corporation, 2001. All rights reserved.
l a n r e t n I e l c a r O
®
ly n O e s U I A O &
...................................................................................................................................................... 9-6 Oracle iDS Forms: Build Internet Applications II
Closing Forms ......................................................................................................................................................
Closing Forms Syntax CLOSE_FORM(form_name); CLOSE_FORM(form_id); Parameter
Description
form_name
The module name of the form (not the .fmx filename)
form_id
The internal form module ID of the form (of type Form Module)
Characteristics of the CLOSE_FORM Procedure • CLOSE_FORM is a restricted procedure that is not valid in Enter Query mode. • When the specified form is the current form, CLOSE_FORM is equivalent to EXIT_FORM. • You cannot close a form that has called another form with CALL_FORM. Web Design Tip The Oracle Forms Developer application will continue if you attempt to exit your Web-deployed form application by closing the browser window, while other browser windows are still open. It will not terminate until the browser is also closed down. It is recommended that users are always able to close their applications either with the CLOSE_FORM or the EXIT_FORM commands. Applications that are not terminated will continue until timed out by the Oracle Forms Server.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 9-7
Lesson 9: Building Multiple Form Applications ......................................................................................................................................................
Navigating Between Forms
Built-ins for navigation between forms:
• • •
NEXT_FORM PREVIOUS_FORM GO_FORM
Copyright Oracle Corporation, 2001. All rights reserved.
®
Navigating Between Forms
Navigation and validation aspects:
• •
Each open form has a current item.
•
No triggers fire when navigating between forms, except the When-WindowActivated/Deactivated and When-Form-Navigate triggers.
•
Click the noncurrent item in the other form.
There is no validation when navigating between forms.
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 9-8 Oracle iDS Forms: Build Internet Applications II
Navigating Between Forms ......................................................................................................................................................
Navigating Between Forms You can programmatically navigate between multiple forms that have been opened with the OPEN_FORM built-in, just as you can navigate between blocks within one form. Built-ins for Navigation Between Forms Built-in NEXT_FORM
PREVIOUS_FORM
GO_FORM
Description Navigates to the open form with the next highest sequence number (Forms are placed in sequence in the order that they were invoked at run time.) If there is no form with a higher sequence number, the built-in navigates to the form with the lowest sequence number. Navigates to the open form with the next lowest sequence number (If there is no form with a lower sequence number, this built-in navigates to the form with the highest sequence number.) Navigates to the specified form (You can use the form-module name or the form-module ID as the form specification.)
Navigation and Validation Aspects of Inter-form Navigation • In a multiple-form application, each open form has one item that is the current item for that form. • When you are navigating between open forms, no validation occurs in the starting form. When you return to the starting form and attempt to navigate within that form, normal validation is enforced. • When you are navigating between (current items of) open forms, no triggers fire. The only exceptions are the When-Window-Activated, When-Window-Deactivated, and When-Form-Navigate triggers. Even the navigational triggers do not fire when you are navigating between open forms. • The triggers that typically fire when you navigate from the current item to the target item will fire when you click a noncurrent item of an open form. When this happens, navigational triggers also fire and validation occurs as required.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 9-9
Lesson 9: Building Multiple Form Applications ......................................................................................................................................................
Opening Forms Within the Same Session •
Commit processing in all forms within the same session, in a certain order
•
If error occurs, then focus set to initiating form
•
Messages per open form within the same session
•
CLEAR_FORM usually causes a ROLLBACK statement
Copyright Oracle Corporation, 2001. All rights reserved.
®
Opening Forms in Different Sessions
Connection Runform
Server
A
B
C
l a n r e t n I e l c a r O Session
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 9-10 Oracle iDS Forms: Build Internet Applications II
Transaction Processing for Opened Forms ......................................................................................................................................................
Transaction Processing for Opened Forms Opening Forms Within the Same Session At run time, Form Builder automatically establishes a single connection to the Oracle server. By default, one database session is created for this connection. When you open forms within the same session, consider these issues: • If you issue a commit, all forms will be processed in the order in which they were opened, starting with the current form. • If an error occurs during commit processing, Form Builder sets the input focus to the form that initiated the commit. • Commit processing usually causes messages to occur for every open form within the same session. Because Form Builder maintains a message line per open form, a user may have to acknowledge messages from noncurrent open forms. This could be confusing. • If you issue a CLEAR_FORM command, Form Builder will usually issue a ROLLBACK statement, which rolls back all the changes in the database and releases all locks. However, noncurrent open forms are not cleared. Opening Forms in Different Sessions The multiple-session feature of the Oracle server enables a single client to establish multiple database sessions within a single connection. All Oracle server transaction management and read-consistency features are implemented at the session level. Therefore, commit processing, record locking, and read-consistency behavior for two forms in different sessions is the same as it would be for two independent forms with separate connections. • You can turn the Session option on for all Runtime invocations by setting the FORMS60_SESSION environment variable to True. • Forms Runtime must be running with the Session option turned on when you execute OPEN_FORM with the SESSION_MODE parameter set to SESSION.
l a n r e t n I e l c a r O
ly n O e s U I A O &
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 9-11
Lesson 9: Building Multiple Form Applications ......................................................................................................................................................
CALL_FORM to Invoke Additional Forms • •
Modal Returns to calling form
A
B
CALL_FORM(‘form_name’, CALL_FORM(‘form_name’, display, display, switch_menu, switch_menu, query_mode, query_mode, data_mode, data_mode, paramlist); paramlist); Copyright Oracle Corporation, 2001. All rights reserved.
®
Characteristics of CALL_FORM • • • • • •
Unrestricted
•
Exiting a called form
Valid in Enter Query mode Savepoint issued Modal with respect to calling form
ly n O e s U I A O &
Does not cause navigation and validation Forms called from query-only form are always query-only
l a n r e t n I e l c a r O
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 9-12 Oracle iDS Forms: Build Internet Applications II
CALL_FORM to Invoke Additional Forms ......................................................................................................................................................
CALL_FORM to Invoke Additional Forms This built-in procedure calls another form in a modal fashion with respect to the calling form; that is, you cannot work in the calling form. When the called form is exited, Form Builder returns to the calling form. Syntax CALL_FORM(’form_name’, display, switch_menu, query_mode, data_mode, paramlist); Parameter
Description
form_name
The file holding the executable form module
display
Either HIDE (the default) or NO_HIDE (This defines whether the calling form should be hidden from view while the called form is running.)
switch_menu
Either NO_REPLACE (the default) or DO_REPLACE (This defines whether the current menu module should be replaced by the default menu of the called form.)
query_mode
Either NO_QUERY_ONLY (the default) or QUERY_ONLY (This defines whether the called form should run in Query Only mode.)
data_mode
Either NO_SHARE_LIBRARY_DATA (the default) or SHARE_LIBRARY_DATA
paramlist
Either the name (in quotes) or internal ID of a parameter list (This argument is optional.)
ly n O e s U I A O &
Characteristics of CALL_FORM • Is valid in Enter Query mode • Causes Forms to issue a savepoint • Causes called form to be modal • Does not cause navigation or validation in the initial form • Can call a form in Query Only mode • Propagates query-only parameter through all subsequent called forms • Returns control to the calling form and resumes processing of the PL/SQL code at the statement immediately following the calling statement (This occurs when Forms exits the called form.)
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 9-13
Lesson 9: Building Multiple Form Applications ......................................................................................................................................................
Save Not Allowed in Post-Only Mode Form
A calling form has unapplied changes. Save not allowed.
Copyright Oracle Corporation, 2001. All rights reserved.
®
Transaction Processing for Called Forms •
Characteristics of Post-Only mode: – Commit not allowed, only a post – Full rollback not allowed, only a rollback to savepoint
• •
Rollback behavior of called forms Call savepoints and post savepoints
l a n r e t n I e l c a r O
ly n O e s U I A O &
Copyright Oracle Corporation, 2001. All rights reserved.
®
...................................................................................................................................................... 9-14 Oracle iDS Forms: Build Internet Applications II
Transaction Processing for Called Forms ......................................................................................................................................................
Transaction Processing for Called Forms If you call forms, you need to understand the commit and rollback processing between the forms. What Is Post-Only Mode? When a calling form has pending updates or deletes that have not been explicitly posted or committed, Form Builder runs the called form in Post-Only mode. Additionally, any form called from a form running in Post-Only mode is also in Post-Only mode. In Post-Only mode, you can submit DML statements to the database, but you cannot commit the changes. You can only commit the changes after you exit the form that is running in Post-Only mode. Characteristics of Post-Only Mode If a form runs in Post-Only mode, Forms does not allow certain commit processing operations to prevent losing locks in the calling form. • A commit is not allowed, only a post. In other words, the changes are written to the database, but a commit statement is not issued. An error message appears on the status line: “A calling form has unapplied changes. Save not allowed.” If a user makes changes in the called form and then exits from the form, Forms usually asks if the user wants to apply (post), rather than Save (commit), the changes that were made. • A full rollback is not allowed, only a rollback to savepoint. Rollback Behavior of Called Forms If a user exits from a called form, Form Builder issues a rollback to the call savepoint that was set when the form was called. This means that all changes posted in the called form are rolled back upon exit from the called form. This is because of the EXIT_FORM built-in default arguments:
ly n O e s U I A O &
EXIT_FORM(ask_commit, to_savepoint);
Do not confuse call savepoints, which are set when a form is called or started, with post savepoints, which are set at the start of a post.
l a n r e t n I e l c a r O
...................................................................................................................................................... Oracle iDS Forms: Build Internet Applications II 9-15
Lesson 9: Building Multiple Form Applications ......................................................................................................................................................
Transaction Processing for Called Forms •
Examples of adjusting default transaction processing:
•
Key-Commit on form
IF IF