Oracle Reports Reference Manual 2.5

��

��

Reports ReferenceManualRelease 2.5Part No. A32489–1

Oracle Reports� Reference Manual, Release 2.5Part No. A32489–1, April 1995Copyright � Oracle Corporation 1984, 1988, 1995All rights reserved. Printed in the U.S.A.Contributing Author: Frank RovittoContributors: Per Brondum, Alex Hsieh, Yueh–Hong Lin, Karen Denchfield–Masterson, Ashok Natesan, Boris Protasov, Ingrid Snedecor, Gene Sohn, AtulSuklikar, Lori Ann White, Simon Wong

This software was not developed for use in any nuclear, aviation, masstransit, medical, or other inherently dangerous applications. It is thecustomer’s responsibility to take all appropriate measures to ensure the safeuse of such applications if the programs are used for such purposes.

This software/documentation contains proprietary information of OracleCorporation; it is provided under a license agreement containing restrictions onuse and disclosure and is also protected by copyright law. Reverse engineeringof the software is prohibited.

If this software/documentation is delivered to a U.S. Government Agency ofthe Department of Defense, then it is delivered with Restricted Rights and thefollowing legend is applicable:

Restricted Rights Legend Use, duplication, or disclosure by the Government issubject to restrictions as set forth in subparagraph (c)(1)(ii) of DFARS252.227–7013, Rights in Technical Data and Computer Software (October 1988).

Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.

If this software/documentation is delivered to a U.S. Government Agency notwithin 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 youfind any problems in the documentation, please report them to us in writing.Oracle Corporation does not warrant that this document is error–free.

ORACLE, Pro*COBOL, Pro*FORTRAN, Pro*Pascal, Pro*PL/I, SQL*Connect,SQL*Net, SQL*Plus, and SQL*ReportWriter are registered trademarks of OracleCorporation.Developer/2000, ORACLE7, Oracle Book, Oracle Forms, Oracle Graphics,Oracle Help, Oracle*Mail, Oracle Reports, PL/SQL, and Pro*C are trademarksof Oracle Corporation.All other products or company names are used for identification purposes only,and may be trademarks of their respective owners.

T

iRead This First

Read This First

his book is one of six documents in the Oracle Reports Version 2.5documentation set. Before you use it, you should be familiar with thefollowing topics:

• audience

• Oracle Reports documentation and related information

• how to use this book

• how to contact Oracle about documentation and productcomments

ii Reports Reference ManualGUI Version

Audience

The information in this manual is intended for application developerswho want to create reports. Readers should have a workingknowledge of SQL, PL/SQL, and ORACLE server concepts.

Oracle Reports Documentation and Related Information

Oracle Reports has the capability to interact with a variety of products,such as the ORACLE server, various networking tools, and severalprogramming languages. Sometimes, knowledge of these otherproducts is necessary.

The following map is provided to help you determine any additionaldocumentation you may need.

Oracle ReportsDocumentation

Related Information

iiiRead This First

The following books are included in the Oracle Reports documentationset:

• Reports Documentation Set Version 2.5, Part No. A32486, is a collection of all Oracle Reports manuals.

• Reports Enhancements Version 2.5, Part No. A32487, containsinformation about features new to Oracle Reports Version 2.5.

• Building Reports Manual Version 2.5, Part No. A32488, contains a tutorial and a rich discussion ofOracle Reports concepts as well as many example reports.

• Reports Reference Manual Version 2.5, Part No. A32489, contains detailed reference information aboutall aspects of Oracle Reports. It is intended primarily to answerspecific questions that you might have about using OracleReports.

• Reports Messages and Codes Manual Version 2.5, Part No. A32490, contains all Oracle Reports messages withcause and action descriptions.

• Reports Runtime Manual Version 2.5, Part No. A32493, contains information for end users (i.e., thosewho only run reports). It contains a tutorial and referenceinformation about the Oracle Reports runtime executable.

• Reports Migration Manual Version 2.5, Part No. A32491, contains all information that you need toconvert SQL*ReportWriter Version 1.1 reports and printerdefinitions to Oracle Reports Version 2.5.

• The online help system consists of the Reports Reference Manual,Reports Messages and Codes Manual, and procedural informationin online format.

Each Oracle Reports manual is also shipped as an Oracle Bookdocument. For the names and locations of the document files, see yourDeveloper/2000 Installation Guide.

As an application designer using Oracle Reports Version 2.5, you mayneed to refer to some or all of the documents listed below. Please seethe document in question for information on its specific purpose andusage.

Major Sections of thisBook

iv Reports Reference ManualGUI Version

• Developer/2000 Installation Guide or System Release Bulletin. Thisdocument is different for each hardware/software platform.Ask your sales representative for the appropriate part number.

• ORACLE7 Server Documentation Set, Part No. 5030–70

• ORACLE7 Server Documentation Set V7.1, Part No. A12383

• Oracle Network Products Messages Manual, Part No. A16263

• MultiProtocol Interchange Administrator’s Guide, Part No. A10157

• PL/SQL User’s Guide and Reference, Version 1.0, Part No. 800–V1.0

• PL/SQL User’s Guide and Reference, Version 2.0, Part No. 800–20

• Programmer’s Guide to ORACLE Precompilers, Part No. A18820

• Pro*C Precompiler Supplement, Part No. A16084

• Pro*COBOL Precompiler Supplement, Part No. A16083

• Pro*FORTRAN Precompiler Supplement, Part No. A16086

• Pro*Pascal Precompiler Supplement, Part No. A16145

• Pro*PL/I Precompiler Supplement, Part No. A16146

• Understanding SQL*Net, Part No. A16029

• Oracle Network Manager Administrator’s Guide, Part No. A16264

How to Use this Book

This book provides comprehensive information about Oracle Reportspresented in concise modules.

Before you use this book, we recommend that you read the first threechapters of the Building Reports Manual.

The Reports Reference Manual consists of the following major sections, orparts:

Executables

Externals

Integration

Internals

Administration

Appendixes

PART I

PART II

PART III

PART IV

PART V

PART VI

NotationalConventions

vRead This First

You should be familiar with the notational conventions listed in thefollowing table.

Convention Explanation

File—>New—>Report Indicates a selection of submenu item Reportfrom the New submenu of the File menu.

Data/Selection:Repeat Indicates a selection of Repeat from the Data/Selection tab of a property sheet.

Font Change Indicates text to be entered exactly as shown.

UPPERCASE Indicates command, column, parameter, field,boilerplate, and anchor names.

Initial Caps Indicates table, menu, query, group, frame,and repeating frame names, as well as proper-ty sheet names.

Bold Indicates items within a menu, buttons, ortabs on a property sheet.

Italics Indicates options for Oracle Reports settings.

[ ] Indicates that the enclosed item is optional.Do not enter the brackets.

{ } Indicates that one, and only one, of the en-closed items must be entered. If the braces aresurrounded by brackets, then all of the en-closed items are optional. Do not enter thecurly braces.

| Is used to separate options within bracketsand braces. You must enter one, and onlyone, of the options separated by the verticalbar. Do not enter the vertical bars.

_ Indicates that the underlined text is the de-fault.

vi Reports Reference ManualGUI Version

Your Comments Are Welcome

We value and appreciate your comments as an Oracle user. As wewrite, revise, and evaluate our work, your opinions are the mostimportant input we receive. At the back of this manual is a Reader’sComment Form. We encourage you to use this form to tell us bothwhat you like and dislike about this (or other) Oracle manuals. If theform is gone, or you would like to contact us, please use the followingaddresses and phone numbers.

For documentation questions/comments, contact:

Oracle Reports Documentation Manager

Oracle Corporation

500 Oracle Parkway

Box 659412

Redwood Shores, California 94065–5028

(415) 506–7000

(415) 506–7200 (fax)

For product questions/comments, contact:

Oracle Reports Product Manager

Oracle Corporation

500 Oracle Parkway

Box 659412

Redwood Shores, California 94065–5028

(415) 506–7000

(415) 506–7200 (fax)

viiContents

Contents

PART I EXECUTABLES

Chapter 1 Executables 1 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable Overview 1 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable Names 1 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable Invocation 1 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help on Command Line Options 1 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . Executable Syntax Rules 1 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keyword Usage 1 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Login 1 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Explicit Login 1 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Automatic Login 1 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remote Login 1 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

R25CONV 1 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R25RUN 1 – 17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R25DES 1 – 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PART II EXTERNALS

Chapter 2 Defaulting 2 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Model Defaulting 2 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Layout Defaulting 2 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Object Defaulting 2 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Defaulting For Each Layout Style 2 – 6. . . . . . . . . . . . . . . . .

viii Reports Reference ManualGUI Version

Tabular Reports 2 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mailing Label Reports 2 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form Reports 2 – 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form Letter Reports 2 – 17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Master/Detail Reports 2 – 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Matrix Reports 2 – 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Global Layout Defaulting Rules 2 – 41. . . . . . . . . . . . . . . . . . . . . . . . . . . . Rules About Summaries 2 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Implicit Anchoring Algorithm 2 – 43. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header/Body/Trailer Algorithm 2 – 43. . . . . . . . . . . . . . . . . . . . . . . Margin Algorithm 2 – 46. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Print Condition Algorithm 2 – 47. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header/Margin/Body/Trailer Algorithm 2 – 47. . . . . . . . . . . . . . .

Parameter Form Defaulting 2 – 47. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Defaulting 2 – 47. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 3 Menus 3 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 4 Report Properties 4 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Tab of Report Property Sheet 4 – 2. . . . . . . . . . . . . . . . . . . . . . . .

Direction 4 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical Page Size 4 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Body Pages 4 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Header Pages 4 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Trailer Pages 4 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Height 4 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Width 4 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Panel Print Order 4 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unit of Measurement 4 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Parameter Form Tab of Report Property Sheet 4 – 10. . . . . . . . . . . . . . . Form Height 4 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form Width 4 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Number of Pages 4 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Previewer Title 4 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Character Mode Tab of Report Property Sheet 4 – 11. . . . . . . . . . . . . . . Comment Tab of Report Property Sheet 4 – 15. . . . . . . . . . . . . . . . . . . . .

ixContents

Chapter 5 Data Model Editor 5 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose 5 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access 5 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components 5 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Painting Region 5 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolbar 5 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tool Palette 5 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Status Line 5 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Pop–Up Menu 5 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6 Data Model Properties 6 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Query Properties 6 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Query Property Sheet 6 – 2. . . . . . . . . . . . . . . . . . . . . . .

External Query 6 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List 6 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Rows 6 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name 6 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SELECT Statement 6 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tables/Columns 6 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Comment Tab of Query Property Sheet 6 – 8. . . . . . . . . . . . . . . . . . . . . Link Properties 6 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Child Column 6 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Child Query 6 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Condition 6 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parent Column 6 – 13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parent Group 6 – 13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL Clause 6 – 13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Group Properties 6 – 14. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Group Property Sheet 6 – 15. . . . . . . . . . . . . . . . . . . . . . .

Edit 6 – 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter 6 – 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name 6 – 16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Comment Tab of Group Property Sheet 6 – 17. . . . . . . . . . . . . . . . . . . . . Common Column Properties 6 – 17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Column Property Sheets 6 – 17. . . . . . . . . . . . . . . . . . . . .

Break Order 6 – 18. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Datatype 6 – 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format 6 – 21. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name 6 – 22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Read from File 6 – 23. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Value If Null 6 – 24. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Width 6 – 25. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

x Reports Reference ManualGUI Version

Comment Tab 6 – 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Column Properties 6 – 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary Column Properties 6 – 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Summary Column Property Sheet 6 – 28. . . . . . . . . . . .

Compute At 6 – 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function 6 – 32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Product Order 6 – 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reset At 6 – 39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source 6 – 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Formula Column Properties 6 – 41. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Formula Column Property Sheet 6 – 41. . . . . . . . . . . . . .

Formula 6 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Product Order 6 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Placeholder Column Properties 6 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Placeholder Column Property Sheet 6 – 44. . . . . . . . . . .

Edit 6 – 45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Properties 6 – 45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Parameter Property Sheet 6 – 47. . . . . . . . . . . . . . . . . . . .

Datatype 6 – 47. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Edit 6 – 48. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initial Value 6 – 48. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input Mask 6 – 48. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name 6 – 49. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Width 6 – 49. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Data/Selection Tab of Parameter Property Sheet 6 – 50. . . . . . . . . . . . . Add 6 – 51. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remove 6 – 51. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restrict List to Predetermined Values 6 – 51. . . . . . . . . . . . . . . . . . . SELECT Statement/Static Values 6 – 51. . . . . . . . . . . . . . . . . . . . . . . Hide First Column 6 – 52. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Value 6 – 52. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Comment Tab of Parameter Property Sheet 6 – 52. . . . . . . . . . . . . . . . . .

Chapter 7 Layout Editor 7 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose 7 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access 7 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components 7 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


Pop–Up Menu 7 – 18. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xiContents

Navigation 7 – 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Pages 7 – 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Margins 7 – 21. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 8 Layout Properties 8 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Layout Object Properties 8 – 2. . . . . . . . . . . . . . . . . . . . . . . . . General Layout Tab 8 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Format Trigger 8 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Horizontal Sizing 8 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keep with Anchoring Object 8 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . Name 8 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Break After 8 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Break Before 8 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Protect 8 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Print Condition Object 8 – 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Print Condition Type 8 – 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vertical Sizing 8 – 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Printer Codes Tab 8 – 26. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . After 8 – 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before 8 – 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Comment Tab 8 – 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Frame Properties 8 – 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Repeating Frame Properties 8 – 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Tab of Repeating Frame Property Sheet 8 – 29. . . . . . . . . . . . . . .

Column Mode 8 – 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Horizontal Spacing 8 – 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Records per Page 8 – 33. . . . . . . . . . . . . . . . . . . . . . . . . . . Minimum Widow Records 8 – 34. . . . . . . . . . . . . . . . . . . . . . . . . . . . Print Direction 8 – 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source 8 – 39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vertical Spacing 8 – 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Field Properties 8 – 41. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Tab of Field Property Sheet 8 – 41. . . . . . . . . . . . . . . . . . . . . . . . . .

Datatype 8 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format Mask 8 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hidden 8 – 49. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Minimum Widow Lines 8 – 51. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Numbering 8 – 52. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source 8 – 56. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Boilerplate Properties 8 – 59. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xii Reports Reference ManualGUI Version

Object Tab of Boilerplate Property Sheet 8 – 59. . . . . . . . . . . . . . . . . . . . . Format 8 – 60. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link File 8 – 60. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Minimum Widow Lines 8 – 62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Anchor Properties 8 – 62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . % (Child) 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . % (Parent) 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Edge (Child) 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Edge (Parent) 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Horizontally 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parent 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vertically 8 – 70. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Matrix Properties 8 – 70. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Matrix Property Sheet 8 – 70. . . . . . . . . . . . . . . . . . . . . . .

Cross Product Group 8 – 72. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Horizontal Frame 8 – 72. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vertical Frame 8 – 73. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Oracle Graphics Properties 8 – 73. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . O.G. Display Tab of Oracle Graphics Property Sheet 8 – 75. . . . . . . . . .

Display Name 8 – 76. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display Parameter 8 – 77. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List 8 – 77. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Column (for Display Parameter) 8 – 77. . . . . . . . . . . . . . . .

O.G. Query Tab of Oracle Graphics Property Sheet 8 – 78. . . . . . . . . . . Display Column 8 – 78. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display Query 8 – 79. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Column (for Display Column) 8 – 79. . . . . . . . . . . . . . . . . . . Source 8 – 80. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

User–Defined Button Properties 8 – 80. . . . . . . . . . . . . . . . . . . . . . . . . . . Object Tab of Button Property Sheet 8 – 81. . . . . . . . . . . . . . . . . . . . . . . .

Action 8 – 81. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Label 8 – 83. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Text String 8 – 83. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

OLE2 Object Properties 8 – 84. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 9 Parameter Form Editor 9 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Runtime Parameter Form 9 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Definition and Purpose 9 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access 9 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components 9 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Definition and Purpose 9 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xiiiContents

Access 9 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components 9 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


Pop–Up Menu 9 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Navigation 9 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Parameter Form Pages 9 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Pages 9 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 10 Parameter Form Properties 10 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Form Field Properties 10 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Parameter Form Field Property Sheet 10 – 2. . . . . . . . .

Datatype 10 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name 10 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source 10 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Comment Tab of Parameter Form Field Property Sheet 10 – 3. . . . . . . . Parameter Form Boilerplate Properties 10 – 4. . . . . . . . . . . . . . . . . . . . . General Tab of Parameter Form Boilerplate Property Sheet 10 – 4. . . .

Name 10 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Type 10 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Comment Tab of Parameter Form Boilerplate Property Sheet 10 – 5. .

Chapter 11 Previewer 11 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose 11 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access 11 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components 11 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Main Menu 11 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Title 11 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Region 11 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Navigation 11 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modification 11 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Title 11 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Region 11 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Character Mode Previewing 11 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Multimedia Objects 11 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Accessing Sound 11 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Video 11 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Images 11 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Printing from the Previewer 11 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xiv Reports Reference ManualGUI Version

Chapter 12 Object Navigator 12 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose 12 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access 12 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components 12 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Module List 12 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Find Field 12 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolbar 12 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Tree 12 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Pop–Up Menu 12 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Nodes 12 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Node Format 12 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Node Types 12 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hierarchical Views 12 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Navigation 12 – 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Navigation Within the Object Navigator 12 – 15. . . . . . . . . . . . . . . . . Navigation to Other Report Objects 12 – 17. . . . . . . . . . . . . . . . . . . . .

PART III INTEGRATION

Chapter 13 PL/SQL Interface 13 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL Overview 13 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Definition and Purpose 13 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Types and Usage of PL/SQL Constructs 13 – 2. . . . . . . . . . . . . . . . .

Value Constructs 13 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non–value Constructs 13 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Procedures 13 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Packages 13 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PL/SQL Exceptions 13 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User–Created Exceptions 13 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Packaged Exceptions 13 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exception Rules 13 – 14. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PL/SQL in Oracle Reports 13 – 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . External PL/SQL Libraries 13 – 16. . . . . . . . . . . . . . . . . . . . . . . . . . . . Attached Libraries 13 – 16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Triggers 13 – 17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Program Units 13 – 22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Group Filters 13 – 23. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formulas 13 – 25. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Triggers 13 – 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format Triggers 13 – 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Action Triggers 13 – 32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xvContents

Oracle Reports References in PL/SQL 13 – 32. . . . . . . . . . . . . . . . . . . . . . Bind References 13 – 32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Literal References 13 – 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PL/SQL Restrictions within Oracle Reports 13 – 33. . . . . . . . . . . . . . . . . Oracle Procedure Builder 13 – 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL Compilation 13 – 37. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Compiling Single Program Units 13 – 37. . . . . . . . . . . . . . . . . . . . . . . Batch–compiling Program Units 13 – 37. . . . . . . . . . . . . . . . . . . . . . . . Compiler Error Syntax 13 – 38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Oracle Procedure Builder Packages 13 – 39. . . . . . . . . . . . . . . . . . . . . . . . . The Developer/2000 PL/SQL Package: CDE_MM 13 – 40. . . . . . . . . . .

CDE_MM.GET_REF 13 – 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Oracle Reports PL/SQL Package: SRW 13 – 41. . . . . . . . . . . . . . . . .

SRW.BREAK 13 – 41. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.CONTEXT_FAILURE 13 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.DO_SQL 13 – 43. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.DO_SQL_FAILURE 13 – 46. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.GETERR_RUN 13 – 47. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.GET_PAGE_NUM 13 – 47. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.INTEGER_ERROR 13 – 48. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.MAXROW_INERR 13 – 48. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.MAXROW_UNSET 13 – 49. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.MESSAGE 13 – 50. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.NULL_ARGUMENTS 13 – 51. . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.PROGRAM_ABORT 13 – 52. . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.REFERENCE 13 – 53. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.RUN_REPORT 13 – 54. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.RUN_REPORT_BATCHNO 13 – 57. . . . . . . . . . . . . . . . . . . . . . . SRW.RUN_REPORT_FAILURE 13 – 57. . . . . . . . . . . . . . . . . . . . . . . . . SRW.SET_ATTR 13 – 58. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.SET_FIELD_CHAR 13 – 64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.SET_FIELD_DATE 13 – 64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.SET_FIELD_NUM 13 – 65. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.SET_MAXROW 13 – 66. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.TRACE_ADD_OPTION 13 – 67. . . . . . . . . . . . . . . . . . . . . . . . . . SRW.TRACE_END 13 – 67. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.TRACE_REM_OPTION 13 – 68. . . . . . . . . . . . . . . . . . . . . . . . . . SRW.TRACE_START 13 – 68. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.TRUNCATED_VALUE 13 – 70. . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.UNKNOWN_QUERY 13 – 70. . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.UNKNOWN_USER_EXIT 13 – 71. . . . . . . . . . . . . . . . . . . . . . . .

xvi Reports Reference ManualGUI Version

SRW.USER_EXIT 13 – 71. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.USER_EXIT20 13 – 73. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.USER_EXIT_ FAILURE 13 – 73. . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 14 User Exit Interface 14 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose 14 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Types of User Exits 14 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

ORACLE Precompiler User Exits 14 – 3. . . . . . . . . . . . . . . . . . . . . . OCI (ORACLE Call Interface) User Exits 14 – 3. . . . . . . . . . . . . . . . Non–ORACLE User Exits 14 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Steps to Build a User Exit 14 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing a User Exit 14 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Supported Functions 14 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax of a Passed User Exit Call 14 – 8. . . . . . . . . . . . . . . . . . . . . . . Raising Errors from the User Exit 14 – 9. . . . . . . . . . . . . . . . . . . . . . .

Implementing User Exits 14 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying the Sample Source File 14 – 9. . . . . . . . . . . . . . . . . . . . . .

Calling a User Exit 14 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing a User Exit Call 14 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checking for and Defining User Exit Errors in PL/SQL 14 – 13. . .

Packaged Oracle Reports User Exits 14 – 16. . . . . . . . . . . . . . . . . . . . . . . . Complete User Exit Example 14 – 21. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

User Exit Call 14 – 22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example User Exit 14 – 22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 15 Call Interface 15 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose 15 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Steps to Build a Procedure Call 15 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure Call Syntax 15 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure Call Error Checking 15 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure Call Rules 15 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example Programs that Call R25RUN (RWCRUN) 15 – 5. . . . . . . . . . .

Ada 15 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C 15 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COBOL 15 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FORTRAN 15 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pascal 15 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/l 15 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xviiContents

Chapter 16 Integrating with Other Products 16 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . ORACLE7 Server 16 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting to ORACLE and Other Databases 16 – 2. . . . . . . . . . . . . . .

SQL*Net 16 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OLE2 16 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Including OLE2 Objects 16 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activating OLE2 Objects 16 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PL/SQL 16 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Forms 16 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Graphics 16 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Referencing a Display 16 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executing a Display 16 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Passing Data 16 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Passing Parameters 16 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Oracle Mail 16 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Terminal 16 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Exit Interface 16 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Call Interface 16 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PART IV INTERNALS

Chapter 17 Performance and Tuning 17 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Monitoring 17 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Oracle Reports Tracing 17 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL TRACE 17 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Design Interface Suggestions 17 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Design Preferences 17 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Templates 17 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Data Model Suggestions 17 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Number of Queries 17 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL Statements Faster 17 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Reports Query Modifications 17 – 6. . . . . . . . . . . . . . . . . . . . Indexes 17 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.DO_SQL Statements 17 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . CDE_MM.GET_REF 17 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Rows and Group Filters 17 – 8. . . . . . . . . . . . . . . . . . . . . Unused Data Model Objects 17 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . Break Columns 17 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multiple Layouts, One Source 17 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . Matrices 17 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xviii Reports Reference ManualGUI Version

Layout Suggestions 17 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unused Frames 17 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transparent Objects 17 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sizing for Non–Graphical Objects 17 – 12. . . . . . . . . . . . . . . . . . . . . . Sizing for Graphical Objects 17 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . Reduce Image Resolution 17 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Word Wrapping 17 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formatting Attributes 17 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format Triggers 17 – 13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Total Number of Pages 17 – 13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Graphics Integration 17 – 13. . . . . . . . . . . . . . . . . . . . . . . . . . . .

PL/SQL 17 – 13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL Versus User Exits 17 – 14. . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL Versus SRW.DO_SQL for DML 17 – 14. . . . . . . . . . . . . . . . . Stored Procedures Versus Local PL/SQL 17 – 14. . . . . . . . . . . . . . . . Local PL/SQL Versus External PL/SQL Libraries 17 – 15. . . . . . . . . SRW.SET_ATTR 17 – 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Execution Suggestions 17 – 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable Arguments 17 – 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Previewer 17 – 17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

System Suggestions 17 – 18. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Storage 17 – 18. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operating–System Setup 17 – 19. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client/Server 17 – 19. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 18 Storage 18 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Reports File Storage 18 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preferences Files 18 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Important Files Shipped with Oracle Reports 18 – 5. . . . . . . . . . . . . . . .

Executable Files 18 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation Files 18 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Demo Files 18 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administration Files 18 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Definition and Driver Files 18 – 7. . . . . . . . . . . . . . . . . . . . . . Terminal Definition Files 18 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Font Mapping File 18 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Temporary Files 18 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Security and Restrictions 18 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File–Searching Method 18 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Printer and Terminal Definitions 18 – 10. . . . . . . . . . . . . . . . . . . . . . . Icon Files 18 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Oracle Reports Environment Variables 18 – 10. . . . . . . . . . . . . . . . . . . . . .

xixContents

Database Table Storage 18 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Reports Tables 18 – 12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Reports– specific Tables 18 – 13. . . . . . . . . . . . . . . . . . . . . . . . .

Integrated Oracle Product Tables and Other Objects 18 – 27. . . . . . . . . . Establishing Database Security and Restrictions 18 – 31. . . . . . . . . . . . .

Controlling Access to Oracle Reports 18 – 31. . . . . . . . . . . . . . . . . . . Controlling Access to Other Users’ Modules 18 – 31. . . . . . . . . . . . .

Database Storage Requirements 18 – 31. . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory and Disk Space Requirements 18 – 32. . . . . . . . . . . . . . . . . . . . .

PART V ADMINISTRATION

Chapter 19 Administration 19 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using SQL Scripts 19 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

SQL Script Descriptions 19 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing Tables 19 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Granting User Privileges 19 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Revoking User Privileges 19 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrading from Previous Versions of Oracle Reports 19 – 5. . . . . . . . . Dropping Version 1.1 Tables 19 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving Reports Between the File System and the Database and Vice–versa 19 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Modules 19 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Documenting Reports 19 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Which Files Are Being Used 19 – 6. . . . . . . . . . . . . . . . . . .

Files You Create 19 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files Created By Oracle Reports 19 – 7. . . . . . . . . . . . . . . . . . . . . . . .

PART VI APPENDIXES

Appendix A Environment and GUI Differences A – 1. . . . . . . . . . . . . . . . . . . . . . . . Environment and GUI Differences Overview A – 2. . . . . . . . . . . . . . . .

Environment Differences A – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GUI Differences A – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Designing Reports for Character Mode A – 3. . . . . . . . . . . . . . . . . . . . . Report Conversion Across GUIs A – 4. . . . . . . . . . . . . . . . . . . . . . . . . . .

xx Reports Reference ManualGUI Version

Appendix B Printer and Terminal Definitions B – 1. . . . . . . . . . . . . . . . . . . . . . . . . . Purpose of Printer Definitions B – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Packaged Printer Definitions B – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Descriptions B – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Location B – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating or Modifying Printer Definitions B – 3. . . . . . . . . . . . . . . . . . . Printer Definition File Syntax B – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Definition Rules B – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Definition Examples B – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing Printer Definitions B – 13. . . . . . . . . . . . . . . . . . . . . . . . . . . . Purpose of Terminal Resources B – 14. . . . . . . . . . . . . . . . . . . . . . . . . . . . Packaged Terminal Resource Files B – 14. . . . . . . . . . . . . . . . . . . . . . . . . . Creating or Modifying Terminal Resources B – 15. . . . . . . . . . . . . . . . . .

Modifying Key Bindings B – 17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying Terminal Definitions B – 19. . . . . . . . . . . . . . . . . . . . . . . .

Terminal Definition Rules B – 21. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing Terminal Resource Files B – 21. . . . . . . . . . . . . . . . . . . . . . . .

Appendix C National Language Support C – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose of NLS C – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying NLS_LANG, DEV_NLS_LANG, and USER_NLS_LANG C – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overriding NLS Defaults C – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using ALTER SESSION C – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Date and Number Formats C – 4. . . . . . . . . . . . . . . . . . . . . . . Using NLS Parameters/Functions in SQL Functions C – 5. . . . . . Using CONVERT to Convert Data C – 5. . . . . . . . . . . . . . . . . . . . . . Using NLSSORT to Sort Character Data C – 5. . . . . . . . . . . . . . . . .

Translating Reports C – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Definitions and NLS C – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bidirectional Support C – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix D Naming Conventions D – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Module Naming Conventions D – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Database Objects D – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files D – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Data Model Object Naming Conventions D – 2. . . . . . . . . . . . . . . . . . . . Layout Object Naming Conventions D – 3. . . . . . . . . . . . . . . . . . . . . . . . Parameter Form Object Naming Conventions D – 3. . . . . . . . . . . . . . . .

xxiContents

Appendix E SQL Topics E – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Tables and Columns Dialog Box E – 2. . . . . . . . . . . . . . . . . . Using Aliases E – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inserting Comments E – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reviewing SELECT Statement Errors E – 3. . . . . . . . . . . . . . . . . . . . . . . Referencing Columns and Parameters E – 3. . . . . . . . . . . . . . . . . . . . . .

Bind References E – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lexical References E – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using DML or DDL E – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix F Pattern and Color Palette F – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pattern Palette F – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Color Palettes F – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Default Color Palette F – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplemental Color Palette F – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Glossary

Index

xxii Reports Reference ManualGUI Version

P A R T

I Executables

C H A P T E R

1E

1 – 1Executables

Executables

xecutables are the different programs of Oracle Reports:

• executable overview – 1 – 2

• help on command line options – 1 – 3

• command line syntax rules – 1 – 4

• keyword arguments – 1 – 6

• database login – 1 – 7

• R25CONV syntax – 1 – 9

• R25RUN syntax – 1 – 17

• R25DES syntax – 1 – 35

1 – 2 Reports Reference ManualGUI Version

Executable Overview

The names and purposes of the four Oracle Reports executables arelisted below:

Converts your report definitions from one storageformat (i.e., database, .rdf file, .rep file, .rex file) toanother, or from one unit of measurement (i.e.,character, centimeter, inch, point) to another. Formore information on file formats, see “OracleReports File Storage” on page 18 – 2. If theconversion is run in interactive mode, the Convertdialog box will appear. If the conversion is run inbatch mode, the Convert dialog box will notappear.

Converts your SQL*ReportWriter Version 1.1reports and printer definition files to OracleReports. For more information on this executable,see the Reports Migration Manual.

Runs your report in either batch or interactivemode. If the report is run in interactive mode, theroot window from which you can run reportsappears. If the report is run in batch mode, thiswindow will not appear.

If you wish to enter values for runtime parameters,but you want to run a report in batch mode, eitherenter the parameters on the command line orcreate a command file.

Invokes the designer (that is, the root window andpainters in which you build and maintain reports).

R25CONV

R25MREP

R25RUN

R25DES

1 – 3Executables

Executable Names

Letters are appended to the executable names listed above to indicate ifthe GUI mode of the executable is something other than the native GUI.For example, ”a” indicates a GUI mode of Apple MacIntosh and ”m” aGUI mode of Motif. (No added letter means the executable’s GUImode is the native GUI.) In addition, an ”x” is used to indicate if userexits are linked to the executable.

For more information, see the Developer/2000 Installation Guide for youroperating system.

Executable Invocation

The Oracle Reports executables can be invoked in one of two ways:

• by command line

• by icon

Executable Arguments When you invoke an Oracle Reportsexecutable, you can enter executable arguments that govern how theexecutable behaves. If you invoke the executable via command line,you enter the executable arguments on the command line after theexecutable name.

If your operating system does not have a command line available (e.g.,Apple Macintosh or Windows) and you invoke the executable via icon,an intermediary dialog box may appear where you can enter values forthe executable arguments or you may need to use the Runtime Settingsor Runtime Parameters tab on the Tools Options dialog box(Tools—>Tools Options) for executable arguments. For moreinformation, see the Developer/2000 Installation Guide for your operatingsystem.

The syntax and executable arguments for R25CONV, R25RUN, andR25DES are described in the sections that follow.

Help on Command Line Options

If you are on a command line, you can view an executable’s commandline options by typing the executable’s name, then a space and aquestion mark, and then pressing Return. For example, r25conv ”?”.


Note: Some operating systems require quotes around thequestion mark. For more information, see the Developer/2000Installation Guide for your operating system. For example, toview the command line options for the R25DES executable inthe UNIX C shell, you need to enter r25des ”?”.

Executable Syntax Rules

When you enter an executable on the command line, it generally hasthe form shown below:

executable_name keyword1=value1 keyword2=value2 ...

If your operating system does not have a command line available (e.g.,Apple Macintosh or Windows) and you invoke the executable via icon,an intermediary dialog box may appear where you can enter values forthe executable arguments or you may need to use the Runtime Settingsor Runtime Parameters tab on the Tools Options dialog box(Tools—>Tools Options) for executable arguments. For moreinformation, see the Developer/2000 Installation Guide for your operatingsystem.

Each keyword=value is called an executable argument. Because it wouldbe cumbersome to enter the keywords each time, they may be omitted.For more information on keywords, see “Keyword Usage” on page1 – 6.

The following syntax rules apply to all Oracle Reports executables:

Rules:

1. No spaces should be placed before or after the equal sign of anargument.

2. Separate arguments with one or more spaces; do not use commasto separate arguments.

3. Values of arguments may be in single or double quotes. The effect of single or double quotes is operating system–specific. For moreinformation, see the Developer/2000 Installation Guide for youroperating system.

1 – 5Executables

4. The keyword= part of all arguments is not case sensitive. The valueportion of the SOURCE, DEST, CMDFILE, TERM, DESNAME,DESFORMAT, DNAME, and SNAME arguments may be casesensitive, depending on your operating system. The value portionof all other arguments is not case sensitive. For more information,see the Developer/2000 Installation Guide for your operating system.

5. Keywords may sometimes be omitted. For more information onkeywords, see “Keyword Usage” on page 1 – 6.

6. To give an argument an empty string as its value, you enterkeyword= or keyword=””. If you enter an empty string in this way,the Runtime Parameter Form will display an empty string for theargument instead of its Initial Value.

7. Full pathnames are supported for all file references (e.g.,desname=/revenues/q1/nwsales ). If you do not specify the fullpath, Oracle Reports will use its file path search order to find thefile. For more information about file path search order, see “FileSearching Method” on page 18 – 9.

Note: To help ensure the portability of your reports, you canuse the Oracle Reports–specific environment variableREPORTS25_PATH for referencing reports, external queries,external PL/SQL libraries, text files, graphics, etc.REPORTS25_PATH enables you to access files stored outside ofOracle Reports without hardcoding directory paths into yourreport.

For more information on these variables, see “File SearchingMethod” on page 18 – 9. For more information on how to set theseenvironment variables, see the Developer/2000 Installation Guide foryour operating system.

8. Values entered from the Runtime Parameter Form override thoseentered on the command line. For example, if you specifiedR25RUN on the command line with COPIES equal to 1, but, in theRuntime Parameter Form, specified COPIES equal to 2, then twocopies of the report would be generated.

Similarly, values entered on the command line override valuesspecified in command files. For example, suppose that you specifyR25RUN from the command line with COPIES equal to 1 andCMDFILE equal to RUNONE (a command file). In RUNONE,COPIES is set to 2 by a R25RUN command. Only one copy of thereport would be generated in this case.


You can specify values for DESTYPE, DESNAME, DESFORMAT,ORIENTATION, and COPIES in a number of different places inOracle Reports. The following list shows the order of precedencefor the places where you specify these values. The first item in thelist takes precedence over all others, the second takes precedenceover all but the first item, and so on:

• Print Job dialog box

• Runtime Parameter Form

• Runtime Parameters/Settings tab of Tools Options dialog box

• keywords on the command line

• values specified in the report definition

• Choose Printer dialog

Keyword Usage

The keyword= part of each argument is optional as long as thearguments are entered in the order specified by the syntax. If you skipone of the arguments, you must use keywords after the skippedargument.

If an executable has four arguments and you want to specify only thefirst, second, and fourth arguments, you can specify the first twowithout the keywords. The fourth would require a keyword, though,because you are not entering it in the order specified by the syntax.

Examples (Valid):

1. Below are examples of valid command line sequences:

r25des userid=scott/tiger paramform=no destype=mail desname=rmiller

r25des scott/tiger no destype=mail desname=rmiller

Notice that, in this example, after the keyword DESTYPE is used allsubsequent arguments use keywords, too. Once you have entereda keyword, the rest of the arguments on the command line mustalso use keywords.

Examples (Invalid):

2. Below are examples of invalid command line sequences:

r25des paramform=no scott/tiger destype=maildesname=rmiller

Explicit Login

USERID

Automatic Login

1 – 7Executables

The sequence above is invalid because scott/tiger has been typedout of order and without the USERID keyword.

r25des scott/tiger mail rmiller no

The sequence above is invalid because the value NO has beenentered out of order and without the PARAMFORM keyword.

Database Login

When invoking the R25CONV, R25RUN, and R25DES executables orusing the R25DES designer, you can connect to a database in thefollowing ways:

• explicit login – 1 – 7

• automatic login – 1 – 7

• remote login – 1 – 8

You explicitly login to the database by using the USERID keyword forR25CONV, R25RUN, and R25DES or by selecting File—>Connect inthe R25DES designer and R25RUN run–time engine. The USERIDkeyword is described below.

Is your ORACLE username and password with an optional SQL*Netaddress (not the SYSTEM account). If you omit your password, alogon screen is provided. For more information about the optionalSQL*Net address, see “Remote Login” on page 1 – 8. For moreinformation about automatic login, see “Automatic Login” on page1 – 7.

The logon definition must be in one of thefollowing forms and cannot exceed 512 bytes inlength:

username username/password

username@node username/password@node

The ORACLE automatic login feature allows you to connect to OracleReports without explicitly stating a username and password. You canuse the automatic login feature with all Oracle Reports’ executablesthat have the USERID keyword. For more information on how toemploy this feature, see the ORACLE7 Server Administrator’s Guide.

Options:

Remote Login

Syntax

Arguments


When you connect in this way, ORACLE uses a default logon (e.g.,OPS$) to associate your ORACLE username to your operating systemusername. To invoke an automatic login procedure, do one of thefollowing:

• Type r25conv / on the command line.

• Enter a slash (/ ) in the logon screen as your username.

• Omit your username/password on the command line and pressthe Return key twice when the logon form appears.

Note: When logging on in this way, you can access a remotelogin by typing @node after the slash.

For more information on default logons, see the ORACLE7 Server SQLLanguage Reference Manual.

Through SQL*Net, you can specify a remote database (i.e., one not onyour computer). When you use the remote login feature, the remotedatabase is transparent to you—Oracle Reports behaves the samewhether it is accessing a node across the country or accessing thedatabase on your computer.

@driver_name:node_name[:db_name]

Is the driver you want to use to access the remotedatabase (e.g., @t:, @d:). The default setting issystem dependent.

Is the remote network node that contains the targetdatabase (e.g., london).

Is the name of the database (e.g., :rds). Unless youspecify a database, you will log in to the defaultdatabase on the specified node.

For more information on SQL*Net, see the SQL*Net User’s Guide.

Examples:

1. To run the order_entry report on the default database of the londonnode, you might type the following:

r25run order_entry scott/tiger@D:london

2. To run the ORDER_ENTRY report on a specific database (rds) ofthe LONDON node, you might type the following:

r25run order_entry scott/tiger@D:london:rds

driver_name

node_name

db_name

Syntax:

Description:

1 – 9Executables

Rules:

1. To perform a remote connect, you must have an account on theremote computer node where the target database resides.

R25CONV

R25CONV enables you to convert one or more report definitions orPL/SQL libraries from one storage format to another.

r25conv [ [keyword=]value ] ...

where the following are valid keyword=value arguments:

[[USERID=]userid ]

[[STYPE=]{database |plldb|pldfile|pllfile|rdffile|rexfile} ]

[[SOURCE=]{sname|(sname1,sname2,...)} ]

[[DTYPE=]{database|plldb|pldfile|pllfile|rdffile|repfile|

rexfile } ]

[[DEST=]{dname|(dname1,dname2,...)|pathname} ]

[[CMDFILE=]cmdfile ]

[[LOGFILE=]logfile ]

[[OVERWRITE=]{yes|no |PROMPT} ]

[[BATCH=]{yes|no } ]

[[DUNIT=]{centimeter|character|inch|point} ]

[[PAGESIZE=]width x height

[[FORMSIZE=]width x height

Use the R25CONV executable to convert one or more report definitionsor PL/SQL libraries from one storage format to another. (Thisexecutable replaces the Version 1.1 executables DUMPREP, GENREP,and LOADREP.)

The following report conversions can be performed using R25CONV:

• convert a report stored in the database into a .rep, .rex, or .rdf file

• convert a report stored in a .rdf file into a .rep or .rex file, or adatabase report

• convert a report stored in a .rex file into a database report, .rdffile, or .rep file

USERID


The following PL/SQL library conversions can be performed usingR25CONV:

• convert a library stored in the database into a .pld or .pll file

• convert a library stored in a .pld file into a database library or a.pll file

• convert a library stored in a .pll file into a database library or a.pld file.

For more information on storage formats, see “Oracle Reports FileStorage” on page 18 – 2. For more information database storage, see“Database Table Storage” on page 18 – 12.

Note: You can also convert reports while in the designer byselecting File—>Administration—>Convert....

Rules:

1. In some cases, Convert will automatically compile the report’sPL/SQL as part of the conversion process. Provided that yourconversion Destination is not a .rex file, PL/SQL is automaticallycompiled under the following conditions:

• You try to create a .rep file using Convert. If there are compileerrors, an error message is displayed and the .rep file is notcreated.

• You use a .rex file as the Source report. If there are compileerrors, a warning is displayed, but the conversion continues.

• You use a report that was created on another platform as theSource report. If there are compile errors, a warning isdisplayed, but the conversion continues.

In all other situations, you must compile the report’s PL/SQL yourself(e.g., File—>Compile).

Note: To avoid compilation problems during conversion,compile the Source report’s PL/SQL using File—>Compilebefore you try to convert it.

2. Fonts are mapped when a report is opened by Oracle Reportsruntime or designer. Fonts are not mapped during the conversion.

Is your database login. For more information, see “Database Login” onpage 1 – 7.

STYPE

SOURCE

1 – 11Executables

Rules:

1. The USERID keyword is only needed if STYPE or DTYPE isdatabase.

Is the format of the report(s) or libraries to be converted.

database means that the source report(s) are storedin ORACLE.

plldb means that the source PL/SQL libraries arestored in the database.

pldfile means that the source PL/SQL libraries arestored in files in ASCII format.

pllfile means that the source PL/SQL libaries arestored in files containing source code and P–code.

rdffile means that the source report(s) are stored inone or more report definition files (files with anextension of .rdf).

rexfile means that the source report(s) are stored inone or more text files (files with an extension of.rex).

database

Is the report/library or list of reports/libraries to be converted.R25CONV requires that you specify a source report or library.

Any valid report/library name or filename (e.g.,qanda).

A list of valid report/library names or filenamesenclosed by parentheses with a comma separatingthe names (e.g., (qanda,test,dmast)).

Note: SQL wildcard characters (% and _) may be used forreports or libraries that are stored in the database. Forexample, R% would fetch all reports stored in the database thatbegin with R. All reports that match will be converted.

Rules:

1. A list of report/library names or filenames must be enclosed inparentheses with commas separating the names. For example:

(qanda,test,dmast) (qanda, test, dmast)

Options:

Default:

Options:

DTYPE


2. Wildcard characters are invalid for reports/libraries stored in files(i.e., with extensions of .rdf, .rep, .rex, .pld, .pll).

3. The argument(s) for this keyword may be operatingsystem–specific. For more information, see the Developer/2000Installation Guide for your operating system.

4. If you are converting reports/libraries stored in ORACLE and areusing system–owned Oracle Reports tables, you may listreports/libraries of other users, for example:

SOURCE=(sday.qanda,dsmith.test,dmast.sal)

5. If you are using user–owned Oracle Reports tables,reports/libraries from multiple users must be converted for eachuser individually.

6. You must have created the reports/libraries, or have been grantedaccess to the ones you did not create, in order to convert them. Ifno userid is prefixed to the report/library name, the userid isassumed to be the current user.

7. If you are converting from database to file and the databasereport/library name is too long to be a filename, Oracle Reportsprompts you to provide a filename of the correct length for youroperating system.

Is the format to which to convert the reports or libraries .

database means that the converted reports will bestored in ORACLE.

plldb means that the converted PL/SQL librarieswill be stored in the database.

pldfile means that the converted PL/SQL librarieswill be stored in files in ASCII format.

pllfile means that the converted PL/SQL libarieswill be stored in files containing source code andP–code.

rdffile means that the converted reports will bestored in one or more report definition files (fileswith an extension of .rdf).

repfile means that the converted reports will bestored in one or more binary runfiles (files with anextension of .rep).

Options:

DEST

1 – 13Executables

rexfile means that the converted reports will bestored in one or more text files (files with anextension of .rex).

rexfile

Rules:

1. When you try to create a .rep file using R25CONV, the sourcereport’s PL/SQL is automatically compiled. If there are compileerrors, an error message is displayed and the .rep file is not created.

To avoid this problem, make sure you compile the source report’sPL/SQL using File—>Compile before you try to create a .rep file.

Is the name(s) of the converted reports or libraries, if they are stored inthe database, or the names of the files.

Any valid report/library name or filename (e.g.,qanda).

A list of valid report/library names or filenamesenclosed by parentheses with a comma separatingthe names (e.g., (qanda,test,dmast)).

If the DEST keyword is not specified, R25CONVuses the following default names:

• If DTYPE is database or plldb, then DEST isSOURCE.

• If DTYPE is pldfile, then DEST is SOURCE withthe .pld extension.

• If DTYPE is pllfile, then DEST is SOURCE withthe .pll file extension.

• If DTYPE is rdffile, then DEST is SOURCE withthe .rdf extension.

• If DTYPE is repfile, the DEST is SOURCE withthe .rep extension.

• If DTYPE is rexfile, then DEST is expdat.rex.

Rules:

1. A list of report/library names or filenames must be enclosed inparentheses with commas separating the names. For example:

(qanda,test,dmast) (qanda, test, dmast)

Default:

Options:

Default:

CMDFILE

LOGFILE

OVERWRITE


2. If you have more destination names than there are source names,the extra destination names are ignored. If you have fewerdestination names than there are source names, default names willbe used after the destination names run out.


Is a file that contains arguments for the R25CONV command. Thisoption enables you to convert a report/library without having tospecify a large number of arguments each time you invoke R25CONV.

Any valid command file.

Rules:

1. A command file may reference another command file.

2. Command file syntax for R25CONV arguments is identical to thatused on the command line.

3. Values entered on the command line override values specified incommand files. For example, suppose that you specify R25RUNfrom the command line with COPIES equal to 1 and CMDFILEequal to RUNONE (a command file). In RUNONE, COPIES is setto 2. Only one copy of the report would be generated in this case.For more information, see “Command Line Syntax Rules” on page1 – 4.


Is the name of the file to which status and error output is sent.

Any valid filename.

dfltrep.log in the current directory.

Is whether to overwrite existing files or database objects with theconverted files or objects.

YES means automatically overwrite any existingfiles or database objects of the same name.

NO means not to convert reports if there areexisting files or database objects of the same nameand display a warning message.

Options:

Options:

Default:

Options:

BATCH

DUNIT

PAGESIZE

1 – 15Executables

PROMPT means to prompt you before overwritingany existing or database objects.

NO

Suppresses all terminal input and output, in order to convertreports/libraries without user intervention.

YES suppresses all terminal input and output.

NO allows special terminal input and output. TheConvert dialog box is displayed and, when youaccept the dialog box, the conversion is performed.

NO

Is the destination unit of measurement to which the report should beconverted. If specified, DUNIT must differ from the SOURCE report’sunit of measurement. If left blank, the SOURCE report’s unit ofmeasurement is used as the DEST report’s unit of measurement.

centimeter means that the converted reports willinitially use centimeters as the unit ofmeasurement.

character means that the converted reports willinitially use characters as the unit of measurement.

inch means that the converted reports will initiallyuse inches as the unit of measurement.

point means that the converted reports will initiallyuse points as the unit of measurement.

Blank

Is the size of a logical page for the converted reports in terms ofdestination unit of measurement (specified using the DUNIT keyword).

Any valid value in the unit of measurement and ofthe form width x height.

For bitmap, 8.5 x 11 inches. For character mode, 80x 66 characters. If the report was designed forcharacter mode and is being run or converted onbitmap, the following formula is used to determinepage size if none is specified: (default page size *character page size)/default character page size.For example, if the character page size is 80 x 20,the bit–mapped page size would be: (8.5 * 80)/80 x(11 * 20)/66 = 8.5 x 3.33.

Default:

Options:

Default:

Options:

Default:

Options:

Default:

FORMSIZE


Rules:

1. For non–character DUNITs, you can use a decimal to specifyfractions (e.g., 8.5 x 11).

Is the size of the Runtime Parameter Form for the converted report interms of destination unit of measurement (specified using the DUNITkeyword).

Any valid value in the unit of measurement and ofthe form width x height.

Rules:

1. For non–character DUNITs, you can use a decimal to specifyfractions (e.g., 8.5 x 11).

Options:

Syntax:

1 – 17Executables

R25RUN

R25RUN runs a report (i.e., .rdf or .rep file) interactively or in batch.

r25run [ [keyword=]value|(value1, value2, ...) ]


[ [MODULE|REPORT=]runfile ]

[ [USERID=]userid ]

[ [PARAMFORM=]{yes |no} ]

[ [CMDFILE=]cmdfile ]

[ [TERM=]termfile ]

[ [ARRAYSIZE=]n ]

[ [DESTYPE=]{screen|file|printer|preview|sysout|mail|}]

[ [DESNAME=]desname ]

[ [DESFORMAT=]desformat ]

[ [COPIES=]n ]

[ [CURRENCY=]currency_symbol ]

[ [THOUSANDS=]thousands_symbol ]

[ [DECIMAL=]decimal_symbol ]

[ [READONLY=]{yes|no } ]

[ [LOGFILE=]logfile ]

[ [BUFFERS=]n ]

[ [BATCH=]{yes|no } ]

[ [PAGESIZE=]width x height ]

[ [PROFILE=]profiler_file ]

[ [RUNDEBUG=]{yes|no } ]

[ [ONSUCCESS=]COMMIT|ROLLBACK|NOACTION]

[ [ONFAILURE=]COMMIT|ROLLBACK|NOACTION]

[ [KEYIN=]keyin_file

[ [KEYOUT=]keyout_file

[ [ERRFILE=]error_file

[ [LONGCHUNK=]n ]

[ [ORIENTATION=]DEFAULT |LANDSCAPE|PORTRAIT ]

[ [BACKGROUND=]{yes|no } ]

[ [MODE=]BITMAP|CHARACTER|DEFAULT ]

[ [PRINTJOB]{yes |no} ]

[ <param>=value ]

[ [TRACEFILE=]tracefile ]

[ [TRACEMODE=]{TRACE_APPEND|TRACE_REPLACE} ]

[ [TRACEOPTS=]{TRACE_ERR|TRACE_PRF|TRACE_APP|

TRACE_PLS|TRACE_SQL|TRACE_TMS|TRACE_ALL|(opt1, opt2, ...)} ]

[ [AUTOCOMMIT=]{yes|no } ]

[ [NONBLOCKSQL=]{yes |no}

Description:

MODULE/REPORT


Use the R25RUN executable to execute a report from the operatingsystem. With R25RUN, you can also execute a report in batch mode,that is, without user intervention. You must have created a runfilebefore you can execute the report (i.e., the file will have an extension of.rdf or .rep). For more information on creating a runfile, see “R25RUN”on page 1 – 9. For more information, see “Convert” on page iv.

Caution: R25RUN does not compile the PL/SQL in your report beforerunning it. In an .rep file, the PL/SQL is already compiled, but, in an.rdf file, it is only compiled if you have specifically compiled it. If anyPL/SQL is uncompiled when you run the report, you will get an errorand the report will not execute. Use File—>Compile... to compile allPL/SQL in an .rdf file beforehand.

There are two versions of R25RUN:

• The character–mode executable is for users who are runningreports from character–mode machines (e.g., VT220).

• The GUI executable is for users who are running reports frombit–mapped machines (e.g., a PC running Windows).

It is important to note that with either executable, you can runcharacter–mode or bit–mapped reports. The only limiting factor is theoutput device (e.g., you could not run a bit–mapped report to thescreen of a vt220).

Is the report to run. (REPORT is allowed for backward compatibility.)

Any valid runfile (i.e., a file with an extension of.rdf or .rep). If you do not enter a file extension,Oracle Reports searches first for a file withextension .rep, then extension .rdf, and then noextension. Oracle Reports will use its file pathsearch order to find the file. For more informationabout file path search order, see “File SearchingMethod” on page 18 – 9.

Rules:

1. If you specify a runfile using MODULE/REPORT, the R25RUNroot window is not raised and File—>Run, File—>Print, andEdit—>Runtime Settings are disabled. (This behavior providesseamless entry into R25RUN from other applications.) If you donot specify a runfile using MODULE/REPORT and you specifyBATCH=NO, a window is opened that enables you to run reportsinteractively.

Options:

USERID

PARAMFORM

CMDFILE

1 – 19Executables

2. If you run a character–mode report via bit–mapped R25RUN,Oracle Reports displays a warning, then runs the report using apage size of 8.5” x 11” and a form size of 7” x 6”.


Displays the Runtime Parameter Form when you execute a report. Formore information on the Runtime Parameter Form, see “RuntimeParameter Form” on page 9 – 2.

YES means to display the Form.

NO means to suppress the Form.

YES

Rules:

1. PARAMFORM=YES is incompatible with BATCH=YES because it is notmeaningful to have the Runtime Parameter Form appear in batchmode.

Is a file that contains arguments for the R25RUN command. Thisoption enables you to run a report without having to specify a largenumber of arguments each time you invoke R25RUN.


Rules:


2. Command file syntax for R25RUN arguments is identical to thatused on the command line.

3. Values entered on the command line override values specified incommand files. For example, suppose that you specify R25RUNfrom the command line with COPIES equal to 1 and CMDFILEequal to RUNONE (a command file). In RUNONE, COPIES is setto 2. Only one copy of the report would be generated in this case.For more information, see “Command Line Syntax Rules” on page1 – 4.


Options:

Default:

Options:

TERM

ARRAYSIZE

DESTYPE


Is the terminal definition file that describes the terminal from whichyou are using R25RUN. In turn, this file determines which keyscorrespond to which Oracle Reports functions. TERM is useful for theRuntime Parameter Form and Previewer only. This keyword is onlyused in character mode.

Any valid terminal definition file.

Installation dependent. (See your SystemAdministrator for a compatible definition.)

Rules:

1. The argument(s) for this keyword may be case sensitive, dependingon your operating system. For more information, see theDeveloper/2000 Installation Guide for your operating system.

Is the size of the array in kilobytes for use with ORACLE arrayprocessing. Generally, the larger the arraysize, the faster the report willrun.

A number from 1 through 9,999. This means thatOracle Reports can use this number of kilobytes ofmemory per query in your report.

The default arraysize is 10K. For details about theORACLE array processing, see the ORACLE7Server Administrator’s Guide.

Is the type of destination device that will receive the report output.

Screen routes the output to the Previewer forinteractive viewing. This value is valid only whenthe BATCH=NO.

File saves the output to a file named in DESNAME(the next keyword discussed).

Printer routes the output to the printer named inDESNAME (the next keyword discussed).

Preview also routes the output to the Previewer forinteractive viewing. However, Preview causes theoutput to be formatted as PostScript output. ThePreviewer will use DESNAME to determine whichprinter’s fonts to use to display the output.

Options:

Default:

Options:

Default:

Options:

DESNAME

1 – 21Executables

Mail sends the output to the Oracle*Mail usersspecified in DESNAME. If your system does nothave Oracle*Mail installed, or is not an Oracle*Mailnode, an error will be returned. The report can besent as part of the message or as an attached file.

For more information, see “Integrating with OtherProducts” on page 16 – 1.

Sysout sends the output to your operating system’sdefault output device. This value is valid onlywhen BATCH=YES.

Taken from the Initial Value field of the Parameterproperty sheet for the DESTYPE parameter. Formore information on the Parameter property sheet,see “Parameter Properties” on page 6 – 45.

Rules:

1. If you set DESTYPE to Printer, File, or Mail, the Print Job dialog boxwill appear after you accept the Runtime Parameter Form, unless itis suppressed. After you accept the Print Job dialog box, the reportis executed and the output is sent to the printer (specified inFile—>Choose Printer), file, or mail id.

If DESTYPE is something other than Printer, File, or Mail, then thereport is executed after you accept the Runtime Parameter Form.The appearance of the dialog box varies between operatingsystems. For more information, see the Developer/2000 InstallationGuide for your operating system.

2. In some cases, this parameter may be overridden by your operatingsystem. For more information, see the Developer/2000 InstallationGuide for your operating system.

3. All DESTYPE values are not supported on every operating system.For more information, see the Developer/2000 Installation Guide foryour operating system.

Is the name of the file, printer, or Oracle*Mail username (or distributionlist) to which the report output will be sent. To send the report outputto an Oracle*Mail user, specify the username as you do in Oracle*Mail.You can specify multiple usernames by enclosing the names inparentheses and separating them by commas (e.g., (<name>, <name>, . ..<name>)).

Default:

DESFORMAT


Any valid filename, printer name, or Oracle*Mailuserid not to exceed 1K in length. For printernames, you can optionally specify a port. Forexample:

DESNAME=<printer_name>,LPT1:

DESNAME=<printer_name>,FILE:

Taken from the Initial Value field of the Parameterproperty sheet for the DESNAME parameter. IfDESTYPE=FILE and DESNAME is an emptystring, it defaults to <reportname>.lis at runtime.For more information on the Parameter propertysheet, see “Parameter Properties” on page 6 – 45.

Rules:

1. This keyword is ignored if DESTYPE is Screen or Sysout.

2. If DESTYPE is Preview, Oracle Reports uses DESNAME todetermine which printer’s fonts to use to display the output.



In bit–mapped environments, specifies the printer driver to be usedwhen DESTYPE is File. In character–mode environments, specifies thecharacteristics of the printer named in DESNAME.

Any valid destination format not to exceed 1K inlength. Examples of valid values for this keywordare hpl, hplwide, dec, decwide, decland, dec180, dflt,wide, etc. Ask your System Administrator for a listof valid destination formats.

Taken from the Initial Value field of the Parameterproperty sheet for the DESFORMAT parameter.For more information on the Parameter propertysheet, see “Parameter Properties” on page 6 – 45. For bit–mapped Oracle Reports, if DESFORMAT isblank or dflt, then the current printer driverselected in Choose Printer is used. If nothing hasbeen selected in Choose Printer, then Postscript isused by default.

Options:

Default:

Options:

Default:

COPIES

CURRENCY

THOUSANDS

1 – 23Executables

Rules:

1. This keyword is ignored if DESTYPE is Screen or Sysout.


Is the number of copies of the report to print.

Any valid integer from 1 through 9,999.

Taken from the Initial Value field of the Parameterproperty sheet for the COPIES parameter. Formore information on the Parameter property sheet,see “Parameter Properties” on page 6 – 45.

Rules:

1. This keyword is ignored if DESTYPE is not Printer.

2. If COPIES is left blank on the Runtime Parameter Form, it defaultsto one.

Is the currency character to be used in number formats.

Any valid alphanumeric string not to exceed 1K inlength.

The default for ORACLE is determined by theORACLE National Language Support facilities.You can also set a default of up to four charactersin the Initial Value field of the Parameter propertysheet for the CURRENCY parameter.

For more information on the Parameter propertysheet, see “Parameter Properties” on page 6 – 45.

Rules:

1. A CURRENCY value entered on the Runtime Parameter Form willoverride any CURRENCY value entered on the command line.

Is the thousands character to be used in number formats.

Any valid alphanumeric character.

Options:

Default:

Options:

Default:

Options:

DECIMAL

READONLY


The default for ORACLE is determined by theORACLE National Language Support facilities.You can also set a default in the Initial Value fieldof the Parameter property sheet for theTHOUSANDS parameter. For more informationon the Parameter property sheet, see “ParameterProperties” on page 6 – 45.

Rules:

1. A THOUSANDS value entered on the Runtime Parameter Formwill override any THOUSANDS value entered on the commandline.

Is the decimal character to be used in number formats.


The default for ORACLE is determined by theORACLE National Language Support facilities.You can also set a default in the Initial Value fieldof the Parameter property sheet for the DECIMALparameter. For more information on the Parameterproperty sheet, see “Parameter Properties” on page6 – 45.

Rules:

1. A DECIMAL value entered on the Runtime Parameter Form willoverride any DECIMAL value entered on the command line.

Requests read consistency across multiple queries in a report. Whenaccessing data from ORACLE, read consistency is accomplished by aSET TRANSACTION READ ONLY statement (refer to your ORACLE7Server SQL Language Reference Manual for more information on SETTRANSACTION READ ONLY).

YES requests read consistency.

NO means do not provide read consistency.

NO

Rules:

1. The list below shows the order of events when a report is executed.Notice where the SET TRANSACTION READONLY occurs.

1.1 Before Form trigger is fired.

1.2 Runtime Parameter Form appears (if not suppressed).

Default:

Options:

Default:

Options:

Default:

LOGFILE

1 – 25Executables

1.3 After Form trigger is fired.

1.4 Report is ”compiled.”

1.5 Before Report trigger is fired and queries are parsed.

1.6 SET TRANSACTION READONLY is executed (if specified viathe READONLY argument or setting).

1.7 The report is executed and the Between Page trigger fires foreach page except the last one. (Note that data can be fetched atany time while the report is being formatted.)

Note: COMMITs can occur during this time due to any of thefollowing—user exit with DDL, SRW.DO_SQL with DDL, or ifONFAILURE=COMMIT, and the report fails.

1.8 COMMIT is executed (if READONLY is specified) to end thetransaction.

1.9 After Report trigger is fired.

1.10COMMIT/ROLLBACK/NOACTION is executed based onwhat was specified via the ONSUCCESS argument or setting.

Caution: In steps 1.4 through 1.8, avoid DDL statements that wouldmodify the tables on which the report is based. Step 1.3 takes asnapshot of the tables and the snapshot must remain valid throughoutthe execution of the report. In steps 1.6 through 1.8, avoid DMLstatements that would modify the contents of the tables on which thereport is based. Queries may be executed in any order, which makesDML statements unreliable (unless performed on tables not used by thereport).

Caution: If you specify READONLY, you should avoid DDLaltogether. When you execute a DDL statement (e.g., via SRW.DO_SQLor a user exit), a COMMIT is automatically issued. If you are usingREADONLY, this will prematurely end the transaction begun by SETTRANSACTION READONLY.

2. This keyword is only useful for reports using multiple queries,because ORACLE automatically provides read consistency, withoutlocking, for single query reports.

Is the name of the file to which File—>Print Screen output is sent. Ifthe specified file already exists, output will be appended to it. Thiskeyword is only used in character mode.

Any valid filename.

dfltrep.log in the current directory.

Options:

Default:

BUFFERS

BATCH


Is the size of the virtual memory cache in kilobytes.

Note: You should tune this setting to ensure that you haveenough space to run your reports, but not so much that you areusing too much of your system’s resources.

A number from 1 through 9,999. For someoperating systems, the upper limit may be lower.For more information, see the Developer/2000Installation Guide for your operating system.

640K

Rules:

1. If this setting is changed in the middle of your session, the changedoes not take effect until the next time the report is run.

Suppresses all terminal input and output, in order to run reportswithout user intervention. BATCH=YES enables you to run the reportwithout bringing up the R25RUN interface. To run reports in thebackground, see “BACKGROUND” on page 1 – 31.

YES suppresses all terminal input and output.

NO allows special terminal input and output.

NO

Rules:

1. If BATCH=YES, error messages are sent to Sysout. For moreinformation on Sysout, see “DESNAME” on page 1 – 21.

2. If BATCH=YES, PARAMFORM=YES is invalid because it is not meaningfulto have the Runtime Parameter Form appear in batch mode.

3. When BATCH=NO and you are using the character–mode R25RUN,bit–mapped reports cannot be run. (It is not possible to run abit–mapped report to the screen of a character–mode device.)

4. When BATCH=YES, MODE=BITMAP, and you are using thecharacter–mode R25RUN, you cannot run a character–modereport.

Options:

Default:

Options:

Default:

PAGESIZE

1 – 27Executables

Is the dimensions of the physical page (i.e., the size of the page that theprinter outputs).

Any valid page dimensions of the form: pagewidth x page height, where page width and pageheight are zero or more. The maximumwidth/height depends upon the unit ofmeasurement. For inches, the maximumwidth/height is 512 inches. For centimeters, it is1312 centimeters. For picas, it is 36,864 picas.

Note that the page must be large enough to containthe report. For example, if a frame in a reportexpands to a size larger than the page dimensions,the report will not run.


Rules:

Caution: On some printers the printable area of the physical page isrestricted. For example, the sheet of paper a printer takes may be 8.5 x11 inches, but the printer might only be able to print on an area of 8 x10.5 inches. If you define a page width x page height in Oracle Reportsthat is bigger than the printable area your printer allows, clipping mayoccur in your report output. To avoid clipping, you can either increasethe printable area for the printer (if your operating system allows it) oryou can set the page width x page height to be the size of the printablearea of the page.

1. If this keyword is used, its value overrides the page dimensions of the report definition.

2. A PAGESIZE value entered on the Runtime Parameter Form willoverride any PAGESIZE value entered on the command line.

Options:

Default:

PROFILE

RUNDEBUG


Is the name of a file in which you want to store performance statisticson report execution. If you specify a filename, Oracle Reportscalculates statistics on the elapsed and CPU time spent running thereport. PROFILE calculates the following statistics:

• TOTAL ELAPSED TIME is the amount of time that passesbetween when you issue R25RUN and when it finishes runningthe report. TOTAL ELAPSED TIME is the sum of Oracle ReportsTime and ORACLE Time.

• Oracle Reports Time is the amount of time spent in OracleReports.

• ORACLE Time is the amount of time spent in the database andis composed of the following:

– UPI is the amount of time spent to do such things asconnect to the database, parse the SQL, and fetch the data.

– SQL is the amount of time spent performing SRW.DO_SQL.

• TOTAL CPU Time used by process is the CPU time spentrunning the report.

Note: For some operating systems, the Oracle Reports timeincludes the database time because the database is included inOracle Reports’ process. For more information, see theDeveloper/2000 Installation Guide for your operating system.

Any valid filename in the current directory.

Is whether you want extra runtime checking for logical errors in thereport. RUNDEBUG checks for things that are not errors but mightresult in undesirable output. RUNDEBUG checks for the following:

• frames or repeating frames that overlap but do not encloseanother object. This can lead to objects overwriting other objectsin the output.

• layout objects with page–dependent references that do no havefixed sizing. Oracle Reports will make such objects fixed in sizeregardless of the Vertical and Horizontal Sizing properties. Formore information, see “Vertical Sizing” on page 8 – 20.

• bind variables referenced at the wrong frequency in PL/SQL.

• the report is character mode or bitmap and the environment isthe opposite.

YES means perform extra runtime error checking.

Options:

Options:

ONSUCCESS

ONFAILURE

1 – 29Executables

NO means do not perform extra runtime errorchecking.

NO

Is whether you want a COMMIT or ROLLBACK performed when thereport is finished executing.

COMMIT means perform a COMMIT when thereport is done.

ROLLBACK means perform a ROLLBACK whenthe report is done.

NOACTION means do nothing when the report isdone.

COMMIT, if a USERID is provided.

NOACTION, if called from an external source (e.g.,Oracle Forms) with no USERID provided.

Rules:

1. The COMMIT or ROLLBACK for ONSUCCESS is performed afterthe After Report trigger fires. Other COMMITs and ROLLBACKscan occur prior to this one. For more information, see“READONLY” on page 1 – 24.

Is whether you want a COMMIT or ROLLBACK performed if an erroroccurs and the report fails to complete.

COMMIT means perform a COMMIT if the reportfails.

ROLLBACK means perform a ROLLBACK if thereport fails.

NOACTION means do nothing if the report fails.

ROLLBACK, if a USERID is provided.


Rules:

1. The COMMIT or ROLLBACK for ONFAILURE is performed afterthe report fails. Other COMMITs and ROLLBACKs can occur priorto this one. For more information, see “READONLY” on page1 – 24.

Default:

Options:

Default:

Options:

Default:

KEYIN

KEYOUT

ERRFILE

LONGCHUNK

ORIENTATION


Is the name of a keystroke file that you want to execute at runtime.KEYIN is used to run the keystroke files created with KEYOUT.

Caution: Since KEYIN is used to execute a keystroke file, it is onlyrelevant when runnning in a character–mode environment.

Any valid key filename in the current directory.

Is the name of a keystroke file in which you want Oracle Reports torecord all of your keystrokes. You can then use KEYIN to execute thekeystroke file. KEYOUT and KEYIN are useful when you have certainkeystrokes that you want to do each time you run a report. They arealso useful for debugging purposes.

Caution: Since KEYOUT is used to create a keystroke file, it is onlyrelevant when running reports in a character–mode environment.

Any valid filename.

Is the name of a file in which you want Oracle Reports to store all errormessages that are issued during the execution of your report.

Any valid filename.

Is the size (in kilobytes) of the increments in which Oracle Reportsretrieves a LONG column value. When retrieving a LONG value, youmay want to retrieve it in increments rather than all at once because ofmemory size restrictions. LONGCHUNK applies only to ORACLE7.


10K

Controls the direction in which the pages of the report will print.

DEFAULT means use the current printer setting fororientation.

LANDSCAPE

PORTRAIT

DEFAULT

Options:

Options:

Options:

Options:

Default:

Options:

Default:

BACKGROUND

MODE

1 – 31Executables

Rules:

1. If ORIENTATION=LANDSCAPE for a character–mode report, youmust ensure that your printer definition file contains a landscapeclause. For more information, see “Printer Definition File Syntax”on page B – 3.

Specifies whether the report should be run in the background. WhenBACKGROUND is YES, another process is spawned. This option isuseful when you want to work on something else in the foregroundwhile the report runs.

Additional Information: On Windows, specifyingBACKGROUND=YES means that the report will go into theOracle Reports Server queue.

YES

NO

NO

Rules:

1. BACKGROUND=YES is not supported for BATCH=YES,DESTYPE=SCREEN or PREVIEW, or R25DES.

2. If you run a report from Oracle Reports Runtime (i.e., not thecommand line or SRW.RUN_REPORT), you should commitdatabase changes you make in the Before Form, After Form, andValidation triggers before the report runs. When running in thisway, these triggers will share the parent process’ databaseconnection. When the report is actually executed, however, it willestablish it’s own database connection.

Specifies whether to run the report in character mode or bitmap. Thisenables you to run a character–mode report from bit–mapped OracleReports or vice versa. For example, if you want to send a report to aPostscript printer from a terminal (e.g., a vt220), you could invokecharacter–mode R25RUN and run the report with MODE=BITMAP.

Additional Information: On Windows, specifyingMODE=CHARACTER means that the Oracle Reports ASCII driverwill be used to produce editable ASCII output.

BITMAP

DEFAULT means to run the report in the mode ofthe current executable being used.

CHARACTER

Options:

Default:

Options:

PRINTJOB

<PARAM>


DEFAULT

Specifies whether the Print Job dialog box should be displayed beforerunning a report.

NO

YES

YES

Rules:

1. When a report is run as a spawned process (i.e., one executable,such as R25RUN, is called from within another executable, such asR25DES), the Print Job dialog box will not appear, regardless ofPRINTJOB.

2. When DESTYPE=MAIL, the Print Job dialog box will not appear,regardless of PRINTJOB.

Is a parameter that is part of the report’s definition. The value youspecify is used for that parameter’s value.

Any valid value for that parameter.

Taken from the Initial Value field of the Parameterproperty sheet for the parameter. For moreinformation on the Parameter property sheet, see“Parameter Properties” on page 6 – 45.

Examples:

1. Following is an example of R25RUN specifying a parameter’svalue:

r25run scott/tiger myparam1=100 yourparam=’Stratford’ theirparam=’10–DEC–93’

Rules:

1. You can override the default value on the Runtime ParameterForm. For more information, see “Runtime Parameter Form” (onpage 9 – 2).

2. Values of arguments may be in single or double quotes. The effectof single or double quotes is operating–system specific. For moreinformation, see the Developer/2000 Installation Guide for youroperating system.

3. If you specify runfile(s) using the REPORT keyword, the PARAMvalues will be validated using the settings specified for eachparameter (e.g., Input Mask, Validation Trigger) in the report(s).

Default:

Options:

Default:

Options:

Default:

TRACEFILE

TRACEMODE

TRACEOPTS

1 – 33Executables

4. If you do not specify runfile(s) using the REPORT keyword, thePARAM value is not parsed, or validated, because the parametersmay refer to those that have not yet been defined.

Is the name of the file in which Oracle Reports logs trace information.

Any valid filename.

trace.dat

Rules:

1. Trace information can only be generated when running a .rdf file.You cannot specify logging when running a .rep file.

2. If you specify LOGFILE or ERRFILE as well as TRACEFILE, all ofthe trace information will be placed in the most recently specifiedfile. For example, suppose you specify the following:

r25run MODULE=order_entry USERID=scott/tiger TRACEFILE=trace.log LOGFILE=mylog.log ERRFILE=err.log

In this case, all of the specified trace information would be placedin err.log because it is the last file specified in the R25RUNcommand.

Indicates whether Oracle Reports should add the trace information tothe file or overwrite the entire file.

TRACE_APPEND adds the new information to theend of the file.

TRACE_REPLACE overwrites the file.

TRACE_APPEND

Rules:


Indicates the tracing information that you want to be logged in thetrace file.

A list of options in parentheses means you want allof the enlcosed options to be used. For example,TRACE_OPTS=(TRACE_APP, TRACE_PRF) means youwant TRACE_APP and TRACE_PRF applied.

TRACE_ALL means log all possible traceinformation in the trace file.

Options:

Default:

Options:

Default:

Options:

AUTOCOMMIT

NONBLOCKSQL


TRACE_APP means log trace information on all thereport objects in the trace file.

TRACE_ERR means list error messages andwarnings in the trace file.

TRACE_PLS means log trace information on all thePL/SQL objects in the trace file.

TRACE_PRF means log performance statistics inthe trace file.

TRACE_SQL means log trace information on all theSQL in the trace file.

TRACE_TMS means enter a timestamp for eachentry in the trace file.

TRACE_ALL

Rules:


Specifies whether database changes (e.g., CREATE) should beautomatically committed to the database. Note that somenon–ORACLE databases (e.g., SQL Server) require thatAUTOCOMMIT=YES.

YES

NO

NO

On Windows, specifies whether to allow other programs to executewhile Oracle Reports is fetching data from the database. This keywordis ignored on platforms other than Windows (e.g., Motif).

YES

NO

YES

Default:

Options:

Default:

Options:

Default:

Syntax

1 – 35Executables

R25DES

R25DES invokes Oracle Reports’ designer, to create/maintain reports.

r25des [ [keyword=]value ] ...


[ [MODULE|REPORT=]modulename ]

[ [USERID=]userid ]

[ [PARAMFORM=]{yes |no} ]

[ [CMDFILE=]filename ]

[ [ARRAYSIZE=]n ]

[ [DESTYPE=]{screen|file|printer|mail} ]

[ [DESNAME=]desname ]

[ [DESFORMAT=]desformat ]

[ [COPIES=]n ]

[ [CURRENCY=] currency_symbol ]

[ [THOUSANDS=] thousands_symbol ]

[ [DECIMAL=] decimal_symbol ]

[ [READONLY=]{yes|no } ]

[ [BUFFERS=]n ]

[ [PAGESIZE=]width x height ]

[ [PROFILE=]profiler_file

[ [RUNDEBUG=]{yes |no} ]

[ [ONSUCCESS=]COMMIT|ROLLBACK|NOACTION]

[ [ONFAILURE=]COMMIT|ROLLBACK|NOACTION]

[ [ERRFILE=]error_file

[ [LONGCHUNK=]n ]

[ [ACCESS=]{ file|database} ]

[ [ORIENTATION=]DEFAULT |LANDSCAPE|PORTRAIT ]

[ [BACKGROUND=]{yes|no } ]

[ [MODE=]BITMAP|CHARACTER|DEFAULT ]

[ [PRINTJOB]{yes |no} ]

[ <param>=]value ]

[ [TRACEFILE=]tracefile ]

[ [TRACEMODE=]{TRACE_APPEND|TRACE_REPLACE} ]

[ [TRACEOPTS=]{TRACE_ERR|TRACE_PRF|TRACE_BRK|TRACE_APP|

TRACE_PLS|TRACE_SQL|TRACE_TMS|TRACE_ALL|(opt1, opt2, ...)} ]

[ [AUTOCOMMIT]{yes|no } ]

[ [NONBLOCKSQL=]{yes |no}

MODULE/REPORT

USERID

PARAMFORM

CMDFILE


Is a module (report, external query, or external PL/SQL library) thatyou want to open in the designer. (REPORT is allowed for backwardcompatibility.) If you do not specify a report usingMODULE/REPORT, Oracle Reports will start up with a new reportdefinition open.

Any valid report, external query, or externalPL/SQL library name. Oracle Reports will look inthe location specified with the ACCESS keywordfor the module. If ACCESS is not specified, OracleReports will use its file path search order to findthe file. For more information about file pathsearch order, see “File Searching Method” on page18 – 9. If the module is not found, Oracle Reportswill start up without opening the specified module.

Rules:

1. If you open a character mode report via bit–mapped R25DES,Oracle Reports displays a warning, then opens the report using apage size of 8.5” x 11” and a form size of 7” x 6”.


Displays the Runtime Parameter Form when you execute a report. Formore information on the Runtime Parameter Form, see “RuntimeParameter Form” on page 9 – 2.

yes means to display the Form.

no means to suppress the Form.

yes

Is a file that contains arguments for the R25DES command. This optionenables you to run a report without having to specify a large number ofarguments each time you invoke R25DES.


Rules:


2. Command file syntax for R25DES arguments is identical to thatused on the command line.

Options:

Options:

Default:

Options:

ARRAYSIZE

DESTYPE

1 – 37Executables

3. Values entered on the command line override values specified incommand files. For example, suppose that you specify R25DESfrom the command line with COPIES equal to 1 and CMDFILEequal to RUNONE (a command file). In RUNONE, COPIES is setto 2. Only one copy of the report would be generated in this case.For more information, see “Command Line Syntax Rules” on page1 – 4.


Is the size of the array in kilobytes for use with ORACLE arrayprocessing.

A number from 1 through 9,999. This means thatOracle Reports can use this number of kilobytes ofmemory per query in your report.

The default arraysize is 10. For details onORACLE array processing, see the ORACLE7Server Administrator’s Guide.

Is the type of destination device that will receive the report output.

Screen routes the output to the Previewer.

File saves the output to a file named in DESNAME(the next keyword discussed).

Printer routes the output to the printer named inDESNAME (the next keyword discussed).

Preview also routes the output to the Previewer forinteractive viewing. However, Preview causes theoutput to be formatted as PostScript output. ThePreviewer will use DESNAME to determine whichprinter’s fonts to use to display the output.

Mail sends the output to the Oracle*Mail usersspecified in DESNAME. If your system does nothave Oracle*Mail installed, or is not an Oracle*Mailnode, an error will be returned. The report is sentas an attached file, not directly as a mail message.

Taken from the Initial Value field of the Parameterproperty sheet for the DESTYPE parameter. Formore information on the Parameter property sheet,see “Parameter Properties” on page 6 – 45.

Options:

Default:

Options:

Default:

DESNAME


Rules:

1. Sysout is not a valid option for DESTYPE while using R25DES.Sysout can only be used with R25RUN when BATCH=YES.

2. If you set DESTYPE to Printer, File, or Mail, the Print Job dialog boxwill appear after you accept the Runtime Parameter Form, unless itis suppressed. After you accept the Print Job dialog box, the reportis executed and the output is sent to the printer (specified inFile—>Choose Printer), file, or mail id. (If DESTYPE is somethingother than Printer, File, or Mail, then the report is executed after youaccept the Runtime Parameter Form.) The appearance of the dialogbox varies between operating systems. For more information, seethe Developer/2000 Installation Guide for your operating system.

3. In some cases, this parameter may be overridden by your operatingsystem. For details, see the Developer/2000 Installation Guide foryour operating system.

4. All DESTYPE values are not supported on every operating system.For more information, see the Developer/2000 Installation Guide foryour operating system.

Is the file, printer, or Oracle*Mail userid (or distribution list) to whichthe report output will be sent. To send the report output to anOracle*Mail user, specify the username as you do in Oracle*Mail. Youcan specify multiple usernames by enclosing the names in parenthesesand separating them by commas (e.g., (<name>, <name>, . . .<name>)).

Any valid filename, printer name, or Oracle*Mailuserid not to exceed 1K in length. For printernames, you can optionally specify a port. Forexample:

DESNAME=<printer_name>,LPT1:

DESNAME=<printer_name>,FILE:

Taken from the Initial Value field of the Parameterproperty sheet for the DESNAME parameter. IfDESTYPE=FILE and DESNAME is an emptystring, it defaults to <reportname>.lis at runtime.For more information on the Parameter propertysheet, see “Parameter Properties” on page 6 – 45.

Rules:

1. This keyword is ignored if DESTYPE is Screen.

2. If DESTYPE is Preview, Oracle Reports uses DESNAME todetermine which printer’s fonts to use to display the output.

Options:

Default:

DESFORMAT

COPIES

1 – 39Executables



In bit–mapped environments, specifies the printer driver to be usedwhen DESTYPE is File. In character mode environments, specifies thecharacteristics of the printer named in DESNAME.

Any valid destination format not to exceed 1K inlength. Examples of valid values for this keywordare hpl, hplwide, dec, decwide, decland, dec180, dflt,wide, etc. Ask your System Administrator for a listof valid destination formats.

Taken from the Initial Value field of the Parameterproperty sheet for the DESFORMAT parameter.For more information on the Parameter propertysheet, see “Parameter Properties” on page 6 – 45. For bit–mapped Oracle Reports, if DESFORMAT isblank or dflt, then the current printer driverselected in Choose Printer is used. If nothing hasbeen selected in Choose Printer, then Postscript isused by default.

Rules:

1. This keyword is ignored if DESTYPE is Screen.


Is the number of copies of the report to print.

Any valid integer from 1 through 9,999.

Taken from the Initial Value field of the Parameterproperty sheet for the COPIES parameter. Formore information on the Parameter property sheet,see “Parameter Properties” on page 6 – 45.

Rules:

1. This keyword is ignored if DESTYPE is not Printer.

2. If COPIES is left blank on the Runtime Parameter Form, it defaultsto one.

Options:

Default:

Options:

Default:

CURRENCY

THOUSANDS

DECIMAL


Is the currency character to be used in number formats.

Any valid alphanumeric string not to exceed 1K inlength.

The default for ORACLE is determined by theORACLE National Language Support facilities.You can also set a default of up to four charactersin the Initial Value field of the Parameter propertysheet for the CURRENCY parameter. For moreinformation on the Parameter property sheet, see“Parameter Properties” on page 6 – 45.

Rules:

1. A CURRENCY value entered on the Parameter property sheet willoverride any CURRENCY value entered on the command line.

Is the thousands character to be used in number formats.


The default for ORACLE is determined by theORACLE National Language Support facilities.You can also set a default of up to four charactersin the Initial Value field of the Parameter propertysheet for the THOUSANDS parameter. For moreinformation on the Parameter property sheet, see“Parameter Properties” on page 6 – 45.

Rules:

1. A THOUSANDS value entered on the Parameter property sheetwill override any THOUSANDS value entered on the commandline.

Is the decimal character to be used in number formats.


The default for ORACLE is determined by theORACLE National Language Support facilities.You can also set a default in the Initial Value fieldof the Parameter property sheet for the DECIMALparameter. For more information on the Parameterproperty sheet, see “Parameter Properties” on page6 – 45

Options:

Default:

Options:

Default:

Options:

Default:

READONLY

1 – 41Executables

Rules:

1. A DECIMAL value entered on the Parameter property sheet willoverride any DECIMAL value entered on the command line.

Requests read consistency across multiple queries in a report. Whenaccessing data from ORACLE, read consistency is accomplished by aSET TRANSACTION READ ONLY statement (refer to your ORACLE7Server SQL Language Reference Manual for more information on SETTRANSACTION READ ONLY).

YES requests read consistency.

NO means do not provide read consistency.

NO

Rules:













Options:

Default:

BUFFERS

PAGESIZE




2. This keyword is only useful for reports using multiple queries,because ORACLE automatically provides read consistency, withoutlocking, for single query reports.

Is the size of the virtual memory cache in kilobytes.

Note: You should tune this setting to ensure that you haveenough space to run your reports, but not so much that you areusing too much of your system’s resources.


640K

Rules:

1. If this setting is changed in the middle of your session, the changedoes not take effect until the next time the report is run.

Is the dimensions of the physical page (i.e., the size of the page that theprinter outputs).

Any valid page dimensions of the form: pagewidth x page height, where page width and pageheight are zero or more. The maximumwidth/height depends upon the unit ofmeasurement. For inches, the maximumwidth/height is 512 inches. For centimeters, it is1312 centimeters. For picas, it is 36,864 picas.

Options:

Default:

Options:

PROFILE

1 – 43Executables

Note that the page must be large enough to containthe report. For example, if a frame in a reportexpands to a size larger than the page dimensions,the report will not run.


Rules:

Caution: On some printers the printable area of the physical page isrestricted. For example, the sheet of paper a printer takes may be 8.5 x11 inches, but the printer might only be able to print on an area of 8 x10.5 inches. If you define a page width x page height in Oracle Reportsthat is bigger than the printable area your printer allows, clipping mayoccur in your report output. To avoid clipping, you can either increasethe printable area for the printer (if your operating system allows it) oryou can set the page width x page height to be the size of the printablearea of the page.

1. If this keyword is used, its value overrides the page dimensions of the report definition.

2. A PAGESIZE value entered on the Runtime Parameter Form willoverride any PAGESIZE value entered on the command line.

Is the name of a file in which you want to store performance statisticson report execution. If you specify a filename, Oracle Reportscalculates statistics on the elapsed and CPU time spent running thereport. PROFILE calculates the following statistics:

• TOTAL ELAPSED TIME is the amount of time that passesbetween when you issue R25DES and when you leave thedesigner. TOTAL ELAPSED TIME is the sum of Oracle ReportsTime and ORACLE Time.

• Oracle Reports Time is the amount of time spent in OracleReports.

Default:

RUNDEBUG

ONSUCCESS


• ORACLE Time is the amount of time spent in the database andis composed of the following:

– UPI is the amount of time spent to do such things asconnect to the database, parse the SQL, and fetch the data.

– SQL is the amount of time spent performing SRW.DO_SQL.

• TOTAL CPU Time used by process is the CPU time spent whilein the designer.

Note: For some operating systems, the Oracle Reports timeincludes the database time because the database is included inOracle Reports’ process. For more information, see theDeveloper/2000 Installation Guide for your operating system.

Any valid filename in the current directory.

Is whether you want extra runtime checking for logical errors inreports. RUNDEBUG checks for things that are not errors but mightresult in undesirable output. RUNDEBUG checks for the following:

• frames or repeating frames that overlap but do not encloseanother object. This can lead to objects overwriting other objectsin the output.

• layout objects with page–dependent references that do no havefixed sizing. Oracle Reports will make such objects fixed in sizeregardless of the Vertical and Horizontal Sizing properties. Formore information, see “Vertical Sizing” on page 8 – 20.

• bind variables referenced at the wrong frequency in PL/SQL.

YES means perform extra runtime error checking.

NO means do not perform extra runtime errorchecking.

YES

Is whether you want a COMMIT or ROLLBACK performed when areport is finished executing.

COMMIT means perform a COMMIT when areport is done.

ROLLBACK means perform a ROLLBACK when areport is done.

NOACTION means do nothing when a report isdone.

COMMIT, if a USERID is provided.

Options:

Options:

Default:

Options:

Default:

ONFAILURE

ERRFILE

LONGCHUNK

1 – 45Executables


Rules:

1. The COMMIT or ROLLBACK for ONSUCCESS is performed afterthe After Report trigger fires. Other COMMITs and ROLLBACKscan occur prior to this one. For more information, see“READONLY” on page 1 – 41.

Is whether you want a COMMIT or ROLLBACK performed if an erroroccurs and a report fails to complete.

COMMIT means perform a COMMIT if a reportfails.

ROLLBACK means perform a ROLLBACK if areport fails.

NOACTION means do nothing if a report fails.

ROLLBACK, if a USERID is provided.


Rules:

1. The COMMIT or ROLLBACK for ONFAILURE is performed afterthe report fails. Other COMMITs and ROLLBACKs can occur priorto this one. For more information, see “READONLY” on page1 – 41.

Is the name of a file in which you want Oracle Reports to store all errormessages that are issued during the designer session.

Any valid filename.

Is the size (in kilobytes) of the increments in which Oracle Reportsretrieves a LONG column value. When retrieving a LONG value, youmay want to retrieve it in increments rather than all at once because ofmemory size restrictions. LONGCHUNK applies only to ORACLE7.


10K

Options:

Default:

Options:

Options:

Default:

ACCESS

ORIENTATION

BACKGROUND

MODE


Is the location from which modules should be opened. Oracle Reportswill search in this location for the module you specify with MODULE.If ACCESS is not specified, Oracle Reports will use its file path searchorder to find the file. For more information about file path searchorder, see “File Searching Method” on page 18 – 9.

FILE

DATABASE

FILE

Controls the direction in which the pages of the report will print.

DEFAULT means use the current printer setting fororientation.

LANDSCAPE

PORTRAIT

DEFAULT

Rules:

1. If ORIENTATION=LANDSCAPE for a character mode report, youmust ensure that your printer definition file contains a landscapeclause. For more information, see “Printer Definition File Syntax”on page B – 3.

Specifies whether the report should be run in the background.BACKGROUND=YES is not supported for R25DES. For moreinformation, see “BACKGROUND” on page 1 – 31.

YES

NO is not a valid option for R25DES.

NO

Specifies whether to run the report in character mode or bitmap. Thisenables you to run a character–mode report from bit–mapped OracleReports or vice versa. For example, if you want to send a report to aPostscript printer from a terminal (e.g., a vt220), you could invokecharacter–mode R25RUN and run the report with MODE=BITMAP.

Additional Information: On Windows, specifyingMODE=CHARACTER means that the Oracle Reports ASCIIdriver will be used to produce editable ASCII output.

BITMAP

Options:

Default:

Options:

Default:

Options:

Default:

Options:

PRINTJOB

<PARAM>>

1 – 47Executables

DEFAULT means to run the report in the mode ofthe current executable being used.

CHARACTER

DEFAULT

Specifies whether the Print Job dialog box should be displayed beforerunning a report.

YES

NO

YES

Rules:

1. When a report is run as a spawned process (i.e., one executable,such as R25RUN, is called from within another executable, such asR25DES), the Print Job dialog box will not appear, regardless ofPRINTJOB.

2. When DESTYPE=MAIL, the Print Job dialog box will not appear,regardless of PRINTJOB.

Is a parameter that is part of the report’s definition. The value youspecify for the parameter is used for that parameter’s value.

Any valid value for that parameter.

Taken from the Initial Value field of the Parameterproperty sheet for the parameter. For moreinformation on the Parameter property sheet, see“Parameter Properties” on page 6 – 45.

Examples:

1. Following is an example of R25DES specifying a parameter’s value:

r25des scott/tiger myparam1=100 yourparam=’Stratford’ theirparam=’10–DEC–93’

Rules:

1. You can override the default value on the Runtime ParameterForm. For more information, see “Runtime Parameter Form” onpage 9 – 2.

2. Values of arguments may be in single or double quotes. The effectof single or double quotes is operating–system specific. For moreinformation, see the Developer/2000 Installation Guide for youroperating system.

Default:

Options:

Default:

Options:

Default:

TRACEFILE

TRACEMODE

TRACEOPTS


3. The PARAM value is not parsed, or validated, because theparameters may refer to those that have not yet been defined.

Is the name of the file in which Oracle Reports logs trace information.

Any valid filename.

Rules:


2. If you specify ERRFILE as well as TRACEFILE, all of the traceinformation will be placed in the most recently specified file. Forexample, suppose you specify the following:

r25des USERID=scott/tiger TRACEFILE=trace.log ERRFILE=err.log

In this case, all of the specified trace information would be placedin err.log because it is the last file specified in the R25DEScommand.

Indicates whether Oracle Reports should add the trace information tothe file or overwrite the entire file.

TRACE_APPEND adds the new information to theend of the file.

TRACE_REPLACE overwrites the file.

TRACE_APPEND

Rules:


Indicates the tracing information that you want to be logged in thetrace file.

A list of options in parentheses means you want allof the enlcosed options to be used. For example,TRACE_OPTS=(TRACE_APP, TRACE_PRF) means youwant TRACE_APP and TRACE_PRF applied.

TRACE_ALL means log all possible traceinformation in the trace file.

TRACE_APP means log trace information on all thereport objects in the trace file.

Options:

Options:

Default:

Options:

AUTOCOMMIT

NONBLOCKSQL

1 – 49Executables

TRACE_BRK means list breakpoints in the tracefile.

TRACE_ERR means list error messages andwarnings in the trace file.

TRACE_PLS means log trace information on all thePL/SQL objects in the trace file.

TRACE_PRF means log performance statistics inthe trace file.

TRACE_SQL means log trace information on all theSQL in the trace file.

TRACE_TMS means enter a timestamp for eachentry in the trace file.

TRACE_ALL

Rules:


Specifies whether database changes (e.g., CREATE) should beautomatically committed to the database. Note that somenon–ORACLE databases (e.g., SQL Server) require thatAUTOCOMMIT=YES.

YES

NO

NO

On Windows, specifies whether to allow other programs to executewhile Oracle Reports is fetching data from the database. This keywordis ignored on platforms other than Windows (e.g., Motif).

YES

NO

YES

Default:

Options:

Default:

Options:

Default:

P A R T

II Externals

C H A P T E R

2D

2 – 1Defaulting

Defaulting

efaulting in Oracle Reports creates objects and defines certainsettings so that you don’t have to. Without defaulting, you would haveto manually create each object in your report and for each of theobjects’ settings, enter a value. You should know the following aboutOracler Reports defaulting:

• data model defaulting – 2 – 2

• layout defaulting – 2 – 4

• global layout defaulting rules – 2 – 41

• implicit anchoring algorithm – 2 – 43

• print condition algorithm – 2 – 47

• parameter form defaulting – 2 – 47

Groups

Columns


Data Model Defaulting

While you define the data for your report, Oracle Reports might createthe following data objects for you:

• groups – 2 – 2

• columns – 2 – 2

• parameters – 2 – 3

The circumstances under which Oracle Reports creates these objects aredescribed below.

Note: Queries and links (parent–child relationships) are nevercreated by default. You must always create those objectsyourself.

Objects Created/Circumstances Oracle Reports will create one groupfor each query you create.

Ownership The group will be owned by the query you created. Inturn, the group will own all of the columns found in the query’sSELECT list (e.g., ENAME, EMPNO, SAL).

Ordering The order of the groups determines the default order inwhich the groups’ columns appear in a default layout. Specifically, agroup above, or to the left of other groups will have its columns appearabove or to the left of others (if two groups have the same x coordinate,the group above the second will appear in the default layout above orto the left of the second group).

Note: The previous sentence is true only when a report’sdefault layout is first generated. Adding PL/SQL to theformatting objects, adding anchors, changing format settings,moving layout objects, etc. can cause a group’s data to appearelsewhere in a report output.

Name: G_queryname

Query: Q_queryname

Filter... Type: None

All other fields are blank.

Objects Created/Circumstances Oracle Reports will create one columnfor each item in a query’s SELECT list.

Ownership The default columns are assigned to the default group forthe query.

Settings

Parameters

2 – 3Defaulting

Ordering Columns appear in the default group in the order in whichthe columns appear in the SELECT list. (For example, if the SELECTstatement is SELECT ENAME, EMPNO, SAL FROM EMP, ENAME willappear in the default group above EMPNO, and EMPNO will appearabove SAL.) Also, the order of the columns in the default groupdetermines the order in which the columns appear in a default layout.(For example, using the SELECT statement above, ENAME will appearin a default layout above or to the left of EMPNO, and EMPNO willappear above or to the left of SAL in a default layout.)

Note: The previous sentences are true only when a report’sdefault layout is first generated. Adding PL/SQL to theformatting objects, adding anchors, changing format settings,moving layout objects, etc. can cause a column to appearelsewhere in a report output.

If additional columns are added to the query, the additional defaultcolumns will be added to the end of the list of default columns.

Name: G_queryname

Query: Q_queryname

Filter... Type: None

All other fields are blank.

Objects Created/Circumstances Oracle Reports will create systemparameters (e.g., DESTYPE) each time you create a new report. Also,Oracle Reports will create one parameter for each bind parameterreference you make in a query. It will not create a parameter in thefollowing cases:

• for a bind column reference in your query

• for a lexical reference, because the query cannot parse without aninitial value for a lexical reference

Ownership Parameters are not owned by other objects.

Settings

When you create a new parameter, its default settings are as follows:

Name Data Type Width

P_1 character 40

Settings

Object Defaulting

Frames


Layout Defaulting

This section contains the following topics:

• object defaulting – 2 – 4

• object defaulting for each layout style – 2 – 6

Note: This chapter does not provide steps on how to create adefault layout. For more information, see “How To” inChapter 8 of Building Reports Manual.

Oracle Reports might create any of the following layout objects for you:

• frames – 2 – 4

• repeating frames – 2 – 5

• fields – 2 – 5

• boilerplate – 2 – 5

• anchors – 2 – 5

• matrix objects – 2 – 5

• buttons – 2 – 5

The circumstances under which Oracle Reports creates these layoutobjects are described later in this chapter.

A conceptual overview of layout object defaulting is below. It isimportant to realize, however, that the layout objects Oracle Reportsgenerates are layout–style specific (e.g., different layout objects arecreated for a tabular report and a matrix report). For more informationabout exactly which objects are created for a particular layout style, see“Object Defaulting for Each Layout Style” on page 2 – 6.

Note: Reading the introduction below will help youunderstand the remainder of this layout defaulting section.

Objects Created/Circumstances Oracle Reports will create one frame tosurround all objects owned by a group (it is namedM_groupname_GRPFR), to surround column labels (it is namedM_groupname_HDR), and to surround summaries (it is namedM_groupname_FTR).

Ownership A frame is owned by the object surrounding it (a frame orrepeating frame), unless otherwise noted.

Repeating Frames

Fields

Boilerplate

Anchors

Matrix Objects

Buttons

2 – 5Defaulting

Objects Created/Circumstances Oracle Reports will create onerepeating frame to surround all fields that are created for a group’scolumns (it is named R_groupname). The repeating frame prints (isfired) once for each record of the group.

Ownership A repeating frame is owned by the object surrounding it (aframe or repeating frame), unless otherwise noted.

Objects Created/Circumstances Oracle Reports will create one field foreach column selected in the Default Layout dialog box (it is namedF_columnname).

Ownership A field is owned by the object surrounding it, typically arepeating frame, unless the field is a summary (in which case it isowned by a frame).

Objects Created/Circumstances Oracle Reports will create oneboilerplate object for each label selected in the Default Layout dialogbox (it is named B_columnname). Also, one boilerplate object issometimes created for each report summary. For more informationabout the conditions under which summaries have boilerplategenerated, see “Global Layout Defaulting Rules” on page 2 – 41.

Ownership A boilerplate object is owned by the object surrounding it,unless otherwise noted.

Objects Created/Circumstances (Recall that there are two types ofanchors: explicit and implicit. See the glossary for an explanation ofthese terms.) Oracle Reports will create implicit anchors at runtime.

Ownership An anchor is owned by the child object to which it isanchored.

Objects Created/Circumstances Oracle Reports will create one matrixobject for each pair of intersecting, perpendicular repeating frames.The matrix object is only created for layouts with a Matrix layout style.

Ownership A matrix object merely defines a relationship between tworepeating frames: it isn’t really owned by anything, nor does it ownanything.

Objects Created/Circumstances Oracle Reports will create a buttonobject for you if you have selected a column that contains or points to amultimedia object (e.g., sound or video).

Ownership A button object is owned by the object surrounding it,unless otherwise noted.

Object Defaulting ForEach Layout Style

Tabular Reports

Tabular ReportRequirements

Repeat DirectionExample


This section describes what objects are created for each layout style(i.e., tabular, mailing label, form letter, form, master/detail, andmatrix). The following layout styles are covered:

• tabular – 2 – 6

• mailing label – 2 – 12

• form – 2 – 15

• form letter – 2 – 17

• master/detail – 2 – 20

• matrix – 2 – 27

This section describes the layout requirements, object generation, andrules for the tabular report layout style.

Data Model Requirements You can use any type of data relationship.

Default Layout Requirements In a group tree, all children of thehighest–selected group must have the same initial Repeat direction.For example, if the highest–selected group repeats Across, its childrenmust have a Repeat direction of Across or Across/Down. Likewise, if thehighest–selected group repeats Down/Across, its children must have aRepeat direction of Down or Down/Across. If more than one tree has aselected group, each tree’s highest–selected group may have a differentrepeat direction.

A cross–product group may not be selected.

Assume you have a report with the following group trees, and youselected the shaded groups.

Tabular Report Defaulting

Single–groupDefaulting

2 – 7Defaulting

If group 1 has a Repeat direction of Across, its children (groups 2, 3, and5—even though group 4 is not selected) must have either a Repeatdirection of Across or Across/Down. Group 6 may have any Repeatdirection, because it has no ancestors. If you have it Repeat Down, itschildren (groups 7 and 8) must have a Repeat direction of Down orDown/Across; if it repeats Across, its children must repeat Across orAcross/Down. Finally, group 10 may also have any Repeat directionbecause it is the highest–selected group in its tree.

The way that your tabular report defaults depends on the number ofgroups you select in the Default Layout dialog box, and on therelationship of those groups. Therefore, this section is divided intotwo sections:

• single–group defaulting (i.e., when only one group is selected)

• multiple–group defaulting (i.e., when multiple groups areselected)

Note: This section describes defaulting for down reports, only.Across tabular reports are transposed Down reports. For moreinformation on how to transpose a report, see “Global LayoutDefaulting Rules” on page 2 – 41.

This section is divided into two parts:

• defaulting without summaries

• defaulting with summaries

Tabular Defaulting without Summaries Assume you selected only onegroup, and that group owns two columns.

Generated Objects: If you use the default Repeat direction, Down, yourLayout editor will contain the following objects:

For the label of each selected column in the DefaultLayout dialog box. B_ implies it is a boilerplateobject.

For each column that you selected in the DefaultLayout dialog box. F_ implies it is a field.

For each group that you selected in the DefaultLayout dialog box. R_ implies it is a repeatingframe.

For each group you selected in the Default Layoutdialog box. M_ implies it is a frame; HDR impliesit is for the header information (i.e., labels).

B_columnname

F_columnname

R_groupname

M_groupname_HDR


For each group that you selected in the DefaultLayout dialog box. M_ implies it is a frame;GRPFR implies it is a group frame.M_groupname_GRPFR is used to keep all of thatgroup’s objects together.

Appearance:

Layers: Objects must be on a layer above the objects that enclose them.For example:

• Boilerplate objects and fields must be on a layer above therepeating frame that encloses them.

• A header frame that contains boilerplate labels for fields must beon a layer below the boilerplate. It must also be on a layer abovethe repeating frame that contains it.

Print Conditions: All objects have a Print Condition Type/Object ofDefault/Anchoring, except M_groupname_HDR, which isAll/Enclosing. Recall that whenever a setting has Default as its default,it means that Oracle Reports will determine what the setting should beat runtime, based on the layout style the object is in, the object’ssettings, and the settings of the objects near it.

Tabular Defaulting with Report–level Summaries Assume the samescenario as above, only this time there are also two report–levelsummaries.

Generated Objects: The following objects are generated in addition tothose created for the tabular report without summaries:

For the label of each selected column in the DefaultLayout dialog box, and if there is room, forsummary labels. For more information, see “Rulesabout Summaries” on page 2 – 42. B_ implies it is aboilerplate object.

M_groupname_GRPFR

B_columnname

Multiple–groupDefaulting

2 – 9Defaulting

For each report–level summary that you selected inthe Default Layout dialog box.

For each group that owns a report summary thatyou selected in the Default Layout dialog box. M_implies it is a frame; FTR implies it is footer frame.M_groupname_FTR is used to protect all summaryfields for that group from being overwritten byother objects in the report.

Appearance:

Layers: Objects must be on a layer above the objects that enclose them.For example:

• Boilerplate objects and fields must be on a layer above therepeating frame that encloses them.

• A footer frame that surrounds fields must be on a layer belowthe fields it contains. It must also be on a layer above the groupframe that contains it.

Print Conditions: All objects have a Print Condition Type/Object ofDefault/Anchoring, except M_groupname_HDR, which isAll/Enclosing.


• defaulting for sibling groups

• defaulting for parent/child groups

F_columnname

M_groupname_FTR


Tabular Defaulting for Sibling Groups Tabular reports produced withtwo or more sibling groups are almost identical to tabular reportsproduced with master/detail models. If the siblings have the sameparent (directly or indirectly), they appear side–by–side in the layout.If the siblings do not have the same parent, the sibling that is higher inthe group hierarchy appears above the other siblings in the layout. Thelatter case is illustrated in the figure below.

Tabular Defaulting for Parent/Child Groups (with report–levelsummaries) Assume you only have one group tree, you selected onlytwo groups, one of which is the parent of the other, and each groupowns two columns. Assume also that there are four summaries (seethe figure below): two parent–level summaries, which sum thecolumns in the child group; and two report–level summaries, whereone sums a column in the child group and one sums a column in theparent group.


For the label of each selected column in the DefaultLayout dialog box, and if there is room, forsummary labels. (For details, see “Rules aboutSummaries” on page 2 – 42.) B_ implies it is aboilerplate object.



B_columnname

F_columnname

R_groupname

2 – 11Defaulting

For each group for which you have selected one ormore labels in the Default Layout dialog box. M_implies it is a frame; HDR implies it is for theheader information (i.e., labels).

For each group that you selected in the DefaultLayout dialog box. (M_ implies it is a frame;GRPFR implies it is a group frame.M_groupname_GRPFR is used to protect all of thatgroup’s objects from being overwritten by otherobjects in the report.)

Appearance:

Layers: In general, if there is room for a frame and a repeating frame toappear on the same level (i.e., if they do not overlap), they will appearon the same level. In a tabular report with a parent/child relationship,the child’s frames and repeating frames overlap the parent’s framesand repeating frames; therefore, the child frame and repeating frameobjects are always placed on a level above those of the parent. Finally,all boilerplate and fields are still placed on the first level.

Print Conditions: The graphic below illustrates the Print Conditionsassigned to each object, where:

Indicates a Type/Object of All/Anchoring.

Indicates a Type/Object of Default/Anchoring.

Indicates a Type/Object of Last/Anchoring.

Indicates a Type/Object of All/Enclosing.

M_groupname_HDR

M_groupname_GRPFR

AA

DA

LA

AE

Tabular Rules

Mailing Label Reports

Mailing Label ReportRequirements


Note: Whenever a setting has Default as its default, it meansthat Oracle Reports will determine what the setting should beat runtime, based on the layout style the object is in, theobject’s settings, and the settings of the objects near it.

Rules: Below are rules for tabular reports with master/detail andcontrol–break data models:

1. Header (HDR) and footer (FTR) frames have a Horizontal Sizingand Vertical Sizing of Fixed.

2. The repeating frame of the inner–most detail has a HorizontalSizing and Vertical Sizing of Fixed, unless it contains a column witha datatype of LONG, in which case it has a Vertical Sizing ofExpanding.

3. All other frames and repeating frames have a Horizontal Sizing ofFixed, and Vertical Sizing of Expanding.

1. In Across reports, no labels for summaries will appear by default.

Note: For more information on rules on summaries and theirlabels, see “Global Layout Defaulting Rules” on page 2 – 41.

This section describes the layout requirements, object generation, andrules for the mailing label report layout style.


Default Layout Requirements In a group tree, all groups you selectmust be siblings (i.e., not parent groups and children groups). Thereport group is an exception; it is treated like a sibling group. See thefigure below for an example of valid and invalid selected groups.

Mailing Label ReportDefaulting


2 – 13Defaulting

This section is divided into two sections:

• single–group defaulting (i.e., when only one group is selected)

• multiple–group defaulting (i.e., when multiple groups areselected)

Note: This section describes defaulting for Down reports, only.For other Repeat directions, the layout is identical, except thatthe default repeating frame will have a corresponding Printdirection.

Assume you only have one group tree, you selected only one group,and that group owns two columns.




F_columnname

R_groupname



Appearance:

Layers: Objects must be on a layer above the objects that enclose them.For example, fields must be on a layer above the repeating frame thatencloses them.

Print Conditions: All objects have a Print Condition Type/Object ofDefault/Anchoring.

Mailing label reports produced with two or more selected siblinggroups are almost identical to those produced with only one selectedgroup. The only difference is that the default layout for the first groupappears above the second. See the figure below for an example.

Rules: Below are rules for mailing label reports with multiple groupsselected:

1. Oracle Reports creates the default layout objects for each selectedgroup in the following manner: 1) find the bottom left–mostselected group; 2) move up the tree one node and check forsiblings, recursively. For example, assume that the shaded groupsin the figure below are the groups you selected. In your defaultlayout, group 5 would appear above all other groups, and group 4would appear above group 2.

Mailing Label Rules

Form Reports

Form ReportRequirements

Form Report Defaulting


2 – 15Defaulting

1. In a group tree, all groups you select must be siblings (i.e., notparent groups and children groups). The report group is anexception.

2. A field created for a column with a LONG datatype has aHorizontal and Vertical Sizing of Fixed. As a result, the data of thatfield will be truncated if the size of the data is greater that the sizeof the field.

This section describes the layout requirements, object generation, andrules for the form report layout style.

Data Model Requirements You can use any type of data relationship

Default Layout Requirements In a group tree, all groups you selectmust be siblings. The report group is an exception; it is treated like asibling group.


• defaulting when only one group is selected

• defaulting when multiple groups are selected

Note: This section describes defaulting for Down reports, only.For other Repeat directions, the layout is identical, except thatthe default repeating frame will have a corresponding Printdirection.



For the label of each selected column in the DefaultLayout dialog box. B_ implies it is a boilerplateobject.

B_columnname





Appearance:

Layers: Objects must be on a layer above the objects that enclose them.For example, fields must be on a layer above the repeating frame thatencloses them.


Form reports produced with two or more selected sibling groups arealmost identical to those produced with only one selected group. Theonly difference is that the default layout for the first group appearsabove the second. See the figure below for an example.

F_columnname

R_groupname

Form Rules

Form Letter Reports

Form Letter ReportRequirements

Form Letter ReportDefaulting


2 – 17Defaulting

1. To ensure that only one set of records is printed on each form, theMaximum Records per Page setting of each repeating frame is 1.Also, the Page Break Before setting for the repeating frame isselected (but is ignored for the first record).

2. If a repeating frame owns a LONG field (i.e., a field with a Sourceof a column with a LONG datatype), the repeating frame will havea Horizontal Sizing of Fixed, and Vertical Sizing of Variable.Otherwise, it will have a Vertical Sizing of Fixed.

3. If there is no room for both a field and its label to fit at the end of aline, they will both be moved to the next line.

This section describes the layout requirements, object generation, andrules for the form letter report layout style.


Default Layout Requirements In a group tree, all groups you selectmust be siblings. The report group is an exception; it is treated like asibling group.




Note: This section describes defaulting for down reports, only.Across form letter reports are transposed down form letterreports. For other Repeat directions, the layout is identical,except that the default repeating frame will have acorresponding Print direction.



For each group that you selected in the DefaultLayout dialog box. B_ implies it is a boilerplateobject.


B_groupname

F_columnname


In form letters, fields are hidden. A hidden field’sdata does not appear in the place in which it islocated in the editor; instead, its data appearswhere the hidden field is referenced in its relatedboilerplate object. (The related boilerplate object isthe boilerplate object created for the group thatowns the field’s column). To reference a hiddenfield, type &fieldname in the field’s relatedboilerplate object.


Note: &fieldnames seen in the editor are simply text of theboilerplate object. At runtime, the field’s content will appearwhere the &fieldname appears.

Appearance:

Layers: Objects must be on a layer above the objects that enclose them.For example, boilerplate and fields must be on a layer above theirenclosing repeating frame. In form letter reports, the boilerplate isplaced on a layer above the hidden fields. And the hidden fields andthe boilerplate are on layers above their enclosing repeating frame.


R_groupname


Form Letter Report Rules

2 – 19Defaulting

Form letter reports produced with two or more selected sibling groupsare almost identical to those produced with only one selected group.The only difference is that the default layout for the first group appearsabove the second. See the figure below for an example.

1. The repeating frame must enclose its boilerplate object. It has aMaximum Records per Page setting of 1, and its Page Break Beforesetting is selected (but is ignored for the first instance).

2. The repeating frame’s width is the width of the logical page, minusthe margin; its length is the length of the field references(&fieldname), plus a little more, so that it can surround thereferences.

3. Hidden fields may only be referenced within a boilerplate object,and the reference must be in the form of &fieldname.

4. A hidden field may be referenced in a boilerplate object that is notowned by that hidden field’s repeating frame.

5. A hidden field may, but is not restricted to have the same PrintCondition as its related boilerplate object.

6. All hidden fields have a Horizontal Sizing of Variable, and a VerticalSizing of Fixed.

7. Parameters do not become hidden fields. To reference a parameter,create a field that has a source of the parameter, then reference thefield.

Master/Detail Reports

Master/Detail ReportRequirements

Master/Detail ReportDefaulting



This section describes the layout requirements, object generation, andrules for the master/detail report layout style.

Data Model Requirements You can use any type of data relationship

Default Layout Requirements A cross product group may not beselected. In a group tree, all children of the highest–selected groupmust have the same initial Repeat direction. For more information onthis requirement, see “Tabular Report Requirements” on page 2 – 6.




Note: This section describes defaulting for down reports, only.Across master/detail reports are transposed Downmaster/detail reports. For more information on how totranspose a report, see “Global Layout Defaulting Rules” onpage 2 – 41.

Assume you selected only one group, and that group owns twocolumns. The defaulting for this type of report is identical to that of asimple tabular report. For more information, see “Tabular Reports” onpage 2 – 6.


2 – 21Defaulting

Master/Detail report layouts are almost identical to Tabular reportlayouts. The only difference is that if there is a parent/childrelationship (a link) between two selected groups, the parent group isformatted like a Form report, and the child group(s) are formatted likea Tabular report. For example, the parent group in a tabular report:

Deptno looks like this in master/detail: Deptno Deptno

––––––

Deptno

This section is divided into four sections:

• one group tree with multiple groups selected, all of which aresiblings

• multiple group trees with multiple groups selected, all of whichare siblings

• one group tree with multiple groups selected, some of which areparents of others

• multiple group trees with multiple groups selected, some ofwhich are parents of others

Single Group Tree, All Siblings Assume you only have one group tree,you selected two sibling groups, and each group owns two columns.The defaulting for this type of report is identical to that of a tabularreport with two groups. For more information, see “Tabular Reports”on page 2 – 6.


Multiple Group Tree, All Siblings Assume you have two group trees,you selected two groups from each—all of which are siblings—andeach group owns two columns. See the figure below for an example.

The defaulting for this type of report is identical to that of a tabularreport with two groups. For more information, see “Tabular Reports”on page 2 – 6.

2 – 23Defaulting

Single Group Tree, Parents and Children Assume you only have onegroup tree, you selected three groups—one of which is the parent of theother two—and each group owns two columns. See the figure belowfor an example.



For the label of each selected column in the DefaultLayout dialog box, and if there is room, forsummary labels. B_ implies it is a boilerplateobject.



For each group for which you have selected one ormore labels in the Default Layout dialog box. M_implies it is a frame; HDR implies it is for theheader information—i.e., labels.

For each group that you selected in the DefaultLayout dialog box. M_ implies it is a frame;GRPFR implies it is a group frame.M_groupname_GRPFR is used to protect all of thatgroup’s objects from being overwritten by otherobjects in the report.

Appearance:

B_columnname

F_columnname

R_groupname

M_groupname_HDR

M_groupname_GRPFR

2 – 25Defaulting

Layers: In general, if there is room for a frame and a repeating frame toappear on the same level (i.e., if they do not overlap), they will appearon the same level. In a master/detail report, a child group’s framesand repeating frames overlap its parent’s frames and repeating frames;therefore, the child’s frames and repeating frames are always placed ona level above those of the parent. Finally, all boilerplate and fields arestill placed on the first level.


Multiple Group Tree, Parents and Children (with Summaries) Assumeyou only have one group tree, you selected three groups—one of whichis the parent of the other two—and each group owns two columns. Seethe figure below for an example. Assume also that group 1 owns asummary that sums a field in group 2.

Generated Objects: The following objects are generated in addition tothose created for the ”Single Group Tree, Parents and Children” report:

For each group that owns a report summary thatyou selected in the Default Layout dialog box. M_implies it is a frame; FTR implies it is footer frame.M_groupname_FTR is used to protect all summaryfields for that group from being overwritten byother objects in the report.

M_groupname_FTR


Appearance:

Note: If a parent is selected (e.g., group 1), its siblings (e.g.,groups siblings 3 and 4) appear beside each other. If no parentis selected, or if the report group is selected, siblings (e.g.,groups 1 and 2) appear one above the other. (The upper–leftmost sibling in the group tree will appear above its othersiblings.)

Layers: If there is room for a frame or a repeating frame to appear onthe same level (i.e., if they do not overlap), they will be on the samelevel. In a master/detail report, a child group’s frames and repeatingframes overlap its parent’s frames and repeating frames; therefore, thechild’s frames and repeating frames are always placed on a level abovethose of the parent. Finally, all boilerplate and fields are still placed onthe first level.


Matrix Reports

Matrix ReportRequirements

Matrix Report Defaulting

Matrix Defaultingwithout Summaries

2 – 27Defaulting

This section describes the layout requirements, object generation, andrules for the matrix report layout style.

Data Model Requirements You must have a matrix, nested matrix, ormatrix break data model. The data model must have at least fourgroups, one of which must be a cross product group. For moreinformation, see the Building Reports Manual.

Note: For data models that require a break group, you shouldcreate the break group before creating the cross–product group.If the cross–product group already exists, delete it, create thebreak group(s), and then recreate the cross–product group.

Matrices and Summaries When creating summaries that will appearwithin the matrix, the summary must be owned by the cross productgroup and must have Product Order specified. Oracle Reports uses theProduct Order to determine where to place the fields for the summariesin the layout. (Note that summaries owned by the cross–product groupcannot have a Reset At or Compute At of Page or rely on columns thatdo.)

Default Layout Requirements You must select the cross product group,and at least two of the groups inside of it.

This section is divided into six sections:

• matrix defaulting without summaries

• matrix defaulting with summaries

• nested matrix defaulting without summaries

• nested matrix defaulting with summaries

• matrix break defaulting without summaries

• matrix break defaulting with summaries

Assume you only have one group tree, you selected the cross productgroup, two groups inside of it, and one group below it. Assume thateach group contains one column.

Generated Objects: Your Layout editor will contain the followingobjects:

For the label of each selected column in the DefaultLayout dialog box. (B_ implies it is a boilerplateobject.)

For each column that you selected in the DefaultLayout dialog box. (F_ implies it is a field.)

B_columnname

F_columnname


For each group that you selected in the DefaultLayout dialog box. (R_ implies it is a repeatingframe.)

For each group that you selected in the DefaultLayout dialog box. (M_ implies it is a frame; HDRimplies it is a header frame. M_groupname_HDR isused to protect field labels from being overwrittenby other objects in the report.)

For each pair of repeating frames that intersect toform the matrix. By multiplying the number ofacross dimensions by the number of downdimensions, you can calculate the number ofmatrix objects created. In this case, one dimensiongoing down multiplied by one dimension goingacross yields one matrix object.

Appearance:

Layers: Objects must be on a layer above the objects that enclose them.For example, boilerplate and fields must be on a layer above theirenclosing repeating frame. In matrix reports, the matrix object must beon a layer above the repeating frames that it relates (i.e., theacross/down dimension repeating frames). The across dimensionrepeating frame also must be on a layer above the down dimensionrepeating frame.

R_groupname

M_groupname_HDR

X_groupname

Matrix Defaultingwith Summaries

Matrix Defaulting withSummary of Child Group

2 – 29Defaulting

Assume you only have one group tree, you selected the cross productgroup, the two groups inside of it (each of which has one column), thechild group, and three summary columns. One summary column thatsums salary by department, one that sums salary by job, and one thatsums all salaries in the report.

Generated Objects: The objects generated are the same as a matrixreport without summaries, except for the additional fields andboilerplate for the summary columns.

Appearance:

Layers: The layers are almost identical to those of a matrix reportwithout summaries. The only difference is the fields and boilerplatethat appear for the summary columns on a layer above the frames andrepeating frames that contain them.

Assume you only have one group tree, you selected the cross productgroup, two groups inside of it (each of which has one column), and thecross product–level summary of the child group. The child group isnot selected because the cross product–level summary is the source ofthe field inside the matrix object.

Generated Objects: The objects generated are almost identical to amatrix report without summaries. The difference is the absence of arepeating frame for the child group.

Nested MatrixDefaulting without

Summaries


Appearance:

Layers: The layers are almost identical to those of a matrix reportwithout summaries. The differences are that the repeating frame is notgenerated for the child group (because it is not selected).

Assume you only have one group tree, you selected the cross productgroup, three groups inside of it (one of which is the parent of one of thegroups), and one group below it. Assume that each group contains onecolumn.






B_columnname

F_columnname

R_groupname

M_groupname_HDR

Nested MatrixDefaulting with

Summaries

2 – 31Defaulting

For each pair of repeating frames that intersect toform the matrix. By multiplying the number ofacross dimensions by the number of downdimensions, you can calculate the number ofmatrix objects created. In this case, twodimensions going down multiplied by onedimension going across yields two matrix objects.

Appearance:

Layers: Objects must be on a layer above the objects that enclose them.For example, boilerplate and fields must be on a layer above theirenclosing repeating frame. In matrix reports, the matrix object must beon a layer above the repeating frames that it relates (i.e., theacross/down dimension repeating frames). The innermost matrixobject must be on a layer above the outermost matrix object. The childdimension repeating frame must be on a layer above the parentdimension repeating frame.

Assume you only have one group tree, you selected the cross productgroup, four groups inside of it, and one group below it. Assume thateach group contains one column.

Generated Objects: The objects generated are almost identical to thenested matrix report without summaries. The difference is that youhave two dimensions going across the top of the matrix instead of one.Consequently, you have two across repeating frames instead of one. Inaddition, fields and boilerplate are generated for the summaries.

The fields are placed in the layout according to the position andProduct Order of their source columns in the data model. Below is alist of the summaries (their numbers correspond to the numbers in thediagram that follows):

X_groupname


Owned by cross–product group. Product Order:all possible combinations of all four groups(G_State, G_City, G_Dept, G_Job).

Owned by cross–product group. Product Order:G_State, G_Job, G_Dept.

Owned by cross–product group. Product Order:G_Job, G_Dept.

Owned by cross–product group. Product Order:G_Dept, G_State, G_City.

Owned by cross–product group. Product Order:all possible combinations of G_State and G_Dept.

Owned by cross–product group. Product Order:G_Dept

Owned by cross–product group. Product Order:G_State, G_City

Owned by cross–product group. Product Order:G_State

Owned by the report. Because this summary is notwithin the matrix (i.e., it is owned by the report), ithas no Product Order.

Appearance:

1

2

3

4

5

6

7

8

9

Matrix Break Defaultingwithout Summaries

2 – 33Defaulting

Layers: The layers are identical to those of the nested matrix reportwithout summaries. The only differences are the fields and boilerplatethat appear for the summary columns, the additional across repeatingframe, and the two additional matrix objects.

Assume you only have one group tree, you selected the cross productgroup, a group that is its parent, two groups inside of it, and one groupbelow it. Assume that each group contains one column.






For each pair of repeating frames that intersect toform the matrix. By multiplying the number ofacross dimensions by the number of downdimensions, you can calculate the number ofmatrix objects created. In this case, twodimensions going down multiplied by onedimension going across yields two matrix objects.

B_columnname

F_columnname

R_groupname

M_groupname_HDR

X_groupname

Matrix Break Defaultingwith Summaries


Appearance:

Layers: Objects must be on a layer above the objects that enclose them.For example, boilerplate and fields must be on a layer above theirenclosing repeating frame. In matrix reports, the matrix object must beon a layer above the repeating frames that it relates (i.e., theacross/down dimension repeating frames). The across dimensionrepeating frame also must be on a layer above the down dimensionrepeating frame.

Assume you only have one group tree, you selected the cross productgroup, a group that is its parent, two groups inside of it, one groupbelow it, and three summary columns. One summary column thatsums salary by department, one that sums salary by job, and one thatsums all salaries by year.

Generated Objects: The objects generated are the same as a matrixbreak report without summaries, except for the additional fields andboilerplate for the summary columns.

Matrix Restrictions

2 – 35Defaulting

Appearance:

Layers: The layers are identical to those of the matrix break reportwithout summaries. The only differences are the fields and boilerplatethat appear on Layer 0 for the summary columns.

1. A cross–product group cannot contain another cross–productgroup (i.e., cross–product groups cannot be nested within eachother).

2. A cross–product group must have a child group. Thecross–product group contains the dimensions of a matrix and itschild is needed to fill the dimensions with data. Without the child,the data model would make no sense.

3. A cross–product group cannot have a filter on it.

4. A cross–product group cannot contain a placeholder column.

5. A cross–product group must contain at least two dimensiongroups. A matrix requires at least two dimensions (one goingacross and one going down) and, as a result, the cross–productmust contain at least two groups.


6. In multi–query data models, you need more than two queriesbecause separate queries are required for the down and acrossdimensions. You need at least two queries because dimensiongroups from the same query must have repeating frames with thesame Print Direction. Consequently, if you did not have two ormore queries in the cross–product group, your dimensions wouldeither be all down or all across dimensions, which wouldn’t makeany sense. In addition to having separate queries for dimensions,the data for the matrix cells must also be selected by a separatequery.

For example, in the data model below, one query (Q_YrD) selectsvalues for the down dimensions (year and department) and onequery (Q_Job) selects values for the across dimension (job).Another query (Q_Sum) selects the data for the matrix cells. In thiscase, it would be invalid to have only one query for YEAR,DEPTNO, and JOB. In addition, it would be invalid to have SALselected by Q_YrD or Q_Job.

7. For multi–query data models with cross–product groups, thefollowing rules apply:

• You cannot create links between cross–product groups or theircontents.

2 – 37Defaulting

• You cannot create links between the children of cross–productgroups and queries whose groups are contained in cross–productgroups. This would create a circular dependency.

• You cannot create links between the children of cross–productgroups and queries whose groups are the parents ofcross–product groups. This would create a circular dependency.

• You cannot create a direct link between a dimension group (agroup inside the cross–product group) and anything outside ofthe cross–product group. All links that go outside of thecross–product group emanate from the cross–product group.

• You cannot create a link the cross–product group to its parent orone of its dimension groups.

8. If you have a multi–query data model, then all of the groups of aquery must either be inside or outside of the cross–product group.You cannot have some of a query’s groups inside and some outsideof the cross–product group. (Note that in single–query datamodels, a query can have some of its groups inside and some of itsgroups outside of the cross–product group.)

9. Matrix objects cannot be anchored to anything (i.e., they may notbe the parent or child object for an anchor).

10. When you create layout objects for a matrix report, you must becareful where you place them. You need to place objects such thatit is clear where you want the object to appear. In the diagrambelow, objects B_1, B_2, B_3, B_4, and B_5 are placed ambiguously.Oracle Reports would be unable to determine whether the objectsshould appear beside, above, or below the nearest repeating frame.For example, it is impossible to tell whether B_3 should appearbelow R_D_2 or to the right of R_D_2. A layout like the one belowwould cause unpredictable results.


In the diagram below, objects B_1, B_2, B_3, B_4, and B_5 areplaced correctly. It is clear to Oracle Reports where the objectsshould appear in relationship to the repeating frames.

Note: If the objects in the layout above had Expand or Variablesizing and grew such that their positioning became ambiguous,an error would be raised when you ran the report. Forexample, if object B_2 grew horizontally beyond the right edgeof R_A_2, an error would be raised. Similarly, an objectanchored to B_2 would also need to be able to fit within theboundary defined by R_A_2.

11. While you can have matrices with nested dimensions (i.e., a nestedmatrix report), you cannot have one matrix contained entirelyinside another matrix. For example, the layout below is invalidand would cause and error when run:

2 – 39Defaulting

12. Layout objects that you want to appear inside the matrix must beentirely within the border defined by the outermost repeatingframes of the matrix. In the diagram below, object B_1 wouldcause an error when the report is run. Object B_2 would not causean error.

13. The following areas in a matrix layout can only contain fixed sizedobjects:

• heading labels (designated by 1 in the diagram below)

• summary areas (designated 2 in the diagram below)

• title (designated by 3 in the diagram below)

14. The contents of the matrix cell (e.g., a repeating frame and/or afield) can have its Vertical Sizing be variable (i.e., Variable, Expand,or Contract). It cannot have its Horizontal Sizing be variable.


15. If you want a layout object to appear completely outside of thematrix, you should create a frame around the matrix and place theobject outside of the frame. This ensures that the matrix will notoverwrite the object.

16. You can put a border on a matrix object, its dimension repeatingframes, or the fields and repeating frames inside of it just as youwould any other object. The width, however, will always be theminimum width possible. You cannot widen the border due to thecloseness of the objects in a matrix layout.

17. If a repeating frame’s source group is a dimension group (i.e., agroup within a cross–product group), then the repeating framemust appear inside the repeating frame(s) of it’s source group’sancestors (if any). For example, in the data model shown below,the repeating frame with a source group of G_Dept would have tobe placed inside of the repeating frame with the source group ofG_Year.

2 – 41Defaulting

Global Layout Defaulting Rules

1. Unless otherwise noted, a group with a Repeat direction of Acrossdefaults identically as a group with a Repeat direction of Down,except that the default format is transposed. To quickly determinethe defaulting of an across group, do the following:

1.1 Draw the down layout for that group on translucent paper.

1.2 Turn the page over as you do to a page in a book.

1.3 Rotate the page counter–clockwise 90 degrees.

2. In form letter reports, all default fields are hidden, and have aHorizontal Sizing of Variable and a Vertical Sizing of Fixed. Inmailing label reports, all default fields have a Horizontal andVertical Sizing of Fixed. And, in all other reports (tabular, form,master/detail, and matrix reports), those fields have a Horizontaland Vertical Sizing of Fixed. The only exception to this rule isfound in the next rule.

3. If you select one the following columns in the Default Layoutdialog box:

• a CHAR column and you reduce its default Width in the DefaultLayout dialog box

• a LONG column

Oracle Reports will do the following for tabular, form,master/detail, and matrix reports: create a default field with aHorizontal Sizing of Fixed and a Vertical Sizing of Variable. As aresult, all of the field’s data will be displayed, instead of truncated,by word–wrapping any data to the next lines.

Caution: For form letter and mailing label reports, Oracle Reports willcreate a default field with a Horizontal and Vertical Sizing of Fixed. Asa result, the data of that field will be truncated if the size of the data isgreater than the size of the field.

4. When you default a layout, and one or more selected fields have aHorizontal or Vertical Sizing of Variable, Oracle Reports will do thefollowing for Down reports:

• create a frame called M_groupname_EXP that has a width equalto the width of the repeating frame that owns the variable–sizedfield, and a length of one field

• place the frame around that variable–width field and any otherfields that are found to the right or left of it

Rules AboutSummaries


It does this to ensure that all fields to the right and left of theVariable field begin to print ”on the same line,” even though theVariable field may span several lines.

Note: For Across reports, transpose the rule.

5. All fields and boilerplate have a Print Condition Type/Object ofDefault/Anchoring, except for matrices. (That is, it will take on thePrint Condition of the frame or repeating frame that owns it.)

6. Summaries that are owned by the report, not by a group, areallowed in all report layout styles. They are all formatted in thefollowing way:

• If the layout style is form, form letter, or mailing label, thesummary is a report column. A report column is formatted likeany other database column for that report style.

• If the layout style is tabular, master/detail, or matrix, and thecolumn on which the summary performs its function is notselected, the summary is a report column. (It is formatted as isstated in the bullet above.) Otherwise, the summary is a reportsummary. It is formatted left–justified at the end of the report,with the label to the left of the field (if there is room.

The following rules apply to tabular, master/detail, and matrixreports only.

7. A summary is defaulted like a database column if the column itsummarizes is not selected. Otherwise, a summary is defaultedlike summaries (i.e., appearing inside the M_groupname_FTRframes).

Header/Body/TrailerAlgorithm

2 – 43Defaulting

8. Oracle Reports places one summary type per–line, in the following order:

• SUM

• AVERAGE

• MINIMUM

• MAXIMUM

• COUNT

• FIRST

• LAST

• % OF TOTAL

• STANDARD DEVIATION

• VARIANCE

9. The summary label will appear to the far–left of the group footerframe (M_groupname_FTR). If there is not room for the full label,the label will be truncated.

Implicit Anchoring Algorithm

This section describes the algorithm that Oracle Reports uses to createimplicit anchors at runtime. This algorithm is the same for the header,body, and trailer regions. The margin algorithm differs slightly.

1. Determine which objects are not entirely enclosed by a repeatingframe of frame (directly or indirectly), or explicitly anchored to anobject that is enclosed by a frame or repeating frame (directly orindirectly). We’ll call these objects Type A objects. (Type A objectsare typically group frames, repeating frames, other objects youcreate that are not owned by a frame or repeating frame, etc..)

An object is considered to be enclosed by another object only if allof the following are true:

• Both objects belong to the same region (Body, Margin, Header, orTrailer).

• The outermost of the two objects is a frame or repeating frame.

• The outermost of the two objects is behind the other object.


• The innermost of the two objects lies entirely within the bordersof the other object.

2. Determine all children objects of a frame or repeating frame (theseare the non–Type A objects). We’ll call these objects Type B objects.

3. Follow this procedure for Type A and Type B objectsindependently:

3.1 Find all objects that are of the same type (e.g., Type A), and are on the same layer.

3.2 Determine which of those objects have potential to ”push”other objects of that type. An object has potential to ”push”object of that type if it has a Horizontal and/or Vertical Sizingof Variable or Expand, and a second object is located in its ”pushpath” (i.e., in the area in which it can possibly grow). Also, arepeating frame with a Horizontal and/or Vertical Sizing ofFixed or Contract has a ”push path”: its Repeat Direction.

3.3 Create pairs of objects found in step 3.2. Each pair mustcontain a pusher (i.e., the object that will grow) and a pushee(i.e., the object that will be pushed). When creating these pairs,a pushee object cannot be a child of an explicit anchor—thoseobjects are ignored.

3.4 Go through this loop. For each pair, determine the distance in the ”push path” between the pusher and pushee. Next, findthe pair with the shortest distance. Finally, create an implicitanchor between those two objects using this algorithm:

– If the ”push path” direction is Down, anchor the pusheeobject’s top 0% to the pusher object’s bottom 0%.

– If the ”push path” direction is Across, anchor the pusheeobject’s left 0% to the pushed object’s right 0%.

That pair is now treated like one object, and the loop continues until either all objects have one anchor, or nothingwill push the remaining, unanchored objects.

3.5 For each remaining, unanchored object, create an implicitanchor from the top–left corner of the object to the top–leftcorner of the region (header, body, or trailer).

3.6 Move to the next layer, and follow the procedure starting atstep 1.

2 – 45Defaulting

Rules:

1. If an object is in the ”push path” of two other objects and it isequidistant from the other two objects, the implicit anchoring of theobject may vary between executions of the report. For example, thedrawing below shows two cases where this could occur:

Margin Algorithm


In the first case, M_Sums is in the ”push path” of both B_Text1 andR_Ename. Because M_Sums is equidistant from B_Text1 andR_Ename, though, Oracle Reports’ normal criteria (shortestdistance) for determining implicit anchors does not work in thiscase. Consequently, Oracle Reports will randomly create animplicit anchor between M_Sums and either B_Text1 or R_Enameat runtime. To avoid this behavior, you could create an explicitanchor between M_Sums and B_Text1 or R_Ename.

In the second case, B_Text3 is in the ”push path” of M_Emp. Sincethe bottom edges of M_Emp and R_Mgr are virtually in the sameposition, though, Oracle Reports cannot determine whether toimplicitly anchor B_Text3 to M_Emp or R_Mgr. Consequently,Oracle Reports will randomly create an implicit anchor betweenB_Text3 and either M_Emp or R_Mgr at runtime. To avoid thisbehavior, you could create an explicit anchor from B_Text3 to oneof the objects or remove the explicit anchor between R_Ename andB_Text2. Removing the explicit anchor would cause Oracle Reportsto treat R_Mgr as a descendant of M_Emp and, therefore, theimplicit anchor would always be created between B_Text3 andM_Emp.

(Note that Case 2 is most likely to occur in character mode, whereit is common to have the edges of objects overlap in the Layouteditor.)

Create implicit anchors for all Type B objects this region using theHeader/Body/Trailer Algorithm. For each Type A object, however,create an implicit anchor from the top–left corner of the object to thetop–left corner of the margin. No Type A object will be implicitlyanchored to another Type A object. (This ensures that Type A objectswill not be pushed off the page. However, they may be overwritten byanother Type A object, if they are found on the same layer.)

Header/Margin/Body/Trailer Algorithm

Object Defaulting

Fields

2 – 47Defaulting

Print Condition Algorithm

This section describes the algorithm that Oracle Reports uses to definean object’s Print Condition at runtime. This algorithm is the same forthe header, body, and trailer regions.

1. If you specified a Print Condition for an object, Oracle Reports usesthat condition.

2. If you specified a Print Condition Type of *Default, then OracleReports sets it to either *First or *Last. If the object is a child of animplicit or explicit anchor and its parent has a Print Condition Typeof All, All but First, or All but Last, Oracle Reports sets it to *Firstand Enclosing. If the object is a child of an implicit or explicitanchor and its parent has any other Print Condition Type, OracleReports sets it to *Last. Otherwise, for objects that are implicitlyanchored to the region (header, body, or trailer), Oracle Reportssets it to *First.

Parameter Form Defaulting

When you create a default Runtime Parameter Form for your report,Oracle Reports will create the following parameter form objects foryou:

• default fields

• default boilerplate

The circumstances under which Oracle Reports creates these objects aredescribed below.

Objects Created/Circumstances Oracle Reports will create one field foreach parameter that is selected in the Default Parameter Form dialogbox (it is named F_parametername).

Ownership The field is not owned by other parameter form objects.

Boilerplate


Ordering The fields will appear in the order in which the parametersappear in the Default Parameter Form dialog box. The dialog boxorders the parameters in the following way: first, all defaultparameters appear in the following order—DESTYPE, DESNAME,DESFORMAT, COPIES, CURRENCY, THOUSANDS,DECIMAL—next, all user–created parameters appear in the order inwhich they appear in the Parameter property sheet. (Specifically, auser–created parameter above, or to the left of other user–createdparameters will have its fields appear above others (if two parametershave the same x coordinate, the parameter above the second willappear in the Default Parameter Form dialog box above the secondparameter).

Name: F_parametername

Datatype: Is the datatype on the Parameterproperty sheet.

Source: Is the source on the Parameter propertysheet.

Objects Created/Circumstances Oracle Reports will create oneboilerplate object for each label selected in the Default Parameter Formdialog box (it is name B_parametername).

Ownership The boilerplate is not owned by other parameter formobjects.

Name: B_parametername

Type: Is the datatype on the Parameter propertysheet.

Settings

Settings

C H A P T E R

3T

3 – 1Menus

Menus

he menu items for Oracle Reports are described in the online helpsystem. Select Help—>Contents for more information.

C H A P T E R

4R

4 – 1Report Properties

Report Properties

eport properties are properties that you define for your report as awhole. When you select a report in the Object Navigator anddouble–click on its node or select Tools—>Properties, its Reportproperty sheet, shown below, is displayed.

The Report property sheet is divided into the following tabs:

• Report – 4 – 2

• Parameter Form – 4 – 10

• Character Mode – 4 – 11

• Comment – 4 – 15


Report Tab of Report Property Sheet

The Report tab of the Report property sheet is shown below. Itcontains the following properties:

• Direction – 4 – 3

• Logical Page Size – 4 – 2

• Maximum Body Pages – 4 – 5

• Maximum Header Pages – 4 – 5

• Maximum Trailer Pages – 4 – 6

• Page Height – 4 – 6

• Page Width – 4 – 7

• Panel Print Order – 4 – 7

• Unit of Measurement – 4 – 9

Direction

Logical Page Size


Is the reading direction for the entire report.

Required/Optional: Required.

Default means that the reading direction isdetermined by the NLS environment variables.

Left to Right

Right to Left

Is the dimensions of the logical page (report page) in physical pages(printer pages). For instance, a logical page size of 1 x 1 means there isone physical page for each logical page. For another example, look at”Examples” below. Note: Logical Page Size is not necessarily thenumber of physical pages that the report will require when printed.


Enter any dimensions of the form A x B, where Aand B are whole numbers from 1 through 50.

1 x 1

Examples:

1. In the following illustration, one logical page is made up of sixphysical pages. The logical page is three physical pages wide andtwo physical pages high. Consequently, the Logical Page Size is 3 x2. If you wanted the logical page to be two physical pages wideand three physical pages high, you would specify a Logical PageSize of 2 x 3.

Options:

Options:

Default:


Panels are the representations of the physical pages within a logicalpage. Notice in the following illustration that the physical pagescontinue to number sequentially from the first logical page to thesecond, while the panel numbers reset; e.g., the first panel ofLogical Page 1 is Physical Page 4, while the first panel of LogicalPage 2 is Physical Page 8.

Notice that the header and trailer pages are of a different width.This is because both header and trailer pages are only one physicalpage wide.

Maximum Body Pages

Maximum HeaderPages


Rules

1. Logical Page Size applies to the body/margin pages of a report.Header pages and trailer pages have independent logical sizes.They are both one physical page wide, while their heights aredetermined by the positions of the objects on the pages.

Is the maximum number (wide and tall) of body pages you want toappear in your report.


Enter any dimensions of the form A x B, where Aand B are whole numbers from 1 through 999.

10

Is the maximum number of header pages you want to appear in yourreport.


Enter a whole number from 1 through 999.

Options:

Default:

Options:

Maximum TrailerPages

Page Height


10

Is the maximum number of trailer pages you want to appear in yourreport.


Enter a whole number from 1 through 999.

10

Is the height of one physical page (including the margin) in the Unit ofMeasurement (e.g., 11 inches).


Enter a valid height of zero or more. Themaximum height depends upon the unit ofmeasurement. For inches, the maximum height is512 inches. For centimeters, it is 1,312 centimeters.For picas, it is 36,864 picas.

Note that the page must be large enough to containthe report. For example, if a frame in a reportexpands to a size larger than the Page Height, thereport will not run.

11 inches

Rules:

1. If you change the Unit of Measurement after you have alreadyspecified the Page Height, the Page Height will automaticallychange to the approximate height in the new Unit of Measurement.

2. If you change the width or height of the physical page, the size ofthe logical page will change accordingly, so that the dimensions ofthe margin are preserved wherever possible.

Caution: On some printers the printable area of the physical page isrestricted. For example, the sheet of paper a printer takes may be 8.5 x11 inches, but the printer might only be able to print on an area of 8 x10.5 inches. If you define a Page Width x Page Height in OracleReports that is bigger than the printable area your printer allows,clipping may occur in your report output. To avoid clipping, you caneither increase the printable area for the printer (if your operatingsystem allows it) or you can set the Page Width x Page Height to be thesize of the printable area of the page.

3. You can override the dimensions of a page by specifying differentvalues for the PAGESIZE parameter on the command line.

Default:

Options:

Default:

Options:

Default:

Page Width

Panel Print Order


4. The default top and bottom margin is a half an inch each.

Is the width of one physical page (including the margin) in the Unit ofMeasurement (e.g., 8.5 inches).


Enter a valid width of zero or more. Themaximum width depends upon the unit ofmeasurement. For inches, the maximum width is512 inches. For centimeters, it is 1,312 centimeters.For picas, it is 36,864 picas.

Note that the page must be large enough to containthe report. For example, if a frame in a reportexpands to a size larger than the Page Width, thereport will not run.

8.5 inches

Rules:

Caution: On some printers the printable area of the physical page isrestricted. For example, the sheet of paper a printer takes may be 8.5 x11 inches, but the printer might only be able to print on an area of 8 x10.5 inches. If you define a Page Width x Page Height in OracleReports that is bigger than the printable area your printer allows,clipping may occur in your report output. To avoid clipping, you caneither increase the printable area for the printer (if your operatingsystem allows it) or you can set the Page Width x Page Height to be thesize of the printable area of the page.

1. If you change the Unit of Measurement after you have alreadyspecified the Page Width, the Page Width will automatically changeto the approximate width in the new Unit of Measurement.

2. If you change the width or height of the physical page, the size ofthe logical page will change accordingly, so that the dimensions ofthe margin are preserved wherever possible.

3. You can override the dimensions of a page by specifying differentvalues for the PAGESIZE parameter on the command line.

4. The default right and left margin size is zero.

Is the order in which the physical pages comprising a logical pageshould be printed. It also determines the order in which panels arenumbered within the logical page. The figure below illustrates logicalpages, physical pages, and panels.

Options:

Default:



Across/Down means the physical pages of the reportbody will print left–to–right then top–to–bottom.

Down/Across means the physical pages of the reportbody will print top–to–bottom and thenleft–to–right.

Across/Down

Examples:

1. Suppose that you have a logical page size of 2 x 2 (i.e., the logicalpage is two physical pages wide and two physical pages tall). IfPanel Print Order were Across/Down, the order in which thephysical pages would print for each logical page would be asfollows:

Options:

Default:

Unit of Measurement


If Panel Print Order were Down/Across, the order in which thephysical pages would print for each logical page would be asfollows:

Is the standard of measure used to specify the dimensions of the reportand the parameter form.


Centimeter

Inch

Point is a printer’s type size that makes up a pica.Each pica contains twelve points and is equivalentto one–sixth of an inch.

Inch

Options:

Default:

Form Height

Form Width


Parameter Form Tab of Report Property Sheet

The Parameter Form tab of the Report property sheet is shown below.It contains the following properties:

• Form Height – 4 – 10

• Form Width – 4 – 10

• Number of Pages – 4 – 11

• Previewer Title – 4 – 11

Is the height of one parameter form page in the Unit of Measurement.


Enter a valid height of zero or more. Themaximum height depends upon the unit ofmeasurement. For inches, the maximum height is512 inches. For centimeters, it is 1,312 centimeters.For picas, it is 36,864 picas.

Default: 4 inches or 10 centimeters or 300 points

Rules:

1. If you change the Unit of Measurement after you have alreadyspecified Form Height, the Form Height will change automaticallyto the approximate height in the new Unit of Measurement.

Is the width of one parameter form page in the Unit of Measurement.


Options:

Number of Pages

Previewer Title


Enter a valid width of zero or more. Themaximum width depends upon the unit ofmeasurement. For inches, the maximum width is512 inches. For centimeters, it is 1,312 centimeters.For picas, it is 36,864 picas.

4 inches or 10 centimeters or 300 points

Rules:

1. If you change the Unit of Measurement after you have alreadyspecified the Form Width, the Form Width will changeautomatically to the approximate width in the new Unit ofMeasurement.

Is the total number of pages you want in your Runtime Parameterform.


Enter a number from 1 through 9,999.

1

Is the text that appears at the top of the Previewer. To change thedefault title, type the desired text in the field provided. For moreinformation, see “Previewer” on page 11 – 1.

Enter an alphanumeric string not to exceed 256bytes. You can restore the default title by deletingwhatever title text you entered yourself.

Character Mode Tab of Report Property Sheet

The Character Mode tab of the Report property sheet is shown below. Itcontains the following properties:

• Convert Bit–Mapped Objects to Boxes – 4 – 12

• Convert Borders – 4 – 13

• Disable Host – 4 – 13

• Disable Split – 4 – 13

• Disable Zoom – 4 – 13

• Previewer Hint Line – 4 – 13

• Previewer Status Line – 4 – 14

Options:

Default:

Options:

Default:

Options:

Convert Bit–mappedObjects to Boxes


• Report Width x Height – 4 – 14

• Start in Zoom – 4 – 15

• Suppress Previewer Title – 4 – 15

• Use Character Units in Designer – 4 – 15

Some character–mode settings (Use Character Units in Designer,Convert Bit–Mapped Objects to Boxes, Convert Borders) apply tocharacter–mode output. These settings take effect whenever you areviewing character mode output (e.g., previewing ASCII output in thePreviewer) Other settings (e.g., Start in Zoom) apply to thecharacter–mode environment and only take effect when running thereport in a character–mode environment.

Oracle Reports is designed to support the native look–and–feel of theenvironment on which it is running. Therefore, the GUI andcharacter–mode versions of Oracle Reports differ in some respects. Forexample, character–mode Oracle Reports has a Host item in the Filemenu. This menu item enables the user to access the operating systemfrom Oracle Reports. In GUI Oracle Reports, this feature isunnecessary because the operating system can be accessed in otherways.

Converts all bit–mapped objects (i.e., Oracle Graphics displays andboilerplate objects except for text, lines, and rectangles) to boxes whenthe report is run in character mode. If this setting is unchecked, allbit–mapped objects and any explicit anchors to them will be deletedwhen the report is run in character mode.

Convert Borders

Disable Host

Disable Split

Disable Zoom

Previewer Hint Line


Unchecked.

Rules:

1. Lines that are not horizontal or vertical will always be converted tohorizontal or vertical lines in character mode, regardless of thissetting. Similarly, rotated rectangles will be converted tonon–rotated rectangles in character mode, regardless of this setting.

Turns on borders in character mode for any objects that have a linewidth greater than zero in bit–mapped. If you do not check thissetting, all borders are turned off in character mode. Specifying thisand Use Character Units in Designer causes the Layout Editor todisplay character–mode borders for objects with line widths greaterthan zero.

Unchecked.

Disables the Host item in the File menu in both the Runtime ParameterForm and the Previewer. The Host item appears in the File menu ofcharacter–mode Oracle Reports.

Unchecked.

Disables the [Split Vertical] and [Split Horizontal] function keys.

Unchecked.

Disables the [Zoom/Unzoom] function key in the Previewer.

Unchecked.

Rules:

1. If Disable Zoom and Start in Zoom are both checked, the Previewerwill be started in zoom and you will be unable to toggle out ofzoom.

Is the line of the Previewer that is displayed on the second to last line ofyour screen. To change the default hint line, select the check box nextto Previewer Hint Line and type the desired text. You can restore thedefault hint line by deleting whatever hint text you entered yourself.For more information about the Previewer, see “Previewer” on page11 – 1.

Enter an alphanumeric string not to exceed 80bytes.

Unchecked and blank.

Default:

Default:

Default:

Default:

Default:

Options:

Default:

Previewer Status Line

Report Width x Height


Rules:

1. If Previewer Hint Line is unchecked, Oracle Reports does notreserve a line for it. This enables you to see one more line of yourreport output per screen.

Is the last line of the Previewer. To change the default status line, selectthe check box next to Previewer Status Line and type the desired text.You can restore the default status line by deleting whatever status linetext you entered yourself. For more information about the Previewer,see “Previewer” on page 11 – 1.

Enter an alphanumeric string not to exceed 80bytes.

Unchecked and blank.

Rules:

1. If Previewer Status Line is unchecked, Oracle Reports does notreserve a line for it. This enables you to see one more line of yourreport output per screen.

2. When you change the Previewer Status Line, the report name willnot appear in the status line unless you enter it there yourself. Forexample, you could enter:

This report is for Human Resources personnel only (Report: deptinfo)

Is the page dimensions for your report in character units. The firstnumber is the page height and the second number is the page width.


Enter any dimensions of the form A x B, where Aand B are whole numbers from 1 through 9,999.

80 x 66 characters

Rules:

1. When displaying a character mode report in the bit–mappedPreviewer of the designer, Oracle Reports uses this setting tochoose the font to display. The font may be slightly larger orsmaller than the actual character cell size. As a result, when yourun a report designed for character mode in the bit–mappedPreviewer, you may see some truncation.

Options:

Default:

Options:

Default:

Start in Zoom

Suppress Previewer Title

Use Character Units inDesigner


Starts the Previewer as if you had pressed [Zoom], i.e., the border thatnormally appears around the Previewer is not visible and all you see isthe report output.

Unchecked.

Rules:

1. If Disable Zoom and Start in Zoom are both checked, the Previewerwill be started in zoom and you will be unable to toggle out ofzoom.

Suppresses the display of the Previewer title.

Checked.

Specifies that the Layout Editor and its grid use units of character cells. Using this and Convert Borders causes the Layout Editor to displaycharacter–mode borders for objects with line widths greater than zero.

Default: Unchecked

Comment Tab of Report Property Sheet

The Comment tab of the Report property sheet is a field in which youcan document the report. For example, you could describe the purposeof the report so that someone else would be able to quickly understandwhat it does.

Required/Optional: Optional.

Enter any text not to exceed 64K.

Blank.

Default:

Default:

Options:

Default:

C H A P T E R

5T

5 – 1Data Model Editor

Data Model Editor

he Data Model editor enables you to create and edit your report’sdata model. You should know the following about the Data Modeleditor:

• definition and purpose – 5 – 2

• access – 5 – 3

• component descriptions – 5 – 3

• pop–up menu – 5 – 7


Definition and Purpose

The Data Model editor is a work area in which you define the data tobe used in your report. You create, define, and modify data modelobjects (queries, groups, columns, parameters, and links). For moreinformation, see “Data Model Properties” on page 6 – 1.

Oracle Reports uses the data model to determine what data to retrievefor the report. Note that the data retrieved from the database may ormay not appear in the report output.

The figure below displays an example data model in the Data Modeleditor.

Painting Region

Objects


Access

There are several ways to access the Data Model editor:

• Select Tools—>Data Model Editor. This menu option togglesbetween displaying and hiding the Data Model editor.

• From the Windows menu, select a window with the Data Modeleditor in it.

• From the Object Navigator, double–click on the Data Modelnode.

Components

The Data Model editor has the following components:

• painting region

• toolbar

• tool palette

• status line

The painting region is the area in which you can create, modify,position, or delete objects while viewing their graphical representationson the screen. Objects have only their relative positions in the datamodel graphically represented in an editor. To see an object’s settings,you must open its property sheet by double–clicking on the object. Thepainting region consists of the following:

• objects

• rulers

• grid

The data model objects that you can create in the painting regioninclude queries, groups, columns (summary and formula), parameters,and links. For more information on each object, see “Data ModelProperties” on page 6 – 1. You cannot cut, copy, paste, or duplicatedata model objects (i.e., Cut, Copy, Paste, and Duplicate are disabled inthe Edit menu).

Rulers

Grid


Note: Group hierarchy in the data model is determined byparent–child relationships or position in the editor. If there isno parent–child relationship between two groups (e.g., they aresiblings or unrelated groups), then the hierarchy is determinedby reading from left to right then top to bottom in the DataModel editor. Column hierarchy is determined by readingfrom top to bottom inside each group.

The groups and columns in the Default Layout dialog box are orderedaccording to the group and column hierarchy in the data model. Theorder of the groups and columns in the Default Layout dialog box, inturn, determines the order in which objects will appear in the defaultlayout.

Rulers are located around the left and top edges of the painting region.Rulers are initially hidden in the Data Model editor. To show rulers,select the Rulers menu option in the View menu.

Units You can set the unit of measurement of the ruler to any of thefollowing from Ruler Settings dialog box:

• inches

• centimeters

• points

• character cells

Markers Markers move along both of the rulers to track your cursorlocation in the painting region. The rulers scroll along with thepainting region. Likewise, when you magnify part of the paintingregion, the rulers are updated to reflect the magnification.

Ruler Guides Ruler guides provide you with a point of reference forcreating and modifying objects. To create a ruler guide, click on one ofthe rulers and drag into the painting region.

Note: To show rulers and ruler guides, select the Rulers andRuler Guides menu options in the View menu. To hide rulersand ruler guides, deselect these menu options.

Inside the painting region is a grid to help you position objects in thepainting region.

Grid Lines The grid is drawn in relationship to the rulers. From theRuler Settings dialog box, you specify the interval at which grid linesappear per unit on the ruler. For example, if you have a Unit of inchesand a Grid Spacing of 0.5, there will be one grid line per half–inch onthe ruler.

Toolbar

Tool Palette

Activating Tools


The Toolbar contains the following in the Data Model editor:

• Open

• Save

• Run

• Print

• Clear

• Default Layout

• Help

To use the tools in the Toolbar, click on one or more objects in theoutline view to select them, then click on the desired tool. The actionrepresented by that tool will be performed on the selected object(s).

The Tool palette contains the following tools:

• Selecting – 5 – 6 • Summary Column – 5 – 6

• Magnify – 5 – 6 • Formula Column – 5 – 6

• Query – 5 – 6 • Placeholder Column – 5 – 6

• Data Link – 5 – 6 • Cross Product – 5 – 6

The sections that follow provide information on how to use the Toolpalette and brief descriptions of the items in the Tool palette.

Only one tool is available for use, or active, at a time. The Selectingtool is the default active tool. There are two ways to activate a differenttool:

• Position the cursor over the desired tool and click once. Thisactivates the tool for a single operation, such as creating a singlequery. You can tell that the tool is activated for a singleoperation because its border is highlighted. After you performthe operation with the tool, the default tool (the Selecting tool)once again becomes active.

• Position the cursor over the desired tool icon and double–click.This ”locks” the tool for multiple operations, such as creatingmultiple queries consecutively. You can tell that a tool is lockedbecause the entire icon is highlighted. The tool remains theactive tool until you click or double–click on another tool.

Constrained Modes

Selecting Tool

Magnify Tool

Query Tool

Data Link Tool

Summary ColumnTool

Formula ColumnTool

Placeholder ColumnTool

Cross Product Tool


In the Data Model editor, the column tools offer a constrained modewhich produces only squares when drawing those objects. Note thatthe constrained mode only works if you make your column orparameter larger than a minimum size. For more information, see“Constrained Modes” on page 7 – 8.

The Selecting tool is used to choose one or more objects for anoperation. By clicking and dragging on a point on an object with theSelect tool, you can resize the object. When you select an object(s) inthe Data Model editor, it is also selected in the Object Navigator.

The Magnify tool magnifies an area around the cursor by a factor oftwo (i.e., the area becomes twice as big). This tool is useful when youwant to focus on one part of a large data model.

The Query tool creates a new query in the data model. Once the queryis created, you can further define it from its property sheet.

The Data Link tool draws a link between a parent group and a childquery. Once the link is created, you can further define it from itsproperty sheet. Creating a link is a drag and drop operation. Clickingand dragging from one column to another creates a link between thosetwo columns. Clicking and dragging from one query to another createsall possible links between columns selected by the queries based ondatabase constraints. Clicking and dragging between two groupscreates a group–to–group link (i.e., a link with no columns).

The Summary Colum tool creates a new summary column in the datamodel. Once the column is created, you can further define it from itsproperty sheet.

The Formula Colum tool creates a new formula column in the datamodel. Once the column is created, you can further define it from itsproperty sheet.

The Placeholder Column tool creates a new placeholder in the datamodel. Once the placeholder is created, you can further define it fromits property sheet.

The cross product tool creates a cross product–group around two ormore other groups. A cross product is a mathematical cross product.Cross products are most often used to build a matrix. Once thecross–product group is created, you can further define it from itsproperty sheet.

Status Line

☞


In the Data Model editor, the status line displays the followinginformation:

• absolute mouse position (in pixels, inches, or centimeters)

• mouse drag distance (in pixels, inches, or centimeters)

• zoom levels

The behavior of the status line varies based on the tool being used andaction being performed. The following table shows what is displayedin the status line under different circumstances:

Tool Action Status Information

Every tool moving mouse x,y coordinates ofcursor

Magnify clicking mouse zoom level

Select dragging rectangle x,y coordinates ofstarting point

moving object change in x,y

resizing object change in x,y

Pop–Up Menu

The pop–up menu appears when you click your right mouse button inthe Data Model editor.

Attention: If your platform does not support a right mousebutton, then you can use the right mouse button equivalent(e.g., on Mac, the command button plus a mouse click isequivalent to a right mouse click) to access the pop–up menu.

The pop–up menu in the Data Model editor contains the followingitems:

Is always disabled.

Is always disabled.

Is always disabled.

Is the same as Edit—>Clear.

Is the same as Tools—>Properties. This item only appearsif the cursor is over an object.

Cut

Copy

Paste

Clear

Properties


Is the same as Tools—>Program Unit Editor. This itemonly appears if the cursor is over an object.

Is the same as Help—>Help System.

If your cursor is in a blank area of the editor when you bring up thepop–up menu, only a subset of these items appears.

ProgramUnitEditor

Help

C H A P T E R

6D

6 – 1Data Model Properties

Data Model Properties

ata model properties define the objects that make up a data modelfor a report. Each object has a property sheet associated with it thatdefines its properties:

• query – 6 – 2

• link – 6 – 8

• group – 6 – 14

• common column – 6 – 17

• database column – 6 – 27

• summary column – 6 – 27

• formula column – 6 – 41

• placeholder column – 6 – 42

• parameter – 6 – 45


Query Properties

A query contains a SQL SELECT statement that retrieves data from thedatabase for your report. When you double–click on a query in theData Model editor or its icon in the Object Navigator, the Queryproperty sheet is displayed. The Query property sheet is alsodisplayed if you select a query and then select Properties from theTools menu.

The Query property sheet is divided into the following tabs:

• General – 6 – 2

• Comment – 6 – 8

General Tab of Query Property Sheet

The General tab of the Query property sheet is shown below. Itcontains the following properties.

• External Query – 6 – 3

• List – 6 – 4

• Maximum Rows – 6 – 4

• Name – 6 – 5

• SELECT Statement – 6 – 5

• Tables/Columns

External Query


Is the name of an external query (stored in the database or a file) whoseSELECT statement should be used as the query’s SELECT statement.


Enter a valid external query name not to exceed1K. The external query you reference cannotexceed 32K in length. If it does, it will be truncatedand a warning raised.

If the query is stored in a file, you can prefix a pathto the query name. If a path is not prefixed to thefilename, Oracle Reports uses its file path searchorder to find the file.

For more information about file path search order,see “File–Searching Method” on page 18 – 9.

Note: To ensure the portability of your reports,you can take advantage of the OracleReports–specific environment variable calledREPORTS25_PATH. You can use this variable tospecify the default directory or directories whereyou want Oracle Reports to search for external filesyou use in your reports (e.g., external queries,boilerplate, and PL/SQL). This prevents the needto hardcode directory paths in your report.

For more information on setting this variable, see“Oracle Reports Environment Variables” on page18 – 10.

If the query is stored in the database, you canprefix DB: to it to indicate that it is stored in thedatabase. For example:

DB:myquery

If you prefix DB: to the query name, OracleReports will go directly to the database to find thequery. If you are not connected to the database,Oracle Reports will not be able to find the queryand will issue a message to that effect.

Blank.

Rules:

1. The SELECT statement of the external query you reference fromthis field is validated when you accept the Query property sheet.

Options:

Default:

List

Maximum Rows


2. If you update the external query, you must ensure that the updatedoes not invalidate the report definition. For example, if the reporthas a column for DEPTNO and you delete DEPTNO from theSELECT list of the external query, the report cannot run.

3. When you specify an external query name, the SQL SELECTstatement of the external query appears in the SELECT Statementfield as read–only. To modify it, you must open the external query.

Is a button that brings up the Display dialog box. After you accept thisdialog box, the External Query from File or External Query fromDatabase dialog box appears. From these dialog boxes, you can selectan external query for the External Query field.

Is the maximum number of rows of data that the query should retrieve.Oracle Reports will only retrieve the number of rows for the query thatyou specify in this field. When you are designing a report, you oftenmust run it many times to see how it looks. If your report retrieves alot of data, this can be very time consuming. This property canimprove performance by reducing the amount of data retrieved andformatted.

To restrict the rows retrieved by some, but not all, of a query’s groups,use Filter in the Group property sheet. For more information, see“Filter” on page 6 – 15.


A whole number from 1 through 32K.

Blank means that all the rows selected by the queryshould be retrieved.

Blank

Rules:

1. Rows that were not retrieved because they were beyond themaximum will not be used in any Oracle Reports–specifiedcalculations. For example, if you set Maximum Rows to 5 on achild query, then a summary of the child contained in the parentgroup will only use the five records that are retrieved by the query.

If you want to use data in calculations but not have it appear in thereport output, use a Format Trigger to restrict what appears in theoutput. For more information, see “Format Trigger” on page13 – 28.

Options:

Default:

Name

SELECT Statement


Is the name that Oracle Reports uses to identify the current query.


Enter a valid name not to exceed 30 bytes. Formore information on naming conventions, see“Naming Conventions” on page D – 1.

Q_n, where n is a number that is unique amongquery names of the report.

Is a SQL SELECT statement that retrieves data from the database foryour report. In building your SQL SELECT statement, you can do thefollowing:

• use the Tables and Columns dialog box

• insert comments

• insert bind and lexical references

• review SQL errors

For more information, see “SQL Topics” on page E – 1.


Enter a valid SELECT statement not to exceed 64K.The upper limit may vary between operatingsystems. Refer to your Installation and User’s Guide.All features of the SELECT statement aresupported, except the INTO and FOR UPDATEclauses.

Examples:

1. Following is an example of a SELECT statement:

SELECT O.CUSTID, P.DESCRIP, I.ITEMTOT, O.ORDERDATE, I.ORDID FROM ORD O, PRODUCT P, ITEM I WHERE O.ORDID = I.ORDID AND I.PRODID = P.PRODID ORDER BY O.CUSTID, P.PRODID, O.ORDERDATE /* For each customer, show the products they bought */ /* (DESCRIP), the amount they spent on that product */ /* (ITEMTOT), the date they ordered the product */ /* (ORDERDATE),and the order id (ITEM.ORDID) of the */ /* order in which they bought the product. */

Options:

Default:

Options:


2. Following is an example of a SELECT statement that uses bind andlexical references:

SELECT CUSTID, SUM(TOTAL) TOTAL FROM &FROMGROUP HAVING SUM(TOTAL) > :MINTOTAL

where:

Is ORD GROUP BY CUSTID (or some other valuethat you enter at runtime). Note that, in thiscase, you must define a parameter namedFROMGROUP with an Initial Value specified.If the value of &FROMGROUP is null when theSELECT statement is parsed, you will get anerror because the statement has no table nameafter FROM.

Is a column from another query that is used toselect customers with a minimum total oforders.

For more information on bind and lexical references, see “SQLTopics” on page E – 1.

3. Following is an example of a SELECT statement that uses a lexicalreference to a parameter:

SELECT ENAME, EMPNO FROM EMP WHERE ENAME LIKE UPPER (&NAME)

where:

Refers to a parameter with a default value of’JO%’. Note that you can also specify a valuefor the parameter at runtime. For example,from the command line, you could type:

r25run REP SCOTT/TIGER NAME=’SM%’

Rules:

1. The SELECT statement must follow all SQL syntax rules. Fordetails, see the ORACLE7 Server SQL Language Reference Manual.Oracle Reports checks the syntax when you leave SELECTStatement and when the report is generated or executed.

2. No semicolon, slash, or any other character should be used to endthe SELECT statement.

&FROMGROUP

:MINTOTAL

&NAME

Tables/Columns


3. You must have the appropriate privileges on the tables and viewsreferenced in the SELECT statement in order for the SELECTstatement to be validated.

4. A query that is the child in a link with a SQL Clause of STARTWITH should contain a CONNECT BY clause in its SELECTStatement (without a START WITH clause, since that is in the Linkproperty sheet). Similarly, a query that is the child in a link with aSQL Clause of HAVING should contain a GROUP BY clause in itsSELECT Statement (without a HAVING clause, since that is in theLink property sheet).

5. If SELECT expressions are added to, renamed in, or deleted from aquery, Oracle Reports automatically creates or deletes thecorresponding columns. If the layout has been defined (i.e., theLayout editor contains objects), Oracle Reports will not update theLayout editor based upon changes to the SELECT statement. Youmust update the effected layout objects in the editor manually orcreate a new default layout for the report. The reason OracleReports does not update the layout for you automatically is thatyou could inadvertently lose manual modifications to your layout.

6. If you make any changes in the database to the datatype or name ofcolumns that are selected by your query, you must manually makewhatever changes are necessary to the Oracle Reports columns andfields that use the changed column as a Source.

Caution: If the width of a column in the database is increased afteryou have created your report, you need to update both the data modeland the layout to reflect the change. Otherwise, truncation may occur.Database columns are automatically updated when the query isre–parsed (e.g., enter a space in SELECT Statement and select OK).Summaries, formulas, and placeholders whose source columns haveincreased in width must have their own widths updated manually.Similarly, fields in the layout must be resized or have their sizingsettings changed to accommodate the increased size of their sourcecolumns.

7. The order of the columns in the SELECT statement determines theinitial column order. Subsequent changes to the order of columnsin the SELECT statement will not change the order of the columns.If you add new columns to the SELECT statement, they will beadded at the end of the lowest child group belonging to the query.The order of the columns is used to order the associated fields inthe default layout.

Is the same as Tools—>Tables/Columns.


Comment Tab of Query Property Sheet

The Comment tab of the Query property sheet contains a field in whichyou can document the query. For example, you could describe thepurpose of the query so that someone else would be able to quicklyunderstand what it does.

Note: You can also insert comments directly into your SELECTstatement using Oracle’s standard SQL comment delimiters (e.g., /* comment */). For more information, see the ORACLE7Server SQL Language Reference Manual.



Blank.

Link Properties

Links relate the results of multiple queries. When you double–click ona link in the Data Model editor, the Link property sheet, shown below,is displayed. The Link property sheet contains the followingproperties:

• Child Column – 6 – 12

• Child Query – 6 – 12

• Condition – 6 – 12

• Parent Column – 6 – 13

• Parent Group – 6 – 13

• SQL Clause – 6 – 13

For more information on creating and accessing links, see “Data ModelEditor” on page 5 – 1.

Options:

Default:


A link (or parent–child relationship) causes the child query to beexecuted once for each instance of its parent group. From the Linkproperty sheet settings, Oracle Reports constructs a clause that will beadded to the child query’s SELECT statement at runtime.

The column names in Parent Column and Child Column are thecolumns that relate the parent group to the child query. These fieldsare read–only, their values are derived from what you have drawn inthe Data Model editor. The value in Condition tells Oracle Reports howto relate these two columns (e.g., DEPT.DEPTNO = EMP.DEPTNO).SQL Clause is the type of clause you want to be used in creating thelink (e.g., WHERE).

The diagram below illustrates a link.


Examples:

1. Suppose that you are creating a master/detail report with thefollowing two queries:

Q_1: SELECT DISTINCT ENAME, EMPNO FROM EMP WHERE JOB = ’SALESMAN’ Q_2: SELECT REPID, AMOUNT FROM SALES ORDER BY REPID

To join these two queries, you create a link such that the Linkproperty sheet settings are as follows:

SQL Clause Parent Column Condition Child Column

WHERE EMPNO = REPID

This creates a link as if you wrote one query as follows:

SELECT DISTINCT ENAME, EMPNO, REPID, AMOUNT FROM EMP, SALES WHERE EMPNO = REPID (+) AND JOB = ’SALESMAN’ ORDER BY REPID

Note: If you used a single query, you would also have to create abreak group for ENAME and EMPNO. For more informationabout deciding when it is best to use one or multiple queries, see“Performance and Tuning” on page 17 – 1.

Using a tabular default layout, your output would look somethinglike the figure below.

Ename Empno Repid Amount ––––––––––– –––––– –––––– –––––––––––– ALLEN 7499 7499 3000 7499 810 7499 847 7499 24 7499 1500 7499 340 7499 240 7499 400 7499 180 7499 280 7499 250 MARTIN 7654 7654 16569 7654 2301 7654 3306 7654 5600 TURNER 7844 7844 350 7844 485


7844 293 7844 50 7844 1703

2. Suppose that you wanted to create a report that listed employeesby their position in the management hierarchy. Following are thequeries you might use:

Q_1: SELECT EMPNO FROM EMP WHERE JOB = ’MANAGER’ Q_2: SELECT ENAME, JOB, EMPNO, MGR, LEVEL FROM EMP CONNECT BY PRIOR EMPNO = MGR

To join these two queries, you create a link such that the Linkproperty sheet settings are as follows:

SQL Clause Parent Column Condition Child Column

START WITH EMPNO = EMPNO1

Using a tabular default layout, your output would look somethinglike the figure below.

Empno Ename Job Empno1 Mgr Level –––––– –––––––––– ––––––––– –––––– –––––– –––––––– 7566 JONES MANAGER 7566 7839 1 SCOTT ANALYST 7788 7566 2 ADAMS CLERK 7876 7788 3 FORD ANALYST 7902 7566 2 SMITH CLERK 7369 7902 3 7698 BLAKE MANAGER 7698 7839 1 ALLEN SALESMAN 7499 7698 2 WARD SALESMAN 7521 7698 2 MARTIN SALESMAN 7654 7698 2 TURNER SALESMAN 7844 7698 2 JAMES CLERK 7900 7698 2 7782 CLARK MANAGER 7782 7839 1 MILLER CLERK 7934 7782 2

Rules:

1. If you are creating a link with columns specified, then you musthave both a parent and a child column and the columns must havecompatible datatypes. For example, if the parent column is acharacter datatype (e.g., VARCHAR) then the child column alsomust be a character datatype (e.g., CHAR).

2. For more information about rules regarding links in data modelswith cross–product groups, see “Matrix Restrictions” on page2 – 35.

Child Column

Child Query

Condition


Is a column in the child query that relates to a column in the parentgroup (i.e., parent column). The Child Column must be a databasecolumn, it cannot be a summary or formula. It also cannot dependupon a lexical reference (look at ”Rules” below). For more informationon creating and accessing links, see “Data Model Editor” on page 5 – 1.

Rules:

1. An Oracle Reports link should not depend upon a lexical reference.That is, neither the child column of a link or its table name shouldbe determined by a lexical reference. To achieve this functionality,you need to create a link with no columns specified and then enterthe SQL clause (e.g., WHERE) for the link directly in the query. Forexample, your parent and child queries might be written asfollows:

Parent Query: SELECT DEPTNO FROM EMP Child Query: SELECT &PARM_1 COL_1, &PARM2 COL_2 FROM EMP WHERE &PARM_1 = :DEPTNO

Note how the WHERE clause makes a bind reference to DEPTNO,which was selected in the parent query. Also, this exampleassumes that you have created a link between the queries in theData Model editor with no columns specified.

Is the name of the query defined as the child when you created the linkin the Data Model editor. This field is read–only. For more informationon creating and accessing links, see “Data Model Editor” on page 5 – 1.

Rules:

1. A Child Query can have only one Parent Group. Multiple parentsfor the same child are not allowed.

Is a SQL operator that defines the relationship between Parent Columnand Child Column. For details, see the ORACLE7 Server SQL LanguageReference Manual.

Required/Optional: Required, if a Parent Column is specified.

= (equal to)

< (less than)

<= (less than or equal to)

<> (not equal to)

> (greater than)

>= (greater than or equal to)

Options:

Parent Column

Parent Group

SQL Clause


Like means that the condition is true when thevalue in one column matches the pattern in theother column. The pattern can contain % and _ aswildcard characters.

Not Like means that the condition is true when thevalue in one column does not match the pattern inthe other column. The pattern can contain % and _as wildcard characters.

= (equal sign)

Is a column in the parent group that relates to a column in the childquery (i.e., child column). Parent Column can be a database, summary,or formula column in the parent group. If Parent Column is asummary or formula column, it cannot depend, directly or indirectly,on a column owned by the child query. This field is read–only. Formore information on creating and accessing links, see “Data ModelEditor” on page 5 – 1.

Is the name of the group defined as the parent when you created thelink in the Data Model editor. This field is read–only. For moreinformation on creating and accessing links, see “Data Model Editor”on page 5 – 1.

Rules:

1. You can create a link from a parent group to a child query withoutspecifying any columns by which to link. This establishes arelationship between the two objects; however, all of the detailrecords will appear for each master record in the parent group.

2. A Parent Group cannot have the Child Query as one of itsancestors. In other words, your links cannot create a circulardependency (i.e., a situation where the child query depends on theparent group and the parent group depends on the child query).

Is the type of clause that relates the parent group to the child query.For details, see the ORACLE7 Server SQL Language Reference Manual.

Required/Optional: Required, if Parent Column(s) is specified.

HAVING

START WITH

WHERE

WHERE

Default:

Options:

Default:


Rules:

1. If you use a SQL Clause of START WITH, then the SELECTStatement of the Child Query should contain a CONNECT BYclause (without a START WITH clause, since that is contained inthis property). Similarly, if you use a SQL Clause of HAVING, thenthe SELECT Statement of the Child Query should contain aGROUP BY clause (without a HAVING clause, since that iscontained in this property).

Group Properties

Groups are created to organize the columns in your report. When youdouble–click on a group in the Data Model editor or its icon in theObject Navigator, the Group property sheet is displayed.

The property sheet is divided into the following tabs:

• General – 6 – 15

• Comment – 6 – 52

Edit

Filter


Rules:

1. Any group that is not the lowest group owned by a query mustcontain at least one column with Break Order specified.

2. For rules regarding cross–product groups, see “MatrixRestrictions” on page 2 – 35.

General Tab of Group Property Sheet

The General tab of the Group property sheet is shown below. Itcontains the following properties.

• Edit – 13 – 23

• Filter – 6 – 15

• Name – 6 – 16

Is a button that displays the Program Unit editor in which you canenter your PL/SQL group filter. For more information about groupfilters, see “Group Filters” on page 13 – 23.

Is a set of radio buttons that specifies the type of filter Oracle Reportsshould use on the records being fetched for the group. To restrict therows retrieved by the entire query, use Maximum Rows in the Queryproperty sheet. For more information, see “Maximum Rows” on page6 – 4.


Name


Condition means that a PL/SQL function fordetermining which records to include in the groupwill be defined (or referenced). Select Edit toaccess the group filter.

First means that the first n records retrieved shouldbe included in the group. n is a number specifiedin the field next to First.

Last means that the last n records retrieved shouldbe included in the group. n is a number specifiedin the field next to Last.

No Filter means that you are not using a filter forthe group.

No Filter

Examples:

1. Suppose that you have a group named EMP that contains twocolumns (ENAME and SAL). The parent group of EMP is DEPT,which contains one column (DEPTNO). You specify a Filter of First3 for DEPT and a Filter of First 5 for EMP. This will return the firstthree department numbers retrieved by Oracle Reports with thefirst five names and salaries retrieved for each department.

Rules:

1. If Filter is First or Last, you must specify a positive whole numberin the associated field. The number cannot exceed 64K in size.

2. A cross–product group cannot have a filter on it.

3. Records excluded from the group by filter are not used incomputations. If you want to use data in calculations but not haveit appear in the report output, use a Format Trigger to restrict whatappears in the output. For more information, see “Format Trigger”on page 13 – 28.

Is the name Oracle Reports uses to identify the current group.


Enter any valid group name not to exceed 30 bytes.For more information on naming conventions, see“Naming Conventions” on page D – 1.

Options:

Default:

Options:


G_queryname, where queryname is the name of thequery and a number that is unique among groups.If the query has a default name (e.g., Q_1), thedefault group name is of the form: G_n, where n isa number that is unique among group names forthe report. If the group is not associated with aquery (i.e., a cross product group), the defaultgroup name is also G_n.

Comment Tab of Group Property Sheet

The Comment tab of the Group property sheet contains a field in whichyou can document the group.



Blank.

Common Column Properties

A column contains data for your report. When you double–click on acolumn in the Data Model editor or its icon Object Navigator, aproperty sheet is displayed. Columns have a number of properties incommon.

These common properties appear on the following tabs:

• General – 6 – 17

• Comment – 6 – 27

General Tab of Column Property Sheets

The General tab of the column property sheets is shown below. Itcontains the following properties:

• Break Order – 6 – 18

• Datatype – 6 – 20

• Format – 6 – 21

Default:

Options:

Default:

Break Order


• Name – 6 – 22

• Read from File – 6 – 23

• Value If Null – 6 – 24

• Width – 6 – 25

Note: Some columns have a superset or a subset of theseproperties in their General tab.

Is the order in which to display the column’s values. This propertyconsists of a check box and a list of values. The check box indicatesthat the column is a break column and the list of values indicates theordering to use for the column’s values.

This property applies only to columns that identify distinct values ofuser–created groups (i.e., break groups). The order of column values ina default group is determined by the ORDER BY clause of the query.For column values in user–created groups, however, you must useBreak Order to specify how to order the break column’s values.


Ascending

Descending

Ascending

Options:

Default:


Examples:

1. Suppose that you create a report with the following query:

SELECT DEPTNO, JOB, ENAME, SAL FROM EMP ORDER BY SAL

You then create two groups, G_DEPT and G_JOB. G_DEPTcontains the DEPTNO column and G_JOB contains the JOBcolumn. If you select the check box and specify a Break Order ofDescending for the DEPTNO column and Ascending for the JOBcolumn, your output would appear similar to that below (assumingyou use a tabular layout):

Deptno Job Ename Sal –––––– –––––––––– –––––––––– ––––––––– 30 CLERK JAMES 950.00 MANAGER BLAKE 2850.00 SALESMAN WARD 1250.00 MARTIN 1250.00 TURNER 1500.00 ALLEN 1600.00 20 ANALYST SCOTT 3000.00 FORD 3000.00 CLERK SMITH 800.00 ADAMS 1100.00 MANAGER JONES 2975.00 10 CLERK MILLER 1300.00 MANAGER CLARK 2450.00 PRESIDENT KING 5000.00

2. Suppose that you created a break report with DEPTNO andENAME. In the query, you have ORDER BY DEPTNO. You havealso selected the check box and specified a Break Order ofDescending for the DEPTNO column. The output would appearsimilar to that below:

Deptno Ename –––––– –––––––––– 30 JAMES WARD MARTIN TURNER ALLEN BLAKE 20 SMITH ADAMS JONES SCOTT FORD 10 MILLER

Datatype


CLARK KING

Notice that the Break Order property takes precedence over theORDER BY clause (i.e., the department numbers are in descendingorder).

Rules:

1. Break Order has no effect on columns that belong to the lowestgroup of a particular query. Break Order only effects columns ingroups that are above the lowest child group of a query.

2. Every group above the lowest child group of a query must have atleast one column with Break Order set.

3. Break Order cannot be specified for columns of Datatype Long orLong Raw.

4. Break Order only affects the ordering of the column on which youare breaking. It does not affect the ordering of the columns withinthe break group. For example, suppose that you break onDEPTNO and for each department you list ENAME. If the BreakOrder is Ascending, then department numbers are printed inascending order, but the names within each department print in theorder specified by the query. (You would need to use an ORDERBY clause in your SELECT statement to change their ordering.)

5. A column with a Function of % of Total cannot be a break columnand cannot have Break Order set.

Is the column’s datatype.


Character

Date

Long

Long Raw

Number

Raw

REFmeans that the column is to always retrieve itsdata from the database. The data will not becached locally. This is useful for reports with largenumbers of images, where caching locally wouldtake up too much space.

Options:

Format


Varchar

Varchar2

Note: Trusted Oracle datatypes (MLSLABEL andROWLABEL) are supported by Oracle Reports. When runningon an operating system with Trusted Oracle, Oracle Reportstreats these columns as Trusted Oracle datatypes. This meansthat the columns can be properly sorted. When running on anoperating system without Trusted Oracle (e.g., Windows),Oracle Reports treats these columns as character datatypes.

For database columns, the default Datatype isderived from the database. For summary columns,the default Datatype is Number, if the Function isCount; otherwise, the default is derived fromSource. For formula and placeholder columns, thedefault Datatype is Number.

Rules:

1. You can only edit the Datatype of a formula or placeholder column.For formula and placeholder columns, you can set the Datatype toCharacter, Date, and Number.

2. A column of Datatype Long, Long Raw, or Raw is treated as textunless you specify otherwise in the Format field. For moreinformation, see “Format” on page 6 – 21.

3. If a column has an alias and you change your query, causing thedatatype of the column to change, the change in datatype will beautomatically reflected in Datatype when you accept the query.

Is the format of the object being retrieved by the column from thedatabase. This property tells Oracle Reports whether the object isgraphic, image, or text, and the format in which it is stored. This list issimilar to the one that appears next to Read from File when it ischecked.

Text is text in ASCII format

Image is a bitmapped image

CGM is a line drawing in CGM format

Oracle Format (Drawing) is a line drawing in Oracleformat

Sound

Video

Default:

Options:

Name


OLE2 is a linked object to be embedded in yourreport

All the other image formats are provided in caseyou want to open the report in Oracle ReportsVersion 2.0. If you are planning to open/run thereport in Version 2.0, select the specific imageformat of the column. If not, you can choose fromthe above choices.

For more information on the available formats, see“Oracle Reports File Storage” on page 18 – 2.

Rules:

1. Format may only be specified if the column has a Datatype of Long,Long Raw, or Raw.

2. Sound and Video sources can only be accessed from user–createdbuttons. For more information on user–created buttons, see“Button Properties” on page 8 – 81.

Is the name that Oracle Reports uses to identify the current column.


Enter any valid name not to exceed 30 bytes. Formore information on naming conventions, see“Naming Conventions” on page D – 1.

For a database column, the name as referenced inthe SELECT list of the SELECT statement. For asummary column, CS_n, where n is a number thatis unique among summary names for the report.For a formula column, CF_n, where n is a numberthat is unique among formula names for the report.For a placeholder column, CP_n, where n is anumber that is unique among placeholder namesfor the report.

Rules:

1. Name is only editable for summary, formula, and placeholdercolumns.

2. Oracle Reports uses the column name, alias, or text of theexpression from the query as the default name for a databasecolumn.

Options:

Default:

Read from File


Indicates that the column contains the names of files. When you checkRead from File, you then must specify the format of the files in the listof values next to it. This list of values is similar to the one for Format.For more information, see “Format” on page 6 – 21.

Read from File is useful if you have image, graphic, or text files that arepointed to by a column in a table. If you check Read from File, thecontents of the files will be imported and used as the values of thecolumn. If you do not check Read from File, the column will get itsvalues from the database. As a result, if a column contains filenamesand you do not specify Read from File, the filenames will be printedinstead of the file contents.

You can use Read from File with database, summary, formula, orplaceholder columns (assuming that the column’s values arefilenames). You can also include files in your report as boilerplate. Formore information, see “Link File” on page 8 – 60.


Examples:

1. Suppose that for each of your employees you have a .bmp file thatcontains a picture of the employee. In your employee table, youhave a column named PICTURE that contains the name of the .bmpfile with the employee’s picture.

To generate a report that displays the employees’ pictures, youselect the PICTURE column in your query. On the Columnproperty sheet for the PICTURE column, you check Read from Fileand specify Image as the format. Oracle Reports will then displaythe files pointed to by the PICTURE column wherever you havereferenced the PICTURE column in your layout.

Note: If you do not specify Read from File, the filenames will beprinted instead of the pictures.

2. Suppose that you want to create an employee listing with some textfrom a file next each employee’s information. If the employee’ssalary is greater than $2000 you want text from a file calledsalary1.txt to appear next to the employee. If the employee’s salaryis less than $2000 you want the text from a file called salary2.txt toappear next to the employee.

Value If Null


You create a formula column with a Datatype of Character and Readfrom File set (with a format of Text). In the Formula field for thecolumn, you enter the following PL/SQL:

if :sal > 2000 then return(’/home/jsmith/txt/salary1.txt’); else return(’/home/jsmith/txt/salary2.txt’); end if;

Rules:

1. The size of each file may be at most 4 gigabytes. (On someoperating systems the file may be at most 64K.)

2. Read from File may only be set if the Datatype of the column ischaracter–compatible (i.e., Character, VARCHAR, or VARCHAR2).

3. You can prefix paths to the filenames in the column. If a path is notprefixed to the filename, Oracle Reports uses its file path searchorder to find the file. For more information about file path searchorder, see “File–Searching Method” on page 18 – 9.

Note: To ensure the portability of your reports, you can takeadvantage of the Oracle Reports–specific environment variablecalled REPORTS25_PATH. You can use this variable to specify thedefault directory or directories where you want Oracle Reports tosearch for external files you use in your reports (e.g., externalqueries, boilerplate, and PL/SQL). This prevents the need tohardcode directory paths in your report.

For more information on setting this variable, see “Oracle ReportsEnvironment Variables” on page 18 – 10.

4. If you set Read from File on a summary or formula column, thesummary or formula is calculated before the file is read. Similarly,for placeholder columns with Read from File set, the column’svalue is calculated first.

Is a value to be substituted for any null values of the column. Forexample, if you enter X in this field, then an X will be displayed for nullvalues fetched for the column. If left blank, no substitution will bedone for null values.


Enter any valid value that conforms to thecolumn’s Datatype. Value if Null cannot exceed 1Kin length.

Blank.

Options:

Default:

Width


Rules:

1. For columns with a character datatype (e.g., VARCHAR), if thewidth of the string you enter for Value if Null exceeds the Width ofthe column, the string is truncated.

2. If a column is referenced via a lexical reference in a query, thatcolumn’s Value if Null is used to validate the query.

3. The value entered for Value If Null must be the same datatype asthe column. For example, if the column’s Datatype is Number, youcannot specify ”XX” in Value If Null, you must specify a number.

4. If you enter a date value in Value If Null, it is validated againstOracle Reports’ internal mask for dates (i.e., DD–MON–YY).(Number and character values are not validated.)

5. Entering a string for Value if Null on a break column causes OracleReports to prefetch all of the rows in the break column’s group.This could degrade performance when you run the report. Toavoid prefetching, use the NVL function in your query rather thanentering a string for Value if Null.

Is the maximum number of characters that the values of the columncan occupy. This Width refers to the width that Oracle Reports usesinternally for the column. It effects such things as the calculation ofsummaries and formulas. The size used to display the column’s data,however, is determined by the size of the associated field in the Layouteditor and its Vertical and Horizontal Sizing properties.


Enter any number from 1 through 64K.

Enter two numbers in the form a,b where aindicates the number of digits to the left of thedecimal point and b indicates the number of digitsto the right of the decimal point. (This form canonly be used for defining the width of numbers.)

For database columns, the default Width is derivedfrom the database. For summary and formulacolumns, the default for Width is 10, 0. If a columnhas a Type of Summary, Oracle Reports updates theWidth based upon what you enter as the column’sSource and Function.

Options:

Default:


Rules:

1. If the column’s Type is Database and the Datatype is Character, Date,Number, or Raw, Width is uneditable. However, this does not meanyou cannot control the width of the column’s values in the reportoutput. You can change the width of the values in the output bymodifying the field’s width in the Default Layout dialog box or theField property sheet.

2. If the column’s Type is Database or Placeholder and the Datatype isLong or Long Raw, you can enter a value in Width. Note that if youdo not specify a width for a Long or Long Raw column, OracleReports allocates the maximum width for the column. You can alsoenter a Width for a column of Type Formula.

Caution: If the value of a column of Type Database and DatatypeLong or Long Raw exceeds the Width of the column, the value istruncated.

3. If the value of a column of Type Placeholder or Formula exceeds theWidth of the column, an exception is raised.

4. If a column has an alias and you change your query, causing thewidth of the column to change, the change in width will beautomatically reflected in Width when you accept the query.


Comment Tab

The Comment tab is a text field in which you can document thecolumn.



Blank.

Database Column Properties

A database column represents a column that is selected by the query.When you double–click on a database column in the Data Model editoror the Object Navigator, the Database Column property sheet isdisplayed. The Database Column property sheet is also displayed ifyou select a Database column and then select Properties from the Toolsmenu.


• General – 6 – 17

• Comment – 6 – 27

Rules:

1. Only Oracle Reports can create database columns (it creates one foreach item in the SELECT lists of your queries). To create a databasecolumn, you must add to the SELECT list of your query and OracleReports will then create the database column for you.

2. Database columns can only be deleted by removing the associateditem from the SELECT list.

Summary Column Properties

A summary column performs a computation on another column’s data.When you double–click on a summary column in the Data Modeleditor or the Object Navigator, the Summary Column property sheet isdisplayed. The Summary Column property sheet is also displayed ifyou select a summary column and then select Properties from the Toolsmenu.

Options:

Default:



• General – 6 – 28

• Comment – 6 – 27

General Tab of Summary Column Property Sheet

The General tab of the Summary Column property sheet is shownbelow. It contains the following properties:


• Compute At – 6 – 29


• Function – 6 – 32

• Name – 6 – 22

• Product Order – 6 – 33


• Reset At – 6 – 39

• Source – 6 – 40

• Value if Null – 6 – 24

• Width – 6 – 25

Compute At


Is the group over which a % of Total summary column is computed.Compute At is used only for columns with a Function of % of Total.When you calculate a percentage, you divide a value by a total (e.g.,SMITH’s salary/total department salaries). Compute At defines thetotal for a percentage calculation. Using this field, Oracle Reportsdetermines the total of which each source column value is a percentage. For matrix reports, Compute At can be multiple groups. See”Examples” below. Compute At is a list of values containing validcompute groups.

Required/Optional: Required, for summary columns with a Function of% of Total.

Page is used to calculate the source column as apercentage of the total values on a page.

Report is used to calculate the source column as apercentage of the total values in the report.

Select any valid group name(s).

The parent group of the summary column’s group

Examples:

1. Suppose that you have a report that looks like the one below:

Deptno 10 Dname ACCOUNTING Ename Sal %Dept %Total ––––––––––– –––––––––– –––––– –––––– MILLER 1300.00 14.86% 6.62% CLARK 2450.00 28.00% 12.48% KING 5000.00 57.14% 25.48% Deptno 20 Dname RESEARCH Ename Sal %Dept %Total ––––––––––– –––––––––– –––––– –––––– SMITH 800.00 7.36% 4.08% ADAMS 1100.00 10.11% 5.61% JONES 2975.00 27.36% 15.16% SCOTT 3000.00 27.59% 15.29% FORD 3000.00 27.59% 15.29%

The parent group, G_DEPT, contains the DEPTNO and DNAMEcolumns. The child group, G_EMP, contains the ENAME and SALcolumns.

Options:

Default:


To get a summary that calculates each employee’s salary as apercentage of total department salaries (Pct_Dept), you create asummary column in G_EMP with the following settings:

Function Reset At Compute At

% of Total G_EMP G_DEPT

In this case, Reset At indicates that the summary should be reset tonull for each employee. This is because you want a separatepercentage for each individual employee. Compute At indicatesthat the total of salaries for the department is the whole (100%)across which to compute the percentages. It should also be notedthat this summary is placed in the G_EMP group because you wantthe percentage to appear for each employee.

To get a summary that calculates each employee’s salary as apercentage of total salaries for the entire report (Pct_Total), youcreate a summary column in G_EMP with the following settings:

Function Reset At Compute At

% of Total G_EMP Report

In this case, Compute At indicates that the total of salaries for theentire report is the whole (100%) across which to compute thepercentages. As with the Pct_Dept summary above, Reset Atindicates that the summary should be reset to null for eachemployee and the summary is placed in the G_EMP group becauseyou want the percentage to appear for each employee.

2. Suppose that you have a matrix report that looks something likethe one below and you want to add some percentage summaries toit.

Dept Analyst Clerk Manager Total 10 1300 2450 3750 20 6000 1900 2975 10875 30 950 2850 3800 Total 6000 4150 8275 18425

Group G_JOB contains the column JOB, G_DEPT containsDEPTNO, G_SAL contains SUMSAL, and G_CROSS is thecross–product group. (G_CROSS contains all of the summaries forthe matrix.)


To get a summary that calculates each job category’s total salariesper department as a percentage of total salaries for that job in alldepartments, you would enter the following settings for asummary column in G_CROSS:

Function Reset At Compute At Product Order

% of Total G_DEPT G_JOB G_JOB, G_DEPT

In this case, Reset At indicates that the summary should be reset tonull for each department. This is because you want a separatepercentage for each individual department. Compute At indicatesthat the total of salaries for the job category is the whole (100%)across which to compute the percentages. It should also be notedthat this summary is placed in G_CROSS because all summariesthat apply to the matrix itself must belong to the cross–productgroup.

Note: Because this is a matrix report, you need to use ProductOrder for the summary. For further information about ProductOrder, see “Product Order” on page 6 – 33. (One of theexamples uses the same output as this example and more fullyexplains the use of Product Order.)

This would calculate the percentages as follows:

Analyst Pct_Job Clerk Pct_Job Manager Pct_Job Total

Dept –––––––– ––––––– –––––– ––––––– –––––––– ––––––– ––––––

10 1300 31.33% 2450 29.61% 3750

20 6000 100.00% 1900 45.78% 2975 35.95% 10875

30 950 22.89% 2850 34.44% 3800

Total 6000 4150 8275 18425

(100%) (100%) (100%)

Rules:

1. Compute At is only editable when the column is a summary andthe Function is % of Total.

2. The Compute At group of a summary column may be any groupabove the summary column’s group, including Report and Page, ifthe summary column’s group is not Report.

3. Summary columns that are owned by a cross–product groupcannot have a Compute At of Page.

4. If a summary has a Compute At of Page, then the sizing of the fieldor boilerplate object that displays it must be fixed. For moreinformation, see “Vertical Sizing” on page 8 – 20.

Function


Is the computation to be performed on the values of the columnspecified in Source. To create running summaries, you place thecolumn in the appropriate group and use Function in conjunction withReset At.

Required/Optional: Required, if column is a summary column.

Average calculates the average of the column’svalues within the reset group.

Count counts the number of records within thereset group.

First prints the column’s first value fetched for thereset group.

Last prints the column’s last value fetched for thereset group.

Maximum calculates the column’s highest valuewithin the reset group.

Minimum calculates the column’s lowest valuewithin the reset group.

% of Total calculates the column’s percent of thetotal within the reset group.

Std. Deviation calculates the column’s positivesquare root of the variance for the reset group.

Sum calculates the total of the column’s valueswithin the reset group.

Variance sums the squares of each column value’sdistance from the mean value of the reset groupand divides the total by the number of valuesminus 1.

Blank.

Rules:

1. Function is only editable when the Type of the column is Summary.

2. Sum, Average, % of Total, Std. Deviation, and Variance can only beapplied to fields with a Datatype of Number.

3. Oracle Reports sets the Datatype for the summary based on theDatatype of the column being summarized.

4. If the column being summarized is changed, the datatype of thesummary changes to match.

Options:

Default:

Product Order


5. A report–level summary cannot have a Function of % of Total. Sucha column would make no sense because it would always be 100%.

6. A column with a Function of % of Total cannot be a break columnand cannot have Break Order set.

Is the order in which groups are evaluated in the cross product for asummary. Product Order also defines the frequency of a summary,formula, or placeholder in a cross product group. That is, thesummary, formula, or placeholder has one value for each combinationof values of the groups in its Product Order.

Product Order is used only for columns owned by cross–productgroups. Because a cross product relates multiple groups, the groups inthe cross product could be evaluated in any one of many differentorders. Therefore, when creating a summary for a cross product, youmust use Product Order to specify for Oracle Reports which groupshould be evaluated first, which second, and so on. You must also useProduct Order to specify the frequency of a summary, formula, orplaceholder within the cross product.

Required/Optional: Required, if the column is a summary or formulacolumn belonging to a cross product group.

Select a valid group combination.Options:


Examples:

1. Suppose that you have a matrix report like the one below.

Job ANALYST CLERK MANAGER PRESIDENT SALESMAN

––––––– ––––– ––––––– ––––––––– ––––––––

Year Dept

–––– ––––

80 10

20 800 800

30

––––––

800

81 10 2450 5000 7450

20 3000 2975 5975

30 950 2850 5600 9400

––––––

22825

82 10 1300 1300

20 3000 3000

30

––––––

4300

83 10

20 1100 1100

30

––––––

1100

––––––– ––––– ––––––– ––––––––– ––––––––

6000 4150 8275 5000 5600

Group G_JOB contains the column JOB, G_DEPT containsDEPTNO, G_YEAR contains YEAR, G_SAL contains SUMSAL,and G_CROSS is the cross product group. (G_CROSS contains allof the summaries for the matrix.)

To get the summary of salaries by job, you create a summarycolumn in G_CROSS with the following settings:

Function Reset At Product Order

% of Total G_JOB G_JOB


In this case, you want the summary to calculate a sum for eachrecord of G_JOB (i.e., each job category) so Product Order isG_JOB. (This summary appears along the bottom of the matrix.)For more information about Reset At, see “Reset At” on page6 – 39.

To get the summary of salaries by year, you create a summarycolumn in G_CROSS with the following settings:


Sum G_YEAR G_YEAR

In this case, you want the summary to calculate a sum for eachrecord of G_YEAR (i.e., each year) so Product Order is G_YEAR.(This summary appears along the right edge of the matrix directlyunderneath a boilerplate line.)

To get the summary of salaries for each department in each year,you create a summary column in G_CROSS with the followingsettings:


Sum G_DEPT G_YEAR, G_DEPT

In this case, you want the summary to calculate a sum for eachdepartment in each year (G_DEPT and G_YEAR). For thissummary, G_YEAR has the lowest frequency (i.e., it changes onlyonce for each three records of G_DEPT) and G_DEPT has thehighest frequency (i.e., it changes three times for each record ofG_YEAR). As a result, G_YEAR (lowest frequency) appears firstand G_DEPT (highest frequency) appears second in Product Order.

2. Suppose that you have a matrix report that looks something likethe one below and you want to add some percentage summaries toit.

Dept Analyst Clerk Manager Total 10 1300 2450 3750 20 6000 1900 2975 10875 30 950 2850 3800 Total 6000 4150 8275 18425

Group G_JOB contains the column JOB, G_DEPT containsDEPTNO, G_SAL contains SUMSAL, and G_CROSS is the crossproduct group.


To get a summary column that calculates each job category’s totalsalaries per department as a percentage of total salaries for that jobin all departments, you would enter the following settings for asummary column in G_CROSS:


% of Total G_DEPT G_JOB G_JOB, G_DEPT

In this case, you want the summary to go down the matrix andthen across. Since the summary goes down the matrix first, G_JOBhas the lowest frequency (it changes only once per threedepartments) and is the first group in Product Order. Since thesummary goes across the matrix after going down, G_DEPT hasthe highest frequency (it changes three times per one job) and is thesecond group in the Product Order.

For more information about Reset At and Compute At, see “ResetAt” on page 6 – 39. For more information, see “Compute At” onpage 6 – 29. (”Compute At” contains an example based on thesame output as this example and more fully explains Compute At.)



Dept –––––––– ––––––– –––––– ––––––– –––––––– ––––––– ––––––

10 1300 31.33% 2450 29.61% 3750

20 6000 100.00% 1900 45.78% 2975 35.95% 10875

30 950 22.89% 2850 34.44% 3800

Total 6000 4150 8275 18425

100% 100% 100%

To get a summary that calculates each department’s total salariesper job category as a percentage of total salaries for thatdepartment, you would enter the following settings for a summarycolumn in G_CROSS:


% of Total G_JOB G_DEPT G_DEPT, G_JOB

In this case, you want the summary to go across the matrix andthen down. Since the summary goes across the matrix first,G_DEPT has the lowest frequency (it changes only once per threejobs) and is the first group in Product Order. Since the summarygoes down the matrix only after going across, G_JOB has thehighest frequency (it changes three times per one department) andis the second group in the Product Order.




Dept –––––––– ––––––– –––––– ––––––– –––––––– ––––––– ––––––

10 1300 34.67% 2450 65.33% 3750

100%

20 6000 55.17% 1900 17.47% 2975 27.36% 10875

100%

30 950 25.00% 2850 75.00% 3800

100%

Total 6000 4150 8275 18425

To get a summary that calculates each department’s total salariesper job category as a percentage of total salaries in the report, youwould enter the following settings for a summary column inG_CROSS:


% of Total G_JOB Report G_DEPT, G_JOB

In this case, the summary could go across the matrix and thendown, or down the matrix and then across because you arecomputing this summary for the entire report (e.g., Compute At isReport). Product Order could be either G_DEPT, G_JOB (across,down) or G_JOB, G_DEPT (down, across). Note, however, thatReset At must be the group that has the highest frequency:G_DEPT if Product Order is G_JOB, G_DEPT; G_JOB if ProductOrder is G_DEPT, G_JOB.


Analyst Pct_Job Clerk Pct_Job Manager

Pct_Job Total

Dept –––––––– ––––––– –––––– ––––––– –––––––– ––––––– ––––––

10 1300 7.06% 2450 13.30% 3750

20 6000 32.56% 1900 10.31% 2975 16.15% 10875

30 950 5.16% 2850 15.47% 3800

Total 6000 4150 8275 18425

100%

3. Suppose that you have a matrix report that looks something likethe one below and you want to add a formula to it.

Dept Analyst Clerk Manager President Salesman 10 1300 2450 5000 20 6000 1900 2975 30 950 2850 5600


Group G_JOB contains the column JOB, G_DEPT containsDEPTNO, G_SAL contains SUMSAL, and G_CROSS is the crossproduct group.

To add a formula that calculates the sum of after–tax salaries foreach department, you first create a summary column (DEPTSUM)in G_CROSS with the following settings:


% of Total G_DEPT G_DEPT

Next, you create a formula (AFTERTAX) in G_CROSS with thefollowing settings:

Formula Product Order

:deptsum * .9 G_DEPT

Because the formula is in G_CROSS, you must give it a ProductOrder. In this case, the frequency of the formula is the same as thesummary column, DEPTSUM. This would calculate the formula asfollows:

Dept Analyst Clerk Manager President Salesman Comp 10 1300 2450 5000 7875 20 6000 1900 2975 978830 950 2850 5600 8460

Rules:

1. This field is only available if the summary, formula, or placeholdercolumn’s group is a cross product.

2. A summary which is not a running summary (i.e., its Reset At isnot Report) must have a Product Order that is a subset of its sourcecolumn’s Product Order. The source column of the summary mustbe at least as frequent as the summary, which means that thesummary’s Product Order should be some subset of the sourcecolumn’s Product Order.

A running summary (i.e., its Reset At is Report) must have aProduct Order that is a prefix of the source column’s ProductOrder. For example, if the source column’s Product Order wereA,B,C, then the summary column’s Product Order would have tobe either A (by itself) or A,B. The summary’s Product Order couldnot be B,A.

Reset At


Is the group at which the summary column value resets to zero (ifFunction is Count), null (if Function is not Count), or Value If Null (if thecolumn has one). Reset At has a list of values containing valid resetgroups. Reset At determines if the summary is a running summary ora periodic (e.g., group–level) summary.

Required/Optional: Required, for columns of Type Summary.

Page is used for page–level summaries. Thesummary is reset between pages.

Report is used for summaries that apply to theentire report, such as grand totals. The summary isreset after the report (i.e., it is never reset).

Select any valid group name. The summary is resetafter each record of the group.

Examples:

1. Suppose that you want to create a master/detail report like the onebelow:

DEPT NAME SAL RESETSUM RUNSUM –––– ––––––– –––– –––––––– –––––– 10 SMITH 1000 1000 1000 JONES 1000 2000 2000 KING 1000 3000 3000

20 JOHNSON 1500 1500 4500 WARD 1000 2500 5500

The parent group, G_DEPT, contains the DEPTNO column. Thechild group, G_EMP, contains ENAME and SAL. To get the sum ofsalaries for each department (RESETSUM), you create a summarycolumn in G_EMP with the following settings

Function Reset At

Sum G_DEPT

In this case, Reset At indicates that the summary should be set tonull after each department.

To get the running sum of salaries (RUNSUM), you create asummary column in G_EMP with the following settings:

Function Reset At

Sum Report

In this case, Reset At indicates that the summary should not bereset to null but should accumulate throughout the report.

Options:

Source


For more information about how to use Reset At in percent of totalcalculations, see “Compute At” on page 6 – 29.

Rules:

1. Reset At is only editable when the Type of the column is Summary.

2. The reset group of a summary column may be its group or anygroup above its group, including Report and Page.

3. Summary columns that are owned by a cross–product groupcannot have a Reset At of Page.

4. If a summary has a Reset At of Page, then the sizing of the field orboilerplate object that displays it must be fixed. For moreinformation, see “Vertical Sizing” on page 8 – 20.

5. If a column has a Reset At of Page, then any fields that use it as asource must be contained in repeating frames that use the column’sgroup as their source.

Is the name of the column whose values will be summarized. Source isa list of values containing those columns that are valid for the specifiedFunction.

Required/Optional: Required, if the column is a summary column.

Select any valid column name.

Blank.

Rules:

1. The source of a summary column may be any column within or below the summary column’s group (with a valid Datatype for thefunction).

2. If you change the Source of a summary column, the Datatype of thesummary column changes to reflect the Datatype of the new sourcecolumn, unless the column has Read from File specified.

3. Any column can be the Source of multiple summary columns.

4. If you specify a source for a summary column and later delete thesource column from your report, your summary column no longerhas access to data to summarize.

Options:

Default:


Formula Column Properties

A formula column performs a user–defined computation on anothercolumn(s) data. When you double–click on a formula column in theData Model editor or its icon in the Object Navigator, the FormulaColumn property sheet is displayed.


• General – 6 – 41

• Comment – 6 – 27

Rules:

1. You can set placeholder or formula columns to any of the followingDatatypes: Character, Number, and Date.

General Tab of Formula Column Property Sheet

The General tab of the Formula Column property sheet is shown below.It contains the following properties:



• Formula – 13 – 25

• Name – 6 – 22




• Width – 6 – 25

Formula

Product Order


Is a button that displays the Program Unit editor in which you canenter your formula. For more information about Formulas, see“Formulas” on page 13 – 25.

Product Order is the same for summaries, formulas, and placeholders.For more information, see “Product Order” on page 6 – 33.

Placeholder Column Properties

A placeholder is a column for which you set the datatype and value inPL/SQL that you define. You can set the value of a placeholdercolumn in the following places:

• the Before Report Trigger, if the placeholder is a report–levelcolumn

• a report–level formula column, if the placeholder is areport–level column

• a formula in the placeholder’s group or a group below it (thevalue is set once for each record of the group)

When you double–click on a placeholder column in the Data Modeleditor or its icon in the Object Navigator, the Placeholder Columnproperty sheet is displayed.



• General – 6 – 44

• Comment – 6 – 27

Examples:

1. Suppose that you wanted to create a master/detail report thatwould list the highest paid employee(s) for each department. Theoutput below shows a sample of what you would get:

Dname ACCOUNTING Loc NEW YORK Highest Paid Employee(s): Ename Job Sal –––––––––– ––––––––– ––––––––– CLARK MANAGER 2450.00 KING KING PRESIDENT 5000.00 MILLER CLERK 1300.00 Dname RESEARCH Loc DALLAS Highest Paid Employee(s): Ename Job Sal –––––––––– ––––––––– ––––––––– SMITH CLERK 800.00 SCOTT and FORD JONES MANAGER 2975.00 SCOTT ANALYST 3000.00 ADAMS CLERK 1100.00 FORD ANALYST 3000.00

To get the names of the highest paid employee(s), you create acolumn named HIGHEST_PAID_EMP of Type Placeholder andDatatype Character. The value of HIGHEST_PAID_EMP is set by acolumn named SET_HIGHEST_PAID_EMP of Type Formula andDatatype Character. R_COUNT is a column of Type Summary witha Function of Count. SET_HIGHEST_PAID_EMP contains thefollowing PL/SQL function in Formula:

function set_plch_high_emp return character is begin /* Check if we are at first record in child, if so, then reset placeholder */ if (:r_count <= 1) then :highest_paid_emp := ’ ’; end if; /* Does this child record compare to the max sal for the dept ? If yes, and placeholder already set (i.e. we have more than one max sal) set the placeholder to the concatenated string. Else set the placeholder to the employee’s name */ if (:sal = :max_dept_sal) then if (:highest_paid_emp <> ’ ’) then


:highest_paid_emp := :highest_paid_emp||’ and ’ ||:ename; else :highest_paid_emp := :ename; end if; end if; return (:highest_paid_emp); end;

Rules:

1. You can set placeholder or formula columns to any of the followingDatatypes: Character, Number, and Date.

2. You can only assign the value of a placeholder column from onegroup. You cannot assign its value in multiple groups.

General Tab of Placeholder Column Property Sheet

The General tab of the Placeholder Column property sheet is shownbelow. It contains the following common column properties:



• Formula – 13 – 25

• Name – 6 – 22




• Width – 6 – 25

Edit


Is a button that displays the Program Unit editor in which you canenter your formula. For more information about Formulas, see“Formulas” on page 13 – 25.

Parameter Properties

A parameter is a variable whose value can be changed at runtime.When you double click on a parameter’s icon in the Object Navigator,the Parameter property sheet is displayed. The parameter propertiesare described alphabetically after the figure.


• General – 6 – 47

• Data/Selection – 6 – 50

• Comment – 6 – 52

User and System Parameters When you are in the Object Navigator,you will notice a heading node called User Parameters and another onecalled System Parameters. User parameters are parameters that youcreate for the report. System parameters are parameters that OracleReports creates for every report. Both user and system parameters canbe assigned values at runtime (e.g, from the Runtime Parameter Formor the command line). Note, though, that while you can delete orrename a user parameter you cannot delete or rename a systemparameter.


Additional Information: You can prevent system parametersfrom appearing on the Runtime Parameter Form. Deselect theparameter in the Default Parameter Form dialog box or deleteits related field in the Parameter Form editor. Alternatively, ifyou do not create your own parameter form, only DESTYPE,DESNAME, and any user–created parameters will appear inthe Runtime Parameter Form.

The system parameters are described in the following table:

Name Function

BACKGROUND Is whether the report should run in the foreground or the background.

COPIES Is the number of report copies that should bemade when the report is printed.

CURRENCY Is the symbol for the currency indicator(e.g., ”$”).

DECIMAL Is the symbol for the decimal indicator(e.g., ”.”).

DESFORMAT Is the definition of the output device’s format(e.g., landscape mode for a printer). Note:This parameter is not used in a bit–mappedenvironment. It is only used when runningthe report in a character–mode environment.

DESNAME Is the name of the output device (e.g., the filename, printer’s name, mail userid).

DESTYPE Is the type of device to which to send the report output (screen, file, mail, printer, orscreen using PostScript format).

MODE Is whether the report should run in charactermode or bitmap.

ORIENTATION Is the print direction for the report (landscape,portrait, default).

PRINTJOB Is whether the Print Job dialog box should appear before the report is run.

THOUSANDS Is the symbol for the thousand’s indicator (e.g., ”,”).

Datatype


General Tab of Parameter Property Sheet

The General tab of the Parameter property sheet is shown below. Itcontains the following properties:


• Edit – 13 – 27

• Initial Value – 6 – 48

• Input Mask – 6 – 48

• Name – 6 – 49

• Width – 6 – 49

Is the parameter’s datatype.


Character

Date

Number

Character

Rules:

1. Any values supplied for a parameter must conform to theparameter’s Datatype, even at runtime.

2. Datatype cannot be edited for packaged parameters (e.g.,DESTYPE).

Options:

Default:

Edit

Initial Value

Input Mask


3. Parameters with a Datatype of Character are not padded, unlessyou explicitly pad them in a SQL statement.

Is a button that displays the Program Unit editor in which you canenter your Validation Trigger for the parameter. For more information{about Validation Triggers, see ”Validation Triggers” on page 13 – 27.

Is the default value for the parameter. This value is used unless it isoverridden on the command line or the Runtime Parameter Form. IfInitial Value is left blank, the parameter has no default value.


Enter any value appropriate for the Datatype.Initial Value cannot exceed 1K in length.

For DESTYPE, Screen. For DESFORMAT, dflt. ForCOPIES, 1. For all other parameters, blank.

Rules:

1. Initial Value is validated according to the Datatype and Width ofthe parameter. In addition, Initial Value is validated against formatmasks:

• If you specify one, the mask in Input Mask is used.

• If Input Mask is blank and the value is a date, Oracle Reports’internal mask (e.g., DD–MON–YY) is used. (Number andcharacter values are not validated unless you specify an InputMask.)

2. If no value is specified and the parameter is referenced in SQL orPL/SQL, a null is used to parse the SQL or PL/SQL. If a nullcauses the SQL or PL/SQL construct to parse incorrectly, an errorwill be raised.

Is the format mask to be used by Oracle Reports to validate the valuesupplied for the parameter on the command line or the RuntimeParameter Form. It is also used to validate the Initial Value of theparameter. For more information, see “Format Mask” on page 8 – 42.


Enter any valid format mask not to exceed 128bytes.

Select a value from the list.

Options:

Default:

Options:

Name

Width


Blank. This implies that when the Datatype is Date,the input format is the default for your language(e.g., in the United States, the default is’DD–MON–YY’), and when the Datatype isNumber, the input format is –9999.

Rules:

1. The values displayed initially in the Input Mask list are determinedby the datatype of the parameter (e.g., for a parameter of DatatypeNumber, only number masks are shown in the list). If you enter amask not in the list for Input Mask and accept the Parameterproperty sheet, the new format mask will appear in the list ofvalues.

However, these format masks are only valid during the currentOracle Reports session. If you quit Oracle Reports and then invokeit again, the list for the Input Mask field does not contain theformat masks you created in the previous Oracle Reports session(unless you open the report(s) that used these masks). To includemasks in the list that will be saved between sessions, use FormatMasks in the Preferences dialog box (Tools—>Options).

2. You cannot enter a format mask for parameters of DatatypeCharacter.

Is the name that Oracle Reports uses to identify the current parameter.


Enter any valid parameter name not to exceed 30bytes. For more information on namingconventions, see “Naming Conventions” on pageD – 1.

P_n, where n is a number that is unique amongcolumn names for the report. If you create aparameter by making a bind reference in yourquery, though, the name that you used in the queryis the default.

Rules:

1. You cannot rename system parameters.

Is the maximum number of characters of the parameter value whenentered on the command line and the Runtime Parameter Form.


Enter a number from 1 through 64K.

Default:

Options:

Default:

Options:


40 characters

Rules:

1. Oracle Reports truncates any parameter value supplied at runtimethat is longer than Width.

2. Width cannot be edited for packaged parameters (e.g.,DESNAME).

Data/Selection Tab of Parameter Property Sheet

The Data/Selection tab of the Parameter property sheet is shownbelow. It contains the following properties:

• Add – 6 – 51

• Remove – 6 – 51

• Restrict List to Predetermined Values – 6 – 51

• SELECT Statement/Static Values – 6 – 51

• Hide First Column – 6 – 52

• Value – 6 – 52

Additional Information: The Data/Selection tab is onlyavailable for user–created parameters. System parameters onlyhave the General and Comment tabs.

Default:

Add

Remove

Restrict List toPredetermined Values

SELECTStatement/Static Values


Is a button that adds the value in the Value field to the list of staticvalues.

Required/Optional: Required, if you want to add to the static values.

Is a button that removes the selected value(s) from the list of staticvalues.

Is a checkbox that indicates whether a value for the parameter must bein the list of values. For example, if you check Restrict List toPredetermined Values and the Initial Value does not match a value inthe list of values, an error will be generated when you accept theParameter property sheet. Similarly, if you set a value for theparameter on the command line or in a command script and it does notmatch a value in the list of values, an error will be generated when thereport is run.

If you check Restrict List to Predetermined Values, a list of values willappear in the runtime parameter form. If you do not check it, a combobox will appear (i.e., you can enter values as well as select from thelist).

Checked.

Is a radio button that indicates whether you want to use a SELECTstatement or a static list to populate the list of values for the parameter.


SELECT Statement indicates that you want to entera SELECT statement to populate the list of valuesfor the parameter. If you select this option, thenyou must enter a SELECT statement in the areaunderneath the SELECT Statement radio button.

Static List indicates that you want to manuallyenter values to populate the list of values for theparameter. If you select this option, you mustcreate a list of values manually. To do this, youenter a value in the Value field and then choose theAdd button. Repeat this process for each valueyou want in the list. To remove value(s), selectthem in the list and then choose the Removebutton.

Default:

Options:

Hide First Column

Value


Is a checkbox that indicates whether the first column in your SELECTlist should be displayed in the parameter’s list of values. This setting isuseful for hiding values that the user doesn’t know about or areconfidential. Look at “Examples” below.

Checked.

1. You want to create a report that lists the employees in a departmentthat the user specifies at runtime. The tables you will be usinghave DEPTNO as the primary/foreign key. The people using thereport do not know departments by number, they only know themby name. The report query would be as follows:

SELECT * FROM EMP

WHERE DEPTNO = :MYDEPT

In the Data/Selection tab of the Parameter property sheet, youchoose SELECT Statement and enter the following SQL statementto populate the list of values:

SELECT DEPTNO, DNAME FROM DEPT

You then check Hide First Column. This means that DEPTNO willnot appear in the list of values when you run the report. OnlyDNAME will appear. When the user selects a DNAME value fromthe list, the corresponding DEPTNO value will be used for theparameter MYDEPT.

Is a value that will be added to the static list of values for theparameter when you choose the Add button.

Required/Optional: Required, if you want to add a value to the staticlist.

Enter a valid value for the parameter and thenchoose the Add button to add it to the static list ofvalues.

Comment Tab of Parameter Property Sheet

The Comment tab of the Parameter property sheet contains a field inwhich you can document the parameter.



Blank.

Default:

Options:

Options:

Default:

C H A P T E R

7T

7 – 1Layout Editor

Layout Editor

he Layout editor enables you to create and edit your report’slayout. You should know the following about the Layout editor:


• access – 7 – 3

• components – 7 – 3


• navigation – 7 – 20

• margins – 7 – 21



The Layout editor is a work area in which you define the format ofyour report output. To do this, you define and modify layout objects(frames, repeating frames, fields, boilerplate, anchors, and OracleGraphics objects) For more information, see “Layout Properties” onpage 8 – 1.

When you run a report, Oracle Reports uses the Layout editor as atemplate for the report output. This template will grow or shrinkbased on the data fetched for and the PL/SQL logic assigned to thelayout objects.

The figure below displays an example report layout in the Layouteditor.

Painting Region

Objects


Access

There are several ways that you can access the Layout editor:

• Select Tools—>Default Layout. After Oracle Reports builds theobjects for you, you are placed in the Layout editor to see theresults of the defaulting.

• Select Tools—>Layout Editor.

• From the Windows menu, select a window with the Layouteditor in it.

• From the Object Navigator, double–click on the Layout node’sicon.

Components

The Layout editor has the following components:

• painting region – 7 – 3

• toolbar – 7 – 7

• tool palette – 7 – 7

• status line – 7 – 17

The painting region is the area in which you can create, modify,position, or delete objects while viewing their graphical representationson the screen. Objects have their sizes, relative positions, patterns,colors, and fonts graphically represented in the editor. To see anobject’s settings, you must open its property sheet by double–clickingon the object. The painting region consists of the following:

• objects – 7 – 3

• regions – 7 – 4

• rulers – 7 – 6

• grid – 7 – 6

The layout objects that you can create in the painting region includeframes, repeating frames, fields, boilerplate, anchors, buttons, OLE2objects, and Oracle Graphics objects. For more information, see“Layout Properties” on page 8 – 1.

Report Layout Regions


Graphic representations (or icons) in the editor indicate the type ofobject being represented and, in some cases, its settings. The figurebelow illustrates the meaning of these icons in the editor.

There are three report regions in the Layout editor:

• header

• body/margin

• trailer

The report regions are illustrated in the following figure and describedbelow the figure.


The report header pages appear once at thebeginning of each report on a set of separate pages.They can contain text, graphics, data, andcomputations.

The body/margin pages appear between theheader and trailer pages, and are the bulk of thereport. Each physical page in this section consistsof a body and a margin.

The body contains the majority of the report’s text,graphics, data, and computations.

A top and bottom margin appear on each page,until all data within the body has been formatted.A margin may include text, graphics, pagenumbers, page totals, and grand totals. Thedefault margin size is one half inch each for the topand bottom margins and zero for the left and rightmargins. For more information about the margin,see “Margins” on page 7 – 21.

Header

Body/Margin

Rulers

Grid


The report trailer pages appear once at the end ofeach report on a set of separate pages. They cancontain text, graphics, data, and computations.

Rulers are located around the left and top edges of the painting region.Rulers are initially shown in the Layout editor. To hide rulers, deselectthe Rulers menu option in the View menu.

Units You can set the unit of measurement of the ruler to any of thefollowing from Ruler Settings dialog box:

• inches

• centimeters

• points

• character cells

When you change the report’s Unit of Measurement in GlobalProperties, the ruler units are updated to reflect the Unit ofMeasurement. When you select Use Character Units in the CharacterMode Settings dialog box, the ruler units are changed to character cells.

Markers Markers move along both of the rulers to track your cursorlocation in the painting region. The rulers scroll along with thepainting region. Likewise, when you magnify part of the paintingregion, the rulers are updated to reflect the magnification.

Ruler Guides Ruler guides provide you with a point of reference forcreating and modifying objects. To create a ruler guide, click on one ofthe rulers and drag into the painting region.

Note: To hide rulers and ruler guides, deselect the Rulers andRuler Guides menu options in the View menu. To show rulersand ruler guides, select these menu options.

Inside the painting region is a grid to help you position objects in thepainting region.

Grid Lines The grid is drawn in relationship to the rulers. From theRuler Settings dialog box, you specify the interval at which grid linesappear per unit on the ruler. For example, if you have a Unit of inchesand a Grid Spacing of 0.5, there will be one grid line per half–inch onthe ruler.

Trailer

Toolbar

Tool Palette


The Toolbar contains the following tools in the Layout editor:

• Open • Body

• Save • Margin

• Run • Header

• Print • Trailer

• Cut • Confine

• Copy • Flex

• Paste • Help

• Default Layout


The Tool palette contains the following tools in the Layout editor:

• Selecting – 7 – 9 • Frame – 7 – 13

• Frame Select – 7 – 10 • Repeating Frame – 7 – 13

• Rotate – 7 – 10 • Field – 7 – 14

• Reshape – 7 – 11 • Link File – 7 – 14

• Magnify – 7 – 11 • Oracle Graphics – 7 – 14

• Line – 7 – 11 • Button – 7 – 14

• Rounded Rectangle – 7 – 12 • Anchor – 7 – 14

• Rectangle – 7 – 12 • OLE2 – 7 – 15

• Ellipse – 7 – 12 • Additional Default Layout – 7 – 15

• Arc – 7 – 12 • Border/Fill/Font display – 7 – 15

• Polygon – 7 – 12 • Fill Color – 7 – 15

• Polyline – 7 – 13 • Line Color – 7 – 16

• Freehand – 7 – 13 • Text Color – 7 – 17

• Text – 7 – 13

For more information about how to use the tools in the Tool palette, see“How To” in Chapter 8 of Building Reports Manual.

Activating Tools

Constrained Mode


Only one tool is available for use, or active, at a time. The Selectingtool is the default active tool. There are two ways to activate a differenttool:

• Position the cursor over the desired tool icon and click once.This activates the tool for a single operation, such as creating arectangle. You can tell that the tool is activated for a singleoperation because its border is highlighted. After you performthe operation with the tool, the default tool (the Selecting tool)once again becomes active.

• Position the cursor over the desired tool icon and double–click.This ”locks” the tool for multiple operations, such as creatingmultiple frames consecutively. You can tell that a tool is lockedbecause the entire icon is highlighted. The tool remains theactive tool until you click or double–click on another tool.

Note: If you are typing/editing text in the editor, you mustexit text mode (i.e., click outside of the boilerplate text object)before activating another tool.

Some tools offer a constrained mode of operation which makes it easierto draw certain shapes or move objects in a straight line. For example,the constrained mode of operation for the rectangle tool produces onlysquares. Similarly, the constrained mode of operation for the ellipsetool produces only circles. When moving an object, the constrainedmode forces the object to be moved in a straight line (either diagonally,horizontally, or vertically). To perform a constrained operation, holddown the constrain key (usually the shift key, check yourplatform–specific documentation) while drawing.

Constraints are imposed only during the initial creation of objects andwill not be retained by the object after creation. For example, when aconstrained rectangle operation is used and a square results, thatsquare can later be resized into a rectangle. However, if the constraintkey is also used during the resizing operation, the object will retain theconstraint characteristics.

Confine Mode and FlexMode

Selecting Tool


When moving or resizing an object, you often want to ensure that theobject maintains the same relationship to its parent object. Forexample, if you resize a field such that it no longer fits in its parentrepeating frame, you will get a frequency error when you run thereport. To ensure that objects maintain the correct relationship to theirparent objects, Oracle Reports’ Layout editor provides the followingmodes:

• Confine mode prevents you from performing an operation thatwould cause the layout not to work. For example, in confinemode, Oracle Reports will not allow you to move a field outsideof its parent repeating frame. Confine mode is on by default inthe Layout editor. To turn confine mode on or off, use theConfine tool in the toolbar or the Layout tab of the LayoutOptions dialog box (View—>Settings—>Layout).

• Flex mode moves or resizes the object, its enclosing objects, andobjects in their push path simultaneously to maintain the sameoverall relationships in the layout. For example, if you try tomove a field outside of its parent repeating frame in flex mode,its repeating frame will grow as necessary to contain it and anyobjects around the repeating frame will also grow or be pushedas necessary. You can only move or resize objects in onedirection at a time (vertically or horizontally, not diagonally). Touse flex mode, select the Flex tool in the toolbar or Flex in theLayout Options dialog box, or hold down the Control key whilemoving or resizing the object.

Caution: You can only resize one object at a time in flex mode.If you try to resize more than one object at a time in flex mode,only the object whose control point you click on will be resized.The other selected objects will be deselected.

The Selecting tool enables you to select an object or a group by clickingon it. To select an object, you click on it with the Selecting tool. If youclick on an object that has been grouped together via Group in theArrange menu, the entire group of objects is selected. To select onlyone object in a group at a time you must click on the border of theobject. By shift–clicking, you can select multiple objects or groups.

When you select an object, its control points become visible. When youselect an object(s) in the Layout editor, it is also selected in the ObjectNavigator. Once you have selected one or more objects, you canperform operations on them (e.g., set colors, copy, align). When theSelecting tool is active, you can move objects by clicking on them anddragging them. You can resize objects by dragging their control points.

Frame Select Tool

Rotate Tool


Scoping Rules Oracle Reports enforces certain scoping rules forselecting objects. These rules are enforced while any object is selected,regardless of whether you use the Selecting or Single Select tool toselect other objects. The rules are:

1. The two selecting tools allow you to select only objects that belongto the same group as the currently selected object(s). To select anobject in another group (or one not in any group), do one of thefollowing:

• First deselect all objects by clicking on an unoccupied part of theLayout editor, then select the other object as you normallywould.

• Choose one of the items in the Arrange—>Group Operationssubmenu.

2. You can select multiple objects only if they belong to the samegrouped set of objects in the Layout editor (i.e., they are siblings).

The Frame Select tool enables you to select a frame or repeating frameand all of the objects within it.

Note: Explicit anchors can affect which objects are selected bythe Frame Select tool. Any object that is indirectly or directlyanchored to an object within the frame or repeating frame willbe selected. Any object that is anchored to the frame orrepeating frame or an object outside of the frame or repeatingframe will not be selected.

The Rotate tool enables you to rotate the currently selected objects orgroups. You can only rotate boilerplate text and graphics. To rotate theobjects or groups, you click and drag a handle of one of the selectedobjects. The selected objects or groups will rotate in the direction youdrag.

Note: You cannot rotate a field directly, but you can reference afield (e.g., &ename) in a boilerplate text object, which can berotated.

Rules:

1. You can only rotate boilerplate text that you typed or imported inthe editor. You cannot rotate boilerplate text created with the LinkFile tool.

2. Rotated text is not supported on all operating systems. Forexample, rotated text will not appear rotated in character mode.

Reshape Tool

Magnify Tool

Line Tool


3. For rotated text, the Horizontal Sizing setting refers to the directionin which you read the text. For example, if you rotate your text 90degrees and give it a Fixed Horizontal Sizing, it actually means thatthe text will occupy a fixed vertical space.

4. If you set Horizontal and Vertical Sizing to Variable or Expand andthe rotation angle of the text is not a multiple of 90 degrees, theobject’s width will actually be treated as contracting (for Variable)or fixed (for Expand).

The Reshape tool enables you to change the shape of the selectedobjects. To reshape objects, you click and drag on their handles. Notethat the handles you see when reshaping differ from those you seenwhen selecting an object. The Reshape tool is only useful for certainobjects:

• For arcs, the Reshape tool enables you to change the sweep angleto something other than 90 degrees (the default when creating anarc).

• For polygons, the Reshape tool enables you to move any vertexto a new position.

• For rectangular objects (e.g., frames, fields, and Oracle Graphicsobjects), the Reshape tool enables you to move any vertex to anew position. Note that this is only useful if the rectangle hasbeen rotated such that the select handles no longer coincide withthe reshape handles.

• For anchors, the Reshape tool enables you to move any vertex toa new position, including moving the endpoints to new positionson the same or different objects.

The Magnify tool magnifies an area around the point on which youclick by a factor of two (i.e., the objects become twice as big as theywere). By pressing the constraint key while using the Magnify tool,you magnify by a factor of one–half (i.e., the objects become half as bigas they were). This tool is useful when you want to focus on one partof a large layout.

The Line tool enables you to draw a line boilerplate object. To draw aline, click where you want one endpoint, drag to the other endpoint,and release. To draw perfectly horizontal, vertical, or 45 degree lines,use constrained mode (look at ”Constrained Mode” earlier in thischapter).

Rounded RectangleTool

Rectangle Tool

Ellipse Tool

Arc Tool

Polygon Tool


The Rounded Rectangle tool enables you to draw a rounded,rectangular boilerplate object. Rounded rectangles are drawn by thesame method as rectangles. For more information, see “RectangleTool” on page 7 – 12}. To create squares with rounded corners, useconstrained mode. For more information, see “Constrained Mode” onpage 7 – 8.

The Rectangle tool enables you to draw a rectangular boilerplate object.To draw a rectangle, you click where you want a vertex and drag to theopposite vertex. To draw perfect squares, use constrained mode (lookat ”Constrained Mode” earlier in this chapter).

Note: The way an object is drawn depends upon the ObjectCreation setting in the General Drawing Options dialog box.(To get to this dialog box, select Drawing Options from theFormat menu and General from the submenu.) If ObjectCreation is set to Draw from Center, you click where you wantthe center of the rectangle and drag to a vertex.

The Ellipse tool enables you to draw an elliptic boilerplate object.Ellipses are drawn by the same method as rectangles. For moreinformation, see “Rectangle Tool” on page 7 – 12. To create perfectcircles, use constrained mode. For more information, see “ConstrainedMode” on page 7 – 8.

The Arc tool enables you to draw an arc boilerplate object. Arcs aredrawn by the same method as rectangles. For more information, see“Rectangle Tool” on page 7 – 12. To create circular arcs, useconstrained mode. For more information, see “Constrained Mode” onpage 7 – 8.

The Polygon tool enables you to draw a polygon boilerplate object.Polygons are drawn by clicking on each vertex of the polygon anddouble–clicking on the last vertex. When pressing the constraint keyduring specification of a polygon vertex, that segment of the polygonwill be constrained to the nearest 45 degree increment. Constrainingone vertex does not affect subsequent vertices. Each vertex must beindividually constrained. For more information on constrained mode,see “Constrained Mode” on page 7 – 8.

Note: While you are defining a polygon, the only things youcan do are define a vertex and move the editor scrollbar.

Polyline Tool

Freehand Tool

Text Tool

Frame Tool

RepeatingFrame Tool


The Polyline tool enables you to create a polyline boilerplate object. Apolyline is similar to a polygon except that its last vertex need not bejoined to the first vertex (i.e., the object need not be closed). Polylinesare drawn in the same manner as polygons. For more information,look at ”Polygon Tool”.

The Freehand tool enables you to draw a polyline freehand. To drawwith the Freehand tool, click and drag a path for the object.

The Text tool enables you to create and edit a boilerplate text object.You can create a boilerplate text object with the Text tool in one of twoways:

• Click where you want the text to start and begin typing. Textwill word wrap only when you type a return to start a new line.

• Click and drag to create a bounding box for the text. Textentered in the box will word wrap to fit within the horizontalboundaries of the box. The box will grow vertically, if necessary,to accommodate the text you type.

To edit existing boilerplate text, click on the boilerplate text object andstart typing/editing. When you are typing or editing text, you are intext mode. To get out of text mode, click outside of the boilerplate textobject.

While in text mode, you can perform actions on text (such as changingfonts, cutting, copying, or pasting) by selecting menu items. For moreinformation, see “Edit Boilerplate Text” in Chapter 8 of Building ReportsManual.

Note: If you change the font or size of the boilerplate text, thebounding box automatically grows or shrinks with the text.

The Frame tool enables you to create a frame. Frames are drawn andmodified in the same way as rectangles. For more information, see“Rectangle Tool” on page 7 – 12. To create perfect squares, useconstrained mode. For more information, see “Constrained Mode” onpage 7 – 8.

The Repeating Frame tool enables you to create a repeating frame.Repeating frames are drawn and modified in the same way asrectangles. For more information, see “Rectangle Tool” on page 7 – 12.To create perfect squares, use constrained mode. For moreinformation, see “Constrained Mode” on page 7 – 8.

Field Tool

Link File Tool

Oracle GraphicsTool

Button Tool

Anchor Tool


The Field tool enables you to create a field. Fields are drawn andmodified in the same way as rectangles. For more information, see“Rectangle Tool” on page 7 – 12. To create perfect squares, useconstrained mode. For more information, see “Constrained Mode” onpage 7 – 8.

The Link File tool enables you to create a boilerplate object that is readin from a file. The boilerplate may be text, drawings, or images and isrepresented as a rectangle in the editor. The boilerplate object is drawnand modified with the Link File tool in the same way as rectangles. Formore information, see “Rectangle Tool” on page 7 – 12. To createperfect squares, use constrained mode. For more information, see“Constrained Mode” on page 7 – 8.

The Oracle Graphics tool enables you to create an Oracle Graphicsobject. An Oracle Graphics object is associated with an OracleGraphics display. The object is executed by Oracle Graphics andincorporated in the report at runtime. The Oracle Graphics object isdrawn and modified in the same way as rectangles. For moreinformation, see “Rectangle Tool” on page 7 – 12. To create perfectsquares, use constrained mode. For more information, see“Constrained Mode” on page 7 – 8.

The Button tool enables you to draw a button object. User–definedbuttons are drawn using the same method as is used for rectangles.For more information, see “Rectangle Tool” on page 7 – 12. To createperfect squares, use constrained mode. For more information, see“Constrained Mode” on page 7 – 8. Note: User–defined buttons willappear in the Previewer with the same characteristics as native buttonson your platform.

The Anchor tool enables you to anchor two objects together. To drawan anchor, click on an edge of the child object, click at other positions inthe editor (optionally), and double–click on an edge of the parentobject. When pressing the constraint key during specification of ananchor, the placing of the anchor on the child object is constrained tothe nearest 25 percent increment. For more information, see“Constrained Mode” on page 7 – 8.

Additional Default Layout Tool

OLE2 Object Tool

Line/Fill/Text Display

Fill Color Tool


The Additional Default Layout tool enables you to define a defaultlayout for a portion of your layout. This enables you to create a layoutwithout overwriting the entire Layout editor. To define the area inwhich you want the default layout, you use the same method as youwould for drawing rectangles. For more information, see “RectangleTool” on page 7 – 12. To create perfect squares, use constrained mode.For more information, see “Constrained Mode” on page 7 – 8.

After you have defined the area in which the default layout will appear,the Default Layout dialog box appears. When you accept the dialogbox, the default layout is generated within the area you have defined.

The OLE2 Object tool enables you to place an OLE2 object in yourlayout. OLE2 objects are drawn by the same method as rectangles. Formore information, see “Rectangle Tool” on page 7 – 12. To createperfect squares, use constrained mode. For more information, see“Constrained Mode” on page 7 – 8.

After you have drawn the OLE2 object, the standard Insert ObjectOLE2 dialog box will be displayed. From this dialog box, you definethe type, source, and whether the object is linked or imbedded. Notethat all of these items must be defined to create an OLE2 object. If youcancel out of the dialog box, the object is not created.

The Line/Fill/Text display shows current selections for line, fill, andtext. To change the current selections, use the Fill, Line, Text Colortools.

The Fill Color tool displays all of the available colors, No Fill, andPatterns. Choosing any of the colors or No Fill sets the Fill color for theselected objects and all subsequently created objects. Selecting Patternsdisplays a pattern palette. Choosing any pattern sets the Fill patternfor the selected objects and all subsequently created objects. At thebottom of the Pattern palette are foreground and background colorpalettes. Choosing foreground and background colors sets the colorsfor the patterns.

To change the available colors, you can import a different color paletteor change the colors using Color Palette in the Format menu.

Rules:

1. On Windows, button colors will not display when the report is run.

Line Color Tool


The Line Color tool displays all of the available colors, No Line, andPatterns. Choosing any of the colors or No Line sets the Line color forthe selected objects and all subsequently created objects. SelectingPatterns displays a pattern palette. Choosing any pattern sets the Linepattern for the selected objects and all subsequently created objects. Atthe bottom of the Pattern palette are foreground and background colorpalettes. Click on these to display the available colors. Choosingforeground and background colors sets the colors for the patterns.


Line Width You set the line width of an object by selectingFormat—>Line. Half of the width of the line extends outside of theobject and the other half extends inside of the object. The figure belowillustrates this.

Rules:

1. The borders of sibling objects (e.g., two fields inside the samerepeating frame) can overlap one another. Note, however, that thismeans one of the objects will be at least partially overwritten by theother.

A field or its border cannot overlap its parent repeating frame. Ifthe field and its border do not fit entirely inside the repeatingframe’s borders, you will get a frequency error when you run thereport.

2. If you create a repeating frame with a border, the border applies toeach instance of the repeating frame. If Vertical Spacing is zero forthe repeating frame, there will be no space between the borders ofthe instances. If Vertical Spacing is greater than zero, the space willbe added between the borders of the instances.

Text Color Tool

Status Line


3. Anchors are attached to the edges of objects, not their borders.Therefore, at runtime if an object’s border is displayed, then anyobjects anchored to it will be displayed relative to the object’s edge,not its border.

4. If you set a border using PL/SQL, the PL/SQL will override theborder created using Format—>Line.


The Text Color tool displays all of the available colors. Choosing any ofthe colors sets the Text color for the selected objects and allsubsequently created objects.


Rules:


In the Layout editor, the status line displays the following information:



• rotation angles

• zoom levels

• anchor percentages

The behavior of the status line varies based on the tool being used andaction being performed. The following table shows what is displayedby the status line under different circumstances:

Tool Action Status Information

Every tool move mouse x,y coordinates of cursor

Arc, Ellipse, create object x,y coordinates ofArc, Ellipse, Rectangle, RoundedR t l

create object x,y coordinates ofstarting point, width,

d h i htg

Rectangleg p

and height

Freehand create object x,y coordinates of cursor

Line create line x,y coordinates ofLine create line x,y coordinates ofstarting point, linestarting point, linelength, and rotation

l (h i l)g ,

angle (horizontal)

☞


Tool Status InformationAction

Magnify click mouse zoom level

Polygon, Polyline create object x,y coordinates of Polygon, Polyline create object x,y coordinates of cursor and rotation

l (h i t l)angle (horizontal)

Rotate, Group Rotate drag rectangle x,y coordinates of, p g g ,ystarting point

move object change in x,y

rotate object rotation angle (h l)

j g(horizontal)

Select, Group Select drag rectangle x,y coordinates of, p g g ,ystarting point

move object change in x,y

resize object change in x,y

Anchor move object percentage along childd d

j p g gand parent edges

resize object percentage along childresize object percentage along childand parent edges

Pop–Up Menu

The pop–up menu appears when you click your right mouse button inthe Layout editor.


The pop–up menu in the Layout editor for non–OLE2 objects containsthe following items:

Turns confine mode on or off. For more information, see“Confine Mode and Flex Mode” on page 7 – 9. This itemonly appears if the cursor is over a blank area of the editor.

Turns flex mode on or off. For more information, see“Confine Mode and Flex Mode” on page 7 – 9. This itemonly appears if the cursor is over a blank area of the editor.

Is the same as Edit—>Cut.

ConfineMode

FlexMode

Cut

OLE2 Pop–Up Menu


Is the same as Edit—>Copy.

Is the same as Edit—>Paste.




Is the same as Help—>Contents.

If your cursor is in a blank area of the editor or on an object that cannothave PL/SQL, only a subset of these items appears.

In addition to the standard pop–up menu items, the following appearwhen you click your right mouse button while the cursor is over anOLE2 object in the Layout editor:

Is the same as Edit—>Object.

Is the same as Edit—>Links.

Toggles between showing and not showing special outlinesaround OLE2 objects to indicate whether they are linked.Linked objects will have a dashed outline and imbeddedobjects a solid line.

Copy

Paste

Clear

Properties

ProgramUnitEditor

Help

Object

Links

ShowObjectTypes

Navigating betweenRegions

Defining Pages


Navigation

This section describes how to navigate between regions within theLayout editor.

Note: For more information about how to manipulate objects,see “How To” in Chapter 8 of Building Reports Manual.

When you first enter the Layout editor of a new report, you are placedin the Body/Margin region. You can create, modify, and delete objectsin either the Body or the Margin. To move from the Body to the Margin(in which you can only edit the margin border and the objects ownedby the margin), do the following:

1. Select View—>Settings—>Layout. The Layout Options dialog boxis displayed.

2. In the dialog box, choose Margin under Display Layout Using.

3. Accept the dialog box or select the Apply button. You are placed inthe margin when you accept the dialog box or select the Applybutton.

Likewise, you can move to the header or trailer pages by selectingHeader or Trailer in the Layout Settings dialog box.

You specify the size of each layout page and the number of physicalpages per logical page using Global Properties (double–click on thereports node’s icon in the Object Navigator). For more information ondefining layout pages, see “Report Properties” on page 4 – 1.


Margins

In the Layout editor, the Margin region lies underneath the Bodyregion. The boundary of the Body region of your report is shown as adark box.

When you are in the Margin region, you can create objects anywhere,but those objects that are not outside of the Body region boundary willbe overlaid by the Body in the output. As a result, if the objects in themargin overlap objects in the Body, the Margin objects will beoverwritten by the Body objects.


For example, suppose you have objects in the Body and Margin regionsas shown below:

B_Margin_Text is located in the Margin region and R_Sal and F_Sal arelocated in the Body region. Because B_Margin_Text overlaps R_Sal andF_Sal, it will be partially overwritten by R_Sal and F_Sal. This happensbecause the Body region overlays the Margin region.

You cannot clear, cut, copy, or export the margin, but you can resize it.For more information about resizing margins, see “Adjust Margins” inChapter 8 of Building Reports Manual.

C H A P T E R

8L

8 – 1Layout Properties

Layout Properties

ayout properties define the objects that make up the layout for areport. Each of the following objects has a property sheet associatedwith it that defines its properties:

• common layout object – 8 – 2

• repeating frame – 8 – 28

• frame – 8 – 28

• field – 8 – 41


• anchor – 8 – 62

• matrix – 8 – 70

• Oracle Graphics – 8 – 73

• user–defined button – 8 – 81

• OLE2 object – 8 – 85


Common Layout Object Properties

Frames, repeating frames, fields, boilerplate, Oracle Graphics displayobjects, button objects, and OLE2 objects have a number of propertiesthat are the same.

These common properties appear on the following tabs:

• General Layout – 8 – 3

• Printer Codes – 8 – 26

• Comments – 8 – 27

Rules:

1. You must ensure that properties on the same or different objects donot conflict with each other. Because of the power of the layoutproperties, it is possible to specify properties such that they conflictwith other properties.

You should avoid the following combinations of layout propertieson the same object. If you try to use these combinations on thesame object, you will get an error:

• Print Condition Object of Enclosing and Type of Last

• Print Condition Object of Enclosing and Type of All But Last

• Print Condition Type of All and Page Break Before set

• Print Condition Type of All But First and Page Break Before set

• Print Condition Type of All But Last and Page Break Before set

• Keep With Anchoring Object and Page Break Before set (for anobject that is located after its anchoring object) or Page BreakAfter set (for an object that is located before its anchoring object)

2. Similarly, combinations of properties on different objects can causeunpredictable results or an infinite report. For example, supposeyou have two boilerplate objects anchored together inside of aframe. The parent object has a Print Condition Type of All and anObject of Enclosing. The child object has a Print Condition Type ofFirst, a Print Condition Object of Anchoring, and Page Break Beforeset. The figure below illustrates this layout:


When you run the report, the child object does not appear in theoutput. Because it has Page Break Before set, the child can neversatisfy its Print Condition (Type First, Object Anchoring). Note,however, that the object underneath the child object (B_Plate3) doesappear.

General Layout Tab

The General Layout tab is shown below. It contains the followingproperties:

• Format Trigger – 8 – 4 • Page Break Before – 8 – 11

• Horizontal Sizing – 8 – 4 • Page Protect – 8 – 12

• Keep with Anchoring Object – 8 – 6 • Print Condition Object – 8 – 15

• Name – 8 – 8 • Print Condition Type – 8 – 15

• Page Break After – 8 – 9 • Vertical Sizing – 8 – 20

Note that some layout objects only have a subset of these properties intheir property sheets.

Format Trigger

Horizontal Sizing


Is a button that displays the Program Unit editor in which you canenter the PL/SQL function or anonymous function body for a FormatTrigger. For more information about Format Triggers, see “FormatTriggers” on page 13 – 28.

Is how the horizontal size of the object will change at runtime toaccommodate the objects or data within it. Horizontal Sizing isidentical to Vertical Sizing, except that it refers to the width rather thanthe height of the object. For more information on sizing options andrules, see “Vertical Sizing” on page 8 – 20.

The figure below illustrates how the Horizontal Sizing setting isdisplayed in the Layout editor.


Examples:

1. Suppose that you have a field with the following characteristics:

Characteristic Value

width 1 inch

Horizontal Sizing Contract

height 1 inch

Vertical Sizing Fixed

The following diagram shows what the field might look like whenformatted:

Note that when the data is less than one inch wide the size of thefield decreases to the minimum size necessary to hold the data. Itis also important to note here that if the data was more than oneinch long, it would be truncated because the field cannot expandvertically or horizontally.

2. Suppose that you have a frame named M_1 with the followingcharacteristics:


Horizontal Sizing Variable

height 7 inches

Vertical Sizing Fixed

Assume further that the Page Width you defined in the reportproperty sheet is eight inches. M_1 contains a repeating frame withone field, F_Ename. The first value of F_Ename is four incheswide, the next value is 3 inches, the next is four inches, and the lastis four inches. The following diagram shows how the frame mightbe formatted:

Keep with AnchoringObject


Note that the first two instances of field F_Ename print on the firstlogical page, but, the second two instances, because there is notenough room on the first logical page, print on the second logicalpage. It is also important to note that if the Horizontal Sizing wasContract or Fixed, instead of Variable, the frame would not printunless it could fit entirely on one logical page.

Indicates whether to keep an object and the object to which it isanchored on the same logical page. Checking Keep with AnchoringObject means that if the object, its anchoring object, or both cannot fiton the logical page, they will be moved to the next logical page.

If you set Keep with Anchoring Object for a repeating frame, it meansthe first instance of the repeating frame must be able to fit on the samepage as its anchoring object. Otherwise, the Keep With AnchoringObject condition is not satisfied. If you set Keep With AnchoringObject for any layout object other than a repeating frame, it means theobject must be able to format entirely on the same page as its anchoringobject.

The anchor between the two objects may be explicit or implicit.Consequently, Keep With Anchoring Object may have an effect even ifyou have not explicitly created an anchor between two objects. Formore information about implicit anchoring, see “Implicit AnchoringAlgorithm” on page 2 – 43.


Unchecked.Default:


Examples:

1. Suppose that you have created three boilerplate objects similar tothe following:

B_2 and B_3 each has Keep With Anchoring Object specified. Onthe logical page where Oracle Reports first tries to print theseobjects, there is enough room for B_1 and B_2 but not for B_3.Since B_3 has Keep With Anchoring Object specified and itsanchoring object is B_2, B_2 and B_3 would be moved to the nextlogical page. Since B_2 also has Keep With Anchoring Objectspecified and its anchoring object is B_1, B_1 would also be movedto the next logical page.

Rules:

1. Keep With Anchoring Object applies only to the first logical pageon which the object is triggered to be formatted. Keep WithAnchoring Object is ignored on subsequent pages.

2. If moving the object and its anchoring object to the next logicalpage would leave the current logical page blank or only containingrepeated objects (e.g., a page heading), Keep With AnchoringObject will not be applied. This prevents unnecessary blank pagesin your report.

3. If the anchoring object is a repeating frame and the current object isoutside of the repeating frame, then anchoring object refers to therepeating frame as a whole (all the instances of the repeatingframe).

Name


4. If two objects are anchored to their enclosing frame and the framehas Vertical and/or Horizontal Sizing of Contract or Variable, thenall three objects must be able to complete formatting on the samepage to satisfy the Keep With Anchoring Object condition. If thetwo objects are enclosed by a repeating frame instead of a frame,then this rule applies to each instance of the repeating frame. Thefigure below illustrates this rule.

In the figure, B_1, B_2, and M_1 would all have to be able tocomplete formatting on the same page in order to satisfy the KeepWith Anchoring Object condition.

Is the name that Oracle Reports uses to identify the current layoutobject.


Enter any valid name not to exceed 30 bytes. Formore information about naming conventions, see“Naming Conventions” on page D – 1.

For frames, M_n, where n is a number that isunique among frame names for the report.

For repeating frames, R_n, where n is a numberthat is unique among repeating frame names forthe report.

For fields,F_n, where n is a number that is uniqueamong field names for the report.

For boilerplate, B_n, where n is a number that isunique among boilerplate names for the report.

Options:

Default:

Page Break After


For matrix objects, X_n, where n is a number that isunique among matrix names for the report.

For Oracle Graphics objects, D_n, where n is anumber that is unique among Oracle Graphicsobject names for the report.

For button objects, U_n, where n is a number that isunique among field names for the report.

For OLE2 objects, B_n, where n is a number that isunique among boilerplate object names for thereport.

Indicates that you want all children of the object to be moved to thenext page. In other words, any object that is a child object of an anchor(implicit or explicit) to this object will be treated as if it has Page BreakBefore set. Note that this does not necessarily mean that all the objectsbelow the object with Page Break After will move to the next page.Look at ”Rules” below.


Unchecked.

Rules:

1. Page Break After delays only the formatting of an object’s childobjects. The formatting of sibling objects is not delayed becausethere is no hierarchy (i.e., parent–child relationship) by whichOracle Reports can determine the order of formatting for siblings.As a result, an object must be anchored (implicitly or explicitly) toanother object as the parent for Page Break After to have an effect.

For example, in the following diagram Page Break After is set onfor frame M_Dept. Both M_Dept and M_Emp have Fixed Verticaland Horizontal Sizing. Page Break After does nothing in this casebecause M_Dept and M_Emp are siblings inside of the parentframe M_Parent.

Default:


In the following diagram, everything is the same as the previouscase except that M_Dept is explicitly anchored to M_Emp as theparent. Page Break After delays the formatting of M_Emp in thiscase because M_Dept is the parent of M_Emp.

2. For repeating frames, Page Break After sets a logical page breakafter the repeating frame as a whole. To have a page break aftereach instance of the repeating frame you should also set MaximumRecords per Page to 1 on the Repeating Frame property sheet.

3. Objects below an object with Page Break After set may not move tothe next page. If an object is not a child of the object with PageBreak After set, then that object, if it can fit, may print on the samepage as the object with Page Break After set. The figure belowprovides an example of this concept:

Page Break Before


Notice how B_Graph, which appears below R_Sal in the layout,actually ends up printing on page 1 with R_Sal. This happensbecause B_Graph is not a child of R_Sal. If you explicitly anchoredB_Graph as a child to R_Sal, then B_Graph would have appearedon page 2 instead of page 1.

4. If an object has no external objects anchored to it (implicitly orexplicitly), then Page Break After has no effect.

Indicates that you want the object to be formatted on the page after thepage on which it is initially triggered to print. Note that this does notnecessarily mean that all the objects below the object with Page BreakBefore will move to the next page. Look at ”Rules” below.


Unchecked.

Rules:

1. For repeating frames, Page Break Before sets a logical page breakbefore the repeating frame as a whole. To have a page break beforeeach instance of the repeating frame, you should also set MaximumRecords per Page to 1 on the Repeating Frame property sheet.

2. Objects below an object with Page Break Before set may not moveto the next page. If an object is set to print on a page but is movedto the next page because of Page Break Before, other objects may beplaced in the space where the object was originally set to print, ifthere is sufficient room. The figure below provides an example ofthis concept:

Default:

Page Protect


Notice how B_Graph, which appears below R_Sal in the layout,actually ends up printing on page 1 instead of page 2.

Indicates whether to try to keep the entire object and its contents on thesame logical page. Checking Page Protect means that if the contents ofthe object cannot fit on the current logical page, the object and all of itscontents will be moved to the next logical page.

Note: Using Page Protect may cause objects below the pageprotected object(s) to appear above the page protectedobject(s). Look at ”Rules” below.


Unchecked.

Examples:

1. Suppose that you have created a frame named M_1 with a numberof fields that display various columns and summaries. For ease ofreading, you want to keep all of the fields in M_1 on the samelogical page so that readers can see the columns and theirsummaries together.

Specify Page Protect for M_1. If M_1 and all its fields cannot fit onthe first logical page that Oracle Reports attempts to print them,Oracle Reports will try to print M_1 and all its objects on the nextlogical page.

The figures below illustrate what would happen to the frame withand without Page Protect checked.

Default:


2. Assume the conditions stated in the above example. Supposefurther, though, that M_1 and all its fields cannot fit on the secondlogical page on which Oracle Reports tries to print it. OracleReports will print as much of M_1 as it can on the logical page andprint the rest of it on the following logical page.

3. Suppose that you have a master–detail report. If at all possible,you would like to have all of the details and the master appearingon the same page. To do this, you select Page Protect for themaster repeating frame (the outermost repeating frame). If thedetails and the master cannot fit on the first page on which they aretriggered to print, they will be triggered to print on the next pageinstead.


Rules:

1. Page Protect applies only to the first logical page on which theobject is triggered to be formatted. Page Protect is ignored onsubsequent pages.

2. For repeating frames, Page Protect refers to each instance of therepeating frame. Each instance of the repeating frame and itsenclosed objects will be kept together by Page Protect. The onlyexception is that page protection is not applied to the first instanceon a page other than the first page of the repeating frame.

For example, in the diagram below, page protection is applied toinstances 1, 2, and 4, but not to instance 3. Instance 3 is the firstinstance to format on the second page of the repeating frame.Notice that, in this case, if page protection had been applied toinstance 3, it would have started on page 3 instead of page 2. Thiswould have left page 2 almost completely blank.

3. Page Protect is not supported for repeating frames that are part of amatrix. When repeating frames are related via matrix object,setting Page Protect will not effect them.

4. If moving the object and its contents to the next logical page wouldleave the current logical page blank or only containing repeatedobjects (e.g., a page heading), Page Protect will not be applied.This prevents unnecessary blank pages in your report.

Print Condition Object

Print Condition Type


5. If Page Protect causes an object to be moved to the next logicalpage when formatting, an object alongside the page protectedobject may or may not be moved as well. If the object alongside thepage protected object is not anchored (implicitly or explicitly) tothe page protected object, and that object can fit in the space wherethe page protected object could not fit, the object will print on thatlogical page. Otherwise, the object will be moved along with thepage protected object to the next logical page.

Is the object on which to base the Print Condition Type of the currentobject. For example, if you specify a Print Condition Type of All and aPrint Condition Object of Anchoring Object, the current object will betriggered to print on every logical page on which its anchoring object(parent object) appears.


Anchoring Object is the parent object to which thecurrent object is implicitly or explicitly anchored.

Enclosing Object is the object that encloses thecurrent object.

Anchoring Object

Examples:

Look at ”Examples” under ”Print Condition Type.”

Rules:

Look at ”Rules” under ”Print Condition Type.”

Is the frequency with which you want the object to appear in the report.The Print Condition Type options indicate the logical page(s) on whichthe object should be triggered to print with regard to the PrintCondition Object. For more information about Print Condition Object,go to ”Print Condition Object” earlier in this chapter.

Note: Just because the object is triggered to print on a logicalpage does not mean it will print on that logical page. Othersettings (e.g., Page Break Before) or the amount of spaceavailable on the page may cause Oracle Reports to print anobject on a page other than the one on which it was initiallytriggered to print.

Options:

Default:


In applying these options, Oracle Reports considers the first page of anobject to be the first logical page on which some part of the object isprinted. Likewise, the last page is considered to be the last logical pageon which some part of the object is printed. For example, if you specifya Print Condition Type setting of First and a Print Condition Objectsetting of Enclosing Object, the object will be triggered to print on thefirst logical page on which its enclosing object appears.


All means the object and all of its contents will beprinted on all logical pages of the Print ConditionObject. The object will be repeated on anyoverflow pages of the Print Condition Object andwill be truncated at the logical page boundary, ifnecessary.

All but First means the object and all of its contentswill be printed on all logical pages of the PrintCondition Object except the first logical page. Theobject will be formatted only on overflow pages ofthe Print Condition Object and will be truncated atthe logical page boundary, if necessary.

All but Last means the object and all of its contentswill be printed on all logical pages of the PrintCondition Object except the last logical page. Theobject will be repeated on any overflow pages ofthe Print Condition Object except the last one andwill be truncated at the logical page boundary, ifnecessary.

*Default means that Oracle Reports will use objectpositioning to set the Print Condition Type to either*First or *Last for you. (The asterisk indicates thatOracle Reports specified the setting for you.) Formore information on how Oracle Reports does this,see “Print Condition Algorithm” on page 2 – 47.

First means that the object and all of its contentswill only be printed on the first logical page of thePrint Condition Object. The object will beformatted and will overflow to subsequent pages,if necessary.

Options:


Last means that the object and all of its contentswill only be printed on the last logical page of thePrint Condition Object. The object will beformatted after the Print Condition Object and willoverflow to subsequent pages, if necessary.

Varies according to object.

Examples:

1. Suppose that you have created a summary column namedCol_Sum that sums the values of a column in a group namedGroup_1. Col_Sum is the source of a field (F_1) that is enclosed ina repeating frame (R_1), which contains the values from Group_1.If you specify a Print Condition Type setting of All and a PrintCondition Object setting of Enclosing Object for F_1, it prints inevery instance of R_1 on every logical page.

2. The diagram below illustrates a layout and the resulting output.

Because it is outside of repeating frame C, boilerplate object D’sPrint Condition Object refers to the repeating frame as a whole.Because they are inside the repeating frame, boilerplate objects Aand B’s Print Condition Object refer to each instance of repeatingframe C.

Default:


Object D appears on all logical pages on which repeating frame Cappears. Object A, however, only prints when an instance ofrepeating frame C overflows. The Print Condition Type of All ButFirst in this case means to trigger the object to print on every logicalpage of each instance of the repeating frame, except for the veryfirst page on which an instance prints.

Since repeating frame C only contains two objects (boilerplateobjects A and B), it only overflows to a second page whenboilerplate object B overflows. Looking at the Print Condition Typeof objects A and B (All But First and First), you would think thatthese two objects could never appear on the same page. In thisscenario, however, they can only appear on the same page.

Rules:

Caution: If its contents cannot fit within the logical page on which itstarts to print, an object with a Print Condition Type of All, All ButFirst, or All But Last cannot overflow onto subsequent pages. In thiscase, the contents of the object will be truncated and the object willprint with the same, truncated contents on every logical page it istriggered to print.

1. If its contents cannot fit within the logical page on which it starts toprint, an object with a Print Condition Type of First or Last canoverflow onto subsequent pages. As a result, even though it istriggered to print only on the first or last page, it may overflowbeyond the first or last page.

Note: As a result of overflow, a Print Condition Type of Firstand a Print Condition Type of All But First are not necessarilymutually exclusive. For example, if one layout object has aPrint Condition Type of First and another has All But First andthey both have the same Print Condition Object, you mightthink that the two objects could never appear on the samepage. If the layout object with First overflows onto the secondpage, though, the two objects could appear on the same page.

2. An object that is implicitly or explicitly anchored to its enclosingframe or repeating frame cannot have a Print Condition Type ofLast or All But Last. An object that is anchored to another objectwithin its frame or repeating frame cannot have a Print ConditionType of Last or All But Last with a Print Condition Object ofEnclosing Object. The figure below illustrates this rule.


3. If the Print Condition Object of a layout object is a repeating framethat encloses the layout object, then it refers to each instance of therepeating frame to which the object is anchored.

4. If the Print Condition Object of a layout object is a repeating frameand the layout object is outside of the repeating frame, then it refersto the repeating frame as a whole. For example, a Print ConditionType of First means the first logical page on which the repeatingframe is triggered to print.

5. Whether the Print Condition Object refers to a repeating frame as awhole or the instances of a repeating frame, the Print ConditionType always refers to logical pages. For example, suppose the PrintCondition Object of a layout object is a repeating frame and thelayout object is outside of the repeating frame. In this case, thePrint Condition Object would refer to the instances of the repeatingframe. A Print Condition Type of First, however, does not meanthe first instance of the repeating frame. It means the first logicalpage on which each instance of the repeating frame is triggered toprint.

6. Objects in the margin region are restarted on every physical page.As a result not all Print Condition Types make sense for marginobjects. Because objects are restarted on every page, it is as if youare always on the first page of the object. First is the same as All.Last and All But Last are invalid because ”last” is never reached.All But First causes the object to never appear because the objectnever goes beyond ”first.”

Vertical Sizing


Is how the vertical size of the object may change at runtime toaccommodate the objects or data within it:

• For frames and repeating frames, sizing defines whether the sizeof the frame or repeating frame should vary with the objectsinside of it.

• For objects containing text, sizing defines whether the field orboilerplate should vary with the size of the text. Fixed size textwill wrap within the defined size of the object and may betruncated if there is not enough room. Look at “Rules.” Numberor date data will appear as asterisks if the data cannot fit withinthe defined size.

• For images, drawings, and Oracle Graphics displays, OracleReports uses proportional scaling. The sizing options for images,drawings, and Oracle Graphics displays determine the scalingfactor.

Sizing choices can also influence on which page an object is formatted.Look at “Rules.”

The figure below illustrates how the Vertical Sizing setting is displayedin the Layout editor.


Contract means the vertical size of the objectdecreases, if the formatted objects or data within itare short enough, but it cannot increase to a heightgreater than that shown in the editor.

Note:Truncation of data may occur; look at”Examples.” (You can think of this option asmeaning ”only contract, do not expand.”)

Options:


Expand means the vertical size of the objectincreases, if the formatted objects or data within itare tall enough, but it cannot decrease to a heightless than that shown in the editor. (You can thinkof this option as meaning ”only expand, do notcontract.”)

Fixed means the height of the object is the same oneach logical page, regardless of the size of theobjects or data within it.

Note: Truncation of data may occur; look at”Examples.” The height of the object is defined tobe its height in the editor.

Variable means the object may expand or contractvertically to accommodate the objects or datawithin it (with no extra space), which means theheight shown in the editor has no effect on theobject’s height at runtime.

Varies according to the object.

Examples:

1. Suppose that you have a field with the following characteristics:


width 1 inch

Horizontal Sizing Fixed

height 2 inches

Vertical Sizing Expand

The following diagram shows what the field might look like whenformatted. Note that the field always takes up at least two inchesvertically and is always one inch wide. If the data takes more thanone inch horizontally and two inches vertically, the field growsvertically to accommodate the data.

Default:


2. Suppose that you have a frame named M_2 with the followingcharacteristics:


width 5 inches

Horizontal Sizing Fixed

Vertical Sizing Variable

Assume further that the Page Height for the report is twelveinches. Because of the size of the objects within it, M_2 requireseight inches vertically to format. Another frame, called M_1,precedes M_2 on the logical page and takes up six inches.

The following diagram shows how the frame might be formatted.

Note that all of M_2 cannot fit on the first logical page. Because theVertical Sizing is Variable, the first five inches of M_2 are printed onthe first logical page and the last two inches are printed on thesecond logical page. Had the Vertical Sizing been Contract or Fixed,all of M_2 would have printed on the second logical page.

3. Suppose that you have an Oracle Graphics display that youincluded in your report. You gave the Oracle Graphics object inyour report a Vertical and Horizontal Sizing of Fixed. OracleReports scales the display to fit within the dimensions you definedfor the object.


Rules:

Caution: If the contents of an object exceed its defined height, itsVertical and Horizontal Sizing determine whether the contentsoverflow onto the next page or are truncated. The table below showsthe combinations of objects and sizing choices that cause overflow andtruncation. (Expand and Variable in the table apply if either the Verticalor Horizontal Sizing is Expand or Variable.) Images, drawings, andOracle Graphics displays cannot overflow. Look at the rules below fordetails about images, drawings, and Oracle Graphics displays.

Object Fixed/Contract

Expand Variable

repeating frameinstances and frames(contents <= definedheight)

no overflow no overflow no overflow

repeating frameinstances and frames(contents > definedheight)

no overflow overflow, ifunable to fiton the page

overflow, ifunable to fiton the page

fields and boilerplate(contents <= definedheight)

no overflow no overflow no overflow

fields and boilerplate(contents > definedheight)

truncate* overflow, ifunable to fiton the page

overflow, ifunable to fiton the page

* To avoid truncation, make the field or boilerplate’s Vertical SizingVariable and surround it with a frame that has Fixed Vertical Sizing.Note also, that when truncation of text occurs, it occurs after thefield or boilerplate text has been wrapped.

Additional Information: If you want your data truncated,you should use the SQL SUBSTR function in your query. Forexample, if you want only the first four characters of a column,then use SUBSTR in your SELECT statement to retrieve onlythose characters from the database.

1. When formatting an object, if Vertical Sizing is Fixed Oracle Reportswill only format it on a logical page if the page has enough space tocontain the entire object.

2. If Vertical Sizing is Expand, Oracle Reports will only format theobject on a logical page if the page has enough space to contain thedefined height of the object (i.e., its minimum size). If formatting isnot complete, the object overflows to the next page.


3. If Vertical Sizing is Variable or Contract, Oracle Reports will formatas much of the object as possible on the first logical page and, ifnecessary, complete the object on the following logical page(s).

4. If a number cannot fit in its field, then asterisks will appear in thefield instead of the value. To get the value to appear, you eitherneed to resize the object or change its Horizontal Sizing to Expandor Variable.

5. The following sizing rules apply to layout objects (e.g., fields orboilerplate) that contain an image/drawing or an Oracle Graphicsdisplay:

• If the sizing of the layout object is variable (i.e., both Vertical andHorizontal Sizing are Variable), then the contents will appear thesame size as they do in their source (e.g., the source file).

• If the sizing of the layout object is fixed (i.e., both Vertical andHorizontal Sizing are Fixed), then proportional scaling isperformed on the contents. In some cases, this may lead toempty space or ”gaps” between the contents and the border ofthe layout object.

For example, if an object is Fixed both horizontally and verticallyand the image is too large for the object, then the image will onlyfill the object in one direction. In the other direction, the imagewill be shorter than the object. To avoid these gaps, you caneither change the sizing (e.g., make it Variable horizontally,vertically, or both) or you can manually resize the object.

• If a layout object containing an image/drawing or an OracleGraphics display is Fixed in only one direction, Oracle Reportswill always attempt to have the contents fill up the Fixeddimension.

• If the sizing of the layout object is Contract in one direction andFixed in the other, the contents may be clipped. To avoidclipping of the contents, you can either change the sizing (e.g.,make it Variable both horizontally and vertically) or you canmanually resize the object.

• If the sizing of the layout object is variable (i.e., Vertical orHorizontal Sizing is Variable) and the layout object cannot fit inits enclosing object (e.g., a frame or the logical page), the reportwill infinitely loop (because the object can never format).


6. If a value to be displayed in the report output relies on theformatting of the report, then the field or boilerplate object thatdisplays the value must have a Vertical and Horizontal Sizing ofFixed. (This is sometimes referred to as page–dependentreferencing.) If the sizing is not fixed, Oracle Reports will change itto be fixed at runtime.

A typical case of page–dependent referencing is a field that has aSource of &Total Logical Pages. The total number of logical pagescannot be determined until the entire report has been formatted.But Oracle Reports must format the field before the end of thereport and cannot wait until the report is completely formatted todetermine how big to make the field. Consequently, the field’ssizing must be fixed, so that Oracle Reports knows how muchspace to reserve for it before its source value is determined.

Following are cases of page–dependent referencing, where a fieldor boilerplate object’s sizing must be fixed because its source valuedepends on the formatting of the report:

• If a summary column has a Reset At or Compute At of Page, thenthe field or boilerplate object that displays its value must havefixed sizing.

• If a formula or summary column relies on a summary columnthat has a Reset At or Compute At of Page, then the field orboilerplate object that displays its value must have fixed sizing.

• If the Source of a field is &Logical Page Number, &Panel Number,&Physical Page Number, &Total Logical Pages, &Total Panels, or&Total Physical Pages, then any layout object that displays thefield (either the field itself or a boilerplate object) must havefixed sizing.

• If a field has a page number as its Source and, in the PageNumbering dialog box, Reset At is a repeating frame, then anylayout object that displays its value must have fixed sizing.

Note: If a field containing a page–dependent reference has Hiddenset, then the field may have Horizontal Sizing of Variable, Expand,or Contract. Any boilerplate object that references the field, though,must be fixed in sizing.


Printer Codes Tab

Printer codes are references to printer escape sequences that definespecial printing instructions (e.g., special font sizes or highlighting) forthe object. The Printer Codes tab is shown below. It contains thefollowing properties:

• After – 8 – 27

• Before – 8 – 27

Caution: Printer codes are only used when running your report incharacter–mode. They are not used when running it in bitmap.

Note: In most cases, you should be able to accomplish anyspecial formatting by writing PL/SQL for the layout objects.

Examples:

1. Suppose that in your printer definition file you created two printercodes named &123 and &456. &123 causes the printer to printspecial font. &456 causes the printer to print the normal font.Assume that you want all fields in a repeating frame (R_1) to beprinted using the special font. You could either use the printercode for each individual field or use it for the entire repeatingframe. The latter case is easier to create and maintain.

You select the Printer Codes button from the R_1 repeating frameproperty sheet and enter &123 in the Before field and &456 in theAfter field. When R_1 is printed, the printer code will be executedbefore and after each line of R_1 is printed. The diagram belowshows the points at which each printer code is invoked:

After

Before


Is a reference to the printer escape sequence to be executed after eachline of the object. The printer escape sequence is inserted after theobject is triggered to print but before it has actually printed. Entries inthis field may be of the form &number, where number is a numberassigned to a packaged Oracle Reports printer code or a printer codeyou created.

Enter a valid printer code reference not to exceed256 bytes in length.

Is a reference to the printer escape sequence to be executed before eachline of the object. The printer escape sequence is inserted after theobject is triggered to print but before it has actually printed. Entries inthis field may be of the form &number, where number is a numberassigned to a packaged Oracle Reports printer code or a printer codeyou created.

Enter a valid printer code reference not to exceed256 bytes in length.

Comment Tab

The Comment tab contains a text field in which you can document thelayout object.



Blank.

Options:

Options:

Options:

Default:


Frame Properties

When you double–click on a frame in the Layout editor or its icon inthe Object Navigator, its Frame property sheet is displayed.

The Frame property sheet is divided into the following tabs:




Repeating Frame Properties

When you double–click on a repeating frame in the Layout editor or itsicon in the Object Navigator, its Repeating Frame property sheet isdisplayed.

The Repeating Frame property sheet is divided into the following tabs:

• Object – 8 – 29




Rules:

1. A repeating frame can be placed anywhere in the Layout editorunless its source group is a dimension of a matrix. For moreinformation about matrix reports, see “Matrix Reports” on page2 – 27.

2. A repeating frame must be behind the objects (e.g, fields andboilerplate) that it contains.

Column Mode


Object Tab of Repeating Frame Property Sheet

The Object tab of the Repeating Frame property sheet is shown below.It contains the following properties:

• Column Mode – 8 – 29

• Horizontal Spacing – 8 – 33

• Maximum Records Per Page – 8 – 33

• Minimum Widow Records – 8 – 34

• Print Direction – 8 – 35

• Source – 8 – 39

• Vertical Spacing – 8 – 40

Controls how Oracle Reports fetches and formats data for instances ofrepeating frames. The figures below illustrate how Column Modeaffects the formatting of repeating frame instances.


With Column Mode, the next instance of a repeating frame can beginformatting before the previous instance is completed. In the figureabove, Instance 3 begins formatting on page 1 even though Instance 2does not finish until page 2. In addition, when an instance overflowsonto another page, the overflow is aligned across pages. In the figureabove, Instance 2 appears in the same relative position on page 2 that itappeared in on page 1.


Without Column Mode, the next instance cannot begin formattingbefore the previous instance is completed. In the figure above, Instance3 begins formatting on page 2 because Instance 2 does not finish untilpage 2. Also, if an instance overflows, the overflow is not alignedacross pages. In the figure above, Instance 2 formats in the middle ofpage 1 and its overflow formats on the left side of page 2.

Column Mode is used mainly for master repeating frames or repeatingframes that contain fields that may expand vertically or horizontally(i.e., sizing is Variable or Expand).


Unchecked.

Examples:

1. The figure below shows a sample layout in which you might useColumn Mode. (Assume that X has Horizontal Sizing of Fixed.)

The first figure below shows instances 1 through 3 if repeatingframe X has Column Mode checked. The positioning is the sameon logical pages 1 and 2, even though instance 2 completed onlogical page 1.

2. The second figure below shows the positioning of instances 1through 5 if repeating frame X does not have Column Modechecked. Instances 1 and 2 complete on logical Page 1. As a result,the position of instance 3, which did not complete on logical Page1, is not the same on logical Page 2 as it was on logical Page 1.

Default:


Rules:

1. You can only specify Column Mode for repeating frames that haveeither:

• Print Direction of Across and Horizontal Sizing of Fixed

• Print Direction Down and Vertical Sizing of Fixed

Horizontal Spacing

Maximum Records perPage


Repeating frames with a Print Direction of Across/Down orDown/Across cannot have Column Mode specified.

Is the amount of space (in the report’s unit of measurement) that youwant horizontally between instances of the repeating frame. The figurebelow illustrates Horizontal Spacing.


Enter a number of zero or more. The maximumamount depends upon the unit of measurement.For inches, the maximum is 512 inches. Forcentimeters, it is 1,312 centimeters. For picas, it is36,864 picas.

0

Rules:

1. When the Print Direction is Down, this setting has no effect.

2. When the Print Direction is Down/Across, this setting affects spacebetween instances that appear one next to the other.

Is the maximum number of instances of the repeating frame that will beformatted on a logical page.


Enter any positive, whole number from 1 through32K.

Blank means that as many instances of therepeating frame as possible can be formatted on alogical page.

Blank.

Options:

Default:

Options:

Default:

Minimum WidowRecords


Examples:

1. Suppose that you have a repeating frame with many instances. Toimprove the appearance of your report, you prefer to have at mostthree instances of the repeating frame on a given logical page. Toensure that you never have more than three instances per logicalpage, you set Maximum Records Per Page to 3.

2. Suppose that you want each instance of a repeating frame to be ona logical page by itself. First, set Maximum Records Per Page to 1for the repeating frame so that only one instance appears on eachlogical page. Then, check Page Break Before and Page Break After,to make sure that the first instance of the repeating frame starts ona new logical page.

Is the minimum number of instances that should appear on the logicalpage where the repeating frame starts to print. If the number ofinstances specified for this property cannot fit on the logical pagewhere the repeating frame is initially triggered to print, then therepeating frame will start formatting on the next page. If this propertyis 1, there is no minimum and the repeating frame will start formattingon any logical page that can fit one instance. Minimum WidowRecords is similar to Minimum Widow Lines for fields and boilerplate.For more information about Minimum Widow Lines, see “MinimumWidow Lines” on page 8 – 51.


Enter any positive, whole number from 1 through32K.

Blank means that there is no minimum.

Blank

Examples:

1. To improve the appearance of your report, you want to make surethat you do not have the first instance of the repeating frameprinted at the bottom of a logical page, by itself. To make sure thatthere are at least two instances on the logical page, you setMinimum Widow Records to 2.

Options:

Default:

Print Direction


2. Suppose that you want all instances of a repeating frame to appearon one logical page. To do this, you set Minimum Widow Recordsto a very large number. If not all instances can fit on the firstlogical page where the repeating frame is triggered to print, nonewill be formatted on that page. Instead, they are all formatted onthe next logical page. Notice, though, that on the next and allsubsequent pages, Minimum Widow Records is ignored. Since youare starting with a fresh page, if all instances cannot fit on thatlogical page, they will not all fit on any one logical page anyway.

Rules:

1. Minimum Widow Records applies only to the first logical page onwhich the object is triggered to be printed. Minimum WidowRecords is ignored on subsequent pages.

2. If Minimum Widow Records is greater than the total number ofinstances of the repeating frame, then all instances must be able tofit on the first logical page where the repeating frame is triggered toformat. If all instances cannot fit on the first logical page where therepeating frame is triggered to format, the repeating frame willstart formatting on the next page.

Is the direction in which successive instances of the repeating frameappear.


Across means that each instance of the repeatingframe subsequent to the first instance is printed tothe right of the previous instance across the logicalpage.

Across/Down means that each instance of therepeating frame subsequent to the first instance isprinted to the right of the previous instance untilan entire instance cannot fit between the previousinstance and the right margin of the logical page.At that time, Oracle Reports prints the instancebelow the left–most instance on the logical page,provided there is enough vertical space left on thelogical page for the instance to print completely.

Down means that each instance of the repeatingframe subsequent to the first instance is printedbelow the previous instance down the logical page.

Options:


Down/Across means that each instance of therepeating frame subsequent to the first instance isprinted below the previous instance until an entireinstance cannot fit inside the bottom margin of thelogical page. At that time, Oracle Reports printsthe instance to the right of the topmost instance onthe logical page, provided there is enoughhorizontal space left on the logical page for theinstance to print completely.

Down

Examples:

1. Suppose that you have a repeating frame like the one shown below.Since the Print Direction is Across/Down, instances of the repeatingframe print from left to right and then top to bottom.

Default:


If, however, there was an object (e.g., a graphic) on a page thatprevented two instances of the repeating frame going across thepage, the repeating frame instances would only print down thepage. Where there is room to print more than one instance acrossthe page, the repeating frame instances begin printing across andthen down.

Source


Rules:

1. If a nested repeating frame has a Print Direction of Across and itsenclosing repeating frame has a Print Direction of Down, the acrossrepeating frame can cause overflow when it is too wide for thecurrent page. The next instance of the outer, down repeating framewill not print until the previous instances of the across repeatingframe completes. The figure below illustrates this rule graphically.

Notice that there are too many instances of B in A3 to fit on the firstlogical page. As a result, A3 overflows onto the second logicalpage and A4 can begin only after A3 completes.

Note: If you wanted A3 on page 1 to be aligned with theoverflow of A3 on page 2, you could use Column Mode. Formore information, see “Column Mode” on page 8 – 29.

2. Matrix dimension repeating frames whose source groups are in thesame ”family” hierarchy (i.e., are descendants or ancestors of eachother) within a cross–product group must have the same PrintDirection. Parent–child relationships within a cross–product groupare used to create nesting in the matrix. As a result, the repeatingframes associated with such groups must print in the samedirection on the page.

Is the group that owns the data for the repeating frame. Source is a listof values containing valid source groups.


Select any valid group name.Options:

Vertical Spacing


Rules:

1. Source cannot be a cross–product group.

Is the amount of space (in the report’s unit of measurement) you wantvertically between instances of the repeating frame. The figure belowillustrates Vertical Spacing.


Enter a number of zero or more. The maximumamount depends upon the unit of measurement.For inches, the maximum is 512 inches. Forcentimeters, it is 1,312 centimeters. For picas, it is36,864 picas.

0

Rules:

1. When the Print Direction is Across, this setting has no effect.

2. When the Print Direction is Across/Down, this setting determinesthe space between instances that appear one below the other.

Options:

Default:


Field Properties

When you double–click on a field in the Layout editor or its icon in theObject Navigator, its Field property sheet is displayed.

The Field property sheet is divided into the following tabs:

• Object – 8 – 41




Rules:

1. The maximum size of text in a field is 64K of text per paragraphand 64K paragraphs. This limit may vary according to youroperating system.

2. The contents of fields are wrapped on word boundaries, i.e., onspaces, hyphens, and tabs. Other punctuation marks areconsidered to be the last character of the word they follow. Newline characters in the field’s contents force new lines. There is nolimit to the number of lines that can be created.

3. In the Layout editor, a field must be placed inside of a repeatingframe whose source group is the group (or a descendant of thegroup) that contains the field’s source column. If a field’s source isa summary owned by a cross–product group, then the field mustbe placed inside of the set of repeating frames whose sources arethe groups in the summary column’s Product Order. For moreinformation on Product Order, see “Product Order” on page 6 – 33.

4. A field must be in front of the repeating frame that contains it.

5. If a number cannot fit in its field, then asterisks will appear in thefield instead of the value. To get the value to appear, you eitherneed to resize the object or change its sizing to Expand or Variable.

Object Tab of Field Property Sheet

The Object tab of the Field property sheet is shown below. It containsthe following properties:


• Format Mask – 8 – 42

Datatype

Format Mask


• Hidden – 8 – 49

• Page Numbering – 8 – 52

• Source – 8 – 56

Is a read–only field that displays the datatype of the field’s Source. Formore information, see “Column Properties” on page 6 – 17. For moreinformation, see “Parameter Properties” on page 6 – 45.

Rules:

1. A field of Datatype Long, Long Raw, or Raw is treated as text unlessyou specify otherwise in the Format field of the Column propertysheet. For more information, see “Format” on page 6 – 21.

Defines how you want to display Date and Number values in the field.You can enter custom masks for numbers and dates using the syntaxdescribed in the tables below or you can select from the predefined listof values. Character values have no format mask. You cannot enter aformat mask for fields with Character values.

The values displayed initially in the list are determined by the datatypeof the field (e.g., for a field of Datatype Number, only number masks areshown in the list). If you enter a mask not in the list for Format Maskand accept the Field property sheet, the new format mask will appearin the list of values.


However, these format masks are only valid during the current OracleReports session. If you quit Oracle Reports and then invoke it again,the list of values for the Format Mask field does not contain the formatmasks you created in the previous Oracle Reports session (unless youopen the report(s) that used these masks). To include masks in the listthat will be saved between sessions, use Format Masks in the ToolsOptions dialog box (Tools—>Tools Options).


Enter any valid number or date format mask not toexceed 1K. Look at the tables below for the syntaxof format masks.

Select a value from the list.

Blank. This implies that the Oracle Reports shoulddetermine how to format the values based on theDatatype of the field’s source.

When the Datatype of the field’s source is Date, theformat mask is the default for your language (e.g.,in the United States, the default is’DD–MON–YY’).

When the Datatype of the source is Number, thevalues are formatted according to the width of thesource. The table below shows some examples.

Note: This default behavior is the same as SQL*ReportWriterVersion 1.1.

Value Width of Source Output Displayed

9.99999 4 10.0

9.99999 3 10.

9.99999 2 10

9.99999 1 *

–9.99999 4 –10.

–9.99999 3 –10

–9.99999 2 **

400 2 **

4.563 5 4.563

4.563 4 4.56

4.563 3 4.6

Options:

Default:

Date Format Masks


Value Output DisplayedWidth of Source

0.001 5 .001

0.001 4 .001

0.001 3 .00

0.001 2 .0

0.001 1 .

–0.01 4 –.01

–0.01 3 –.0

–0.01 2 –.

–0.01 1 –

The following table illustrates the format masks for dates:

Format Mask Explanation

SCC or CC Century, abbreviated; ’S’ prefixes”BC” with (–)

YYYY or SYYYY Year; ’S’ prefixes ”BC” date witha (–)

YYY, YY, or Y Last 3, 2, or 1 digit(s) of year

Y,YYY Year with comma

SYEAR or YEAR Year, spelled out; ’S’ prefixes”BC” date with (–)

BC, AD, or B.C., A.D. Century indicator

Q Quarter of year (Jan–Mar=Quar-ter 1)

MM Month in digits (Jan = 01)

MONTH or MON Name of month, or 3–letter ab-breviation

WW ; W Week in year; week in Juliandays

DDD, DD, or D Day in year, month, or week

DAY Day of week (MONDAY)

DY Name of day, 3–letter abbrevi-ation

J Julian day; the number of dayssince January 1,4712 BC

AM, PM, or A.M., P.M. Meridian indicator

Number Format Masks


Format Mask Explanation

HH or HH12; HH24 Hour of day (1–12); Hour of day(0–23)

MI Minute

SS; SSSSS Second in minute; seconds inday

fm Toggles fill mode which replacesmultiple spaces before or be-tween dates, numbers, or wordswith a single space

The following suffixes may be added to the format masks:

Suffix Explanation

TH Suffixed number (”DDth” for ”4th”)

SP Spelled out number (”DDSP” for ”FOUR”)

SPTH or THSP Spelled and suffixed number (”DDSPTH” for“FOURTH”)

The following table describes the tokens you can use in creating anumber format mask. To create a number format mask, you build astring using these tokens.

Format Token Explanation

0 Prints one digit.

N Prints one digit, unless it is a leading zero to theleft of the decimal point or a trailing zero to theright of the decimal point.

* Prints one digit, unless it is a leading zero to theleft of the decimal point, in which case an aster-isk (*) is printed. Trailing zeros to the right of thedecimal point are printed.

9 Prints one digit, unless it is a leading zero to theleft of the decimal point, in which case a space isprinted. Trailing zeros to the right of the decimalpoint are printed.

+ Prints a leading plus (+) for positive values and aleading minus (–) for negative values. This tokenmust lead the mask.

– Prints a leading minus (–) for negative valuesand nothing for positive values. This token mustlead the other tokens.



MI Prints a minus (–) after negative values and aspace after positive values. This token must trailthe other tokens.

S Prints a minus (–) for negative values and a plus(+) for positive values (wherever the S appearsin the mask). This token must lead or trail theother tokens.

PR Prints angle brackets (<>) around negative valuesand spaces around positive values. This tokenmust trail the other tokens.

( ) Prints parentheses around negative values andspaces around positive values. The parenthesesmust surround the other tokens.

DB Prints a ”DB” after positive values. This tokenmust trail the other tokens.

CR Prints a ”CR” after negative values. This tokenmust trail the other tokens.

Y Causes no sign symbol to be printed for negativeor positive values.

V Causes the number to be multiplied by 10N,where N is the number of 0 9 * and S tokenswhere N is the number of 0, 9, *, and S tokensthat appear to the right of the V.

EEEE Causes the number to be printed in scientificnotation. All digit tokens refer to digits of themantissa. There must be exactly one digit to theleft of the decimal point (displayed or implicit).The token EEEE prints as E followed by a plus(+), if the ordinate is positive or zero, and a mi-nus (–), if the ordinate is negative, and two digitsrepresenting the ordinate (e.g., E–99).

”string” Prints the string between the double quotes. Tostring Prints the string between the double quotes. Tohave double–quotes inside the string, typed bl t b k t b k (””)

q g ypdouble–quotes back to back (””).

. (period) Prints a period (.) to separate the integral andfractional parts of a number.

D Prints the local decimal character to separate theintegral and fractional parts of a number.

, (comma) Prints a comma (,) as the group/thousands sepa-rator.

G Prints the local group/thousands separator.



$ Prints $.

L Prints the local currency symbol.

C Prints the ISO currency symbol.

% Prints %.

” ” Prints a blank space. (Do not include quotes inmask.)

B Prints a blank space for all zero values, regard-less of other tokens.

K Prints a blank space.

<> Delineates the beginning and ending of the deci-mal–aligned region (i.e., that part of the numberthat you want aligned with the decimal point inthe format mask). Angle brackets indicate thatthe number should always occupy the sameamount of space. If necessary, values are paddedwith blanks to the left or right of the decimalpoint. Oracle Reports will align the decimalpoint based on the number of characters to theright of the decimal point. If a proportional fontis used, it does not actually align the decimalpoint.

RN rn

Prints values in uppercase or lowercase Romannumerals, respectively. You cannot enter anyother tokens with this token.

Examples:

The following tables illustrates some sample format masks:

Sample Date Format Sample Date Display

MM/DD/YY 03/04/85

DD MON YYYY 04 MAR 1985

Mon. DD, YYYY Mar. 4, 1985

Day Month DD fmHH:MI AM Monday March 4 11:35 AM

Dy Mon ddth fmHH24:MI:SS Mon Mar 4th 23:35:22

Day ”the” ddthsp ”of” Month Monday the fourth of March


Sample Number Format Value Number Displayed*

–0000 7934 ”7934”

–7934 ”–7934”

–00000 7934 ”07934”

–NNNN 7639 ”7639”

535 ”535”

–NNN 7639 ”****”

–**** 7902 ”7902”

–***** 7902 ”*7902”

+NNNN 100 ”+100”

–99 ”–99”

(NNNN) 1600 ” 1600 ”

–800 ”(800)”

NNNNPR 1600 ” 1600 ”

–800 ”<800>”

NNNNMI 1600 ”1600 ”

–800 ”800–”

NNNVNN 343 ”34300”

N.NNEEEE 7369 ”7.37E+03”

”SRW”–0000 7782 ”SRW7782”

–$NNNN.NN 800 ”$800”

1600 ”$1600”

–%NNN 10 ”%10”

–NN NNN.NN 3000 ”3 000”

+KKNNNNN.00 1950 ”+ 1950.00”

900 ”+ 900.00”

$<NNNNN.00> 1200 ”$ 1200.00”

500 ”$ 500.00”

$<NNNNN.00> DB 1200 ”$ 1200.00 DB”

–500 ”$ 500.00”

$<NNNNN.00> CR 1200 ”$ 1200.00”

–500 ”$ 500.00 CR”

* Note that the quotation marks will not appear in your output.They are used here to make it clear where there are leading or trail-ing spaces.

Hidden


Rules:

1. If For number format masks, if the actual value is longer than thespecified format mask, the value will appear as a string of asterisksin the report output, regardless of the field’s width. For example, ifa fixed field’s width is 8, the value is 1234567, and the formatmask is <NNNNNN>, your output will be *******.

Similarly, if the number format mask causes the value to be largerthan the field width, asterisks will appear in place of the value. Forexample, if a fixed field’s width is 6, the value is 1234, and theformat mask is –99999999, your output will be ******.

This occurs because the format token 9 prints a blank for leadingzeros to the left of the decimal. As a result, the value is too long tobe displayed in a field of width 6.

2. If you do not specify a sign token in the format mask, positivevalues are preceded by a space and negative values are precededby a minus (–). This behavior is different from the default behaviorin SQL*ReportWriter Version 1.1. Specifying the Y format masktoken causes the Version 1.1 default behavior.

3. After you create a format mask it will display in the list of values only if it is an appropriate format mask for the datatype of thesource column—i.e., format masks for numbers are displayed whenthe source column is a number, and format masks for dates aredisplayed when the source column is a date.

4. Format masks that print spaces for zeros (e.g., 9) increase thenumber of bytes per page taken up by your output.

Indicates that the field should not be formatted. Hidden is used forfields that you only want to reference in boilerplate text. This propertyis most often used for form letter reports, where fields are referenced inboilerplate text. To reference a hidden field, type &fieldname within theboilerplate text object. Look at ”Examples” below. For moreinformation about boilerplate, see “Boilerplate Properties” on page8 – 59.


Unchecked.Default:


Examples:

1. Suppose that you are building a form letter report and you want toinsert the name, address, and phone number of the addressee in theletter. You create a field called NAME1 for the name of theaddressee, ADDRESS for the address, and PHONE for the phonenumber. These fields are only to appear within boilerplate text, soyou check Hidden. Within the boilerplate text where you wantthese values to appear, you insert references as follows:

Dear &NAME1,

Our records show that your address and phone are the

following:

&ADDRESS

&PHONE

In the output, the letter would look something like this:

Dear J. Smith,

Our records show that your address and phone are the

following:

234 Summer Lane

San Francisco, CA 11104

415–363–1234

Rules:

1. The following properties and attributes of a hidden field areapplied to references to the hidden field:

• Format menu selections (Font, Size, Weight, Style, Justification)

• Horizontal Sizing

• Format Mask

• Page Numbering attributes (in Page Numbering dialog box).

• Format Trigger

Minimum WidowLines


2. A hidden field reference can appear anywhere in boilerplate text. Ifyou want to place the field reference next to other text with nospaces in between, enclose the field name in angle brackets (e.g.,&<fieldname>Kg). Otherwise, Oracle Reports will assume that all ofthe text between the ampersand and the next space is part of thefield name. Note, however, that you can put references right nextto each other with no spaces in between and without angle brackets(e.g., &field1&field2&field3).

Is the minimum number of lines of the field that should appear on thelogical page where the field starts to print. If the number of linesspecified for this property cannot fit on the logical page, then the fieldstarts to format on the next page. If this property is 1, there is nominimum and the field will start printing on any logical page that canfit one line of the field.

Note: This property applies only to the initial lines of text inthe field. It does not provide widow protection for individualparagraphs within the field.


Enter any whole, positive number from 1 through32K.

Blank means the same as entering 1.

Blank.

Examples:

1. With Minimum Widow Lines set to 1, you might get a situation likethe one shown in the first figure below, where the first line of thefield is printed at the bottom of a logical page and the rest isprinted on the next logical page. With Minimum Widow Lines setto 2 (or more), you can avoid having one line of a field at thebottom of the logical page by itself, as shown in the second figure.

Options:

Default:

Page Numbering


Is a button that displays the Page Numbering dialog box, shown below.Page numbering is how page numbers are calculated for fields thathave a Source of &Physical Page Number, &Total Number of PhysicalPages, &Logical Page Number, or &Total Number of Logical Pages.

Note: The settings for each page are based on the logical orphysical page as specified by the field’s source.

The figure below illustrates the differences between logical page,physical page, and panel numbering. Note that each region maycontain multiple logical pages. Furthermore, within each logical pageyou may have multiple panels. In the Header and Trailer region,however, the logical page can only be one panel wide. In the Bodyregion, the logical page can be more than one panel wide.

Note: In the figure below, physical pages are numberedconsecutively starting with the Header pages. This assumesthat you selected Header, Body, and Trailer under Include.


Indicates which report sections are used tocompute the report page numbers. You can checkHeader, Body, Trailer, or some combination ofchoices. The default is Header, Body, and Trailerall checked, implying that all pages of the reportshould be included in computing page numbers.

Include


Is a number from 1 through 32K that should beused for the first page on which the field isformatted. The default is 1, implying thatnumbering should begin with 1.

Is a number from 1 through 32K by which toincrement for each page. The default is 1, implyingthat the page number should be incremented by 1for each new page.

Is when to reset the page number to the initialvalue specified in Start At. Reset At has a list ofvalues (&Report and all enclosing repeatingframes). The default is &Report, implying that thepage number only be reset once at the beginning ofthe report. When a repeating frame is specified,the page number will be reset for each instance ofthe repeating frame.

Examples:

1. Suppose that you want to number the physical pages of the Bodyregion of your report. You create a field named F_PAGE and give ita Source of &Physical Page Number. You then select PageNumbering from the Field property sheet and fill out the PageNumbering dialog box as follows:

• Check Body and uncheck Header and Trailer because you onlywant to number the Body region pages.

• Enter 1 in the Start At setting.

• Enter 1 in the Increment By setting.

• Enter &Report in the Reset At setting because you want tonumber all the pages in the Body consecutively.

You then position F_PAGE using the Layout editor.

2. Suppose that you want to have the page number at the top of eachpage of your report. Furthermore, you want the page number to beof the form “Page n of total pages.”

2.1 Create a field called F_PAGE and give it a Source of &PhysicalPage Number. You then select Page Numbering from the Fieldproperty sheet and fill out the Page Numbering dialog box.

2.2 Check Body and uncheck Header and Trailer because you onlywant to number the Body region pages.

2.3 Enter 1 in the Start At setting.

Start At

Increment By

Reset At


2.4 Enter 1 in the Increment By setting.

2.5 Enter &Report in the Reset At setting because you don’t wantthe page numbers to reset to zero until the report is done.

Now you need to create a field called F_TOTPGE and give it aSource of &Total Number of Physical Pages.

2.6 Select Page Numbering from the Field property sheet and fillout the Page Numbering dialog box.

2.7 Check Body and uncheck Header and Trailer because you onlywant to number the Body region pages.

2.8 Enter 1 in the Start At setting.

2.9 Enter 1 in the Increment By setting.

2.10Enter &Report in the Reset At setting because you don’t wantthe page numbers to reset to zero until the report is done.

You could hide these fields (i.e., select Hidden in the Fieldproperty sheet) and reference them within boilerplate text:

Page &F_PAGE of &F_TOTPGE

Alternatively, position F_PAGE and F_TOTPGE beside eachother. Insert boilerplate to the left of F_PAGE that contains thetext ”Page”. Insert boilerplate between F_PAGE andF_TOTPGE that contains the text ”of.”

3. Suppose that you have a repeating frame (R_1) with instances that span several pages and you want to number the physical pages thateach instance spans. Assume also that you want the page numberto be of the form Page n of total pages.

Follow the same steps as in Example 2 above, with the followingexceptions:

• Enter R_1 in the Reset At setting for F_PAGE and F_TOTPGE.

• Hide the fields (i.e., select Hidden in the Field property sheet)and create a boilerplate text object inside R_1 with the followingtext:

Page &F_PAGE of &F_TOTPGE

Alternatively, position F_PAGE and F_TOTPGE beside eachother, inside R_1, using the Layout editor. Insert boilerplate tothe left of F_PAGE that contains the text ”Page”. Insertboilerplate between F_PAGE and F_TOTPGE that contains thetext ”of.”

Source


• Set the Print Condition of F_PAGE and F_TOTPGE such thatthey will print on all logical pages of R_1, i.e., Print ConditionType of All and Print Condition Object of Enclosing Object.

Rules:

1. If the Reset At value is a repeating frame, do not have the fieldappear on pages where the repeating frame does not appear.Because the value of the field is determined by the repeating frame,the results will be unpredicatable on pages where the repeatingframe does not appear.

To avoid this situation, you can do any one of the following:

• Place the field inside the repeating frame at which its value isreset. This ensures that the field will only appear when therepeating frame appears.

• Create a Format Trigger for the field such that it will only bedisplayed on pages where its value makes sense (i.e., pages onwhich one instance of the repeating frame appears).

Similarly, if the field is not inside the repeating frame it resets atand multiple instances appear on the same page, Oracle Reportscannot determine the value of the field and the results are againunpredictable.

To avoid this situation, you can do any one of the following:

• Place the field inside the repeating frame at which its value isreset.

• Set Maximum Records Per Page to one for the repeating frame atwhich the the field’s value is reset.

Is the place where the field gets its values (usually a column or aparameter).

Note: If the Source is a page number value (e.g., &Logical PageNumber), you can select Page Numbering to control how thepage numbering is done. For more information, see “PageNumbering” on page 8 – 52.


&Current Date is the operating system date whenthe report runs, after the Runtime Parameter Formis finished.

&Logical Page Number is the current page numberbased upon numbering the output by logical pages.

Options:


&Panel Number is the current panel number withinthe logical page.

&Physical Page Number is the current page numberbased upon numbering the output by physicalpages.

&Total Logical Pages is the total number of pagesbased upon numbering the output by logical pages.

&Total Panels is the total number of panels within alogical page.

&Total Physical Pages is the total number of pagesbased upon numbering the output by physicalpages.

Select any valid column or parameter name.

Examples:

1. Assume that you have a report with a data model like the one inthe figure below. Assume further that G_Dept is the Source forrepeating frame R_Dept and G_Emp is the Source for repeatingframe R_Emp.

In this example, DEPTNO and DNAME could be the Source forfields in either R_Dept or R_Emp. ENAME and SAL could only bethe Source for fields in R_Emp.

Rules:

1. If a field is enclosed in a repeating frame, the column used as itsSource must be in the source group or an ancestor of the sourcegroup of the field’s enclosing repeating frame. The figure belowshows a group tree. If the source group of the repeating framewere 6, then the field source could be 1, 3, or 6.


If the field has no enclosing repeating frame, the column must be areport–level column, i.e., it must be owned by the report.

2. If a column has a Reset At of Page, then any fields that use it as asource must be contained in repeating frames that use the column’sgroup as their source. In addition, any boilerplate objects thatreference the field must also be contained in repeating frames thatuse the column’s group as their source.

3. If you specify a source for a field and later delete that source fromyour report (i.e., create a summary column, specify it as the sourcefor a field, and later delete that summary column), your field nolonger has access to data to display, and *UNDEFINED* appears in

the Source field.

4. If the Source of a field is &Logical Page Number, &Panel Number,&Physical Page Number, &Total Logical Pages, &Total Panels, or &TotalPhysical Pages, then any layout object that displays the field (eitherthe field itself or a boilerplate object) must have fixed sizing. Formore information, see “Vertical Sizing” on page 8 – 20.

5. A field cannot have a Source of Sound or Video.


Boilerplate Properties

When you double–click on a boilerplate object (e.g., text or an image) inthe Layout editor or its icon in the Object Navigator, its Boilerplateproperty sheet is displayed.

The Boilerplate property sheet is divided into the following tabs:

• Object – 8 – 59




Object Tab of Boilerplate Property Sheet

The Object tab of the Boilerplate property sheet is shown below. Itcontains the following properties:

• Format – 8 – 60

• Link File – 8 – 60

• Minimum Widow Lines – 8 – 62

Note: The Object tab only appears for certain types ofboilerplate (e.g., link file boilerplate).

Format

Link File


Rules:

1. The maximum size of boilerplate text is 64K of text per paragraphand 64K paragraphs. This limit may vary according to youroperating system.

2. Boilerplate must be in front of the repeating frame that contains it.

Caution: When you resize boilerplate text, ensure the text fits in theobject. If font descends (the space left for the lower parts of letters likeg and q) do not fit, the text line will appear in the editor, but, when thereport is run, the line may not appear in the output, depending uponthe Horizontal/Vertical Sizing settings.

Is the format of the file displayed in Link File.

Required/Optional: Required, if Link File is specified.

Text is text in ASCII format.

Image is a bitmapped image.

CGM is a line drawing in CGM format.

Oracle Drawing Format is a line drawing in Oracleformat.

All the other image formats are provided in caseyou want to open the report in Oracle ReportsVersion 2.0. If you are planning to open/run thereport in Version 2.0, select the specific imageformat of the boilerplate. If not, you can choosefrom the above choices.

For more information on the available formats, see“Oracle Reports File Storage” on page 18 – 2.

Is the name of a file to which the boilerplate is linked. Link File isuseful for including the contents of files that are likely to change. Theboilerplate is automatically updated to reflect the latest contents of thefile when you do any of the following:

• accept the property sheet

• paste the object

• import the object (if it’s in Oracle Format)

• open the report

• run the report

Options:


The contents of a file linked to a boilerplate object will appear in theLayout editor, but cannot be edited within the Layout editor.

You can also include files in your report using Read from File. Formore information, see “Read From File” on page 6 – 23.

If you specify Link File, you must also specify Format.


Enter a valid filename not to exceed 1K in length.You can prefix a path to the filename. If a path isnot prefixed to the filename, Oracle Reports usesits file path search order to find the file. For moreinformation about file path search order, see“File–Searching Method” on page 18 – 9.

To ensure the portability of your reports, you cantake advantage of the Oracle Reports–specificenvironment variable called REPORTS25_PATH.You can use this variable to specify the defaultdirectory or directories where you want OracleReports to search for external files you use in yourreports (e.g., external queries, boilerplate, andPL/SQL). This prevents the need to hardcodedirectory paths in your report.


Blank.

Rules:

1. The maximum size of the file you specify depends upon youroperating system.

2. The link file name may be operating–system dependent. If youmove the report to another operating system, you may need toupdate the name in Link File.

3. This field appears only for objects created with the Link File tool.For more information, see “Link File Tool” on page 7 – 14.

4. If you specify a file that contains a layout object and its properties(i.e., a file that contains an exported layout object), the file is treatedas an anonymous graphical object (i.e., the properties of the objectwill be ignored). If you want the object’s properties to be used,then you should import it instead of using Link File.

Options:

Default:

Minimum WidowLines


Is the minimum number of lines of the boilerplate text that shouldappear on the logical page where the text starts to print. If the numberof lines specified for this property cannot fit on the logical page, thenall lines of the boilerplate are moved to the next page. If this propertyis 1, there is no minimum and the boilerplate will start printing on anylogical page that can fit one line of the boilerplate. This property issimilar to Minimum Widow Lines for fields. For more informationabout Minimum Widow Lines for fields, see “Minimum Widow Lines”on page 8 – 51.

Note: This property applies only to the initial lines of text inthe boilerplate object. It does not provide widow protection forindividual paragraphs within the boilerplate.


Any whole, positive number from 1 through 32K.

Blank means that the boilerplate should only beprinted if all of its lines can fit on the logical page.

Blank.

Rules:

1. Minimum Widow Lines can only be used on text boilerplate.

Anchor Properties

When you double–click on an anchor in the Layout editor or its icon inthe Object Navigator, the Anchor property sheet, shown below, isdisplayed. The Anchor property sheet contains these fields:

• Collapse Horizontally/Vertically – 8 – 69

• Edge (parent and child) – 8 – 69

• Object – 8 – 69

• Parent – 8 – 69

Options:

Default:


Anchors are used to determine the vertical and horizontal positioningof a child object relative to its parent. The end of the anchor with asymbol on it is attached to the parent object. Since the size of somelayout objects may change when the report runs (and data is actuallyfetched), you need anchors to define where you want objects to appearrelative to one another. An anchor defines the relative position of anobject to the object to which it is anchored. Positioning is based on thesize of the objects after the data has been fetched rather than on theirsize in the editor.

(Note that in positioning the anchor on the objects’ edges, you canshift–click to move along the edge in increments of 25%.)

The diagram below illustrates the parts of the anchor definition.

Examples:

1. Suppose you want to horizontally center a field within a repeatingframe that has its Horizontal Sizing set to Variable. You also wantthe field to be a fixed distance from the top edge of the repeatingframe. Since you don’t know how large or small the formattedrepeating frame will be, you need to use anchors to center the field.

To center the field horizontally within the repeating frame do thefollowing:


1.1 Place the field inside the repeating frame such that the xcoordinate of the center of the top of the field is the same as thex coordinate of the center of the top of the repeating frame. Seethe figure below.

1.2 Draw an anchor from the center of the top of the field to thecenter of the top of the repeating frame.

The field will now be centered horizontally within repeating frame.

2. Suppose you want to vertically center a field within a repeatingframe that has its Vertical Sizing set to Variable. You also want thefield to be a fixed distance from the top edge of the repeatingframe. Since you don’t know how large or small the formattedrepeating frame will be, you need to use anchors to center the field.

To center the field vertically within the repeating frame, draw ananchor from the center of the left edge of the field to the center ofthe left edge of the repeating frame.

The field will now be centered vertically within the repeatingframe. See the figure below.


3. Suppose that you have anchored Field B to Field A and you check Vertically under Collapse. The figure below illustrates theanchor between the two fields.

Assume that on the first logical page of the report, Field A printsand takes up so much room that Field B cannot fit on the logicalpage. Therefore, Field B prints on the second logical page, whereField A does not appear. Because Vertically is checked, the anchorcollapses in the y direction. Field B maintains its relativepositioning to Field A in the x direction even though Field A doesnot actually appear on the logical page.


4. Assume the same conditions as in the previous example, but in thiscase you want Field B to move both vertically and horizontally intothe space where Field A would have printed on the logical page.Do the following:

4.1 Draw an anchor from the top of Field B to the bottom of FieldA.

4.2 Check both Horizontally and Vertically under Collapse.

The figure below illustrates the anchor between the two fields.

On the first logical page of the report, Field A prints and takes upso much room that Field B cannot fit on the logical page.Therefore, Field B prints on the second logical page, where Field Adoes not appear. The anchor collapses and Field B moves into theposition that Field A would have appeared in had it appeared onthe logical page as painted.


The diagram below illustrates this:

When Fields A and B do print on the same logical page, the anchordoes not collapse and the fields maintain their relative position toone another.

Rules:

1. An object may be anchored to only one other object.

2. Matrix objects, anchors, and the margin cannot be anchored toanything (i.e., they may not be the parent or child object for ananchor).

3. A repeating frame that is the vertical or horizontal repeating framefor a matrix cannot be anchored to another object, but other objectsmay be anchored to it (i.e., it can be the parent but not the childobject for an anchor).

4. Nothing can be anchored to a hidden object (an object with Hiddenchecked).

5. Moving an anchor also causes the two objects it anchors together tomove.


6. Objects cannot be anchored together in such a way that they have acircular dependency. For example:

• Assume that object A and object B are anchored together andobject A is the parent. Object B cannot be the parent for anotheranchor between object A and object B. In addition, object Bcannot be the parent for an anchor to object C, if object C is theparent for an anchor to object A.

• Assume that frame A contains field B and field B is above frameA in the editor. Furthermore, frame A is anchored to field C,which is not inside of frame A, and field C is the parent. Field Ccannot be the parent for an anchor to field B. Because it is insideof frame A, field B cannot be anchored to field C, if field C is theparent.

% (Child)

% (Parent)

Edge (Child)

Edge (Parent)

Horizontally

Object

Parent


7. To copy an anchor, you must select the anchor and the two objectsit anchors together. If you select the anchor by itself, nothing willbe copied to the paste buffer. If you select the anchor and one ofthe objects, only the object is placed in the clipboard.

8. An anchor cannot be resized.

9. An anchor must always be on top of the objects it anchors together(i.e., it must be one or more layers above the parent and childobjects). Oracle Reports prevents you from moving the anchor to alayer below its parent and child objects.

10. You cannot use Align, Align Objects, or Size Objects from theArrange menu on anchors.

Is the percentage down or across (from top to bottom or left to right)the child object’s Edge where the anchor is located. This setting is theposition of the anchor on the Edge when the object is populated.

An integer from 0 through 100.

Is the percentage down or across (from top to bottom or left to right)the parent object’s Edge where the anchor is located. This setting is theposition of the anchor on the Edge when the object is populated.

An integer from 0 through 100.

Is the edge of the child object (Top, Bottom, Left, Right) on which theanchor is located.

Bottom

Left

Right

Top

Is the edge of the parent object (Top, Bottom, Left, Right) on which theanchor is located. The options for this setting are the same as thoselisted above for Edge (Child).

Indicates whether the anchor should have zero length if the parentobject does not print for some reason (e.g., because of its PrintCondition or Format Trigger). If the parent object does not print, thechild object moves horizontally into the space vacated by the parent.

Is the name of the child object. This field is read–only.

Is the name of the parent object. This field is read–only.

Options:

Options:

Options:

Vertically


Indicates whether the anchor should have zero height if the parentobject does not print for some reason (e.g., because of its PrintCondition or Format Trigger). If the parent object does not print, thechild object moves vertically into the space vacated by the parent.

Matrix Properties

When you double–click on the matrix area in the center of overlappingrepeating frames or a matrix object’s node in the Object Navigator, theMatrix property sheet is displayed. A report may have multiplematrices within it, provided that the data model contains the necessarygroups. The Matrix property sheet is divided into the following tabs:

• General – 8 – 70

• Comment – 8 – 27

General Tab of Matrix Property Sheet

The General tab of the Matrix property sheet is shown below. Itcontains the following properties:

• Cross Product Group – 8 – 72

• Horizontal Frame – 8 – 72

• Name – 8 – 8

• Vertical Frame – 8 – 73


Examples:

1. Suppose that you have a group named Group1 that contains acolumn called C_DEPTNO, which gets its values from the databasecolumn DEPTNO. A group called Group2, contains columnC_JOB, which gets its values from the database column JOB, andcolumn C_DEPTNO1, which is used for linking to Group1’s query.A group called Group3 contains a column called SUMSAL, whichis a summary of the database column SAL.

Job Analyst Clerk Manager 10 $1300 $2450 Dept 20 $6000 $1900 $2975 30 $ 950 $2850

In this example:

• The Vertical Frame is the repeating frame that contains Group2(the job titles).

• The Horizontal Frame is the repeating frame that containsGroup1 (the department numbers).

• The Cross Product Group is Group4 (the group that is the parentof Group1 and Group2).

If you need to build a more complex matrix, you can do so byadding more columns to Group1 and Group2. For example,instead of having Group1 just contain department numbers, itcould also contain the locations (LOC) of the departments. Thematrix might then look something like the one below.

Job Loc Dept Analyst Clerk Manager New York 10 $1300 $2450 Dallas 20 $6000 $1900 $2975 Chicago 30 $ 950 $2850

Rules:

1. The down repeating frames must be below the across repeatingframes in a matrix.

2. A matrix object must always be on top of the repeating frames thatform it (i.e., it must be one or more layers above its horizontal andvertical repeating frames). Oracle Reports prevents you frommoving the matrix below its horizontal and vertical repeatingframes.

3. Moving a matrix also causes its two repeating frames to move.

Cross Product Group

Horizontal Frame


4. A matrix object cannot be anchored to another object and otherobjects cannot be anchored to it (i.e., a matrix object cannot be theparent or child object for an anchor).

5. To copy a matrix, you must select the matrix and its two repeatingframes. If you select the matrix by itself, nothing will be copied tothe paste buffer. If you select the matrix and one of the repeatingframes, only the repeating frame is placed in the paste buffer.

6. A matrix object can only be resized by resizing its associatedrepeating frames.

7. You cannot use Align, Align Objects, or Size Objects from theArrange menu on matrix objects.

8. The source groups of the repeating frames that make up thedimensions of a matrix must be from the same cross–productgroup.

9. Repeating frames whose source groups are in the same ”family”hierarchy (i.e., are descendants or ancestors of each other) musthave the same Print Direction. Parent–child relationships within across–product group are used to create nesting in the matrix. As aresult, the repeating frames associated with such groups must printin the same direction on the page.

10. You can put a border on a matrix object just as you would anyother object, but the width will always be the minimum widthpossible. You cannot widen the border due to the closeness of theobjects in a matrix layout.

Is the group that contains the source groups of the Horizontal andVertical Frames. The cross product group correlates values betweenone or more groups to produce the data in the matrix. For moreinformation about cross product groups, see “Data Model Properties”on page 6 – 1.


Enter a valid cross product group name.

Blank.

Is the repeating frame whose values produce the row headings andsummaries, and help compute the cross product for the matrix. See thediagram above for a graphic representation of Horizontal Frame.


Enter any valid repeating frame name.

Options:

Default:

Options:

Vertical Frame


Blank.

Rules:

1. The source groups of the repeating frames specified in Horizontaland Vertical Frame must be within the same cross–product group.

Is the repeating frame whose values produce the column headings andsummaries, and help compute the cross product for the matrix. See thediagram above for a graphic representation of Vertical Frame.


Enter any valid repeating frame name.

Blank.

Rules:

1. The source groups of the repeating frames specified in Horizontaland Vertical Frame must be within the same cross–product group.

Oracle Graphics Properties

When you double–click on an Oracle Graphics object in the Layouteditor or its icon in the Object Navigator, its Oracle Graphics propertysheet is displayed.

The Oracle Graphics property sheet is divided into the following tabs:

• O.G. Display – 8 – 75

• O.G. Query – 8 – 78




Default:

Options:

Default:


Examples:

1. Suppose that you have a master/detail report with the followingdata model:

In Oracle Graphics, you have created an Oracle Graphics display(empsal.ogd) that shows a bar chart of salaries for each employeeand you would like to include it in your report. Using the OracleGraphics tool in the Layout editor, you first draw an OracleGraphics object inside the repeating frame for the master repeatingframe (R_Dept). This means that the bar chart will appear once foreach department.

You then go to the property sheet for the Oracle Graphics objectand enter empsal.ogd for Display Name. Display Name canoptionally contain a path, but, in this case, no path was specifiedbecause we want Oracle Reports to use the path specified for theREPORTS25_PATH environment variable. For more informationon the file searching method, see “File–Searching Method” on page18 – 9.

You then fill out the property sheet as follows:

Source Display Query Report /Display Column

G_Emp Q_OG_Emp ENAME/OG_NAMESAL/OG_SALARY

Source is the group (G_Emp) that is summarized by the display.

Display Query is the name of a query in the display. Q_OG_Empcontains the following SELECT statement:

SELECT ENAME OG_NAME, SAL OG_SALARY FROM EMP


Because you specified Q_OG_Emp for Display Query, this querywill retrieve the values of ENAME and SAL from Oracle Reportsinstead of the database.

Report Column and Display Column map the report’s columns tothe display’s columns. You select ENAME and SAL from the listunder Report Column. You must enter the names of the displaycolumns that correspond to ENAME and SAL in Display Column.(Display Column cannot be blank if Report Column is specified.)

Rules:

1. An Oracle Graphics display that passes data can be placedanywhere in the Layout editor unless its source group is adimension of a matrix. If an Oracle Graphics display’s sourcegroup is a dimension group (i.e., a group within a cross–productgroup), then it must appear inside the repeating frame(s) of it’ssource group’s ancestors (if any). For more information on matrixreports, see “Matrix Reports” on page 2 – 27.

2. An Oracle Graphics display that passes parameters must be placedinside of a repeating frame whose source group is the group (or adescendant of the group) that contains the columns or parametersit is passing. If a column being passed is a summary owned by across–product group, then the Oracle Graphics display must beplaced inside of the set of repeating frames whose sources are thegroups in the summary column’s Product Order. For moreinformation on Product Order, see “Product Order” on page 6 – 33.

O.G. Display Tab of Oracle Graphics Property Sheet

The O.G. Display tab of the Oracle Graphics property sheet is shownbelow. It contains the following properties:

• Display Name – 8 – 76

• Display Parameter – 8 – 77

• List – 8 – 77

• Report Column – 8 – 77

Display Name


Is the name of the file in which the Oracle Graphics display is located.


Enter any valid filename (not to exceed 512 bytes inlength) of an Oracle Graphics display (the .ogdextension is optional). You can optionally prefix apath to the filename. If a path is not prefixed to thefilename, Oracle Reports uses its file path searchorder to find the file. For more information aboutfile path search order, see “File–Searching Method”on page 18 – 9.

Note: To ensure the portability of your reports,you can take advantage of the OracleReports–specific environment variable calledREPORTS25_PATH. You can use this variable tospecify the default directory or directories whereyou want Oracle Reports to search for external filesyou use in your reports (e.g., external queries,boilerplate, and PL/SQL). This prevents the needto hardcode directory paths in your report.


Options:

Display Parameter

List

Report Column (forDisplay Parameter)


Is a parameter in the Oracle Graphics display that corresponds to thecolumn or parameter specified in Report Column. Note that one reportcolumn or parameter can correspond to multiple display parameters,but for each display parameter there can only be one report column orparameter.


Enter the name (not to exceed 1K in length) of avalid parameter in your Oracle Graphics display.

Enter a list of valid parameter names in yourOracle Graphics display, separating each one witha comma (e.g. parm1,parm2,parm3).

Oracle Reports parameter name.

Is a button that brings up the Display dialog box. After you accept thisdialog box, the Oracle Graphics Display from File dialog box appears.From this dialog box, you can select an Oracle Graphics display for theDisplay Name field.

Is a list of the columns and parameters in your report that could beused to supply the value of a parameter in an Oracle Graphics display.Selecting a column or parameter means that there is a correspondingparameter in the display and that the display parameter will get itsvalue from the selected report column or parameter. If the parameterin the display has a different name than the column or parameter in thereport, you must specify its name in the corresponding DisplayColumn field.


Select valid columns or parameters in your report.

Rules:

1. A page–level summary column (i.e., a summary with a Reset At orCompute At of Page) cannot be passed to an Oracle Graphicsdisplay. Similarly, any summary or formula column that dependsupon a page–level summary cannot be passed to a display.

Options:

Default:

Options:

Display Column


O.G. Query Tab of Oracle Graphics Property Sheet

The O.G. Query tab of the Oracle Graphics property sheet is shownbelow. It contains the following properties:

• Display Column – 8 – 78

• Display Query – 8 – 79

• Report Column – 8 – 79

• Source – 8 – 80

Is a column or list of columns in the Oracle Graphics display thatcorresponds to the column or parameter specified in Report Column.Note that one report column or parameter can correspond to multipledisplay columns, but for each display column there can only be onereport column or parameter.


Enter the name (not to exceed 1K in length) of avalid column in your Oracle Graphics display.

Enter a list of valid column names in your OracleGraphics display, separating each one with acomma (e.g. col1,col2,col3).

Oracle Reports column name.

Options:

Default:

Display Query

Report Column (forDisplay Column)


Is the name of the query in the Oracle Graphics display that should getits records from Oracle Reports. If you specify a query name, thatquery will retrieve its records through Oracle Reports instead of thedatabase. This enables your display to reflect any filtering orsummarizing that your report performs on the data. Display Queryensures that the data used in the display is the same as the data in thereport.

If you specify a query name here, you must also specify which reportcolumns or parameters should have their values used by the display’squery. For more information on report columns, see “Report Column(for Display Column)” on page 8 – 79. For more information ondisplay columns, see “Display Column” on page 8 – 78.


Enter any valid query name (not to exceed 512bytes in length) of the Oracle Graphics displayspecified in Display Name.

Is a list of the columns and parameters in your report that could beused by the query specified in Display Query. Selecting a column orparameter means that there is a corresponding column(s) in the OracleGraphics display and that the display column(s) will get its value fromthe selected report column or parameter. If the column(s) in thedisplay has a different name than the column or parameter in thereport, you must specify its name in the corresponding DisplayColumn field.

Note: The list of columns and parameters is restricted by thegroup that you specify in Source. Only columns in the sourcegroup or above it in the group hierarchy are available forselection.

Required/Optional: Required, if you entered Display Query.

Select valid columns or parameters in your report.

Rules:

1. Any columns that you pass to the Oracle Graphics display viaReport Column (for display column) must be in the Source groupor its ancestor.

2. A page–level summary column (i.e., a summary with a Reset At orCompute At of Page) cannot be passed to an Oracle Graphicsdisplay. Similarly, any summary or formula column that dependsupon a page–level summary cannot be passed to an OracleGraphics display.

Options:

Options:

Source


Is the group in the report that is summarized by the Oracle Graphicsdisplay Source is a list of values containing valid source groups.

Required/Optional: Required, if value entered for Display Query.

Select any valid group name.

Rules:

1. You cannot specify a cross–product group for Source.

2. Any columns that you pass to the Oracle Graphics display viaReport Column (for display column) must be in the Source groupor its ancestor.

3. If you select a Source but not a Display Query, the Source isdeselected when you accept the property sheet.

User–Defined Button Properties

When you double–click on a button object in the Layout editor or theObject Navigator, its Button property sheet is displayed.

The Button property sheet is divided into the following tabs:

• Object – 8 – 81




Rules:

1. Buttons do not appear in printed output. They also do not appearwhen reports containing them are run in character mode.

2. Buttons appear in the Previewer with the characteristics of nativebuttons on your platform. Therefore, changes made in the Layouteditor that affect the appearance of the button (e.g., changingborders to dashed lines) may not appear in your output. Changingthe border to a dashed line appears in the Layout editor but not thePreviewer.

3. The ability to assign different colors and patterns to user–definedbuttons is platform–specific. For more information, refer to yourInstallation and User’s Guide.

4. You cannot rotate a button.

Options:

Action


5. A button is always be displayed on the uppermost layer of objectsin the Previewer. However, it may not truly be on the top layer ofyour layout; for example, if it is covered by a repeating frame in theLayout editor, it will appear above the objects within the repeatingframe in the Previewer, but will not repeat with the repeatingframe.

Object Tab of Button Property Sheet

The Object tab of the Button property sheet is shown below. It containsthe following properties:

• Action – 8 – 81

• Label – 8 – 83

• Text String – 8 – 83

Is a set of radio buttons specifying the origin of the action that isperformed when you press the user–defined button in the Previewer.The Action radio buttons govern whether the button’s source is adatabase column, a file, or a PL/SQL program unit.



Multimedia Column indicates that the action to beperformed when the button is pressed is containedin a database column. If you select MultimediaColumn, you need to select a source column fromthe list to the right of the radio button. Selecting asource column automatically sets the propermultimedia type (i.e., sound, video, or image)under Type.

Multimedia File indicates that the action to beperformed when the button is pressed is containedin a file in your operating system. Enter the nameof the file, including full path information, in thetext field to the right of Multimedia File, or selectList to use the file selection dialog box to choosethe file. Then select Sound, Video, or Image from theType list of values to the right of the text field.

Execute PL/SQL indicates that the action to beperformed when the media button is pressed isgoverned by a PL/SQL program unit associatedwith the button. To create or reference thePL/SQL, select Edit next to the Execute PL/SQLradio button. The PL/SQL Program Unit editorappears.

Multimedia File

Rules:

1. If you select Multimedia Column, the name of the column must beselected under Source.

2. If you select Multimedia File, you must indicate the filename in thetext field provided. If you do not give a path for a file, OracleReports uses its file path search order to find the file. For moreinformation about file path search order, see “File SearchingMethod” on page 18 – 9.

Note: To ensure the portability of your reports, you can takeadvantage of the Oracle Reports–specific environment variablecalled REPORTS25_PATH. You can use this variable to specifythe default directory or directories where you want OracleReports to search for external files you use in your reports (e.g.,external queries, boilerplate, and PL/SQL). This prevents theneed to hardcode directory paths in your report. For moreinformation about setting this variable, see “Oracle ReportsEnvironment Variables” on page 18 – 10.

Options:

Default:

Label

Text String


3. If you specify a source for the action of a button and later deletethat source from your report (i.e., select a image column, specify itas the source of the action for a button, and later delete that columnor change its format to a non–multimedia format), your button nolonger has access to data to display, and Source becomesundefined.

If the button’s property sheet is open at the time the Sourcebecomes undefined, you must choose another source before youcan accept the property sheet. If the property sheet is closed at thetime the Source becomes undefined, you will not be alerted to theloss of the button’s source until you run the report and try toactivate the button. An error will result.

4. If you specify Execute PL/SQL and your PL/SQL usesSRW.RUN_REPORT, the Runtime Parameter Form will not appearby default when the button is selected. If you want the RuntimeParameter Form to appear, you must specify PARAMFORM=YESin the call to SRW.RUN_REPORT.

5. Raising SRW.PROGRAM_ABORT in a button’s action trigger killsany Previewer window that was raised by the button.

Is the identifier appearing on the media button in the Previewer.


Text indicates that you want to use a text string asthe button label. Use the Text String field to theright of Label to enter the text string you want touse as a label.

Icon indicates that you want to use an icon as thebutton label. Use the text field to the right of Labelto the name of the icon you want to use as a label.Oracle Reports will use the path defined by theTK21_ICON environment variable.

Text (text field is blank).

Rules:

1. An icon used as a label should be in the standard icon format ofyour platform, with an extension of .ico. Icons are not portable.

Is the text label that will appear on the button if you selected Text forthe Label.


Options:

Default:


Any text string up to 2K in length; however,practical length is governed by the size of thebutton. Any text string used as a label iscenter–justified both horizontally and vertically onthe button.

Empty.

Rules:

1. You can change the font, size, weight, and style of the label textusing some of the choices on the Format menu. However, certainmenu choices do not affect button text, such as Spacing andJustification.

2. The text does not wrap to a second line, it is clipped on both theleft and the right if it does not fit.

OLE2 Object Properties

When you double–click on an OLE2 object in the Layout editor or itsicon in the Object Navigator, its OLE2 property sheet is displayed.

The OLE2 property sheet is divided into the following tabs:




Additional Information: If you click the right mouse buttonwhile the cursor is on an OLE2 object, a pop–up menu appearswith actions appropriate to the object.

Options:

Default:

C H A P T E R

9T

9 – 1Parameter Form Editor

Parameter Form Editor

he Parameter Form editor enables you to create and edit whatappears in the Runtime Parameter Form, which typically appearsbefore the report is executed. You should know the following about theParameter Form editor:

• what is the Runtime Parameter Form – 9 – 2


• access – 9 – 5


• pop–menu – 9 – 7



Access

Components


Runtime Parameter Form

The sections that follow describe the following about the RuntimeParameter Form:


• access – 9 – 2


The Runtime Parameter Form appears when a report is run. It enablesyou to change the value of parameters in your report at runtime. Forexample, the user can specify the printer name, Oracle Mail userid,number of copies to be made, and bind and lexical values forparameters at runtime.

The Runtime Parameter Form is accessed whenever you run a report,unless you have suppressed it.

Note: To suppress the Runtime Parameter Form, you caninclude the keyword PARAMFORM=NO when you invokeR25DES or R25RUN, or you can check Hide Parameter Form inthe Tools Options dialog box. For more information, see“R25RUN” on page 1 – 17 For more information, see“R25DES” on page 1 – 35.

The Runtime Parameter Form has the following components:

• title

• hint line

• parameter input area

Title

Hint Line

Parameter Input Area


Title is the name given to the Runtime Parameter Form by you orOracle Reports. What appears in the title is determined by what is inthe Parameter Form editor, described later in this chapter.

Hint Line is hint text for the Runtime Parameter Form created by youor Oracle Reports. What appears in the hint line is determined by whatis in the Parameter Form editor, described later in this chapter. Ingeneral, the hint line provides information about what the user shoulddo in the Runtime Parameter Form.

The parameter input area is the part of the Runtime Parameter Formwhere you may enter values for parameters. What appears in theparameter input area is determined by what is in the Parameter Formeditor, described later in this chapter.

In general, the parameter input area contains the names of theparameters, their default value (if any), and a space for you to enter avalue. The Destination Type parameter does not contain a default value,but if you click–and–hold on the value field, a list of values appearsfrom which you can choose.

When you are done with the Runtime Parameter Form, accept it to runyour report.



The Parameter Form editor is the work area in which you define theformat of the report’s Runtime Parameter Form. To do this, you defineand modify parameter form objects (fields and boilerplate). For moreinformation, see “Parameter Form Properties” on page 10 – 1.

When you run a report, Oracle Reports uses the Parameter Form editoras a template for the Runtime Parameter Form. Fields and boilerplateappear in the Runtime Parameter Form exactly as they appear in theParameter Form editor.

Note: If you do not define a Runtime Parameter Form in theParameter Form editor, Oracle Reports displays a defaultParameter Form for you at runtime.

The figure below displays an example parameter form layout in theParameter Form editor.

Painting Region

Objects

Parameter Form Pages


Access

There are several ways you can access the Parameter Form editor:

• Select Tools—>Default Parameter Form. After Oracle Reportsbuilds the objects for you, you are placed in the Parameter Formeditor to see the results of the defaulting.

• Select the Tools—>Parameter Form Editor.

• From the Windows menu, select a window with the ParameterForm editor in it.

• From the Object Navigator, double–click on the Parameter Formnode’s icon.

Components

The Parameter Form editor has the following components:

• painting region

• toolbar

• tool palette

• status line

The painting region is the area in which you can create, modify,position, or delete objects while viewing their graphical representationson the screen. Objects have only their sizes and relative positionsgraphically represented in an editor. To see an object’s settings, youmust open its property sheet by double–clicking on the object.

The Parameter Form objects that you can create in the painting regionare: fields and boilerplate. For more information, see “Parameter FormProperties” on page 10 – 1.

Caution: You can cut, copy, paste, and duplicate objects in theParameter Form editor, but note that only the graphical representationsof the objects are copied. The property sheet settings are not copiedwith the objects.

The Parameter Form editor has no separate regions (such as header andtrailer), and is comprised of physical pages. For more information, see“Parameter Form Pages” on page 9 – 8.

Rulers

Grid

Toolbar

Tool Palette


Around the left and top edges of the painting region are rulers. Theserulers function exactly as their counterparts in the Layout editor. Formore information, see “Painting Region” on page 7 – 3.

Inside the painting region is a grid to help you position objects in thepainting region. The grid functions exactly as its counterpart in theLayout editor. For more information, see “Painting Region” on page7 – 3.

The Toolbar contains the following tools in the Parameter Form editor:

• Open

• Save

• Run

• Print

• Clear

• Default Layout

• Help


The Tool palette contains the following tools in the Parameter Formeditor:

• Selecting – 7 – 9 • Polyline – 7 – 13

• Magnify – 7 – 11 • Rounded Rectangle – 7 – 12

• Rotate – 7 – 10 • Freehand – 7 – 13

• Reshape – 7 – 11 • Text – 7 – 13

• Rectangle – 7 – 12 • Field – 7 – 14

• Line – 7 – 11 • Border/Fill/Font display – 7 – 15

• Ellipse – 7 – 12 • Fill Color – 7 – 15

• Arc – 7 – 12 • Line Color – 7 – 16

• Polygon – 7 – 12 • Text Color – 7 – 17

These tools function exactly as their counterparts in the Layout editor.

Status Line

☞


In the Parameter Form editor, the status line displays the followinginformation:



• rotation angles

• zoom levels

The status line functions exactly as its counterpart in the Layout editor.For more information, see “Status Line” on page 7 – 17.

Pop–Up Menu

The pop–up menu appears when you click your right mouse button inthe Parameter Form editor.


The pop–up menu in the Parameter Form editor for non–OLE2 objectscontains the following items:

Is the same as Edit—>Undo.

Is the same as Edit—>Cut.

Is the same as Edit—>Copy.

Is the same as Edit—>Paste.




Is the same as Help—>Help System.

If your cursor is in a blank area of the editor or on an object that cannothave PL/SQL, only a subset of these items appears.

Undo

Cut

Copy

Paste

Clear

Properties

ProgramUnitEditor

Help

Parameter Form Pages


Navigation

In the Parameter Form editor, you can:

• navigate between parameter form pages

• define parameter form pages

Note: It does not describe how to create objects, select objects,etc. For more information about how to use the tools in theTool palette, see “How To” in Chapter 8 of Building ReportsManual.

A parameter form layout is composed of one or more physical pages.A physical page of the parameter form is a window of information thatcan contain boilerplate text and graphics, and fields.

When you first enter the Parameter Form editor, you are placed on thefirst physical page. You can navigate to other pages of your parameterform by scrolling down. Pages are separated by dark lines in theeditor, as shown below.

Defining Pages


You specify the size of each parameter form page and the number ofpages using the Report property sheet (double–click on the report’snode in the Object Navigator). The Parameter Form editor will displayas many pages vertically as you have specified, separating each pageby a horizontal line. For more information on specifying ParameterForm default settings, see “Report Properties” on page 4 – 1.

Rules:

1. Objects that span pages will only appear on the first page of theRuntime Parameter form and will be truncated.

C H A P T E R

10P

10 – 1Parameter Form Properties

Parameter FormProperties

arameter form properties define the objects that make up theparameter form layout. Each of the following objects has a propertysheet associated with it that defines its properties:

• field – 10 – 2


Datatype

Name


Parameter Form Field Properties

When you double–click on a parameter form field in the ParameterForm editor or its icon in the Object Navigator, its Parameter FormField property sheet is displayed.

The Parameter Form Field property sheet is divided into the followingtabs:

• General – 10 – 2

• Comment – 10 – 3

General Tab of Parameter Form Field Property Sheet

The General tab of the Parameter Form Field property sheet is shownbelow. It contains the following properties:


• Name – 10 – 2

• Source – 10 – 3

Is a read–only field that displays the datatype of the parameter formfield’s Source.

The datatype of the Source parameter.

Is the name that Oracle Reports uses to identify the current field.

Default:

Source



Enter any valid parameter form field name. Formore information about naming conventions, see“Parameter Form Object Naming Conventions” onpage D – 3.

PF_n, where n is a number that is unique amongparameter form field names for the report.

Is the parameter from which the parameter form field gets its value. Alist of values is provided and it contains all parameters in the report.


Enter any valid parameter name.

Blank.

Rules:

1. The Source of a parameter form field must be a data modelparameter.

2. You cannot specify more than one parameter form field with thesame Source.

Comment Tab of Parameter Form Field Property Sheet

The Comment tab contains a field in which you can document theparameter form object.



Blank.

Options:

Default:

Options:

Default:

Options:

Default:

Name


Parameter Form Boilerplate Properties

When you double–click on a parameter form boilerplate object in theParameter Form editor or its icon in the Object Navigator, its ParameterForm Boilerplate property sheet is displayed.

The Parameter Form Boilerplate property sheet is divided into thefollowing tabs:

• General – 10 – 4

• Comment – 10 – 5

General Tab of Parameter Form Boilerplate Property Sheet

The General tab of the Parameter Form Boilerplate property sheet isshown below. It contains the following properties:

• Name – 10 – 4

• Type – 10 – 5

Is the name that Oracle Reports uses to identify the current boilerplate.


Enter any valid boilerplate name. For moreinformation about naming conventions, see“Parameter Form Object Naming Conventions” onpage D – 3.

Options:

Type


PB_n, where n is a number that is unique amongparameter form boilerplate names for the report.

Is the kind of boilerplate the object is. This field is read–only.

Comment Tab of Parameter Form Boilerplate Property Sheet

The Comment tab contains a field in which you can document theparameter form object.



Blank.

Default:

Options:

Default:

C H A P T E R

11T

11 – 1Previewer

Previewer

he Oracle Reports Previewer enables you to view your reportoutput in a window. You should know the following about the OracleReports Previewer:


• access – 11 – 3



• modification – 11 – 6

• character mode previewing – 11 – 7

• accessing multimedia objects – 11 – 8

• printing – 11 – 11



The Previewer is a window in which you view a report’s output. Whenyou run a report, you can send its output to several places, one ofwhich is the Previewer (shown in the figure below). If you have theoutput sent to the Previewer, it appears automatically when you run areport.

Drill–Down Oracle Reports enables you to have user–defined buttonswith PL/SQL actions attached to them. By using the packagedprocedure SRW.RUN_REPORT, you could define an action for a buttonthat calls another report. This second (or detail) report appears in itsown, modal Previewer. There is no limit to the number of levels youcan drill down in this way.

Multimedia Oracle Reports enables you to have user–defined buttonswhich play multimedia objects (e.g., video or sound) from thePreviewer. When you define the button, you associate a multimediaobject with it and when that button is selected in the Previewer themultimedia object is played.

OLE2 Oracle Reports enables you to open OLE2 objects in your reportfrom the Previewer. Double–clicking on an object in the Oracle ReportsPreviewer will open the server application with the currently selectedobject. (Note if the object is linked, its source object is displayed.)

Main Menu

11 – 3Previewer

Access

To display and access the Previewer, you must first run a report. Youcan access the Previewer in the following two ways:

• Run the report and ensure that DESTYPE is Screen or Preview.

Note: The value of DESTYPE can be set in a number of places(i.e., Initial Value in the Parameter property sheet for DESTYPE,the command line, the Runtime Parameter Form, a report trigger,or a validation trigger). If the report does not appear in thePreviewer, the value of DESTYPE is probably being setsomeplace other than the Runtime Parameter Form.

• From the Windows menu, select a window with the Previewer init.

Components

The Previewer has the following components:

• main menu – 11 – 3

• title – 11 – 4

• viewing region – 11 – 4

If you run the report from within the designer (by selecting Run... fromthe File menu), the main menu appearing at the top of the Previewercontains the same activated menu items as in the designer menu.However, if the report was run using R25RUN, a subset of thedesigner’s main menu and its submenu choices is available:

• The File menu contains Connect, Disconnect, Run, Print, PageSetup, Choose Printer, Quit.

• The Edit menu contains Cut, Copy, Paste, Clear, Select All,Runtime Settings, Import Text, Export Text.

• The Windows menu contains the currently open windows.

• The Help menu contains Contents, Module Info, About OracleReports.

Note: When you select a button in the Previewer that runsanother report, an additional, modal Previewer window isopened and some of the above menu items are disabled.

Title

Viewing Region

Report Sections

Physical and LogicalPages


By default, the Previewer title is ”<report name>: Previewer.” Formore information on modifying the Previewer title, see “Modification”on page 11 – 6.

The viewing region is the area in which you can browse through eachpage of your report output. When the Previewer first appears, the topof the report title page is displayed.

To view any other part of the report, you use the navigation buttons.To understand the navigation buttons (described under ”Navigation”on the following page), you must first understand some concepts:

• report sections – 11 – 4

• physical and logical pages – 11 – 4

A report section is one of three parts of your report: Header,Body/Margin, and Trailer. The Header can be any number of physicalpages long, but only one physical page wide. The Body/Margin can beany length or any width. The Trailer can be any number of physicalpages long, but only one physical page wide (like the Header).

For more information on report sections, see “Layout Editor” on page7 – 1.

A physical page (or panel) is the size of a page that will be output byyour printer. A logical page is the size of one page of your actualreport (it can be any number of physical pages wide or long). ThePreviewer displays the logical pages of your report output, one at atime. The figure below illustrates an example of physical and logicalpages.

11 – 5Previewer

Navigation

To navigate within the Previewer, do the following:

• Select the First, Last, Next, and Previous buttons to move to thefirst, last, next, and previous page of output, respectively.

• Select the home, end, page down, and page up keys to move tothe first, last, next, and previous page of output, respectively.

• Type a page number in the field beside the Page button. SelectPage: to go to that page. If the number is greater than thenumber of pages, the last page will be displayed.

• Use the scroll bars and arrows to move the window’s contents tothe direction specified.

• Select the Print button to print the report output. For moreinformation, see “Printing from the Previewer” on page 11 – 11.

Note: If you split your Previewer, you must click in the desiredsection before navigating in it.

Additional Information: If your report contains user–definedbuttons, you can select them to execute their action. Buttonsmay play multimedia objects or execute a PL/SQL action.

Title

Viewing Region

Splitting the ViewingRegion


Modification

You can modify the following components within the Previewer:

• title – 11 – 6

• viewing region – 11 – 6

To modify the Previewer title, do the following:

1. Double–click on the report node’s icon in the Object Navigator todisplay the Report property sheet.

2. Go to the Parameter Form tab and enter new text in the Title field.

3. Accept the Report property sheet.

You can perform the following modifications on the Previewer’sviewing region:

• split – 11 – 6

• magnify – 11 – 7

• open a new instance – 11 – 7

To split the viewing region, do the following:

1. Click–and–hold on the box that appears to the left of the horizontalscroll bar (to split horizontally) or above the vertical scroll bar (tosplit vertically). Drag the box to the point at which you wish tosplit the screen. For example, to split the screen so that theresulting sections are about equal in size, you would drag the boxto the approximate vertical or horizontal center of the Previewer.

When you release the mouse button, the viewing region splits intotwo sections, with the same information displayed in both sections.

2. To ”unsplit” or return the Previewer to a single viewing region,drag the box back to its original position next to the scroll bar.

The figure below displays the Previewer when it is split horizontally.

Magnifying the ViewingRegion

Opening AnotherWindow

11 – 7Previewer

To magnify the viewing region select the Magnify icon in the lower leftcorner of the Previewer. The large Magnify icon increases the size ofthe Previewer contents and the small Magnify icon decreases the size ofthe contents.

To open a new Previewer window with the same contents as thecurrent one, select New from the current Previewer window.

Character Mode Previewing

If you intend to run a report from the character–mode runtime, you canenter settings to change the appearance of the character–modePreviewer by doing the following:

1. Double–click on the report node’s icon in the Object Navigator todisplay the report’s property sheet.

2. Go to the Character Mode tab and change the settings as desired.

3. Accept the Report property sheet.

Accessing Sound

Sound Dialog BoxOptions

Forward


Rules:

1. When displaying a character mode report in the bit–mappedPreviewer, Oracle Reports uses the report width and height definedin the Character Mode tab of the Report property sheet to choosethe font size to display. The measured size of the font becomes thecell size. This ensures that the text of the report is showncompletely (without clipping or overwriting), but it means that thePreviewer page size may not be exactly 8.5 by 11.

Accessing Multimedia Objects

User–defined buttons in your report can play multimedia objects orexecute PL/SQL. User–defined buttons can access the following typesof multimedia objects:

• sound – 11 – 8

• video – 11 – 10

• images – 11 – 10

If the source associated with the user–defined button at design time is asound, when the button is pressed the Sound dialog box is displayed toplay the sound.

Rules:

1. If you close the Previewer while the Sound Dialog is open, theSound Dialog also closes.

2. Button actions are mutually exclusive. This means that only onebutton action can be in effect at a time.

The Sound dialog box is shown below and its options are describedalphabetically following the figure.

Fast forwards to the end of the sound.

Options

Play

Record

Rewind

Slidebar

Stop

11 – 9Previewer

Is a button that displays the Audio Control Panel. You use the Panel toset Sound Dialog options. The figure below shows the Audio ControlPanel; its settings are described alphabetically following the figure.

Playback Setting Under Playback Setting are the following two optionsfor controlling the play of a sound file:

Is the relative loudness of the sound when played.Click on the list and choose a number from zero tonine, with zero being softest and nine beingloudest.

Is whether the sound is output over yourmachine’s own speakers or headphones. Click onthe list and choose your preference.

Record Setting Under Record Setting are options governing therecording of a sound. Since you cannot record from the Previewer,these options are all disabled.

Plays the sound beginning from wherever the slider is currentlypositioned.

Is disabled because you cannot record sound from the Previewer.

Rewinds to the beginning of the sound.

Controls the relative position in the sound being played. You can movethe slider to any position and play from that point.

Stops the sound at any point.

Volume

Device

Accessing Video

Video Player Dialog BoxOptions

Play/Stop

Slidebar

Sound/Mute

Accessing Images


If the source associated with the user–defined button at design time isvideo, when the button is pressed the Video Player dialog box isdisplayed to play the video.

Rules:

1. If you close the Previewer while the Video Player dialog box isopen, the Video Player also closes.


3. Video may not be available on all platforms. For more information,see the Developer/2000 Installation Guide for your operating system.

The Video Player dialog box is shown below and its options aredescribed alphabetically following the figure.

Plays the video from the current slider position or stops it at any point.

Controls the relative position in the video being played. You can movethe slider to any position and play from that point.

Plays the video’s sound or mutes it at any point.

If the source associated with the user–defined button at design time isan image, when the button is pressed an Image Viewer window, shownbelow, is displayed, containing the image.

Additional Information: The Image Viewer window displaysimages with better fidelity than if they were simply imbeddedin the report output.

Rules:

1. If you close the Previewer while the Image Viewer is open, theImage Viewer also closes.

Image Viewer Options

Magnify Tool

Panning Tool

11 – 11Previewer


The Image Viewer is shown in the figure below and its tools aredescribed alphabetically following the figure.

Magnifies an area around the point on which you click by a factor oftwo; i.e., the image becomes twice as big as it was. By pressing theconstraint key (e.g., the shift key) while using the Magnify tool, youmagnify by a factor of one–half; i.e., the image become half as big as itwas. This tool is useful when you want to focus on one part of a largeimage.

Moves the image within the Image Viewer. Panning is similar toscrolling; however, you can move the image in two dimensions at once.To pan the image, select the Panning tool and drag the image.

Printing from the Previewer

You can select the Print button to send report output to a printer, file,or mail id. The Print Job dialog box then appears. The appearance ofthis dialog box varies between operating systems. For moreinformation, see the Developer/2000 Installation Guide for your operatingsystem. After you accept the Print Job dialog box, the output is sent tothe printer (specified in File—>Choose Printer), file, or mail id. If youran the report with a DESTYPE of Screen, a warning appears before thePrint Job dialog box that you should run the report with a DESTYPE ofPreview before printing. Preview creates PostScript output, which istypically more desirable for printing.

Note: The Previewer output is displayed in terms of logicalpages and will also be printed in terms of logical pages.

C H A P T E R

12T

12 – 1Object Navigator

Object Navigator

he Object Navigator provides a simple and powerful way getaround in Oracle Reports. You should know the following about theObject Navigator:


• access – 12 – 2

• component descriptions – 12 – 3


• nodes – 12 – 5

• hierarchical views – 12 – 10




The Object Navigator provides a hierarchical display of all majorobjects in a report, including attached libraries and external queries.Using this view, you can take such actions as select an object in a editor,bring up an object’s property sheet, edit an object’s PL/SQL, drag anddrop PL/SQL program units, and search for an object by name.

For more information about the PL/SQL you can create in OracleReports, see “PL/SQL in Oracle Reports” on page 13 – 15.

The figure below displays an example of the Object Navigator.

Access

There are two ways to access the Object Navigator:

• Invoke the designer.

• Select it from the Windows menu.

Module List

Find Field

Search Forward

Search Backward

Toolbar

Object Tree


Components

The Object Navigator has the following components:

• module list – 12 – 3

• Find field – 12 – 3

• Toolbar – 12 – 3

• object tree – 12 – 3

At the top of the Object Navigator is a list of all of the currently openmodules in the Object Navigator, and the most recently selected nodeand its ancestors. By selecting a name from the list, you canimmediately select it’s node in the Object Navigator.

At the top of the Object Navigator is a field called Find in which youcan enter a target string for the node search. Next to the Find field aretwo tools for directing the search backward or forward:

Finds the next node whose name matches the search string in Find. Itwill search and expand collapsed nodes.

Finds the previous node whose name matches the search string in Find.It will search collapsed nodes.

For more information about searching in the Object Navigator, see“Searching in the Object Navigator” on page 12 – 16.

The Toolbar contains the following in the Object Navigator:

• Open • Delete

• Save • Expand

• Run • Collapse

• Print • Expand All

• Create • Collapse All


The Object Tree is the area that displays a listing of objects in thecurrent session of the designer. This listing consists of nodes, eachrepresenting an object or type of object. For more information, see“Nodes” on page 12 – 5.

☞


Pop–Up Menu

The pop–up menu appears when you click your right mouse button inthe Object Navigator.


The pop–up menu in the Object Navigator contains the following itemsfor most objects:

Is the same as Tools—>Properties.

Displays the editor (Data Model, Layout,Parameter Form) that is associated with thecurrently selected object(s). If you have multipleobjects selected, the editors associated with all theobjects will be displayed. For example, if youselect a field and then a column, the Data Modeland Layout editors would be displayed when youselect Editor.

Is the same as Tools—>Program Unit Editor.

Is the same as Help—>Contents.

The pop–up menu in the Object Navigator contains the following itemsfor breakpoints:

Enables the selected breakpoint.

Disables the selected breakpoint.

The pop–up menu in the Object Navigator contains the following itemsfor program units or built–in program units:

Pastes the name of the selected program unit intothe last active Program Unit Editor.

Pastes the arguments of the selected program unitinto the last active Program Unit Editor.

Additional Information: Paste Name and Paste Argumentsonly work when the Program Unit Editor is already open.

Properties

Editor

Program UnitEditor

Help

Enable

Disable

Paste Name

Paste Arguments

Node Format

Plus/Minus


Nodes

Each object or object type in your current designer session—from eachopen report, to the objects in each report—is represented in the ObjectNavigator by a node. (A node is any selectable line in the ObjectNavigator.) This section discusses the following aspects of nodes:

• node format – 12 – 5

• node types – 12 – 7

• hierarchical views of nodes – 12 – 10

Each node in the Object Navigator consists of some or all of thefollowing:

• a plus or a minus indicating the node’s expansion status – 12 – 5

• an icon representing the object’s PL/SQL (if any) – 12 – 6

• an icon representing the object type or an editor – 12 – 6

• a name or heading – 12 – 7

Each node has the following format:

<{+|–}> <PL/SQL Icon> <Icon> Name

Segments in angle brackets (<>) are dependent on node type andObject Navigator options (Navigator—>Navigator Options).

Indicates the expansion status of the node:

• A plus indicates that the node has other nodes underneath it, butthey are not currently displayed. A node with a plus can beexpanded to display its hidden child nodes. If the plus is greyedout, it means that the node could contain other nodes butcurrently doesn’t.

• A minus indicates that the node has other nodes underneath itand they are currently displayed. A node with a minus can becollapsed to hide all its currently displayed child nodes.

Children of the current node can be displayed by doing any of thefollowing:

• Click on the plus to expand or shift–click to expand all.

• Select Expand from the Toolbar.

• Select Navigator—>Expand or Navigator—>Expand All.

PL/SQL Icon

Object Type or Editor Icon


The tree can be contracted in a similar fashion by doing any of thefollowing:

• Click on the minus to collapse or shift–click to collapse all.

• Select Collapse or Collapse All from the Toolbar.

• Select Navigator—>Collapse or Navigator—>Collapse All.

For more information about navigation in the Object Navigator, see“Navigation” on page 12 – 15.

Indicates that the object can have PL/SQL associated with it andwhether it currently has a program unit defined. To select the node,click on the PL/SQL icon. If the node represents a selectable object,clicking also selects the object in its editor. To display the Program UnitEditor with the object’s program unit in it, double–click on the PL/SQLicon.

The figure below shows two nodes in the Object Tree. Both are forcolumns. Notice the difference between the PL/SQL icons in thenodes. The first node has a PL/SQL program unit associated with it.The second one could have a program unit associated with it but doesnot currently.

Indicates the type of object or editor represented by the node; e.g., anode representing a query will display a query icon and the DataModel heading node will display a Data Model editor icon. To selectthe node, click on the object or editor icon. If the node represents aselectable object and its editor is open (e.g., the Layout editor), clickingalso selects the object in its editor. To display an object’s propertysheet, double–click on its object icon. To display an editor, double–clickon its editor icon.

If you do not want the object icons to display, ensure that the ShowObject Icons checkbox in the Object Navigator Options dialog box isunchecked. Note that if you hide the icons, you will need to use theTools menu to access property sheets (Tools—>Properties) and editors.

Object Name or Heading

Node Types

Heading Nodes


Is the name of the object represented by the node or a heading node.Clicking on the name or heading selects the node. If the node isalready select, a single click on the name places it in edit mode, andyou can edit the name of the object (you cannot edit headings).Clicking outside the object deactivates edit mode and updates theedited name in all appropriate places (e.g., the layout and the object’sproperty sheet). Similarly, if you change the object’s name elsewhere, itwill automatically be updated in the Object Navigator.

Note: If the name in the Object Navigator is in edit mode butedited elsewhere, the name will not get updated in the ObjectNavigator. Instead, the name in the Object Navigator takesprecedence and the object’s final name will be that which is inthe Object Navigator at the time edit mode is deactivated.

Double–clicking on the following heading nodes creates a new node, ifthe heading currently has no nodes underneath it:

• Attached Libraries

• External Queries

• Libraries

• Program Units

• Reports

• Stored Program Units

• Triggers

A node can represent one of the following:

• heading – 12 – 7

• object – 12 – 10

Heading nodes denote types of report objects or properties; e.g.,Reports, Frames, Boilerplate, etc. These headings precede the nodesrepresentng actual report objects and are used in navigation.

The following is a listing of the heading nodes in the Object Navigatorin the order in which they appear. Any actions specific to the node areexplained.

Heading Node Description

Anchor Information Lists all anchors (implicit and explicit)for an explicitly anchored object.

Attached Libraries Lists libraries attached to the report.



Body Lists all the objects in the report’s bodypages. This node only appears whenView Layout by Structure is selected inthe Object Navigator Settings dialogbox.

Built–in Packages Lists the available built–in packages.

Buttons Lists all the button objects in the report.

Database Columns Lists all the columns selected by the re-’

yport’s queries.

Data Links Lists all the data links in the report.

Database Objects Lists database users and the stored pro-gram units, libraries, tables, and viewsowned by these users.

Data Model Lists all data model objects in the re-port. Can be used to access the DataModel editor.

Debug Actions Lists the debug actions in the currentreport.

Dimension RepeatingFrames

Lists the repeating frames that are re-lated by the parent matrix object.

External Boilerplate Lists all the external boilerplate objectsin the report.

External Queries Lists external queries open in the cur-rent session.

Frequency <repeatingframe name>

Lists objects whose frequency is thesame as that of the repeating frame.

Fields Lists all the fields in the report

Formula Columns Lists all the formula columns in the re-port.

Frames Lists all the frames in the report.

Graphics Boilerplate Lists all the boilerplate graphic objectsin the report.

Groups Lists all the groups in the report.

Header Lists all the objects in the report’s head-er pages. This node only appears whenView Layout by Structure is selected inthe Object Navigator Settings dialogbox.



Image Boilerplate Lists all the static image boilerplate ob-jects in the report.

Layout Lists all layout objects in the report.Can be used to access the layout editor.

Libraries Lists external libraries open in the cur-rent session.

Margin Lists all the objects in the report’s mar-gin. This node only appears when ViewLayout by Structure is selected in theObject Navigator Settings dialog box.

Matrices Lists all the matrix objects in the report.

OLE2 Objects Lists all the OLE2 objects in the report.

Oracle Graphics Docu-ments

Lists all the Oracle Graphics documentsin the report.

Parameter Form Lists all parameter form objects in thereport. Can also be used to access theParameter Form editor.

Placeholder Columns Lists all the placeholder columns in thereport.

Program Units Lists all program units in the report.

Referenced By Lists the other program units that refer-ence the program unit.

References Lists the other program units that arereferenced by the program unit.

Repeating Frames Lists all the repeating frames in the re-port

Reports Lists reports open in the current ses-sion. Can be fully expanded to show allobjects in the reports.

Report Triggers Lists all the report triggers in the report.

Specification Shows the program unit’s specification.

Stack Shows all objects in the Reports stackfor current debug session.

Summary Columns Lists all the summary columns in thereport.

System Parameters Lists system parameters in the report.

Text Boilerplate Lists all the text objects in the report.

Object Nodes

Hierarchical Views



Trailer Lists all the objects in the report’s trailerpages. This node only appears whenView Layout by Structure is selected inthe Object Navigator Settings dialogbox.

User Parameters Lists the user–created parameters in thereport.

Object nodes represent specific objects found in open reports duringthe current designer session; e.g., F_1, M_GRPFR_Dept, B_Rectangle,etc. When you select and object node in the Object Navigator, theobject is also select in the appropriate editor (e.g., the Layout editor), ifthe editor is already open.

The Object Navigator enables you to examine the hierarchy of reportobjects. You can examine the:

• data hierarchy – 12 – 11

• layout hierarchy – 12 – 13

Below is a data model and layout for a sample report. Refer back tothis sample during the following discussions.

Data Hierarchy


You can display groups and columns in the Object Navigator in eitherone of the following ways:

• by structure – 12 – 11

• by type – 12 – 12

View by Structure You can display groups and/or columns in ahierarchical tree structure. Child groups appear underneath theirparent groups. Columns appear underneath the groups that own them.The tree is fully expandable and contractable, enabling you to examinerelationships at any level. Siblings are displayed alphabetically.

To view groups by structure, select View by Structure in the Groups tabof the Object Navigator Settings dialog box. To view columns bystructure, select Show Columns in Groups in the Groups tab.

The example below shows a data model object tree while View byStructure and Show Columns in Groups are selected.


View by Type You can display groups and/or columns by type ofobject. Hierarchy is not indicated.

To view groups by type, deselect View by Structure in the Groups tabof the Object Navigator Settings dialog box. To view columns by type,deselect Show Columns in Groups in the Groups tab.

The example below shows the same data model object tree while Viewby Structure and Show Columns in Groups are deselected.

Layout Hierarchy


You can display layout objects in either one of the following ways:

• by structure – 12 – 13

• by type – 12 – 14

View by Structure You can display layout objects in a hierarchical treestructure. Objects are shown underneath the objects that own them.The tree is fully expandable and contractable, enabling you to examinerelationships at any level. Siblings are displayed alphabetically.

To view layout by structure, select View by Structure in the Layout tabof the Object Navigator Settings dialog box.

The example below shows a layout while View Layout by Structure isselected.


View by Type You can display layout objects by type of object.Hierarchy is not indicated.

To view layout by type, deselect View by Structure in the Layout tab ofthe Object Navigator Settings dialog box.

The example below shows the same layout while View Layout byStructure is deselected.

Navigation Within theObject Navigator

Expanding andCollapsing Nodes


Navigation

The Oracle Reports Object Navigator includes features that enable youto navigate among Object Navigator nodes, editors, and report objects:

• navigation within the Object Navigator – 12 – 15

• navigation to other report objects – 12 – 17

To aid in navigation within the Object Navigator, Oracle Reportsprovides the following features:

• expanding and contracting nodes – 12 – 15

• searching in the Object Navigator – 12 – 16

Oracle provides several methods for expanding and collapsing nodesin the Object Navigator, enabling you to view as much or as little of theobject tree as you wish.

Searching in the ObjectNavigator


To display children of the current node, do any of the following:

• Click on the plus.

• Select the Expand tool on the toolbar.

• Select Navigator—>Expand menu option to expand the tree.

To contract children of the current node, do any of the following:

• Click on the minus.

• Select the Collapse tool from the toolbar.

• Select Navigator—>Collapse.

To fully expand all child nodes of the current node, do any of thefollowing:

• Shift–click on the plus.

• Select the Expand All tool on the toolbar.

• Select Navigator—>Expand All.

To fully collapse all child nodes of the current node, do any of thefollowing:

• Shift–click on the minus.

• Select the Collapse All tool from the toolbar.

• Select Navigator—>Collapse All.

Rules:

1. If a parent node is expanded or collapsed, any nodes under it retaintheir expanded or collapsed state, independent of the action takenon their parent node. For example, suppose a node and all itssubnodes are currently expanded. The node is collapsed, thensubsequently expanded again. All its subnodes display in theiroriginal expanded state. To collapse a node without retaining itsprevious state, you must collapse all (e.g., shift–click on the minus).

To search for a specific node in the Object Navigator, type the objectname in the Find field. Select one of the icons to the right of the Findfield to direct the search up or down in the Object Navigator.

The first node name to match the target string is highlighted in theObject Navigator. All parent nodes of the target are expanded asnecessary.

Rules:

1. The Object Navigator search facility is case–insensitive.

Navigation to OtherReport Objects

Accessing Editors

Accessing Property Sheetsand Associated PL/SQL


To aid in navigation among report objects, Oracle Reports provides thefollowing features:

• quick access to editors – 12 – 17

• quick access to property sheets and associated PL/SQL – 12 – 17

If you want to access an editor that is not open, iconized, or simplyhidden behind other windows, double–click on the icon of theappropriate node (e.g., Data Model, Layout, or Parameter Form).Focus will be given to that window.

Note: If the window is open but currently not visible, you canalso use the Windows menu, but editors that are not open willnot appear as menu choices.

To access the property sheet of a report object, go to the noderepresenting that object in the Object Navigator and double–click on itsobject–type icon. (For more information on the different parts of anode, see “Nodes” on page 12 – 5.) The property sheet for that objectis displayed.

To access the PL/SQL associated with a report object, go to the noderepresenting that object in the Object Navigator and double–click on itsPL/SQL icon. This will display the Program Unit Editor with theappropriate PL/SQL code already loaded and ready to edit. You canalso select the node and then select Tools—>Program Unit Editor.

P A R T

III Integration

C H A P T E R

13P

13 – 1PL/SQL Interface

PL/SQL Interface

L/SQL provides conditional control and database transactionprocessing. The following describe PL/SQL in Oracle Reports:

• overview – 13 – 2

• description of value constructs (functions and exceptions) –13 – 4

• description of non–value constructs (procedures and packages) – 13 – 6

• description of exceptions – 13 – 11

• PL/SQL in Oracle Reports – 13 – 15

• description of Oracle Reports references in PL/SQL – 13 – 32

• PL/SQL restrictions in Oracle Reports – 13 – 33

• Oracle Procedure Builder – 13 – 35

• compilation – 13 – 37

• Oracle Procedure Builder packages – 13 – 39

• Developer/2000 PL/SQL package: CDE_MM – 13 – 40

• description of the Oracle Reports PL/SQL package: SRW –13 – 41

Note: For more information on how to write PL/SQL, see thePL/SQL User’s Guide and Reference.


Types and Usage ofPL/SQL Constructs


PL/SQL Overview

This overview covers the following topics:

• PL/SQL definition and purpose – 13 – 2

• types of PL/SQL constructs and their usage – 13 – 2

PL/SQL is a language for application development and databasetransaction processing. It combines extensive proceduralcapabilities—such as conditional control and looping—with thenon–procedural capabilities of SQL.

You use PL/SQL to add its capabilities to an object, for example:

• database manipulation capabilities (DML), such as ORACLEINSERTs, UPDATEs, and DELETEs

• procedural capabilities, such as perform arithmetic, string, andBoolean operations; specify branching with IF...THEN andGOTO statements; specify exception handlers for errorprocessing)

To do so, you write a PL/SQL construct and assign it to an object.

Note: PL/SQL does not support database definitioncapabilities (DDL). You can add DDL capabilities to OracleReports objects using the SRW.DO_SQL packaged procedure.For more information on this packaged procedure, see“SRW.DO_SQL” on page 13 – 43.

There are two basic types of PL/SQL constructs (code structures) thatyou can write: those that return (i.e., set) a value, and those that don’t.The PL/SQL terms for these two types of constructs are:

• value constructs, for PL/SQL code that returns a value

• non–value constructs, for code that does not return a value

In general, you write a value construct when the Oracle Reports objectrequires that you return a value; you write non–value constructs whenthe object requires that you do not.

Objects Requiring Value Constructs

• Report Triggers enable you to check the status of an object orchange the logic of the report. Report Triggers can only returnTRUE, i.e., continue the report execution, or FALSE, i.e., stop theexecution.


• Group Filters enable you to reduce the number of rows that areused in your report. Group Filters can only return TRUE, i.e.,fetch the data specified in the filter, or FALSE, i.e., do not fetchthe data specified.

• Formula Columns enable you to perform customizedcomputations. They can return a number, date, character, orboolean. The value that is returned will become the value of theformula. Formula columns can also be used to set the value ofplaceholder columns.

• Placeholder Columns normally contain no PL/SQL, but, if theirvalues are set in a user exit, their formulas must containSRW.REFERENCE.

• Validation Triggers enable you to check the value entered on theRuntime Parameter Form. Validation Triggers can only returnTRUE, i.e., continue processing, or FALSE, i.e., invalidateparameter.

• Frame, Repeating Frame, Field, and Boilerplate Format Triggersenable you to conditionally suppress or modify the appearanceof data printed by these layout objects. They can either returnTRUE, i.e., print the object with the specified attributes (if any),or FALSE, i.e., do not print the object.

Objects Requiring Non–value Constructs (None.)

Objects Accepting Both Value and Non–Value Constructs

• External PL/SQL Libraries (packages, functions, or procedures)enable you to type code once that will be used by more than onemodule (e.g., report, form, or Oracle Graphics display, etc.).They can return any valid PL/SQL return type.

• Report Program Units (packages, functions, or procedures thatyou can reference from the report’s objects) enable you to typecode once that will be used by more than one report object,thereby reducing redundant code. They can return any validPL/SQL return type.

Advantages

Syntax


Value Constructs

A value construct is a PL/SQL construct (code structure) that returns avalue. You can use value constructs in report triggers; group filters;column formulas; and frame, repeating frame, field, and boilerplateformat triggers. In Oracle Reports, you express a value construct usinga named function.

An example of a function is:

function tax return number is

begin

if :year < 1992 then

return(.05 * :amount);

else

return(.06 * :amount);

end if;

end;

• Functions have a name and, therefore, can be referenced from otherconstructs. This allows constructs to be shared and reducesredundant code.

• Functions support exception handling, local variable declarations,and arbitrary control structure.

FUNCTION function_name [ argument_list ] RETURN [type] IS

[ local_variable_declaration ]

BEGIN

statements

[EXCEPTION exception_handlers ]

RETURN( result );

END;

where:

Is the unique name of the function. This namemust adhere to ORACLE naming conventions.

Is ({var_name [mode] type [:= value]}[, ...])

where:

Is the unique name of a localvariable.

Is {IN|OUT|IN OUT }.

function_ name

argument_ list

var_name

mode


Is{BOOLEAN|CHAR|NUMBER|DATE|

PLS_INTEGER}.

Is a PL/SQL expression.

(Functions entered directly in Formula, ValidationTrigger, Filter Condition, Formula, or a reporttrigger cannot take arguments.)

Is {var_name type [:= value]}[,...]

Are the executable PL/SQL statements.

For more information, see the PL/SQL User’s Guideand Reference.

Is the expression indicating the value of thefunction.

Examples:

1. Suppose you want to create a function that calculates the productof two numbers (e.g., to calculate an employee’s bonus pay). To doso, you first create a report program unit called BONUS_PAY:

FUNCTION BONUS_PAY (PCT IN NUMBER, SAL IN NUMBER) RETURN NUMBER IS BEGIN RETURN(PCT * SAL); END;

Next, you reference BONUS_PAY in the formula for the BONUScolumn:

FUNCTION MY_FORMULA RETURN NUMBER IS BEGIN RETURN BONUS_PAY(:PERCENT,:SAL);END;

2. Another way in which you could accomplish the goal in the aboveexample is to simply write the function completely in the BONUScolumn’s formula:

FUNCTION MY_FORMULA RETURN NUMBER IS BEGIN RETURN(:PERCENT * :SAL); END;

type

value

local_variable_declaration

statements

exception_handlers

result

Procedures


3. Assume that you created a parameter for your report calledMY_PARAM, and before the report is run, you want to set theparameter to 100. To do so, you create the following in the BeforeForm trigger:

FUNCTION FOO RETURN BOOLEAN IS BEGIN :my_param := 100; RETURN (TRUE); END;

Note: Note that report triggers must always return a booleanvalue.

Non–value Constructs

A non–value construct is a PL/SQL construct (valid code syntax) thatdoes not return a value. Non–value constructs are executed solely toperform a specified sequence of actions or ”side effects.” For example,the side effect of an ”after report” trigger might be to mail the reportoutput to an interested party.

A non–value construct may be expressed in PL/SQL as one of thefollowing:

• a procedure definition – 13 – 6

• a package – 13 – 8

You specify a non–value construct by entering a complete proceduredefinition. An example of a procedure is below:

PROCEDURE DOIT (PASTPARAMFORM IN BOOLEAN) IS

BEGIN

if pastparamform then

srw.do_sql(’create table written (checkno number(9),

empno number(9)) pctfree 5 pctused 75’);

else srw.message(100,’Report failed before procedure

doit executed.’);

raise srw.program_abort;

end if;

END;

Advantages

Syntax


• Procedures have names and, therefore, can be referenced from otherconstructs. This allows constructs to be shared and reducesredundant code.

• Procedures support local variable declarations, and arbitrary controlstructure.

PROCEDURE procedure_name [ argument_list ] IS

[ local_variable_declaration ]

BEGIN

statements

[EXCEPTION exception_handlers ]

END;

where:

Is the unique name of the procedure. This namemust adhere to ORACLE naming conventions. Formore information, see the ORACLE7 Server SQLLanguage Reference Manual.

Is ({var_name [mode] type [:= value ]}[, ...])

where:

Is the unique name of a localvariable.

Is {IN|OUT|IN OUT }.

Is {BOOLEAN|CHAR|NUMBER|DATE|

PLS_INTEGER}.

Is a PL/SQL expression.

Is {var_name type [:= value]}[,...]

Are the executable PL/SQL statements.

For more information, see the PL/SQL User’s Guideand Reference.

procedure_ name

argument_ list

var_name

mode

type

value

local_variable_declaration

statements

exception_handlers

Packages

Advantages


Examples:

1. Assume you want to log PL/SQL–detected errors into a tablecalled EXCEPTION_TABLE. To do so, you create the followingreport–level program unit:

PROCEDURE ERROR_LOG (MESSAGE VARCHAR2) IS BEGIN insert into ERROR_TABLE values (MESSAGE); END;

A package is a database object that groups logically related PL/SQLtypes, objects, and functions or procedures. Packages usually have twoparts, a specification and a body, although sometimes the body isunnecessary. The specification is the interface to your module; itdeclares the types, variables, constants, exceptions, cursors, andfunctions or procedures that are available for use. The body fullydefines cursors, functions, or procedures, and so implements thespecification.

• Modularity: packages enable you to encapsulate logically relatedtypes, objects, functions, and procedures in a named module.

• Added Functionality: global (package) variables and cursors persistfor the duration of a session. So, they can be shared by allconstructs. And, they enable you to maintain data acrosstransactions without having to store it in the database.

Note: Globals will perform faster than Oracle Reportsparameters that you treat like globals. Globals are more usefulthan placeholder columns because they are not restricted: aformula column that sets a placeholder must be in the samegroup as the placeholder column. Globals can be used to setany value.

• Better Performance: When you call a packaged function orprocedure for the first time, the whole package is loaded intomemory. Therefore, subsequent calls to related functions orprocedures in the package require no disk I/O.

In addition, packages stop cascading dependencies, and thus avoidunnecessary recompiling. For example, if you change the definitionof a function, you must recompile all constructs that call thefunction. However, if you change the definition of a packagedfunction, you do not need to recompile the calling constructs becausethey do not depend on the package body.

Package Spec Syntax

Package Body Syntax


PACKAGE name IS –– specification (visible part)

–– public type and object declarations

–– function or procedure specifications

END [name];

PACKAGE BODY name IS –– body (hidden part)

–– private type and object declarations

–– function or procedure specifications

[BEGIN

–– initialization statements]

END [name];

The specification holds public declarations, which are visible to yourmodule. The body holds implementation details and privatedeclarations, which are hidden from your module.

Think of the specification as the operational interface, and of the bodyas a ”black box.” You can debug, enhance, or replace a package bodywithout changing the interface.

Rules:

1. You must create a package spec before you can create a package body.

Examples:

1. Suppose you want to create a package named GLOBAL that willincrement a global named NUMGLOB if the salary is greater than2500, or decrement NUMGLOB if the salary is equal to or less than2500. To do so, you must first create a library and write a packagespec:

PACKAGE GLOBAL IS NUMGLOB NUMBER; PROCEDURE INCREMENT; PROCEDURE DECREMENT; END GLOBAL;

2. Next, you would write a package body corresponding to thepackage spec in the same library:

PACKAGE BODY GLOBAL IS PROCEDURE INCREMENT IS BEGIN NUMGLOB := NUMGLOB + 1; END INCREMENT; PROCEDURE DECREMENT IS BEGIN NUMGLOB := NUMGLOB – 1;


END DECREMENT; BEGIN NUMGLOB := 0; ––initializes numglob END GLOBAL;

3. Save the library.

4. Now suppose that you want to create a report that will print thesalary field if the value of NUMGLOB is a multiple of 10 (e.g., 10,20, etc.). (This scenario is for exemplary purposes only—todemonstrate how to reference objects in a package.) To do so, youwould do the following:

4.1 Create a report with a query that selects all columns from EMP.Attach the library.

4.2 Create a default layout.

4.3 In the Before Report trigger, initialize the the package byincluding the following:

GLOBAL.NUMGLOB := 0;

4.4 In the group filter for G_EMP, enter the following fuction:

FUNCTION SET_NUM_GLOB RETURN BOOLEAN IS BEGIN IF :SAL > 2500 THEN GLOBAL.INCREMENT; ELSE GLOBAL.DECREMENT; END IF; RETURN(TRUE); END;

4.5 In the format trigger for F_SAL, enter the following function:

FUNCTION PRINT_SAL RETURN BOOLEAN ISBEGIN IF MOD(GLOBAL.NUMGLOB, 10) = 0 THEN RETURN(TRUE); ELSE RETURN(FALSE); END IF; END;

5. As you probably realized, this report could have been built in otherways; it is just an example of how to use a package.

User–CreatedExceptions

Packaged Exceptions


PL/SQL Exceptions

To trap, or isolate, success and failure in your PL/SQL constructs, youuse exceptions. There are two types of exceptions:

• user–created (i.e., those that you create) – 13 – 11

• packaged (i.e., those shipped with Oracle Reports) – 13 – 11

For more information about exception rules, see “Exception Rules” onpage 13 – 14.

You can declare, raise, and handle your own exceptions. For moreinformation on how to do so, see the PL/SQL User’s Guide and Reference.An example exception is:

DECLARE

out_of_stock EXCEPTION;

number_on_hand NUMBER;

BEGIN

...

IF number_on_hand < 1 THEN

RAISE out_of_stock;

END IF;

...

EXCEPTION

WHEN out_of_stock THEN

––handle the error

END;

A packaged exception is a PL/SQL exception that is shipped withOracle Reports. To execute a packaged exception, all you need to do isto write an exception handler for the exception—it will be declared andraised automatically. For more information on how to write anexception handler, see the PL/SQL User’s Guide and Reference.

Oracle Reports is shipped with two sets of packaged exceptions:

• PL/SQL exceptions – 13 – 12

• Oracle Reports exceptions – 13 – 12

PL/SQL Exceptions

Oracle Reports Exceptions


The following exceptions are shipped with PL/SQL Version 1 and aresupported by Oracle Reports:

• DUP_VAL_ON_INDEX • PROGRAM_ERROR

• INVALID_CURSOR • STORAGE_ERROR

• INVALID_NUMBER • TIMEOUT_ON_RESOURCE

• LOGIN_DENIED • TOO_MANY_ROWS

• NO_DATA_FOUND • VALUE_ERROR

• NOT_LOGGED_IN • ZERO_DIVIDE

• OTHERS

For more information on these exceptions, refer your PL/SQL User’sGuide and Reference.

Note: Notice that the PL/SQL exceptions do not have theSRW. prefix. If you were to add the SRW. prefix, OracleReports would search the SRW package for it, not find it, andthen raise an error. Thus, to use the PROGRAM_ERRORexception, you would type WHEN PROGRAM_ERROR, notWHEN SRW.PROGRAM_ERROR.

The following Oracle Reports exceptions are shipped with OracleReports (notice that they have the SRW. prefix). For more informationon these exceptions, see “Descriptions of Packaged Functions,Procedures, and Exceptions” on page 13 – 41.

Packaged Exception What Raises It

SRW.CONTEXT_FAILURE Oracle Reports, when an Oracle Reports packaged function orprocedure is called from an invalid place.

SRW.DO_SQL_FAILURE Oracle Reports, when the SRW.DO_SQL packaged procedurefails.

SRW.INTEGER_ERROR Oracle Reports, when SRW.MESSAGE or SRW.SET_MAXROWis called with a non–integer.

SRW.MAXROW_INERR Oracle Reports, when it detects an internal error while executing the SRW.SET_MAXROW packaged procedure.

SRW.MAXROW_UNSET Oracle Reports, when the SRW.SET_MAXROW packaged procedure is called after the query’s records have already beenfetched.

SRW.NULL_ARGUMENTS Oracle Reports, when one of its packaged functions or procedures is called with a missing argument.


Packaged Exception What Raises It

SRW.PROGRAM_ABORT Nothing. (To handle this exception, you must first raise it.)

SRW.RUN_REPORT_FAILURE Oracle Reports, when the SRW.RUN_REPORT packaged procedure fails.

SRW.RUN_REPORT_BATCH-NO

Oracle Reports, when the SRW.RUN_REPORT procedure iscalled with a command line string containing BATCH=NO.

SRW.TRUNCATED_VALUE Oracle Reports, when a parameter or column is set with a valuethat is larger than the object’s size.

SRW.UNKNOWN_QUERY Oracle Reports, when the SRW.SET_MAXROW packaged procedure is called with an unknown query.

SRW.UNKNOWN_USER_EXIT Oracle Reports, when the user exit specified for the SRW.USER_EXIT packaged procedure cannot be located.

SRW.USER_EXIT_FAILURE Oracle Reports, when the SRWERB buffer is non–empty. Formore information, see “Raising Errors from the User Exit” onpage 14 – 9.)

Examples: The following example demonstrates how to use bothOracle Reports and PL/SQL packaged exceptions. (The bold codesegments make up the exception handlers.) Notice that the exampletests for a packaged procedure failure in the exception handler of thecurrent construct. This practice is required. If you raise an exceptionbut do not handle it, Oracle Reports will handle it for you.

Exception Rules


1. Assume you call a user exit from the SAL column. To ensure thatthe user exit is successful, you could write your code as follows:

–– AN EXAMPLE OF USING PACKAGED EXCEPTIONS –– FUNCTION CHANGE_VALUE RETURN NUMBER IS BEGIN srw.reference(:sal); srw.user_exit(’myexit sal’); RETURN (:SAL); END; EXCEPTION when SRW.UNKNOWN_USER_EXIT then /* user exit not linked into executable */ srw.message(1, ’MYEXIT user exit is unknown.’); srw.program_abort; when SRW.USER_EXIT_FAILURE then /* user exit failed somehow */ srw.message(2, ’MYEXIT user exit failed.’); srw.program_abort; when OTHERS then /* any other error */ srw.message(3, ’Something is very wrong!’); end;

1. If you do not handle an exception, Oracle Reports will handle it foryou: at the time at which the exception is raised, Oracle Reportswill raise an error and halt report execution.

2. You must test for failure of a construct in the current PL/SQL field.For example, suppose you write PL/SQL for a column formula.That formula must test for its own failure; another object—evenanother formula—cannot test for its failure.


PL/SQL in Oracle Reports

You can use PL/SQL in a number of ways within Oracle Reports:

• external libraries – 13 – 16 • formulas – 13 – 25

• attached libraries – 13 – 16 • validation triggers – 13 – 27

• report triggers – 13 – 17 • format triggers – 13 – 28

• local program units – 13 – 22 • action triggers – 13 – 32

• group filters – 13 – 23

The table below shows the different places in Oracle Reports where youcan use PL/SQL and the type of PL/SQL that is valid there.

Object/Module Valid PL/SQLProgram Units

Location of PL/SQL inthe Object Navigator

external PL/SQL library packages, pro-cedures, andfunctions

Libraries node

attached library packages, pro-cedures, andfunctions

Attached Librariesnode (you cannot editthe PL/SQL here)

report triggers functions Report Triggers node

report program units packages, pro-cedures, andfunctions

Program Units node

group functions PL/SQL icon of group

column functions PL/SQL icon of col-umn

parameter functions PL/SQL icon of pa-rameter

frame functions PL/SQL icon of frame

repeating frame functions PL/SQL icon of re-peating frame

field functions PL/SQL icon of field

boilerplate functions PL/SQL icon of boiler-plate

button procedures andfunctions

PL/SQL icon of buttonobject

External PL/SQLLibraries

Attached Libraries


External PL/SQL libraries are sets of PL/SQL procedures, functions,and packages that are independent of a report definition. By attachingan external library to a report (or another module, e.g., a form), you canreference its contents any number of times. This eliminates the need tore–enter the same PL/SQL for each application. For more informationon attaching external PL/SQL libraries to your report, see “AttachedLibraries” on page 13 – 16.

You can access external PL/SQL libraries via theObject Navigator (File—>New—>ExternalPL/SQL Library or File—>Open).

Function is used to return a single value.

Package Body is used to define a program unit thatis part of a package.

Package Spec is used to define which program unitsmake up the package that you want to include inyour library. Packages are used to providemodularity, added functionality, and betterperformance. For more information, see“Packages” on page 13 – 8. For example, you cancreate a global variable in a package spec.

Procedure is used to perform an action withoutreturning a value.

Attached libraries is a list of external PL/SQL libraries that you want toassociate with a report or another external library. When an externallibrary is attached, you can reference its packages, functions, andprocedures from within your report. For more information aboutexternal PL/SQL libraries, see “External PL/SQL Libraries” on page13 – 16.

You can attach or detach libraries via the ObjectNavigator. For more information, see “ReferenceExternal PL/SQL Libraries In a Report” in Chapter8 of Building Reports Manual.

If a path is not prefixed to the filename, OracleReports uses its file path search order to find thefile. For more information about file path searchorder, see “File Searching Method” on page 18 – 9.Libraries stored in the database have DB: prefixedto them.

Access:

Options:

Access:

Report Triggers


Rules:

1. If Oracle Reports cannot find a library that you specify in theAttached Libraries list, a warning will be raised when you acceptthe dialog box, save the report, or open the report. If you try to runthe report or compile the PL/SQL in it, an error will be raised.

2. The Attached Libraries list is saved. The next time you open thereport or library the list will have the same contents it did whenyou last saved the report.

3. If an external library references another library, you must attachboth libraries to the report even if the first library already has thesecond one attached.

Report triggers enable you to execute PL/SQL functions at specifictimes during the execution and formatting of your report.

Using the conditional processing capabilities of PL/SQL for thesetriggers, you can do things such as customizing the formatting of yourreport, performing initialization tasks, and accessing the database. Tocreate or modify a report trigger, you select Triggers from the Toolsmenu.

Which Trigger to Use As a general rule, any processing that will effectthe data retrieved by the report should be performed in the BeforeForm or After Form triggers. (These are the two report triggers thatfire before anything is parsed or fetched.) Any processing that will noteffect the data retrieved by the report can be performed in the othertriggers. For more information on the order of events when executing areport, look at ”Rules” below.

Oracle Reports has five global report triggers. You cannot create newglobal report triggers. The trigger names indicate at what point thetrigger fires:

Fires before the report is executed but after queriesare parsed and data is fetched.

Fires after you exit the Previewer, or after reportoutput is sent to a specified destination, such as afile, a printer, or an Oracle*Mail userid. Thistrigger can be used to clean up any initialprocessing that was done, such as deleting tables.Note, however, that this trigger always fires,whether or not your report completed successfully.

Before Report

After Report


Fires before each page of the report is formatted,except the very first page. This trigger can be usedfor customized page formatting.

Note: In the Previewer, this trigger only fires thefirst time that you go to a page. If yousubsequently return to the page, the trigger doesnot fire again.

Fires before the Runtime Parameter Form isdisplayed. From this trigger, you can access andchange the values of parameters, PL/SQL globalvariables, and report–level columns.

Note: If the Runtime Parameter Form issuppressed, this trigger still fires. Consequently,you can use this trigger for validation of commandline parameters.

Fires after the Runtime Parameter Form isdisplayed. From this trigger, you can accessparameters and check their values. This triggercan also be used to change parameter values or, ifan error occurs, return to the Runtime ParameterForm. Columns from the data model are notaccessible from this trigger.

Note: If the Runtime Parameter Form issuppressed, the After Form trigger still fires.Consequently, you can use this trigger forvalidation of command line parameters or otherdata.

You can access report triggers via the ObjectNavigator or the Program Unit editor. For moreinformation about creating and deleting PL/SQLfor report triggers, see “Working with ReportTriggers” in Chapter 8 of Building Reports Manual.

PL/SQL functions are used to return a single value.The function or anonymous function must return aboolean value (TRUE or FALSE).

Oracle Reports’ packaged functions, procedures, andexceptions can be referenced in any PL/SQLconstruct you enter here. For more information,see “The Oracle Reports Package: SRW” on page13 – 41.

Between Pages

Before Form

After Form

Access:

Options:


Report triggers must explicitly return TRUE or FALSE. The followingtable describes what happens if a report trigger returns FALSE:

Report Trigger What Happens If Trigger Returns False

Before Report Displays an error message and then returns to thel h h h

p p y gplace from which you ran the report.

After Report Does not affect formatting because the report isdone. You can raise a message, though, to indi-cate that the report did not run correctly. For ex-ample, you could put the system time in a vari-able in the Before Report trigger and thencompare it against the system time in the AfterReport trigger. If the report took longer than acertain time to run, you could raise an error.

Between Page Displays an error message when you try to go toBetween Page Displays an error message when you try to go tothe page for which the trigger returned FALSE.the page for which the trigger returned FALSE.The pages subsequent to the page that returnedFALSE f d N t If h i

p g q p gFALSE are not formatted. Note: If the trigger

t FALSE th l t thi hgg

returns FALSE on the last page, nothing happensbecause the report is done formatting Thebecause the report is done formatting. The Between Page trigger does not fire before the firstBetween Page trigger does not fire before the firstpage. If the trigger returns FALSE on the firstpage. If the trigger returns FALSE on the firstpage, the first page is displayed, but, if you try topage, the first page is displayed, but, if you try togo to the second page, an error message is go to the second page, an error message is displayed.

Before Form Displays an error message and then returns to thel h h h

p y gplace from which you ran the report.

After Form Returns to the Runtime Parameter Form. If theForm is suppressed, then returns to place fromwhich you ran the report.

Rules:

1. The list below shows the order of events when a report is executed.















2. If you are sending your report output to the Previewer, you shouldnote that some or all of the report triggers may be fired before yousee the report output. For example, suppose that you useSRW.MESSAGE to issue a message in the Between Page triggerwhen a condition is met. If there are forward references in thereport (e.g., a total number of pages displayed before the last page),Oracle Reports may have to format ahead to compute the forwardreferences. Hence, even though you have not yet seen a page, itmay already have been formatted and the trigger fired.


3. In report triggers, you can read the values of Oracle Reportscolumns and parameters of the correct frequency (look at the rulebelow). For example, you can use the value of a parameter calledCOUNT1 in a condition (e.g., IF :COUNT1 = 10 ). In the Before andAfter Form, and Before and After Report triggers, you can also setthe values of report–level placeholder columns or parameters (e.g.,give them a value in an assignment statement, :COUNT1 = 15 ). Inthe Between Page trigger, you cannot set the values of any datamodel objects. Note also that the use of PL/SQL global variablesto indirectly set the values of columns or parameters is notrecommended. If you do this, you may get unpredictable results.

4. In report triggers, you can only reference report–level columns orparameters. In addition, you cannot reference any page–dependentcolumns (i.e., Reset At of Page) or columns that rely onpage–dependent columns.

5. If you run a report from Oracle Reports Runtime (i.e., not thecommand line or SRW.RUN_REPORT), you should commitdatabase changes you make in the Before Form, After Form, andValidation triggers before the report runs. When running in thisway, these triggers will share the parent process’ databaseconnection. When the report is actually executed, however, it willestablish it’s own database connection.

6. A lexical reference cannot be used to create additional bindvariables after the After Form trigger fires. For example, supposeyou have a query like the following (note that the WHERE clause isreplaced by a lexical reference):

SELECT ENAME, SAL FROM EMP

&where_clause

If the value of the WHERE_CLAUSE parameter contains areference to a bind variable, you must specify the value in the AfterForm trigger or earlier. You would get an error if you supplied thefollowing value for the parameter in the Before Report trigger:

WHERE SAL = :new_bind

If you supplied this same value in the After Form trigger, the reportwould run.

Report Program Units


Report program units are packages, functions, or procedures that youcan reference from any PL/SQL within the current report.

Note: Report program units cannot be referenced from othermodules. If you want to create a package, function, orprocedure that can be referenced from multiple modules, createan external PL/SQL library. For more information aboutexternal PL/SQL libraries, see “External PL/SQL Libraries” onpage 13 – 16.

You can access report program units via the ObjectNavigator or the Program Unit editor. For moreinformation about how to create and deletereport–level PL/SQL, see “Working with PL/SQL”in Chapter 8 of Building Reports Manual.

PL/SQL packages are used to provide modularity,added functionality, and better performance. Formore information, see “Packages” on page 13 – 8.For example, you can create a global variable in apackage spec.

PL/SQL functions are used to return a single value.

PL/SQL procedures are used to perform an actionwithout returning a value.


Examples:

Suppose that you have a report with the following groups andcolumns:

Groups Columns Summary

RGN REGION

RGNSUMSAL SUM(DEPTSUMSAL)

COSTOFLIVING

DEPT DNAME

DEPTNO

DEPTSUMSAL SUM(EMP.SAL)

JOB JOB

HEADCOUNT COUNT(EMP.EMPNO)

Access:

Options:

Group Filters


Groups SummaryColumns

EMP ENAME

EMPNO

SAL

COMM

Given these groups and columns, you might create multiple formulasthat apply the cost of living factor (COSTOFLIVING) to salaries. Toavoid duplication of effort, you could create the following PL/SQLfunction and reference it from the formulas:

function CompSal(salary number) return number

is

begin

return (salary*CostofLiving);

end;

Following are some examples of how you might reference the PL/SQLfunction in formulas:

CompSal(:RGNSUMSAL)

or

CompSal(:SAL) + COMM

Rules:

1. If you delete a PL/SQL package, function, or procedure, you mustalso delete all references to it in your report. Otherwise, you willget an error when you compile, generate, or run the report.

2. PL/SQL package, function, and procedure names must be uniquewithin the report and may not duplicate the names of any columns,groups, queries, or printable objects, such as repeating frames,frames, fields, and boilerplate.

Group filters are PL/SQL functions that determine which records toinclude in a group, if Filter is Condition. A PL/SQL function is requiredfor any group with a Filter of Condition.

You can access PL/SQL for group filters via theObject Navigator, the Program Unit editor, or theGroup property sheet (i.e., the Edit button). Formore information about how to create and deletereport–level PL/SQL, see “Working with PL/SQL”in Chapter 8 of Building Reports Manual.

Access:


PL/SQL functions or anonymous function bodies areused to return a single value. The function oranonymous function, must return a boolean value(TRUE or FALSE). TRUE means that the recordwill be included and FALSE means it will not beincluded.


Examples:

1. Suppose that you want to display data for salespeople whosecommissions exceed $100. Following is a sample filter for this:

function filter_comm return boolean is begin if :comm IS NOT NULL then if :comm < 100 then return (FALSE); else return (TRUE); end if; else return (FALSE); –– for rows with NULL commissions end if; end;

Rules:

1. Group filters cannot be added to groups if Filter is First, Last, or NoFilter.

2. Group filters cannot be added to cross–product groups.

3. In a group filters, you can read the values of Oracle Reportscolumns and parameters of the correct frequency (look at the rulebelow), but you cannot directly set their values. For example, youcan use the value of a parameter called COUNT1 in a condition(e.g., IF :COUNT1 = 10), but you cannot directly set its value in anassignment statement ( e.g., :COUNT1 = 10). Note also that theuse of PL/SQL global variables to indirectly set the values ofcolumns or parameters is not supported. If you do this, you mayget unpredictable results.

You also cannot reference any page–dependent columns (i.e., ResetAt of Page) or columns that rely on page–dependent columns in agroup filter.

Options:

Formulas


4. The function that you enter for a group filter can only depend uponthe following columns:

• a database column owned by the group’s query or a query aboveit in the data model hierarchy

• computed columns (formulas or summaries) that depend onunrelated queries (i.e., computed columns that do not dependupon columns in the group, the group’s ancestors, or the group’sdescendants)

Formulas are PL/SQL functions that populate columns of TypeFormula. A PL/SQL function is required for any column of TypeFormula.

You can access the PL/SQL for formulas via theObject Navigator, the Program Unit editor, or theColumn property sheet (i.e., the Formula button).

PL/SQL functions are used to return a single value.A column of Datatype Number can only have aFormula that returns a value of datatypeNUMBER. A column of Datatype Date can onlyhave a Formula that returns a value of datatypeDATE. A column of Datatype Character can onlyhave a Formula that returns a value of datatypeCHARACTER, VARCHAR, or VARCHAR2.

Oracle Reports’ packaged functions, procedures, andexceptions can be referenced in the PL/SQLfunction you enter here for the formula. For moreinformation, see “The Oracle Reports Package:SRW” on page 13 – 41.

Examples:

1. Below is a valid function for a formula.

function salcomm return NUMBER is begin return(:sal + :comm); end;

This formula adds the salary and commission paid to eachemployee.

Access:

Options:


2. If you are creating a formula in which a value may be null, it isusually best to use a function rather than an expression. In afunction, you can perform your calculations conditionally. Below isa function that you might enter in Formula which checks a valueprior to performing the calculation:

function calcomm return NUMBER is temp number; begin if :comm IS NOT NULL then temp := :sal + :comm; else temp := :sal; end if; return (temp); end;

Rules:

1. In a Formula, you can read and assign values to the column itself,placeholder columns, and parameters of the correct frequency (lookat the rule below). For example, you can use the value of a columncalled COMP in a condition (e.g., IF :COMP = 10 ) and you candirectly set its value in an assignment statement (e.g., :COMP :=

15).

2. A formula can only make reference to columns that are in the sameor a higher group in the group hierarchy. For example, a formulafor a report–level column can only reference other report–levelcolumns.

3. Formulas are calculated such that any column referenced in theformula will be calculated first. To do so, Oracle Reports builds adependency list, to guarantee proper ordering of calculations.Note that circular dependencies, in which a column referencesanother column which in turn references the first column, eitherdirectly or indirectly, are not allowed.

4. A user exit may only change the value of a column that has a Typeof Placeholder.

Validation Triggers


5. When using SRW.DO_SQL, we recommend that you do not readdatabase values that are updated or inserted in the same report.There is no guarantee of the exact time Oracle Reports will fetchrecords from the database for formatting the output. OracleReports does internal ”data look–ahead” to optimize performance.Thus, a particular record might already have been accessed beforean update is issued to the same record. Oracle Reports buildsinternal dependency lists which guarantee that events, such asinvocation of user exits, calculation of summaries, etc., happen inthe correct order. However, Oracle Reports cannot guarantee theseevents will be synchronized with its internal data access or with theformatting of data.

Validation Triggers are PL/SQL functions that are executed whenparameter values are specified on the command line and when youaccept the Runtime Parameter Form. (Notice that this means eachValidation Trigger may fire twice when you execute the report.)Validation Triggers are also used to validate the Initial Value of theparameter in the Parameter property sheet.

You can access the PL/SQL for validation triggersvia the Object Navigator, the Program Unit editor,or the Parameter property sheet (i.e., the Editbutton).

PL/SQL functions are used to return a single value.The function or anonymous function, must return aboolean value (TRUE or FALSE). TRUE meansthat the parameter is valid, and FALSE means it isnot valid and an error is raised. When theValidation Trigger returns FALSE, the user isreturned to parameter value in the RuntimeParameter Form where they can either change it orcancel the Runtime Parameter Form.


Rules:

1. The PL/SQL in a Validation Trigger can be a maximum of 32Kcharacters. The upward limit may vary between operatingsystems.

Access:

Options:

Format Triggers


2. In a Validation Trigger, you can read and assign values to OracleReports parameters. You cannot read or assign values to columns.For example, you can use the value of a parameter called COUNT1in a condition (e.g., IF :COUNT1 = 10 ) and you can directly set itsvalue in an assignment statement (e.g., :COUNT1 = 15 ).

Note also that the use of PL/SQL global variables to indirectly setthe values of columns is not supported. If you do this, you may getunpredictable results.

3. For reports that are spawned processes of other reports (e.g., runwith BACKGROUND=YES), you should commit database changesyou make in the Before Form, After Form, and Validation triggersbefore the report runs. Spawned processes use their parentprocess’ database connection for the Before Form, After Form, andValidation triggers. When the spawned process runs the report,though, it establishes its own database connection. Any databasechanges not committed by the time the child report runs willtherefore be lost. For more information about when new processesare spawned, see “BACKGROUND” on page 1 – 31.

Format Triggers are PL/SQL functions executed before the object isformatted. The trigger can be used to dynamically change theformatting attributes of the object.

You can access the PL/SQL for Format Triggers viathe Object Navigator, the PL/SQL Program Uniteditor, or the layout object property sheet (i.e., theFormat Trigger button).

PL/SQL functions are used to return a single value.The function must return a boolean value (TRUE orFALSE). TRUE means that the object will beformatted and FALSE means it will not beformatted.


Examples:

1. Suppose that you are building a banking report and would like it toindicate if a customer is overdrawn. To do so, you give therepeating frame around the customer information a Format Triggerthat causes it to have a border only if a customer’s account balanceis less than 0 (or the required minimum balance).

Access:

Options:


The Format Trigger might look something like the following:

function my_formtrig return BOOLEAN isbegin if :bal < 0 then srw.attr.mask := SRW.BORDERWIDTH_ATTR; srw.attr.borderwidth := 1; srw.set_attr (0, srw.attr); end if; return (true); end;

2. Suppose that you are building a master/detail report and, if nodetail records are retrieved for a master record, you do not wantthe boilerplate labels to appear. To do this, you first create asummary column called MYCOUNT with a Function of Count inthe source group of the master repeating frame. In the FormatTrigger for the group frame that surrounds the detail repeatingframe and its labels, you enter the following:

function my_formtrig return BOOLEAN isbegin if :mycount = 0 then return (false); else return (true); end if; end;

3. Suppose that you are building a salary report and you only want tosee salaries above $2500. In the report summary of all salaries,however, you want all salaries to be included. To do this, youcreate a data model for the report without restricting the recordsretrieved. Then, you enter the following Format Trigger for therepeating frame:

function my_formtrig return BOOLEAN isbegin if :sal > 2500 then return (true); else return (false); end if;end;

The report output will only show salaries greater than $2500, butthe summary that calculates the sum of all salaries will include allthe salaries retrieved from the database.


4. Suppose that you want to create a comma–separated list for thenames of employees. First, you create a field inside a repeatingframe with a Print Direction of Across. Next to the field, you createa boilerplate text object that contains a comma followed by a space.To ensure that the comma does not appear after the last name inthe list, enter the following Format Trigger for the boilerplateobject:

function my_formtrig return BOOLEAN isbegin if :ename <> :lastname then return (true); else return (false); end if;end;

LASTNAME is a summary column with a Source of ENAME, aFunction of Last, and Reset At of Report.

Rules:

Caution: The PL/SQL in a Format Trigger is executed each time thatOracle Reports attempts to format the layout object. As a result, formattriggers should only contain PL/SQL program units that set formattingattributes (e.g., color and highlighting). You should not perform otheractions, such as inserting data in a table, because you cannot predictwhen or how many times the trigger will fire. For example, if you havePage Protect checked for an object, the object might not be formattedon the logical page where the trigger is fired. In addition, the triggermay be executed more than once.

1. Comments inserted directly into the PL/SQL code must use thePL/SQL comment delimiters.

2. In a Format Trigger, you can read the values of Oracle Reportscolumns and parameters of the correct frequency (look at the rulebelow), but you cannot directly set their values. For example, youcan use the value of a parameter called COUNT1 in a condition(e.g., IF :COUNT1 = 10 ), but you cannot directly set its value in anassignment statement (e.g., :COUNT1 = 10). (This restriction alsoapplies to user exits called from the Format Trigger.)

Note also that the use of PL/SQL global variables to indirectly setthe values of columns or parameters is not supported. If you dothis, you may get unpredictable results.


3. You cannot reference columns or variables in the Format Trigger ofan object that have a different frequency than the object. Forexample, if you create a master/detail report, the parent group’srepeating frame cannot have a Format Trigger that relies on a valuein the child group. For each parent, there may be multiple children.Therefore, at the parent record level, Oracle Reports cannotdetermine which of the child records to use.

You also cannot reference any page–dependent columns (i.e., ResetAt of Page) or columns that rely on page–dependent columns in aFormat Trigger. The reason for this is that it would result in acircular dependency. That is, the value of a page–dependentcolumn cannot be computed until the report is formatted, but thereport cannot be formatted until the Format Trigger is executed.

4. If a Format Trigger returns false and the object does not format, thiscan cause other objects not to print. For example, if a repeatingframe does not format, any objects (fields, boilerplate, frames, orother repeating frames) it encloses would not format either.

5. For repeating frames, the Format Trigger is executed for eachinstance of the repeating frame. To create a Format Trigger thatacts upon all instances of a repeating frame at once, create a framearound the repeating frame and enter a Format Trigger for theframe. If the Format Trigger returns FALSE for every instance of arepeating frame on a logical page, the repeating frame will occupyno space on the logical page and anchors to other objects willcollapse (if specified).

6. The PL/SQL in a Format Trigger must return consistent results forthe same object. For example, say you have a frame whose FormatTrigger returns FALSE when a certain condition is met. If theframe spans two pages, the Format Trigger actually fires twice(once for each page on which the frame formats). The condition inyour PL/SQL must return the same result both times the FormatTrigger fires. Otherwise, only part of the frame will be formatted(e.g., the part of the frame on the first page formats, but the part onthe second page does not).

7. If the Format Trigger on a repeating frame in a matrix reportreturns FALSE, an entire row or column of the matrix will notformat. For example, if an instance of the across dimensionrepeating frame does not format, the entire column will not formatin the matrix.

8. If you want to conditionally change the cell of a matrix, you shouldput a frame around the field inside the matrix and use the FormatTrigger for the frame.

Action Triggers

Bind References


Action Triggers are PL/SQL procedures executed when a button isselected in the Previewer. The trigger can be used to dynamically callanother report (drill down) or execute any other PL/SQL.

You can access the PL/SQL for Action Triggers viathe Object Navigator, the PL/SQL Program Uniteditor, or the button object property sheet.

PL/SQL procedures are used to perform an actionwithout returning a value.


Oracle Reports References in PL/SQL

In a PL/SQL construct, you can refer to Oracle Reports objects in twoways:

• as a bind variable reference – 13 – 32

• as a literal reference – 13 – 33

You use a bind variable reference to refer to the value of an OracleReports object. All bind variable references are prefixed with a colon.

Examples:

1. To make the value of the EMPNO column equal to 100, type:

:EMPNO := 100;

2. To add column COL1 to a user exit dependency list, type:

SRW.REFERENCE(:COL1);

Note: Only SRW.REFERENCE and SRW.MESSAGE requirebind references when referencing an object name.

Access:

Options:

Literal References


You use a literal reference to refer to the name of an Oracle Reportsobject. All literal references must be enclosed in single quotes.

Examples:

1. To put the F_EMPNO field name into a PL/SQL variable namedFIELDNAME, type:

FIELDNAME := ’F_EMPNO’;

2. To modify the number of records being fetched for the Q_EMPquery, type:

SRW.SET_MAXROW(’Q_EMP’, 0);

Caution: If you change the name, datatype, or width of an OracleReports object, you must ensure that any references to it within yourPL/SQL program units are still valid. For example, if the datatype of acolumn changes, you need to make sure that any calculations that usethe column are still correct.

PL/SQL Restrictions within Oracle Reports

1. Oracle Reports supports PL/SQL Version 1.1 on the client side andPL/SQL Version 2.0 on the server side. You can move a programunit from the client to the server side without restriction. If youmove a program unit from the server to the client, though, youmust ensure that it makes no Version 2.0 specific calls. OracleReports’ PL/SQL Version 1.0 engine supports the following Version2.0 features:

• subprograms

• packages

• the RECORD composite datatype

Program units that use only these Version 2.0 features can bemoved from the server to the client side without restriction.Program units that use other PL/SQL Version 2.0 features cannotbe moved from the server to the client side.

2. You can only use Oracle Reports’ packaged functions, procedures,or exceptions when running PL/SQL within Oracle Reports.

3. When you call an Oracle Reports packaged function, procedure, or exception, you must precede it with:

SRW. ––the period is required


For example:

SRW.USER_EXIT(’my_exit’);

4. When you call user–created packages, you must precede them withthe package name and a period (e.g., MYPACK.MYPROCEDURE;).

5. When referencing a stored procedure from within Oracle Reports,ensure the following:

• The stored procedure has arguments of the supported datatypes(VARCHAR2, NUMBER, DATE, BOOLEAN).

• The stored procedure does not reside in a package that containsa procedure or function with arguments not of the supporteddatatypes (VARCHAR2, NUMBER, DATE, BOOLEAN).

• The stored procedure’s arguments are not declared with a typeof TABLE.COLUMN%TYPE.

• Your System Global Area (SGA) has not become fragmented tothe point where there are no contiguous 32K chunks available.To help avoid this, you can use the KEEP procedure of theDBMS_SHARED_POOL package (available with Version 7.0.15of ORACLE7) to pin the DIUTIL package in memory.

6. When you reference a stored program unit from a report, OracleReports includes a “stub” in the .rdf and .rep files for the report.The stubs decrease startup time when running the report from theOracle Reports Runtime. If you update the stored program units,you should open the report in the Oracle Reports Designer andrecompile it to refresh the stubs. Alternatively, you could useOracle Reports Convert to force a recompilation. Convert thereport using a Destination and Source Type of RDF File.

If you open a Version 2.5 report that has stubs in an earlier versionof Oracle Reports, the stubs will appear as local program units. Topick up changes from the stored program units in this case, youwould need to delete the local program units and then recompilethe report.

7. You can only reference Oracle Reports’ objects in PL/SQL programunits when running PL/SQL within Oracle Reports. WithinORACLE, if you execute or compile PL/SQL that containsreferences to Oracle Reports’ objects, you will receive errors.

8. PL/SQL program units entered directly in Formula, ValidationTrigger, Filter Condition, Formula, or a report trigger cannot takearguments.

The Interpreter

The Program Unit Editor


Oracle Procedure Builder

Most objects in Oracle Reports can have PL/SQL associated with them.Oracle Reports uses Oracle Procedure Builder features andfunctionality to allow you to debug the PL/SQL program units used inyour reports. Oracle Procedure Builder consists of:

• the Interpreter – 13 – 35

• the Program Unit editor – 13 – 35

Rules:

1. You can alter PL/SQL during your debugging session, but youcannot entirely delete PL/SQL unless it is local PL/SQL (i.e., underprogram units in the Object Navigator). For example, you couldnot delete the contents of a formula for a column during reportexecution.

2. You cannot modify the bind references of a program unit.

The Interpreter is the central debugging workspace of Oracle ProcedureBuilder. It is a paned window that enables you to define, display, anddebug your PL/SQL program units. Depending on the context inwhich Oracle Procedure Builder is invoked, the Interpreter can bepresented in two ways:

• modal

• modeless

The modal Interpreter is presented automatically by Oracle Reportswhile executing an application (e.g., during execution Oracle Reportsencounters a breakpoint you have set in a program unit). When themodal Interpreter is displayed, execution of both the application and itsPL/SQL is suspended until you close the modal Interpreter window.

The modeless Interpreter is presented when you manually invokeOracle Procedure Builder by choosing Tools—>Interpreter.

The Program Unit editor in Oracle Reports operates the same way asdescribed in the Oracle Procedure Builder User’s Guide and Reference. Formore information on the Program Unit editor, see the Oracle ProcedureBuilder User’s Guide and Reference. Note, however, that the followingpop–up lists have Oracle Reports–specific contents:

• Type

• Name

• Object


Type: This list indicates what level of program units should bedisplayed in the other lists, Name and Object.

All indicates that you want all the PL/SQLprogram units (local and object–level) displayedunder Name.

Local indicates that you only want report–levelPL/SQL progam units (that are not associated withany one object) displayed under Name.

Object Level indicates that you only want PL/SQLprogram units associated with an object (e.g., thePL/SQL in a Format Trigger for a field) to bedisplayed. If you select Object Level, you can alsoselect from the Object list described above.

Name This list indicates what program unit is currently displayed inthe Program Unit editor. If you are in object–level PL/SQL, this listwill typically contain only one name. The only exception is for buttonobjects.

A valid name for a PL/SQL program unit in thereport.

Button Action indicates that you are editing theprogram unit for a button object’s action. Thisoption applies only to button objects.

Format Trigger indicates that you are editing theprogram unit for a button object’s Format Trigger.This option applies only to button objects.

Object: If you select Object Level for Type, this list indicates what kindof objects should be displayed in the list of objects to its right.

All indicates that you want the names of all theobjects in the report to be included in the list to theright.

Type of object (e.g., repeating frames or fields) indicatesthat you want only the names of that type of objectto appear in the list to the right.

Options:

Options:

Options:

Compiling SingleProgram Units

Batch–compilingProgram Units


PL/SQL Compilation

After you write one or more PL/SQL program units for a report, or alibrary, you must first compile the PL/SQL before you can run it. Thecompiler detects syntax errors, semantic errors, and references tonon–existent objects, procedures, or functions.

There are two ways to compile PL/SQL:

• one program unit at a time – 13 – 37

• all or only uncompiled program units – 13 – 37

For more information about compilation error syntax, see “CompilerError Syntax” on page 13 – 38.

Note: You can disable the PL/SQL compiler while you aredesigning a report. To do so, edit your preferences (i.e., checkDisable Trigger Compilation in the Preferences dialog box).

To compile a specific construct, display the construct by opening theproperty sheet or Program Unit editor, then select the Compile button.

If no errors are detected, Oracle Reports displays a dialog box thatstates ”Compile Complete.” If errors are detected, Oracle Reportsdisplays the Program Unit editor: the construct’s text appears in theSource field, and its errors are displayed in the Message field, with thefirst error highlighted.

For more information on the Program Unit editor, see the OracleProcedure Builder User’s Guide and Reference.

Rules:

1. A program unit must be compiled before any reference to it iscompiled. For example, if FORMULA1 references FORMULA2,you must compile FORMULA2 before compiling FORMULA1.

Below are the ways you can compile all of a report’s PL/SQL programunits simultaneously:

• while designing a report, select File—>Compile (this compilesthe uncompiled PL/SQL)

• while designing a report, select File—>Compile All (thiscompiles all of the PL/SQL)

Compiler Error Syntax


If no errors are detected, Oracle Reports displays a dialog box thatstates ”Compile Complete.” If errors are detected, Oracle Reportsdisplays the Program Unit editor: the Message field occupies the entireeditor, and it contains all construct errors, with the first errorhighlighted.

For more information on how to navigate in the Program Unit editor,see “The Program Unit Editor” on page 13 – 35.

As Oracle Reports compiles each construct, it displays compilationerror messages one at a time. These messages take the following form:

Compiling object_name object_type on owner_name

owner_type . . .

Error error_num at line line_num, column col_num:

error_text

where:

Is the unambiguous name of the PL/SQL constructthat Oracle Reports is compiling.

Is ”construct,” or ”construct spec.”

Is the unambiguous name of the Oracle Reportsobject to which the PL/SQL construct is attached.

Is the type of Oracle Reports object to which thePL/SQL was assigned.

Is the documented error number.

Is the line number of the PL/SQL construct wherethe error occurred. This is the line number withinthe PL/SQL field.

Is the column number of the PL/SQL structurewhere the error occurred. This is the columnnumber within the PL/SQL field.

Is a complete description of the error.

For example, your screen might display the following message:

Compiling COMPUTE column on ORDER_ENTRY report . . .

Error 313 at line 1, column 4:

’COMMIT_REPORT’ not declared in this scope

For more information on the PL/SQL error messages, see theORACLE7 Server Messages and Codes Manual.

object_name

object_type

owner_name

owner_type

error_num

line_num

col_num

error_text


Oracle Procedure Builder Packages

In addition to the Oracle Reports built-in PL/SQL functions, andprocedures, Oracle Procedure Builder provides the following built-inPL/SQL packages that contain many PL/SQL constructs you canreference while debugging your program units:

Provides Dynamic Data Exchange support withinDeveloper/2000.

Provides procedures, functions, and exceptions fordebugging PL/SQL program units.

Provides procedures, functions, and exceptionsyou can use to create and maintain lists ofcharacter strings (VARCHAR2). This provides ameans of creating arrays in PL/SQL Version 1.

Provides a PL/SQL API for creating, manipulatingand accessing attributes of OLE2 AutomationObjects.

Provides a public interface for calling out toforeign(C) functions from PL/SQL.

Enables you to extract high-level information aboutyour current language environment.

Provides procedures, functions, and exceptionsyou can use for tuning your PL/SQL programunits (i.e. examining how much time a specificpiece of code takes to run).

Provides constructs that allow you to read andwrite information from and to files.

Allows you to interact with Oracle environmentvariables.

Allows you to access and manipulate the errorstack created by other built-in packages such asDEBUG.

Provides you with a means of extracting stringresources from a resource file with the goal ofmaking PL/SQL code more portable by isolatingall textual data in the resource file.

For more information on the Program Unit editor, see the OracleProcedure Builder User’s Guide and Reference.

DDE

DEBUG

LIST

OLE2

ORA_FFI

ORA_NLS

ORA_PROF

TEXT_IO

TOOL_ENV

TOOL_ERR

TOOL_RES

CDE_MM.GET_REF

Syntax:

Parameters:

Description:


The Developer/2000 PL/SQL Package: CDE_MM

The Developer/2000 package contains the CDE_MM.GET_REFprocedure that you can call from a SELECT statement in ORACLE7,Version 7.1.

CDE_MM.GET_REF specifies that you always want Oracle Reports togo to the database to get a column’s value (i.e., the column’s values willnot be cached on the client side).

Type: Procedure

CDE_MM.GET_REF (’ table_name ’, ’ col_name ’, tablename.rowid );

Is the name of the table that contains the column youwant to retrieve from the database.

Is the name of a LONG, LONG RAW, or RAW columnthat you want to retrieve from the database.

Is the ROWID of the column that you want to retrievefrom the database.

This procedure can be called in your SELECT statement to indicate thatthe specified column’s values should always be retrieved from thedatabase. The values of the specified column will not be cached on theclient. This behavior is useful if you are running a report with manyimages or sounds that would require more space to cache than theclient has available.

Warning: Always referencing the database for the column’svalues will slow performance. As a result, this procedureshould only be used when the report has so many images orsounds that it would be impractical to cache them on the client.

Rules:

1. Lexical references can be used for the column name you pass toCDE_MM.GET_REF. Note, however, that the datatype of thecolumn cannot change dynamically at runtime. If the columndefinition in the report is expecting one datatype and it receives avalue of a different datatype, an error will occur.

table_name

col_name

tablename.rowid

SRW.BREAK

Syntax:


The Oracle Reports PL/SQL Package: SRW

To save you time, Oracle Reports is shipped with a package—i.e., acollection of PL/SQL constructs—that contains many functions,procedures, and exceptions you can reference in any of your libraries orreports. The name of Oracle Reports’ package is SRW. As a result, anytime you reference a construct in the SRW package, you must prefix itwith SRW, for example, SRW.DO_SQL. The Oracle Reports Packagecontains the following:

• SRW.BREAK • SRW.RUN_REPORT_BATCHNO

• SRW.CONTEXT_ FAILURE • SRW.SET_FIELD_CHAR

• SRW.DO_SQL • SRW.SET_FIELD_DATE

• SRW.DO_SQL_FAILURE • SRW.SET_FIELD_NUM

• SRW.GETERR_RUN • SRW.SET_MAXROW

• SRW.GET_PAGE_NUM • SRW.TRACE_ADD_OPTION

• SRW.INTEGER_ERROR • SRW.TRACE_END

• SRW.MAXROW_INERR • SRW.TRACE_REM_OPTION

• SRW.MAXROW_UNSET • SRW.TRACE_START

• SRW.MESSAGE • SRW.TRUNCATED_VALUE

• SRW.NULL_ARGUMENTS • SRW.UNKNOWN_QUERY

• SRW.PROGRAM_ABORT • SRW.UNKNOWN_USER_EXIT

• SRW.REFERENCE • SRW.USER_EXIT

• SRW.RUN_REPORT • SRW.USER_EXIT20

• SRW.SET_ATTR • SRW.USER_EXIT_FAILURE

• SRW.RUN_REPORT_FAILURE

Note: You cannot reference constructs in the SRW packagefrom another product, e.g., from SQL*Plus.

Constructs found in a package are commonly referred to as”packaged”; i.e., packaged functions, packaged procedures, andpackaged exceptions.

SRW.BREAK stops report execution. You can now use OracleProcedure Builder to perform debugging in Oracle Reports.

Type: Procedure

SRW.BREAK;

Description:

SRW.CONTEXT_FAILURE

Syntax:

Description:


This procedure temporarily stops report execution at the place at whichSRW.BREAK was encountered, and displays (read–only) the currentvalues of all columns and parameters. Report execution resumes whenthe read–only screen is accepted.

Rules:

1. This procedure is not meaningful in a Before Form or After Formtrigger, because data for the report is not fetched until the BeforeReport trigger (which fires after the After Form trigger).

2. All column and parameter values are displayed in the read–onlyscreen. No PL/SQL variables, nor any other object values aredisplayed.

SRW.CONTEXT_FAILURE stops report execution when a program unitis run from the wrong context.

Type: Exception

SRW.CONTEXT_FAILURE;

This exception stops the report execution and raises the following errormessage:

REP–1426: Running <construct_name> from incorrect context.

What Raises It: Oracle Reports, when an Oracle Reports packagedfunction or procedure is called in the wrong context (see the chartbelow).

In this chart, NO means that the function or procedure cannot be calledin that context; YES means it can.

NAME PARAM FORM DATA MODEL FORMAT TRIG REPORT TRIG

srw.break NO YES YES NO

srw.do_sql YES YES YES YES

srw.geterr_run YES YES YES YES

srw.get_page_num NO NO YES NO

srw.message YES YES YES YES

srw.reference YES YES YES YES

srw.run_report YES YES YES YES

srw.set_attr NO NO YES NO

srw.set_field_char NO NO YES NO

srw.set_field_date NO NO YES NO

Examples:

SRW.DO_SQL

Syntax:

Parameters:

Description:


NAME REPORT TRIGFORMAT TRIGDATA MODELPARAM FORM

srw.set_field_num NO NO YES NO

srw.set_maxrow NO YES YES YES

srw.user_exit YES YES YES YES

Suppose you want your own error message raised, instead of thedefault error message (above). You could handle this exception in thefollowing way:

EXCEPTION

when SRW.CONTEXT_FAILURE then

srw.message(4000, ’Contact the Application

Development group regarding SRW.CONTEXT_FAILURE.’);


SRW.DO_SQL executes a specified SQL statement.

Type: Procedure

SRW.DO_SQL (sql_statement CHAR);

Is any valid SQL statement. Remember to precede anyOracle Reports object names with a colon (:).

This procedure executes the specified SQL statement from withinOracle Reports. The SQL statement can be DDL (statements that definedata), or DML (statements that manipulate data). DML statements areusually faster when they are in PL/SQL, instead of in SRW.DO_SQL.

Because you cannot perform DDL statements in PL/SQL, theSRW.DO_SQL packaged procedure is especially useful for performingthem within Oracle Reports, instead of via a user exit. For moreinformation on DDL or DML statements, see the ORACLE7 Server SQLLanguage Reference Manual.

Rules:







sql_statement









Caution: If you specify READONLY, you should avoid DDLaltogether. When you execute a DDL statement (e.g., via SRW.DO_SQLor a user exit), a COMMIT is automatically issued. If you are usingREADONLY, this will prematurely end the transaction begun by SETTRANSACTION READONLY. For more information on READONLY,see “READONLY” on page 1 – 41.

2. A bind variable’s value can be at most 64,000 bytes. (When thevalue exceeds that limit, it will be truncated to the left–most 64,000bytes.)

3. If you use a parameter as the destination of a character column foran INTO clause, you should ensure that the parameter is wideenough to contain the selected values. For example, suppose thatyou have the following SRW.DO_SQL statement:

srw.do_sql(’SELECT ENAME INTO ’||:my_ename||’ FROM EMP’);

Examples:


In this case, the destination parameter (my_ename) needs a widththat is equal to the maximum width of the ENAME column. Thereason for this is that the selected value contains trailing spaces upto the assumed size of the value. If the parameter is not largeenough, you will get a truncation exception. If you are not sureabout the maximum width of the SELECT list item, then youshould use 2000 as the width for the parameter.

The following examples illustrate the use of SRW.DO_SQL.

1. Suppose you want your report to create a table named CHECK justbefore the Runtime Parameter Form is displayed. BecauseCREATE TABLE is a SQL DDL statement (and PL/SQL cannotperform DDL statements), you need to use SRW.DO_SQL.Therefore, your PL/SQL could look like this in the Before Formtrigger:

FUNCTION CREATETAB RETURN BOOLEAN IS BEGIN SRW.DO_SQL(’CREATE TABLE CHECK (EMPNO NUMBER NOT NULL PRIMARY KEY, SAL NUMBER (10,2)) PCTFREE 5 PCTUSED 75’); RETURN(TRUE); EXCEPTION WHEN SRW.DO_SQL_FAILURE THEN SRW.MESSAGE(100, ’ERROR WHILE CREATING CHECK TABLE.’); SRW.MESSAGE(50, ’REPORT WAS STOPPED BEFORE THE RUNTIME PARAMETER FORM.’); RAISE SRW.PROGRAM_ABORT; END;

Additional Information: If you use a table created in this wayfor your report output, the table must exist before you createyour query in the data model. Otherwise, Oracle Reportswould not be able to parse your query.

2. Suppose you want to create a ”table of contents” by getting the firstcharacter of a column’s value, and page number on which its fieldfires to print. Assume that you want to put the ”table of contents”into a table named SHIP. You could write the following construct:

DECLARE PAGE_NO NUMBER; PAGE_FOR INDEX NUMBER; SORT_CHAR CHAR(1); CMD_LINE CHAR(200); BEGIN SORT_CHAR := :SORT_NAME ; IF :CALLED = ’Y’ THEN SRW.GET_PAGE_NUM(PAGE_FOR_INDEX);

SRW.DO_SQL_FAILURE

Syntax:

Description:

See Also:

Examples:


SRW.USER_EXIT(’RWECOP PAGE_FOR_INDEX P_START_PAGENO’); SRW.MESSAGE(2,TO_CHAR(:P_START_PAGENO)); END IF; SRW.GET_PAGE_NUM(PAGE_NO); CMD_LINE := ’INSERT INTO SHIP VALUES (’’’||SORT_CHAR||’’’,’||TO_CHAR(PAGE_NO)||’)’; SRW.MESSAGE(2,CMD_LINE); SRW.DO_SQL(CMD_LINE); COMMIT; EXCEPTION WHEN DUP_VAL_ON_INDEX THEN NULL; WHEN SRW.DO_SQL_FAILURE THEN SRW.MESSAGE(1,’FAILED TO INSERT ROW INTO SHIP TABLE’); WHEN OTHERS THEN COMMIT; END;

SRW.DO_SQL_FAILURE stops report execution when a failure occursin SRW.DO_SQL.

Type: Exception

SRW.DO_SQL_FAILURE;


REP–1425: Error running DO_SQL package – REP–msg ORA–msg

where:

Is an Oracle Reports message.

Is an optional ORACLE message, providing moreinformation on the Oracle Reports message.

What Raises It: Oracle Reports, when the SRW.DO_SQL packagedprocedure fails (e.g., if the user does not have DDL privileges, yet triesto create a table with SRW.DO_SQL).

SRW.DO_SQL


EXCEPTION

when SRW.DO_SQL_FAILURE then

REP–msg

ORA–msg

SRW.GETERR_RUN

Syntax:

Returns:

Description:

Examples:

SRW.GET_PAGE_NUM

Syntax:

Parameters:

Returns:

Description:


srw.message(1000, ’Error occurred while creating

table CHECKS.’);

SRW.GETERR_RUN returns an error message if a failure occurs inSRW.RUN_REPORT.

Type: Function

SRW.GETERR_RUN;

An error message.

This function returns an error message if Oracle Reports detects anerror while running the SRW.RUN_REPORT procedure.

Suppose you are sending parts of a report to users via Oracle*Mail. Formore information, see “SRW.RUN_REPORT” on page 13 – 54. Also,suppose that if SRW.RUN_REPORT fails, you want to display amessage that explains why it failed. Your PL/SQL could look like this:

BEGIN

DECLARE TMP CHAR(100);

begin

srw.run_report(’batch=yes report=send.rdf

destype=file desname=send.lis desformat=dflt’);

exception when srw.run_report_failure then

tmp := srw.geterr_run;

srw.message(1000, tmp);

end;

END;

SRW.GET_PAGE returns the current page number.

Type: Function

SRW.GET_PAGE_NUM (’page_num’);

Is the variable in which you want to place the currentpage number.

The current page number.

This function returns the current page number. This is useful when youwant to use the page number in the field’s Format Trigger.

page_num

Examples:

SRW.INTEGER_ERROR

Syntax:

Description:

Examples:

SRW.MAXROW_INERR


Rules:

1. SRW.GET_PAGE_NUM is only meaningful in a Format Trigger. Ithas no effect when entered in other places.

Suppose you want to perform a computation based upon a pagenumber. In the field’s Format Trigger, you could useSRW.GET_PAGE_NUM function:

BEGIN

DECLARE PAGE_NUM NUMBER;

begin

srw.get_page_num (page_num);

srw.set_field_num (0, page_num + 3);

end;

END;

SRW.INTEGER_ERROR stops report execution when an invalid integerargument is passed.

Type: Exception

SRW.INTEGER_ERROR;

This exception stops the report execution and raises the following errormessage.

REP–1417: Invalid integer argument passed to

<SRW.MESSAGE or SRW.SET_MAXROW>.

What Raises It: Oracle Reports, when SRW.MESSAGE orSRW.SET_MAXROW is called with a non–integer as a result of aninternal error. (If an internal error is not present, PL/SQL will catch thetype mismatch via the PL/SQL exception VALUE_ERROR.)


EXCEPTION

when SRW.INTEGER_ERROR then

srw.message(4000, ’Contact the Application

Development group regarding SRW.INTEGER_ERROR.’);


SRW.MAXROW_INERR stops report execution when a failure occurs inSRW.SET_MAXROW.

Type: Exception

Syntax:

Description:

See Also:

Examples:

SRW.MAXROW_UNSET

Syntax:

Description:

See Also:


SRW.MAXROW_INERR;

This exception stops the report execution and raises the following errormessage.

REP–1424: Internal error while executing SRW.SET_MAXROW.

If it is raised, you should contact Oracle’s customer support.

What Raises It: Oracle Reports, when it detects an internal error whileexecuting the SRW.SET_MAXROW packaged procedure.

Rules:

1. When you handle SRW.MAXROW_INERR, you should alwaysraise SRW.PROGRAM_ABORT to end the report’s execution(because the report has an internal problem).

SRW.SET_MAXROW


EXCEPTION

when SRW.MAXROW_INERR then

srw.message(1000, ’Contact Oracle’’s customer

support: SRW.MAXROW_INERR’);


SRW.MAXROW_UNSET stops report execution when a failure occurssetting the maximum rows for a query.

Type: Exception

SRW.MAXROW_UNSET;

This exception temporarily stops the report execution and raises theerror message below. After the message is raised and you accept it, thereport execution will continue.

REP–1423: Cannot set maximum rows of the query after

it started executing.

What Raises It: Oracle Reports, when the SRW.SET_MAXROWpackaged procedure is called after the query’s records have alreadybeen fetched.

SRW.SET_MAXROW

Examples:

SRW.MESSAGE

Syntax:

Parameters:

Description:



EXCEPTION

when SRW.MAXROW_UNSET then

srw.message(1000, ’Data was fetched before

SRW.SET_MAXROW was called.’);

SRW.MESSAGE displays a specified message and message number.

Type: Procedure

SRW.MESSAGE (msg_number NUMBER, msg_text CHAR);

Is a number from 0–9999, to be displayed on themessage line.

Is at most 190 minus the msg_number alphanumericcharacters to be displayed on the message line.

This procedure displays a message with the message number and textthat you specify. The message is displayed in the format below. Afterthe message is raised and you accept it, the report execution willcontinue.

MSG–mgs_number : msg_text .

Rules:

1. You cannot trap nor change Oracle Reports’ error messages. For alist of existing error numbers and messages, refer to the ReportsMessages and Codes Manual.

2. SRW.MESSAGE does not terminate the report execution; if youwant to terminate a report after raising a message, useSRW.PROGRAM_ABORT.

3. Any extra spaces in the message string will be displayed in themessage; extra spaces are not removed by Oracle Reports.

msg_number

msg_text

Examples:

SRW.NULL_ARGUMENTS

Syntax:

Description:


Suppose you have a user exit named MYEXIT to which you want topass the values of the SAL column. Suppose, also, that you want toraise your own error if the user exit is not found (e.g., because it is notlinked, compiled, etc.). To do these things, you could write thefollowing PL/SQL in the Format Trigger of the F_SAL field:

FUNCTION FOO RETURN BOOLEAN IS

BEGIN

srw.reference(:SAL);

srw.user_exit(’myexit sal’);

EXCEPTION

when srw.unknown_user_exit then

srw.message(1000, ’User exit MYEXIT failed.

Call Karen Smith x3455.’);


RETURN (TRUE);

END;

This trigger will raise your message as follows:

MSG–1000: User exit MYEXIT failed. Call Karen Smith

x3455.

SRW.NULL_ARGUMENTS stops report execution when a requiredargument is missing.

Type: Exception

SRW.NULL_ARGUMENTS;


REP–1418: Passed null arguments to <SRW.DO_SQL or

SRW.MESSAGE or SRW.RUN_REPORT or SRW.SET_MAXROW or

SRW.USER_EXIT>.

What Raises It: Oracle Reports, when one of its packaged functions orprocedures is called with a missing argument. This exception is usefulwhen you pass argument values to a packaged function or procedure,and you want to ensure that the values passed are not NULL (e.g.,when a formula column calls SRW.USER_EXIT, and the user exit stringis passed from a PL/SQL library).

Examples:

SRW.PROGRAM_ABORT

Syntax:

Description:


The following could raise this exception:

• SRW.DO_SQL

• SRW.MESSAGE

• SRW.RUN_REPORT

• SRW.SET_MAXROW

• SRW.USER_EXIT


EXCEPTION

when SRW.NULL_ARGUMENTS then

srw.message(4000, ’Contact Application Development

regarding SRW.NULL_ARGUMENTS.’);


SRW.PROGRAM_ABORT stops report execution when you raise it.

Type: Exception

SRW.PROGRAM_ABORT;


REP–1419: PL/SQL program aborted.

Examples:

SRW.REFERENCE

Syntax:

Parameters:

Description:


What Raises It: You must raise the exception from within yourPL/SQL.

Suppose you want to put a border around the salary if it is greater than0. Suppose, also, that if the report fetches a salary less than 0, you wantto raise a customized error message (i.e., ”FOUND A NEGATIVESALARY. . .”), then terminate the report execution. To do so, you couldwrite the following format trigger for F_SAL.

FUNCTION foo return boolean is

BEGIN

if :sal >= 0 then

srw.attr.mask := SRW.BORDERWIDTH_ATTR;

srw.attr.borderwidth := 1;

srw.set_attr (0, srw.attr);

else

srw.message(100, ’FOUND A NEGATIVE SALARY.

CHECK THE EMP TABLE.’);


end if;

RETURN (TRUE):

END;

SRW.REFERENCE adds the specified object to the dependency list of aprogram unit.

Type: Procedure

SRW.REFERENCE (:object CHAR|DATE|NUMBER);

Is the Oracle Reports parameter or column whosevalue needs to be ascertained before the construct fires.

This procedure causes Oracle Reports to add the referenced object tothe PL/SQL construct’s dependency list. This causes Oracle Reports todetermine the object’s value just before firing the PL/SQL construct.This useful when you want to ensure that a column value passed to auser exit is the most recently computed or fetched value.

Rules:

1. The colon is required before the object name.

2. SRW.REFERENCE is unnecessary when the object is alreadyreferenced in the current PL/SQL construct (e.g., in the examplebelow, srw.reference(:temp) is unnecessary, because :temp isalready referenced in the IF clause of the construct).

object

Examples:

SRW.RUN_REPORT

Syntax:

Parameters:

Description:


Suppose you want to pass the temperature and pressure values to auser exit called SUPERHEAT. Suppose, also, that if the temperature istoo low, you want to raise a customized error message. To do so, youcould write the following formula:

FUNCTION EXIT RETURN BOOLEAN IS

BEGIN

if :temp > 0 then

srw.reference (:temp); –– unnecessary reference

srw.reference (:pressure);

srw.user_exit(’superheat temp pressure’);

else srw.message(1000, ’Temperature is below

normal. Is machine off?’);


end if;

RETURN(TRUE);

END;

SRW.RUN_REPORT executes the specified R25RUN command.

Type: Procedure

SRW.RUN_REPORT (command_line CHAR);

Is a valid R25RUN command.

This procedure invokes R25RUN with the string that you specify. Thisprocedure is useful for the following:

• running drill–down reports (i.e., calling a report from a button’sAction Trigger)

• sending parts of a report to different recipients (e.g., to send areport via Oracle*Mail to each manager with just his or hergroup’s data)

• sending parts of a report to different printers (e.g., to send eachmanager’s report to his or her printer)

• running multiple reports from a single ”driver” report

Rules:

1. If you want parameter values that are entered on the RuntimeParameter Form to be passed in the R25RUN string, you must callSRW.RUN_REPORT after the Before Form trigger.

command_line

Examples:


2. The string that is specified for or passed to this procedure mustfollow the syntax and case–sensitivity rules for your operatingsystem.

3. No userid should be specified for the SRW.RUN_REPORTprocedure. The userid is inherited by the ”calling” report.

4. If the parent report that invokes SRW.RUN_REPORT is run inbatch, then DESTYPE can only be File, Printer, Sysout, or Mail.Otherwise, DESTYPE can be File, Printer, or Mail.

5. If SRW.RUN_REPORT is used in the PL/SQL for a button, theRuntime Parameter Form will not appear by default when thebutton is selected. If you want the Runtime Parameter Form toappear, you must specify PARAMFORM=YES in the call toSRW.RUN_REPORT.

6. If you do not specify a path, Oracle Reports will use its file pathsearch order to find the report. For more information about filepath search order, see “File Searching Method” on page 18 – 9.

The following examples illustrate the use of SRW.RUN_REPORT.

1. Suppose you have the following two reports:

• MGR_RUN, which queries manager names, and invokes asecond report named MAIL_IT

• MAIL_IT, which queries employee names for the manager thatMGR_RUN passes it, and sends the report output to themanager via Oracle*Mail.

The description of MGR_RUN could be as follows:

Query:

SELECT ENAME, EMPNO FROM EMP WHERE JOB=’MANAGER’

Group Filter:

FUNCTION FOO RETURN BOOLEAN IS BEGIN srw.run_report(’report=MAIL_IT desname=’||:ename ||’ desformat=dflt batch=yes mgr_no=’|| TO_CHAR(:empno) ); EXCEPTION when srw.run_report_failure then srw.message(30, ’Error mailing reports.’); raise srw.program_abort; RETURN (TRUE); END;


This PL/SQL invokes MAIL_IT, specifies that MAIL_IT’s outputshould be sent to the manager via Oracle Mail, and passes themanager number, so that the MAIL_IT report can query only themanager’s employees.

Note: EMPNO’s values must be converted to characters(TO_CHAR in the PL/SQL above), becauseSRW.RUN_REPORT requires a character string.

Layout: Tabular.

The description of MAIL_IT could be as follows:

Query:

SELECT DEPTNO, ENAME, SAL FROM EMP WHERE MGR=:MGR_NO

Layout: Master/Detail

2. Suppose that you have three reports that you almost always runtogether. The reports are named SALARY, COMMISS, and TAXES.To run these reports with one R25RUN command, you create adriver report named PAYROLL. The description of PAYROLLcould be as follows:

Query:

SELECT DEPTNO FROM DEPT

Before Report Trigger:

FUNCTION FOO RETURN BOOLEAN IS BEGIN srw.run_report(’batch=yes report=SALARY destype=file desformat=dflt desname=salary.lis’); srw.run_report(’batch=yes report=COMMISS destype=file desformat=dflt desname=comiss.lis’); srw.run_report(’batch=yes report=TAXES destype=file desformat=dflt desname=comiss.lis’);RETURN (TRUE); END;

Layout: Tabular

When you run PAYROLL from the designer or R25RUN, the otherthree reports will all be run. (Note that, in this case, the query andthe layout for Payroll could be anything. They are only used herein order to make it possible to run PAYROLL.)

SRW.RUN_REPORT_BATCHNO

Syntax:

Description:

See Also:

Examples:

SRW.RUN_REPORT_FAILURE

Syntax:

Description:

See Also:


SRW.RUN_REPORT_BATCHNO stops report execution whenBATCH=NO is not a valid choice using SRW.RUN_REPORT. For example,if a report is run with BATCH=YES and it calls another report viaSRW.RUN_REPORT, the called report must be run with BATCH=YES,too. If the called report had BATCH=NO,SRW.RUN_REPORT_BATCHNO would be raised.

Type: Exception

SRW.RUN_REPORT_BATCHNO;


REP–1429: SRW.RUN_REPORT cannot be invoked with batch=no.

What Raises It: Oracle Reports, when the SRW.RUN_REPORTprocedure is called with a command line string containing BATCH=NO

and that is not a valid choice.

SRW.RUN_REPORT


EXCEPTION

when SRW.RUN_REPORT_BATCHNO then

srw.message(4000, ’Contact Application Dev. Services

regarding SRW.RUN_REPORT_BATCHNO.’);


SRW.RUN_REPORT_FAILURE stops report execution when a failureoccurs in SRW.RUN_REPORT.

Type: Exception

SRW.RUN_REPORT_FAILURE;

If the SRW.RUN_REPORT packaged procedure fails, this exceptionstops the report execution and raises the following error message:

REP–1428: Error while running SRW.RUN_REPORT.

What Raises It: Oracle Reports, when the SRW.RUN_REPORTpackaged procedure fails.

SRW.RUN_REPORT

Examples:

SRW.SET_ATTR

Syntax:

Parameters:

Description:


Suppose you want your own error message raised, instead of thedefault error message (above). The PL/SQL below will raise acustomized error message when SRW.RUN_REPORT_FAILURE israised.

EXCEPTION

WHEN srw.run_report_failure then

srw.message(30, ’Error mailing reports.’);


SRW.SET_ATTR applies attibute settings such as font size or color tolayout objects.

Type: Procedure

SRW.SET_ATTR (object_id NUMBER, attr SRW.GENERIC_ATTR);

Is always 0. (The object must always set its ownattributes.)

Is srw.attr (i.e., the attributes to change and theirvalues).

This procedure applies formatting attributes to the current frame,repeating frame, field, or boilerplate object. You specify whichformatting attributes should be applied to an object by defining a mask.A mask is a collection of attributes; each attribute has one or morevalues. You create a mask much like you would create a mask for amasquerade party: first you specify the attributes of the mask (e.g.,eyes), then you ”set the value” of each attribute (e.g., brown). To defineand then apply a mask in PL/SQL, you do the following:

1. Specify the mask’s attributes you wish to set (e.g., the border).

SRW.ATTR.MASK := SRW.BORDERWIDTH_ATTR; –– attribute

2. Specify a value for each attribute that you specified (e.g., width of 1character).

SRW.ATTR.BORDERWIDTH := 1; –– value for attribute

3. Apply the mask to the object by calling the SRW.SET_ATTRprocedure.

srw.set_attr(0, srw.attr);

Below is an example of specifying two attributes (and their values) forthe mask:

SRW.ATTR.MASK := SRW.BORDERWIDTH_ATTR + –– attribute

SRW.FILLPATT_ATTR; –– attribute

object_id

attr


SRW.ATTR.BORDERWIDTH := 1; –– value for attribute

SRW.ATTR.FILLPATT := ’SOLID’;–– value for attribute

SRW.SET_ATTR(0, SRW.ATTR);

Note: Whenever you specify more than one attribute for amask, you must use the plus sign (+) to ”add” them. In theexample above, the plus sign was needed because twoattributes were assigned to the mask.

Attributes and Their Values: Below are the attributes and their valuesthat you can apply to a mask:

Attribute Character Mode Values Bitmap Values

SRW.AFTCODE_ATTR (after printer code)

Integer=the printer code inthe printer definition file forthat integer. Must be astring.

N/A—attribute is ignored.

SRW.BBCOLOR_ATTR N/A—attribute is ignored. For valid color names, select SRW.BBCOLOR_ATTR(background border color)

N/A attribute is ignored. For valid color names, select Format—>Color Palette, then click(background border color) Format >Color Palette, then clickon the color you want. Must be a

iy

string.

SRW.BEFCODE_ATTR(before printer code)

Integer=the printer code inthe in the printer definitionfile for that integer. Must bea string.

N/A—attribute is ignored.

SRW.BFCOLOR_ATTR(background fill color)

N/A—attribute is ignored. For valid color names, selectFormat—>Color Palette, then clickon the color you want. Must be astring.

SRW.BORDER-WIDTH ATTR

0=no border; any other integer= border of 1

0=no border; any other integer= border of that many picasWIDTH_ATTR

(border width)integer= border of 1 character.

border of that many picas.

SRW.BORDPATT_ATTR(b d )

N/A—attribute is ignored. For valid fill pattern names, look atd G b

_(border pattern)

/ g p ,Appendix G. Must be a string.

SRW.FACE_ATTR N/A—attribute is ignored. The name of any font installed on theSRW.FACE_ATTR(type face) Can only be used

N/A attribute is ignored. The name of any font installed on thesystem on which the report will run.(type face) Can only be used

for fields with a Type ofCHAR DATE NUMBER

system on which the report will run.Must be a string.yp

CHAR, DATE, or NUMBER.g

SRW.FBCOLOR_ATTR(foreground border color)

N/A—attribute is ignored. For valid color names, selectFormat >Color Palette then click(foreground border color) Format—>Color Palette, then clickon the color you want. Must be aon the color you want. Must be astring.


Attribute Bitmap ValuesCharacter Mode Values

SRW.FFCOLOR_ATTR(foreground fill color)

N/A—attribute is ignored. For valid color names, selectFormat >Color Palette then click(foreground fill color) Format—>Color Palette, then clickon the color you want. Must be aon the color you want. Must be astring.

SRW.FILLPATT_ATTR(fill pattern)

N/A—attribute is ignored. See “Pattern and Color Palette”

SRW.FORMAT-MASK_ATTR(format mask) Can only beused for fields with a Type ofCHAR, DATE, or NUMBER.

Any format mask. Must bea string.

Any format mask. Must be a string.

SRW.GCOLOR_ATTR(global text color) Can onlybe used for fields with aType of CHAR, DATE, orNUMBER.

N/A—attribute is ignored. For valid color names, selectFormat—>Color Palette, then clickon the color you want. Must be astring.

SRW.GSPACING_ATTR(global text leading) Can onlybe used for fields with aType of CHAR, DATE, orNUMBER, or for boilerplatewith a Type of CHAR.

N/A—attribute is ignored. srw.single_spacingsrw.onehlf_spacingsrw.double_spacingsrw.custom_spacing (You mustspecify the desired vertical spacingin VGS units. See Example 5 below.)

SRW.HJUST_ATTR(h i t l j tifi ti ) C

srw.left_hjustt hj t

srw.left_hjust hj t

J(horizontal justification) Canonly be used for fields with a

jsrw.center_hjustsrw right hjust

jsrw.center_hjustsrw right hjustonly be used for fields with a

Type of CHAR, DATE, orsrw.right_hjustsrw.flush_hjust

srw.right_hjustsrw.flush_hjust—ignored in bitmapType of CHAR, DATE, or

NUMBER.srw.flush_hjust srw.flush_hjust ignored in bitmap

SRW.STYLE_ATTR N/A—attribute is ignored. srw.plain_styleSRW.STYLE_ATTR(style) Can only be used for

N/A—attribute is ignored. srw.plain_stylesrw.italic_style(style) Can only be used for

fields with a Type of CHAR,srw.italic_stylesrw.oblique_stylefields with a Type of CHAR,

DATE, or NUMBER.srw.oblique_stylesrw.underline_styleDATE, or NUMBER. srw.underline_stylesrw.outline_stylesrw.outline_stylesrw.shadow_stylesrw.shadow_stylesrw.inverted_style_ ysrw.overstrike_style

bl k l_ y

srw.blink_styleSRW.SZ_ATTR(size) Can only be used for

N/A—attribute is ignored. The size of the named font that isinstalled on the system on which the(size) Can only be used for

fields with a Type of CHAR,installed on the system on which thereport will run.fields with a Type of CHAR,

DATE, or NUMBER.report will run.

Examples:


Attribute Bitmap ValuesCharacter Mode Values

SRW.TEXT_ATTR(text) Can only be used forfields with a Type of CHAR,DATE, or NUMBER.

srw.plain_textasrw.reverse_textasrw.bold_textasrw.reversebold_textasrw.underline_textasrw.underlinereverse_textasrw.underlinebold_textasrw.reverseboldunder-line_texta

N/A—attribute is ignored; useSRW.WEIGHT_ATTR andSRW.SZ_ATTR instead. (See Example 4 below.)

SRW.WEIGHT_ATTR N/A—attribute is ignored. srw.ultralight_weightSRW.WEIGHT_ATTR(weight) Can only be used

N/A—attribute is ignored. srw.ultralight_weightsrw.extralight_weight(weight) Can only be used

for fields with a Type ofsrw.extralight_weightsrw.light_weightfor fields with a Type of

CHAR, DATE, or NUMBER.srw.light_weightsrw.demilight_weightCHAR, DATE, or NUMBER. srw.demilight_weightsrw.medium_weightsrw.medium_weightsrw.demibold_weightsrw.demibold_weightsrw.bold_weighto _ gsrw.extrabold_weight

Rules:

1. If you specify an attribute (e.g., SRW.FILLPATT_ATTR), you mustspecify a value for it. If you do not specify a value for a specifiedattribute, you will get unpredictable results for that attribute.

2. If you specify a value that is not provided by the Oracle Reportspackage, it must be a string (i.e., enclosed by single quotes). Forexample, a value for SRW.ATTR.FORMATMASK must be enclosedby single quotes, because you may specify any value. A value forSRW.ATTR.HJUST must not be enclosed by single quotes, becauseyou must specify one of the values that Oracle Reports provides.

The following examples illustrate the use of SRW.SET_ATTR.

1. Here’s an example of using all of the formatting attributes valid forcharacter–mode reports. Notice that there are two values appliedto the horizontal justification attribute (HJUST).

Note: For the printer codes &1 and &2 to be meaningful, theprinter definition file for this report must define what theprinter should do for &1 and &2. For more information, see“Printer Definition File Syntax” on page B – 3.

IF :SAL > 2000 THEN SRW.ATTR.MASK := SRW.BEFCODE_ATTR + SRW.AFTCODE_ATTR + SRW.TEXT_ATTR + SRW.FILLPATT_ATTR + SRW.BORDERWIDTH_ATTR +


SRW.FORMATMASK_ATTR + SRW.HJUST_ATTR; SRW.ATTR.BEFCODE := ’&1’; SRW.ATTR.AFTCODE := ’&2’; SRW.ATTR.TEXT := SRW.BOLD_TEXTA; SRW.ATTR.FILLPATT := ’TRANSPARENT’; SRW.ATTR.BORDERWIDTH := 1; SRW.ATTR.FORMATMASK := ’DD–MON–YY’; SRW.ATTR.HJUST := SRW.CENTER_HJUST + SRW.FLUSH_HJUST; END IF; SRW.SET_ATTR(0, SRW.ATTR); RETURN(TRUE);

2. If the salary is 2000, the following code segment sets the formatmask to –99990.

if :sal = 2000 then srw.attr.mask := SRW.FORMATMASK_ATTR; srw.attr.formatmask := ’–99990’; srw.set_attr (0, srw.attr); end if; RETURN (TRUE);

3. If the salary is 2000, this code segement sets the followingattributes: border width to 1, foreground border color to ”red,”background border color to ”blue,” border pattern to ”checker,”foreground fill color to ”yellow,” background fill color to ”green,”and the fill pattern to ”crisscross.”

Note: When you run the report with this PL/SQL construct incharacter mode, only the border width (of 1) and fill pattern (ofsolid) will be set; all other settings will be ignored. When you runthe report with this PL/SQL construct in bitmap, all of theattributes will be set. (Be aware that the border background coloris not set–able on some GUIs.)

if :sal = 2000 then srw.attr.mask := SRW.BORDERWIDTH_ATTR + SRW.FBCOLOR_ATTR + SRW.BBCOLOR_ATTR + SRW.BORDPATT_ATTR + SRW.FFCOLOR_ATTR + SRW.BFCOLOR_ATTR + SRW.FILLPATT_ATTR; srw.attr.borderwidth := 1; srw.attr.fbcolor := ’red’; srw.attr.bbcolor := ’blue’; srw.attr.bordpatt := ’checker’;


srw.attr.ffcolor := ’yellow’; srw.attr.bfcolor := ’green’; srw.attr.fillpatt := ’crisscross’; srw.set_attr (0, srw.attr); end if; RETURN(TRUE);

4. If the salary is 2000, this code segment sets the following textattributes: text to bold, font to TIMES, size to 18 points, style tounderline, weight to bold, text color to ”blue,” and the justificationto center.

Note: When you run the report with this PL/SQL construct incharacter mode, only the text will be set to bold (SRW.TEXT_ATTR); all other attributes will be ignored. When you run thereport with this PL/SQL construct in bitmap, all of theattributes—except SRW.TEXT_ATTR—will be set.

if :sal = 2000 then srw.attr.mask := SRW.TEXT_ATTR + SRW.FACE_ATTR + SRW.SZ_ATTR + SRW.WEIGHT_ATTR + SRW.STYLE_ATTR + SRW.GCOLOR_ATTR + SRW.HJUST_ATTR; srw.attr.text := SRW.BOLD_TEXTA; srw.attr.face := ’times’; srw.attr.sz := 18; srw.attr.weight := SRW.BOLD_WEIGHT; srw.attr.style := SRW.UNDERLINE_STYLE; srw.attr.gcolor := ’blue’; srw.attr.hjust := SRW.CENTER_HJUST; srw.set_attr (0, srw.attr); end if; RETURN (TRUE);

5. If the salary is 2000, this code segment sets the vertical spacingbetween lines to a custom size of 200 VGS units. (One inch isequivalent to 8192 VGS units.)

if :sal = 2000 then srw.attr.mask := SRW.GSPACING_ATTR; srw.attr.gspacing := SRW.CUSTOM_SPACING; srw.attr.custom := 200; srw.set_attr (0, srw.attr); end if; RETURN (TRUE);

SRW.SET_FIELD_CHAR

Syntax:

Parameters:

Description:

Examples:

SRW.SET_FIELD_DATE

Syntax:

Parameters:

Description:


SRW.SET_FIELD_CHAR sets the value of a character field.

Type: Procedure

SRW.SET_FIELD_CHAR (object_id, text CHAR);


Is the character string you want the field to display.

This procedure sets the value of a Character field. This is useful whenyou want to conditionally change a field’s Character value.

Rules:

1. SRW.SET_FIELD_CHAR is only meaningful in the Format Trigger of a field of Datatype Character. It has no affect when entered inother places.

Suppose you want to conditionally change the value of a Characterfield, based on each employee’s salary. In the Format Trigger for thefield, you could type the following:

FUNCTION CHGFIELD RETURN BOOLEAN IS

BEGIN

if :sal >= 2000000 then

srw.set_field_char (0, ’HIGH SALARY’);

else

end if;

RETURN (TRUE);

END;

SRW.SET_FIELD_DATE sets the value of a date field.

Type: Procedure

SRW.SET_FIELD_DATE ( object_id, date DATE);


Is the date you want the field to display.

This procedure sets the value of a Date field. This is useful when youwant to conditionally change a field’s Date value.

object_id

text

object_id

date

Examples:

SRW.SET_FIELD_NUM

Syntax:

Parameters:

Description:

Examples:


Rules:

1. SRW.SET_FIELD_DATE is only meaningful in the Format Triggerof a field of Datatype Date. It has no affect when entered in otherplaces.

Suppose you want to conditionally change the date of the reunioninvitation, based on each student’s graduation year. In the FormatTrigger for the field, you could type the following:


BEGIN

if :graduation >= 1975 then

srw.set_field_date (0, ’02–JUL–95’);

else

end if;

RETURN (TRUE);

END;

SRW.SET_FIELD_NUM sets the value of a number field.

Type: Procedure

SRW.SET_FIELD_NUM (object_id, number NUM);


Is the number you want the field to display.

This procedure sets the value of a Number field. This is useful whenyou want to conditionally change a field’s Number value.

Rules:

1. SRW.SET_FIELD_NUM is only meaningful in the Format Trigger ofa field of Datatype Number. It has no affect when entered in otherplaces.

Suppose you want to conditionally change the number of a field, basedon each employee’s salary. In the Format Trigger for the field, youcould type the following:


TMP NUMBER;

BEGIN

if :sal >= 2000 then

tmp := :sal * 1.08;

srw.set_field_num (0, tmp);

object_id

number

SRW.SET_MAXROW

Syntax:

Parameters:

Description:

Examples:


else

srw.set_field_num (0, ’2500’);

end if;

RETURN (TRUE);

END;

SRW.SET_MAXROW sets the maximum number of rows to beretrieved by the specified query.

Type: Procedure

SRW.SET_MAXROW (query_name CHAR, maxnum PLS_INTEGER);

Is the query whose fetched records will be limited.

Is maximum number of records you want the query tofetch.

This procedure sets the maximum number of records to be fetched forthe specified query. This is useful when your report formats (i.e.,displays) fewer records than the query (or queries) that fetch them.Thus, with SRW.SET_MAXROW, you can conditionally restrict datathat is fetched for your report, enabling you to improve the report’sperformance.

Rules:

1. SRW.SET_MAXROW is only meaningful in a Before Report trigger(i.e., after the query is parsed). If SRW.SET_MAXROW is calledafter the Before Report trigger (i.e., after the queries have beenexecuted), the SRW.MAXROW_UNSET packaged exception israised.

2. Because this procedure causes only the specified number of recordsto be fetched, the ”unfetched” records of the query are not used incomputations, etc.

3. If you specify that 0 records should be fetched, the query will stillbe parsed.

Suppose your report has two queries, Q_Stocks and Q_Bonds.Suppose also, that you have a user–created parameter, namedWHICHDATA, that enables users to specify which data they want thereport to display: either stocks or bonds. In the Before Report trigger,you could use the SRW.SET_MAXROW procedure to ensure that onlyone query’s data is fetched:

query_name

maxnum

SRW.TRACE_ADD_OPTION

Syntax:

Parameters:

Description:

See Also:

SRW.TRACE_END

Syntax:

Description:

See Also:


FUNCTION FETCHIT RETURN BOOLEAN IS

BEGIN

if :whichdata != 1 then

srw.set_maxrow (’Q_Stocks’, 0);

else

srw.set_maxrow (’Q_Bonds’, 0);

end if;

RETURN (TRUE);

END;

SRW.TRACE_ADD_OPTION applies the trace options mask.

Type: Procedure

SRW.TRACE_ADD_OPTION (SRW.TRACEOPTS);

Applies the trace options mask previously defined bySRW.TRACEOPTS.MASK. Note thatSRWTRACE_APPEND and SRWTRACE_REPLACEare not trace options and are not available for use withSRW.TRACE_ADD_OPTION.

SRW.TRACE_ADD_OPTION enables you to specify a new trace optionafter you have begun logging trace information withSRW.TRACE_START.

Description:

Below is an example of specifying three tracing options for the maskand then invoking the mask in a call to SRW.TRACE_ADD_OPTION:

SRW.TRACEOPTS.MASK := SRW.TRACE_ERR +

SRW.TRACE_BRK +

SRW.TRACE_PRF;

SRW.TRACE_ADD_OPTION(SRW.TRACEOPTS);

SRW.TRACE_START

SRW.TRACE_END stops the logging of trace information.

Type: Procedure

SRW.TRACE_END ();

SRW.TRACE_END ends the logging of trace information to a fileduring report execution. To start the logging, use SRW.TRACE_START.

SRW.TRACE_START

SRW.TRACEOPTS

SRW.TRACE_REM_OPTION

Syntax:

Parameters:

See Also:

SRW.TRACE_START

Syntax:

Parameters:

Description:


SRW.TRACE_REM_OPTION removes trace options.

Type: Procedure

SRW.TRACE_REM_OPTION (SRW.TRACEOPTS);

Removes the trace options in the mask previouslydefined by SRW.TRACEOPTS.MASK. Note thatSRWTRACE_APPEND and SRWTRACE_REPLACEare not trace options and are not available for use withSRW.TRACE_REM_OPTION.

Below is an example of specifying three tracing options for the maskand then invoking the mask in a call to SRW.TRACE_REM_OPTION:


SRW.TRACE_BRK +

SRW.TRACE_PRF;

SRW.TRACE_REM_OPTION(SRW.TRACEOPTS);

SRW.TRACE_START

SRW.TRACE_START begins the logging of trace information.

Type: Procedure

SRW.TRACE_START (filename, {SRW.TRACE_REPLACE|SRW.TRACE_APPEND}, SRW.TRACEOPTS);

Is the name of the file in which Oracle Reports storeslogging information.

Adds the new information to the end of the file.

Overwrites the file.

Applies the trace options mask previously defined bySRW.TRACEOPTS.MASK.

SRW.TRACE_START enables you to start logging tracing informationto a file during report execution. To stop the logging, useSRW.TRACE_END. You can also specify what information you wantincluded in the log file. This information can be useful in debugging areport or finding performance bottlenecks. You specify which tracingoptions should be applied by defining a mask. To define and thenapply a mask for tracing options in PL/SQL, you do the following:

SRW.TRACEOPTS

filename

SRW.TRACE_APPEND

SRW.TRACE_REPLACE

SRW.TRACEOPTS


1. Specify the options you want turned on:

SRW.TRACEOPTS.MASK := SRW.TRACE_ERR + SRW.TRACE_PRF;

2. Apply the mask to the object by using SRW.TRACEOPTS when youcall the SRW.TRACE_START procedure:

SRW.TRACE_START(test.dat, SRW.TRACE_APPEND, SRW.TRACEOPTS);

Below is an example of specifying three tracing options for the maskand then invoking the mask in a call to SRW.TRACE_START:


SRW.TRACE_BRK +

SRW.TRACE_PRF;

SRW.TRACE_START(test.dat, SRW.TRACE_APPEND, SRW.TRACEOPTS);

Note: Whenever you specify more than one option for a mask,you must use the plus sign (+) to ”add” them. In the exampleabove, the plus sign was needed because three options wereassigned to the mask.

Options and Their Meaning: Below are the options that you can applyto a trace mask and their meaning:

Mask Option Description

SRW.TRACE_ALL_ Includes all possible trace informationin the log file.

SRW.TRACE_APP_ Includes trace information on all the re-port objects in the log file.

SRW.TRACE_BRK_ Lists breakpoints in the log file.

SRW.TRACE_ERR Includes error messages and warningsin the log file.

SRW.TRACE_PLS_ Includes trace information on all thePL/SQL objects in the log file.

SRW.TRACE_PRF Includes performance statistics in thelog file.

SRW.TRACE_SQL_ Includes trace information on all theSQL in the log file.

Rules:

1. Logging information can only be generated when running a .rdffile. You cannot specify logging when running a .rep file.

2. Only one log session is allowed at one time. SRW.TRACE_STARTautomatically ends any other log sessions.

See Also:

SRW.TRUNCATED_VALUE

Syntax:

Description:

Examples:

SRW.UNKNOWN_QUERY

Syntax:

Description:


SRW.TRACE_END

SRW.TRUNCATED_VALUE stops report execution when a value istruncated.

Type: Exception

SRW.TRUNCATED_VALUE;

This exception will stop the report execution and raise one of two errormessages. If the error resulted from a PL/SQL assignment, thismessage will be displayed:

REP–1435: Value of column <parameter/column name> was

truncated.

If the error resulted from a user exit IAF PUT, this message will bedisplayed:

REP–1416: User exit <name> IAF PUT: value of column

<parameter/column name> was truncated.

If the SRW.TRUNCATED_VALUE exception is handled, the value willbe truncated and remain assigned to the parameter or column.

What Raises It: Oracle Reports, when a user exit or PL/SQL constructattempts to assign a value to a parameter or column which is largerthan the object’s maximum width.


EXCEPTION

when SRW.TRUNCATED_VALUE then

srw.message(2000, ’Contact Dan Brown:

SRW.TRUNCATED_VALUE.’);

SRW.UNKNOWN_QUERY stops report execution when a query nameis not found by SRW.SET_MAXROW.

Type: Exception

SRW.UNKNOWN_QUERY;

This exception will stop the report execution and raise the followingerror message:

REP–1427: Nonexistent query name referenced in

SRW.SET_MAXROW.

See Also:

Examples:

SRW.UNKNOWN_USER_EXIT

Syntax:

Description:

See Also:

Examples:

SRW.USER_EXIT

Syntax:


What Raises It: Oracle Reports, when the SRW.SET_MAXROWpackaged procedure is called with an unknown query.

SRW.SET_MAXROW


EXCEPTION

when SRW.UNKNOWN_QUERY then

srw.message(4000, ’Contact Per Jensen:

SRW.UNKNOWN_QUERY.’);


SRW.UNKNOWN_USER_EXIT stops report execution when a user exitname is not found by SRW.USER_EXIT or SRW.USER_EXIT20.

Type: Exception

SRW.UNKNOWN_USER_EXIT;

If your user exit is unknown (e.g., because it is not linked), thisexception stops the report execution and raises the following errormessage:

REP–1415: Unknown user exit.

What Raises It: Oracle Reports, when the user exit specified for theSRW.USER_EXIT or SRW.USER_EXIT20 packaged procedure cannot belocated (e.g., because the user exit was not linked).

SRW.USER_EXIT, SRW.USER_EXIT20

Suppose you want your own error message raised, instead of thedefault error message (above). The following PL/SQL will raise acustomized error message for SRW.UNKNOWN_USER_EXIT.

EXCEPTION

WHEN srw.unknown_user_exit then

srw.message(200, ’PASS USER EXIT WAS UNKNOWN.

CHECK IF IT’’S LINKED.’);

SRW.USER_EXIT calls the specified user exit with two arguments.

Type: Procedure

SRW.USER_EXIT ( user_exit_string CHAR);

Parameters:

Description:

See Also:

Examples:


Is the name of the user exit you want to call and anycolumns or parameters that you want to pass to theuser exit program.

This procedure calls the user exit named in user_exit_string. It is usefulwhen you want to pass control to a 3GL program during a report’sexecution.

Caution: User exits are not portable. If your report must be portable,and you need to add conditional logic to it, use PL/SQL.

Rules:

1. If the user exit string passes a column or parameter to the user exitprogram, SRW.REFERENCE must be called before this procedure.For more information, see “SRW.REFERENCE” on page 13 – 53.

SRW.USER_EXIT20

Suppose you have a user exit named STORE to which you want to passsalary values from Oracle Reports. To do so, you could write thefollowing formula. For more information on how to call user exits, see“Calling a User Exit” on page 14 – 10.

FUNCTION FOO RETURN BOOLEAN IS

BEGIN

IF :SAL >= 0 THEN

SRW.REFERENCE(:SAL);

SRW.USER_EXIT(’STORE SAL’);

ELSE

SRW.MESSAGE(100, ’FOUND A NEGATIVE SALARY. CHECK THE

EMP TABLE.’);

END IF;

EXCEPTION

WHEN SRW.UNKNOWN_USER_EXIT THEN

SRW.MESSAGE(200, ’STORE USER EXIT WAS UNKNOWN.

CHECK IF IT’’S LINKED.’);

WHEN SRW.USER_EXIT_FAILURE THEN

SRW.MESSAGE(200, ’STORE USER EXIT FAILED.

CHECK ITS CODE.’);

RETURN(TRUE);

END;

user_exit_string

SRW.USER_EXIT20

Syntax:

Parameters:

Description:

See Also:

SRW.USER_EXIT_FAILURE

Syntax:

Description:


SRW.USER_EXIT20 calls the specified user exit with five arguments.

Type: Procedure

SRW.USER_EXIT20 ( user_exit_string CHAR);

Is the name of the user exit you want to call and anycolumns or parameters that you want to pass to theuser exit program.

This procedure is the same as SRW.USER_EXIT, except that it calls theuser exit with five arguments instead of just two. This enables you toshare user exits with other Oracle products, such as Oracle Forms,which pass five arguments instead of two.

SRW.USER_EXIT passes the following when calling a user exit:

• the character string that you specify

• a pointer to the length of the character string

SRW.USER_EXIT20 passes the following when calling a user exit:

• the character string that you specify

• a pointer to the length of the character string

• an error string (This argument is not used by Oracle Reports andwill always pass a value of ’ ’.)

• a pointer to the length of the error string (This argument is notused by Oracle Reports and will always pass a value of 0.)

• an in query argument (This argument is not used by OracleReports and will always pass a value of 0.)

SRW.USER_EXIT

SRW.USER_EXIT_FAILURE stops report execution when a user exitfails.

Type: Exception

SRW.USER_EXIT_FAILURE;

This exception is raised when the user exit you called has failed. Whencalled, it stops the report execution and raises the following errormessage:

REP–1416: User exit <exit_name> failed.

user_exit_string

See Also:

Examples:


What Raises It: Oracle Reports, when the SRWERB buffer isnon–empty. (For details, see “Raising Errors from the User Exit” onpage 14 – 9.)

SRW.USER_EXIT, SRW.USER_EXIT20

Suppose you want your own error message raised, instead of thedefault error message (above). The following PL/SQL will raise acustomized error message for SRW.USER_EXIT_FAILURE.

EXCEPTION

when SRW.USER_EXIT_FAILURE then

SRW.MESSAGE(200, ’PASS user exit failed.

Check its code.’);

C H A P T E R

14U

14 – 1User Exit Interface

User Exit Interface

ser exits enable you to call your 3GL programs from OracleReports. You should know the following about user exits:

• definition and purpose of user exits – 14 – 2

• types of user exits – 14 – 2

• steps to build a user exit – 14 – 3

• writing a user exit – 14 – 4

• implementing a user exit – 14 – 9

• calling a user exit – 14 – 10

• packaged user exits – 14 – 16

• complete user exit example – 14 – 21

Read this information to get an understanding of user exits. Then, usethe appropriate Developer/2000 Installation Guide to guide your actualwork. Before you attempt to implement a user exit, you should have athorough knowledge of operating system concepts. Previous exposureto the ORACLE Precompilers is also very useful.


Note: The section on writing a user exit describes how to writean ORACLE Precompiler user exit—the type of user exit youwill use most often. That section does not cover all details onhow to actually write and implement a user exit. Those detailsvary with the operating system on which you are working andthe language in which you choose to write the user exit.


A user exit is a program that you write and then link into the OracleReports executable files. You build user exits when you want to passcontrol from Oracle Reports to a program you have written, whichperforms some function, and then return control to Oracle Reports.

User exits can perform the following tasks:

• perform complex data manipulation

• pass data to Oracle Reports from operating system text files

• manipulate LONG RAW data

• support PL/SQL blocks

• control real time devices, such as a printer or a robot

You can use user exits for other tasks, such as mathematical processing.However, Oracle Corporation recommends that you perform suchtasks with PL/SQL within Oracle Reports.

Note: Not all types of user exits can perform all of thedescribed tasks. You can accomplish most of these tasks onlywith ORACLE Precompiler user exits.

Types of User Exits

You can write the following types of user exits:

• ORACLE Precompiler user exits

• OCI (ORACLE Call Interface) user exits

• non–ORACLE user exits

You can also write a user exit that combines both the ORACLEPrecompiler interface and the OCI.

ORACLE PrecompilerUser Exits

OCI (ORACLE CallInterface) User Exits

Non–ORACLE UserExits


An ORACLE Precompiler user exit incorporates the ORACLEPrecompiler interface. This interface supports the following:

• You can write a subroutine in one of the host languages (Ada, C,COBOL, FORTRAN, Pascal, PL/l) and embed SQL commands.

• The user exit can access ORACLE (via embedded SQLcommands) and Oracle Reports’ variables, parameters, andcolumns.

Because of these features, you will write most of your user exits asORACLE Precompiler user exits.

For more information on the ORACLE Precompiler interface, refer toyour Programmer’s Guide to the ORACLE Precompilers.

Note: Not all operating systems support all of the listedlanguages. For more information, see the Developer/2000Installation Guide for your operating system.

An OCI user exit incorporates the ORACLE Call Interface. Thisinterface allows you to write a subroutine that contains calls toORACLE. A user exit that incorporates only the OCI (and not theORACLE Precompiler interface) cannot access Oracle Reports’variables, parameters, and columns.

For more information on the OCI, refer to your Programmer’s Guide tothe ORACLE Call Interface.

A non–ORACLE user exit does not incorporate either the ORACLEPrecompiler interface or the OCI. For example, a non–ORACLE userexit might be written entirely in C. By definition, a non–ORACLE userexit cannot access ORACLE or Oracle Reports’ variables, parameters,and columns.

Steps to Build a User Exit

We suggest the following steps to produce a report that contains a userexit:

1. Create your report without user exits.

2. Decide which user exits are needed.

3. Write the user exit using one of the host programming languages.


4. Implement the user exit by modifying the sample source file.

5. Create the Oracle Reports object and the user exit call (followed byarguments that you wish to pass).

Note: Some details of implementing user exits are specific toeach operating system. For more information on the exactsteps you need to follow, see the Developer/2000 InstallationGuide for your operating system.

Writing a User Exit

To write a user exit, you will need to know the following informationabout user exits:

• supported functions (includes how Oracle Reports gets andpasses arguments) – 14 – 5

• syntax of a passed user exit call (i.e., what the call looks likewhen the user exit program receives it) – 14 – 8

• error checking and raising – 14 – 9

Note: This section applies specifically to ORACLE Precompileruser exits, because it is the type of user exit that you will usemost often (it can access Oracle Reports’ variables, parameters,and columns, and ORACLE data), and it is the type that OracleCorporation recommends for most tasks.

Note: This section does not cover how to write a user exit call(i.e., how to invoke the user exit within Oracle Reports). Formore information on how to write user exit calls, see “Calling aUser Exit” on page 14 – 10.

Rules:

1. You cannot perform host language screen I/O from an ORACLEPrecompiler user exit. This restriction exists because the runtimeroutines that a host language uses to perform screen I/O conflictwith the routines that Oracle Reports uses to perform its I/O.

Supported Functions

EXEC SQL Statements

Syntax


When you write a user exit using one of the ORACLE Precompiler hostlanguages, the user exit can perform procedural operations via hostlanguage statements, and perform additional functions via thefollowing types of statements:

Statement Types Use

EXEC SQL Performs SQL commands.

EXEC IAF GET Passes values from Oracle Reports to a user exit.

EXEC IAF PUT Passes values from a user exit to Oracle Reports.

EXEC ORACLE Executes ORACLE Precompiler options.

An EXEC SQL statement is a SQL command, prefixed with ”EXECSQL.” EXEC SQL statements enable you to perform any SQLcommand in an ORACLE Precompiler user exit. It is your means ofselecting or manipulating data in the database from a user exit.

EXEC SQL sql_statement ;

where:

Is any valid ORACLE SQL statement, except forthe restricted commands noted in this section.

You do not need to perform an explicit CONNECT in an ORACLEPrecompiler user exit, because Oracle Reports establishes theconnection automatically. However, ORACLE does support concurrentconnects. For more information, refer to your Programmer’s Guide to theORACLE Precompilers.

Rules:

1. The ONSUCCESS and ONFAILURE keywords for R25DES andR25RUN determine whether Oracle Reports performs a COMMIT,a ROLLBACK, or nothing after a report runs or fails. If you wishto COMMIT at any other time, you can do so in your user exit or inPL/SQL (after your user exit call, add SRW.DO_SQL(’commit’); ).

Caution: Avoid using DDL when you specify READONLY. When youexecute a DDL statement (e.g., via SRW.DO_SQL or a user exit), aCOMMIT is automatically issued. If you are using READONLY, thiswill prematurely end the transaction begun by SET TRANSACTIONREADONLY. For more information, see “READONLY” on page 1 – 41.

sql_statement

EXEC IAF GET

Syntax

Notes

EXEC IAF PUT


An EXEC IAF GET statement passes a value from Oracle Reports to anORACLE Precompiler user exit. Specifically, it places the value of anOracle Reports parameter or column into a host language variable.Once Oracle Reports passes a value to a user exit, the user exit can usethe value for calculation, manipulation, or update.

EXEC IAF GET report_variable_1 [, report_variable_2 , ...]

INTO : host_variable_1 [, : host_variable_2 , ...];

where:

Contains the name of the Oracle Reports parameteror column from which you are reading a value.

Is the name of the host language variable intowhich you are reading a value.

1. Report_variable_n can be a reference to any of the following items:

• an unambiguous Oracle Reports parameter or column name (Toget the current date, create a parameter with a Source of &DATE,then GET the parameter’s value. To get the current logical pagenumber, call the SRW.GET_PAGE_NUM packaged function, thenpass the value to the user exit via your user exit call.)

• a host language variable (prefixed with a colon) whose value isany of the above bulleted items

For possible restrictions on host language variables, refer to yourProgrammer’s Guide to the ORACLE Precompilers.

Rules:

1. If an Oracle Reports object’s data is longer than 64,000 bytes, the value returned from an EXEC IAF GET is truncated to theleft–most 64,000 bytes.

An EXEC IAF PUT statement passes a value from an ORACLEPrecompiler user exit to Oracle Reports. Specifically, it places the valueof a constant or the value of a host language variable into an OracleReports parameter or column.

report_variable_n

host_variable_n

Syntax

EXEC ORACLEStatements


EXEC IAF PUT report_variable [, ...]

VALUES ({: host_variable | constant }[, ...]);

where:

Is the name of the Oracle Reports parameter orcolumn into which you are reading a value, or ahost variable (prefixed with a colon) whose value isthe name of an Oracle Reports parameter orcolumn).

Is the name of the host language variable fromwhich you are reading a value.

Is the constant that you are reading.

Rules:

1. Data that is longer than 64,000 bytes cannot be EXEC IAF PUT intoan Oracle Reports object (the data will be truncated to the left–most64,000 bytes).

2. You must represent host variables and constants in standard SQLformat:

• strings and constants are passed as is

• dates are passed in the YYYYMMDDHH24MISS format

• host variables are prefixed with a colon (:)

The following table provides examples:

Value Result

Summit SportingGoods

Is how the constant string value, SummitSporting Goods, is passed.

413.60 Is how the constant numeric value, 413.60, ispassed.

19910414083000 Is how the date value, April 14, 1991, 8:30A.M., is passed.

:holder1 Is how the value of the host variable, holder1,is passed.

An EXEC ORACLE statement is a statement that is not standard SQLand is used to execute ORACLE Precompiler options. For moreinformation, refer to your Programmer’s Guide to the ORACLEPrecompilers.

report_variable

host_variable

constant

Syntax of a PassedUser Exit Call


Rules:

1. The ONSUCCESS and ONFAILURE keywords for R25DES andR25RUN determine whether Oracle Reports performs a COMMIT,a ROLLBACK, or nothing after a report runs or fails. If you wishto COMMIT at any other time, you can do so with your user exit.

Caution: Avoid using DDL when you specify READONLY. When youexecute a DDL statement (e.g., via SRW.DO_SQL or a user exit), aCOMMIT is automatically issued. If you are using READONLY, thiswill prematurely end the transaction begun by SET TRANSACTIONREADONLY. For more information, see “READONLY” on page 1 – 41.

Note: You can perform host language file I/O from a user exit.

Your user exit program will receive the user exit call as one string thatcontains first the user_exit_name and then optionally an argument_list.Arguments in the argument_list are separated by one space.

Examples:

1. The following call:

SRW.USER_EXIT(’quota 10 20 Q4’);

is passed to the user exit as:

’quota 10 20 Q4’

2. The following call:

SRW.USER_EXIT(’quota’);


’quota’

Rules:

1. It is the responsibility of the user exit—not Oracle Reports—toparse the user exit call string.

2. If more than one space exits between arguments that are passedwith the user exit name, Oracle Reports will delete the extra spacesbefore it passes the strings to the user exit.

Raising Errors from theUser Exit

Using the SRWERBError Buffer

Modifying the SampleSource File


For example, the following call:

’quota 10 20 Q4’


’quota 10 20 Q4’

In your user exit program, you can define an error message and raise itin Oracle Reports’ message region by copying the error string in theSRWERB error buffer.

Note: Within Oracle Reports, you can define and raise an errormessage via PL/SQL. For more information, see “Calling aUser Exit” on page 14 – 10.

You can define an error message in the user exit by writing the errorstring into a named 256 byte buffer, SRWERB. Oracle Reportsinitializes the SRWERB buffer when the report is executed. If, onreturning from a user exit, Oracle Reports finds the buffer non–empty(i.e., the first character in the buffer is not null), then Oracle Reportswill raise an error, using what it finds in the buffer as the errormessage.

Implementing User Exits

You implement user exits by modifying the sample source file.

To implement user exits, you can simply add entries to the samplesource file, ue_xtb.c, for each user exit. The location of this file varies byoperating system. For more information about it’s location, see theDeveloper/2000 Installation Guide for your operating system.

Following is the sample source file:

/* Define the user exit table */

extern exitr iapxtb[] = { /* Holds exit routine pointers */

”UE_OK”, ue_ok, XITCC,

”UE_ERR”, ue_err, XITCC,

”UE_MB”, ue_mb, XITCC,

”UE_EMP_PLAN”, ue_emp_plan, XITCC,

(char *) 0, 0, 0 /* zero entry marks the end */

};

/* end iapxtb */

Writing a User Exit Call

Syntax


The first item in the entry is the name (inside double quotes) you willuse in Oracle Reports to reference the user exit. The second item is theactual name of the user exit routine. The last item (XITCC) indicatesthat the user exit is called using C. For other languages, you would usethe following for this last item:

XITCOB /* COBOL */

XITFOR /* FORTRAN */

XITPLI /* PL/I */

XITPAS /* PASCAL */

XITAda /* ADA */

After modifying the source file, compile it and your user exit program.For more information, see the Developer/2000 Installation Guide for youroperating system. Next, link the resulting IAPXTB object file with theR25DES and R25RUN executable(s).

Calling a User Exit

This section covers two topics:

• writing a user exit call – 14 – 10

• checking for and raising errors – 14 – 13

You can call the user exit from any place in which you can enterPL/SQL within Oracle Reports. Use the following syntax:

[SRW.REFERENCE(:object_name_1);]

[SRW.REFERENCE(:object2_name_2); ...];

SRW.USER_EXIT(’user_exit_name [argument_list]’);

where:

Is the name of an Oracle Reports parameter orcolumn whose value will be passed to the user exitin the user exit string. This causes Oracle Reportsto build a dependency list: it will ensure that eachreferenced object will contain the most recentlycomputed or fetched value before it is passed tothe user exit.

Note: You must reference each parameter orcolumn separately. For details, see“SRW.REFERENCE” on page 13 – 53. For moreinformation, see “SRW.REFERENCE” on page13 – 53.

object_name_n


Is the name of the user exit to which you arepassing control. The user exit name may be anylength. (On some operating systems, the namemay be at most 6 characters. Check with yoursystem administrator.)

Can contain the names of parameters and columns,constants, character strings, or any combinationthereof, that you wish to pass to the user exit. Theargument list may be any length.

Note: The above syntax will need to be embedded in aPL/SQL program unit. For more information about PL/SQL,see “PL/SQL in Oracle Reports” on page 13 – 15.

Additional Information: If you want your user exit calls to beof the same format as user exit calls in Oracle Forms, you canuse SRW.USER_EXIT20 instead of SRW.USER_EXIT.

Examples:

1. Assume you have written a user exit (named INTEGRAL) thatcomputes the area under a curve, based on two points on thecurve. Also assume that you have two Oracle Reports columns(named POINT1 and POINT2) whose values contain the x and ycoordinates of the two points. To pass copies of the column valuesto the user exit, you must reference the column names usingSRW.REFERENCE. SRW.REFERENCE ensures that the values arecomputed before they are passed to the user exit.

Thus far, your PL/SQL should look like this:

srw.reference(:point1); srw.reference(:point2);

Now, you need to define the user exit call. To do so, you use theSRW.USER_EXIT procedure, and pass the following arguments:

• the user exit name (In this case, the name is INTEGRAL.)

• any arguments (In this case, the arguments are the OracleReports columns, POINT1 and POINT2.)

Now, your PL/SQL for the user exit call should look like this:

srw.reference(:point1); srw.reference(:point2); srw.user_exit(’integral point1 point2’);

user_exit_name

argument_list


Finally, assume that you want the user exit program to return(EXEC IAF PUT) the computed area into an Oracle Reports columnnamed AREA. To do this, you write a PL/SQL function and for itsRETURN argument, reference AREA.

Thus, your user exit call should look like this:

function compute_area return char is begin srw.reference(:point1); srw.reference(:point2); srw.user_exit(’integral point1 point2’);return(:area); end;

Notes: You reference AREA as the RETURN argument to ensure thatanother user exit will not PUT a value into the AREA column afterINTEGRAL does (i.e., all other user exit EXEC IAF PUTs into thiscolumn will occur before the INTEGER user exit fires). Becausecolumn formulas must return a value, you must write a functioninstead of a procedure. For more information, see “PL/SQL in OracleReports” on page 13 – 15.

Rules:

1. User exit names must follow the rules of your operating systemand host language. Be aware that these rules might include casesensitivity rules.

2. Maximum length of the user_exit_name is 10 characters (on someoperating systems the limit is 6 characters). Maximum length ofthe argument_list is 230 characters. Spaces are counted. Note: These limits may be operating–system dependent. See your systemadministrator for exact limits.

3. Arguments must be separated by spaces only. If more than one space exists between arguments in the argument_list, Oracle Reportswill delete the extra spaces before it passes the string to the userexit.

For example, the following call:

’quota 10 20 Q4’


’quota 10 20 Q4’

4. To reference a literal double quote within an argument list, use \”.The \ will be deleted before the argument is passed.

Checking for andDefining User ExitErrors in PL/SQL

Checking for ErrorsUsing SRW.USER_EXIT_FAILURE


5. If the argument_list contains the name of an Oracle Reports object(whose value you intend to pass to the user exit), you shouldreference the object name using the PL/SQL procedure,SRW.REFERENCE. SRW.REFERENCE will ensure that the objectcontains the most recently computed or fetched value before it ispassed to the user exit.

Note: There is no guarantee, however, that a user exit for a layoutobject will be calculated on the page on which the layout object isprinted.

6. If the user exit call is part of a PL/SQL value construct puttingvalues into other objects, the value construct should RETURN theOracle Reports object that owns the PL/SQL code. For example, ifyou write a PL/SQL function in the Formula field of the EMPcolumn, the function should RETURN the EMP column:RETURN(:EMP); . (This ensures that another user exit will not PUT avalue into the object after the user exit returns its value into theobject.)

In your PL/SQL code, you can check for errors, and define and raise anerror message using the following:

• SRW.USER_EXIT_FAILURE – 14 – 13

• SRW.MESSAGE – 14 – 14

Note: You can also define and raise a message in your user exitprogram. For more information, see “Raising Errors from theUser Exit” on page 14 – 9.

In PL/SQL, you can determine whether a user exit failed by using thePL/SQL packaged exception, SRW.USER_EXIT_FAILURE. Thisexception has a value of TRUE if the SRWERB buffer is non–empty;otherwise, it is FALSE. For more information on the SRWERB buffer,see “Raising Errors from the User Exit” on page 14 – 9.

For more information on SRW.USER_EXIT_FAILURE, see“SRW.USER_EXIT_FAILURE” on page 13 – 73.

Defining the ErrorMessage UsingSRW.MESSAGE


Examples: Assume you have a user exit called MYEXIT, and you wantto check if it failed. Your user exit call might look like that below:

begin

srw.user_exit(’myexit’);

exception

when srw.user_exit_failure then

srw.message(2000, ’The user exit MYEXIT failed.’);

when others then

srw.message (3000, ’Report error occurred before

user exit MYEXIT returned.’);

end;

Note: In this example, the error checking is in the body portionof the PL/SQL code. Alternatively, you could have put it in theEXCEPTION portion of the code. For more information onexceptions, see “PL/SQL Exceptions” on page 13 – 11.

In PL/SQL, you can define an error message and raise it in OracleReports’ message region with a PL/SQL packaged procedure,SRW.MESSAGE. (Note: You can also define and raise errors withinthe user exit program. For more information, see “Raising Errors fromthe User Exit” on page 14 – 9.)

SRW.MESSAGE has the following syntax:

SRW.MESSAGE (msg_number NUMBER, msg_text CHAR);

Thus, all you need to do is reference SRW.MESSAGE with any errornumber and string you wish. Below are examples of usingSRW.MESSAGE to raise an error.


Examples:

1. Suppose you have a user exit named STORE to which you want topass salary values from Oracle Reports. To do so, you could writethe following formula:

function foo return boolean is begin if :sal >= 0 then srw.reference(:sal); srw.user_exit(’store sal’); else srw.message(100, ’Found a negative salary. Check the EMP table.’); end if; exception when srw.unknown_user_exit then srw.message(200, ’STORE user exit was unknown. Check if it’’s linked.’); when srw.user_exit_failure then srw.message(200, ’STORE user exit failed. Check its code.’); return(true); end;

If the user exit fails and the user exit program does not write amessage to the SRWERB buffer, SRW.USER_EXIT_FAILURE will beFALSE, and Oracle Reports will not raise an error message. If theuser exit program does write a message to the SRWERB buffer,then SRW.USER_EXIT_FAILURE will be TRUE, and Oracle Reportswill raise the message, ”STORE user exit failed. Check its code.”

2. Assume you have a user exit named BIG_EXIT. Assume also thatBIG_EXIT contains code to check itself for errors in three differentlocations. If it finds an error, it will return (EXEC IAF PUT) one ofthe following values: A if portion A of BIG_EXIT failed, B ifportion B of BIG_EXIT failed, and C if portion C of BIG_EXITfailed. Your user exit call could look like this:

Procedure multi_errors is function inner return char is begin srw.user_exit(’big_exit’); return(:error); end; begin if :error=’A’ srw.message(100, ’Portion A of BIG_EXIT failed.’);elsif :error=’B’ srw.message(200, ’Portion B of BIG_EXIT failed.’);

RWEATS

Syntax


else srw.message(300, ’Portion C of BIG_EXIT failed.’); end if; end;

Packaged Oracle Reports User Exits

Oracle Reports has the following packaged user exits:

• RWEATS – 14 – 16

• RWECAT – 14 – 20

• RWECPF – 14 – 20

• RWECTY – 14 – 20

• RWEPLS – 14 – 21

This user exit converts an attribute value, stored in Oracle Reports’internal format, to an associated string retrieved from the OracleReports message file. This user exit is used by Oracle Reports whendocumenting your reports stored in the database usingFile—>Administration—>Report Doc.

SRW.USER_EXIT(’rweats source destination attribute_num ’);

where:

Is the table.column value to be converted.

Is the name of the Oracle Reports object into whichthe converted value will be placed.

Is the attribute number of the Oracle Reportsdatabase table column.

Table Column Attributes Description

SRW2_LAYOUT UNITS 1 Report Unit of Measurement

SRW2_PARAM_FORM UNITS 1 Parameter Form Unit of Measurement

SRW2_LAYOUT ORIENT 2 Panel Print Order

SRW2_LAYOUT RUN_FLAGS 3 Use Character Units in Designer

SRW2_LAYOUT RUN_FLAGS 4 Use Character Units in Browser

source

destination

attribute_num


Table DescriptionAttributesColumn

SRW2_LAYOUT RUN_FLAGS 5 Disable Host

SRW2_LAYOUT RUN_FLAGS 6 Disable Split

SRW2_LAYOUT RUN_FLAGS 7 Disable Zoom

SRW2_LAYOUT RUN_FLAGS 8 Start in Zoom

SRW2_LAYOUT RUN_FLAGS 9 Show Browser Title

SRW2_LAYOUT RUN_FLAGS 10 Show Browser Hint Line

SRW2_LAYOUT RUN_FLAGS 11 Show Browser Status

TOOL_PLSQL TYPE 12 Report Trigger Type

SRW2_LAYOUT SETTINGS 13 Display Settings–Report Section

SRW2_LAYOUT SETTINGS 14 Display Settings–Field Display

SRW2_LAYOUT SETTINGS 15 Display Settings–Show Comment Icons

SRW2_LAYOUT SETTINGS 16 Display Settings–Show Names

SRW2_LAYOUT SETTINGS 18 Display Settings–Show Field Outlines

SRW2_LAYOUT SETTINGS 19 Display Settings–Show BoilerplateOutlines

SRW2_LAYOUT SETTINGS 20 Display Settings–Show Frame Outlines

SRW2_LAYOUT SETTINGS 21 Display Settings–Show Page BreakIcons

SRW2_LAYOUT SETTINGS 22 Display Settings–Show Page ProtectIcons

SRW2_LAYOUT SETTINGS 23 Display Settings–Show Keep w/ Anchoring Icons

SRW2_LAYOUT SETTINGS 24 Display Settings–Show Anchors

SRW2_COLUMN SOURCE_ID 25 Column Source

SRW2_COLUMN COMPUTE_ID 25 Column Compute

SRW2_COLUMN RESET_ID 25 Column Reset

SRW2_FRAME GROUP_ID 25 Repeating Frame Group

SRW2_FIELD SOURCE_ID 25 Field Source

SRW2_FIELD PGN_RESET 25 Field Page Numbering Reset Repeating Frame

SRW2_COLUMN DATA_TYPE 26 Column/Parameter Datatype

SRW2_COLUMN FILE_TYPE 27 Column Format Type

SRW2_BOILERPLATE GRAPH_TYPE 27 Boilerplate Format Type Plate

SRW2_FRAME FORMATFLAG 28 Frame/RFrame Region



SRW2_FIELD FORMATFLAG 28 Field Region

SRW2_BOILERPLATE FORMATFLAG 28 Boilerplate Region

SRW2_OG_DOCUMENT FORMATFLAG 28 Oracle Graphics Document Region

SRW2_FRAME FORMATFLAG 29 Frame/RFrame Vertical Sizing

SRW2_FIELD FORMATFLAG 29 Field Vertical Sizing

SRW2_BOILERPLATE FORMATFLAG 29 Boilerplate Vertical Sizing

SRW2_OG_DOCUMENT FORMATFLAG 29 Oracle Graphics Document VerticalSizing

SRW2_FRAME FORMATFLAG 30 Frame/RFrame Horizontal Sizing

SRW2_FIELD FORMATFLAG 30 Field Horizontal Sizing

SRW2_BOILERPLATE FORMATFLAG 30 Boilerplate Horizontal Sizing

SRW2_OG_DOCUMENT FORMATFLAG 30 Oracle Graphics Document HorizontalSizing

SRW2_FRAME FORMATFLAG 31 Frame/RFrame Print Condition Type

SRW2_FIELD FORMATFLAG 31 Field Print Condition Type

SRW2_BOILERPLATE FORMATFLAG 31 Boilerplate Print Condition Type

SRW2_OG_DOCUMENT FORMATFLAG 31 Oracle Graphics Document Print Condition Type

SRW2_FRAME FORMATFLAG 32 Frame/RFrame Print Condition Object

SRW2_FIELD FORMATFLAG 32 Field Print Condition Object

SRW2_BOILERPLATE FORMATFLAG 32 Boilerplate Print Condition Object

SRW2_OG_DOCUMENT FORMATFLAG 32 Oracle Graphics Document Print Condition Object

SRW2_FRAME FORMATFLAG 33 Frame/RFrame Print Condition De-fault

SRW2_FIELD FORMATFLAG 33 Field Print Condition Default

SRW2_BOILERPLATE FORMATFLAG 33 Boilerplate Print Condition Default

SRW2_OG_DOCUMENT FORMATFLAG 33 Oracle Graphics Document Print Condition Default

SRW2_FRAME FORMATFLAG 34 Frame/RFrame Page Break Before

SRW2_FIELD FORMATFLAG 34 Field Page Break Before

SRW2_BOILERPLATE FORMATFLAG 34 Boilerplate Page Break Before

SRW2_OG_DOCUMENT FORMATFLAG 34 Oracle Graphics Document Page BreakBefore

SRW2_FRAME FORMATFLAG 35 Frame/RFrame Page Break After

SRW2_FIELD FORMATFLAG 35 Field Page Break After



SRW2_BOILERPLATE FORMATFLAG 35 Boilerplate Page Break After

SRW2_OG_DOCUMENT FORMATFLAG 35 Oracle Graphics Document Page BreakAfter

SRW2_FRAME FORMATFLAG 36 Frame/RFrame Page Protect

SRW2_FIELD FORMATFLAG 36 Field Page Protect

SRW2_BOILERPLATE FORMATFLAG 36 Boilerplate Page Protect

SRW2_OG_DOCUMENT FORMATFLAG 36 Oracle Graphics Document Page Protect

SRW2_FRAME FORMATFLAG 37 Frame/RFrame Keep w/Anchoring Object

SRW2_FIELD FORMATFLAG 37 Field Keep w/Anchoring Object

SRW2_BOILERPLATE FORMATFLAG 37 Boilerplate Keep w/Anchoring Object

SRW2_OG_DOCUMENT FORMATFLAG 37 Oracle Graphics Document Keep w/Anchoring Object

SRW2_FIELD ALIGNMENT 38 Field Justification

SRW2_BOILERPLATE ALIGNMENT 38 Boilerplate Justification

SRW2_QUERY MAX_ROWS 39 Query Maximum Rows

SRW2_GROUP GLF_TYPE 40 Group Filter

SRW2_GROUP CROSS_PROD 41 Group Cross Product

SRW2_GROUP PRODUCT_ID 42 Group Within Cross Product

SRW2_COLUMN FLAGS 43 Column Use in Break

SRW2_COLUMN FLAGS 44 Column Read from File

SRW2_COLUMN OPERATOR 45 Column Function

SRW2_FRAME DIRECTION 46 Repeating Frame Print Direction

SRW2_FRAME DIRECTION 47 Repeating Frame Column Mode

SRW2_FIELD FORMATFLAG 48 Field Hidden

SRW2_FIELD PGN_FLAGS 49 Field Page Numbering Include Header

SRW2_FIELD PGN_FLAGS 50 Field Page Numbering Include Body

SRW2_FIELD PGN_FLAGS 51 Field Page Numbering Include Trailer

SRW2_BOILERPLATE TYPE 52 Boilerplate Type (Character–mode)

SRW_DISPLAY_TAG FONTSTYLE 53 Font Style

SRW_DISPLAY_TAG FONTWEIGHT 54 Font Boldness

SRW_DISPLAY_TAG FONTSIZE 55 Font Size

SRW_DISPLAY_TAG DASHSTYLE 56 Dash Appearance

RWECAT

Syntax

RWECPF

Syntax

RWECTY



SRW_DISPLAY_TAG CAPSTYLE 57 Capital Letter Style

SRW_DISPLAY_TAG JOINSTYLE 58 Joined Line Style

SRW_DISPLAY_TAG LINEPAT 59 Line Pattern

SRW_DISPLAY_TAG FILLPAT 59 Fill Pattern

Rules:

1. If the specified source contains no value, the destination columnwill be blank.

This user exit concatenates strings, appending source to the end ofdestination.

SRW.USER_EXIT(’rwecat source destination’);

where:

Is the string to be concatenated.

Is the name of the Oracle Reports object into whichthe string will be placed.

This user exit copies the data in source and places the result indestination.

SRW.USER_EXIT(’rwecpf source destination’);

where:

Is the name of the Oracle Reports object whosevalue is to be copied.

Is the name of the Oracle Reports object into whichthe value will be placed.

Note: RWECPF is useful for LONGs, LONG RAWs, and RAWsbecause of PL/SQL’s 256–character limit. RWECPF supports64,000 bytes.

This user exit converts column properties and source information into acolumn–type string retrieved from the Oracle Reports message file.Input values should be the FLAGS and SOURCE columns from theSRW2_COLUMN table. This user exit is used by Oracle Reports whendocumenting reports stored in the database usingFile—>Administration—>Report Doc.

For more information on the structure of the SRW2_COLUMN table,see “SRW2_COLUMN” on page 18 – 15.

source

destination

source

destination

Syntax

RWEPLS

Syntax


SRW.USER_EXIT(’rwecty flag source destination’);

where:

Is the FLAGS column value from theSRW2_COLUMN table for the object whose valueis to be copied.

Is the name of the Oracle Reports object whosevalue is to be copied.

Is the name of the Oracle Reports object into whichthe value will be placed.

This user exit converts PL/SQL source stored in LONG RAW columnsinto PL/SQL source text. This user exit is used by Oracle Reportswhen documenting your reports stored in the database usingFile—>Administration—>Report Doc.

SRW.USER_EXIT(’rwepls source1 source2 destination ’);

where:

Is the MODID of the source object (e.g., a field)from the Oracle Reports tables.

Is the ID of the source object (e.g., a field) from thethe Oracle Reports tables.

Is a formula column of datatype Character that isassigned the text of the PL/SQL source.

Complete User Exit Example

This example illustrates the following:

• a call to a user exit (from within Oracle Reports) – 14 – 22

• the user exit – 14 – 22

A sample report that uses a user exit is shipped with Oracle Reports. Itis called userexit.rdf. The location of the report may vary according toyour operating system. For more information about subject, see theDeveloper/2000 Installation Guide for your operating system.

flag

source

destination

source1

source2

destination

User Exit Call

Example User Exit


Assume you would like to call the UE_EMP_PLAN user exit. From aformula column, you would enter the following function:

function CF_Set_PlanFormula return Number is

begin

/* Call User Exit to set the CP_PLAN Placeholder */

srw.user_exit(’UE_EMP_PLAN CP_PLAN’);

return 1;

exception

when srw.user_exit_failure then

/* User Exit did not return a string for this */

/* EMPNO value */

srw.message(1000,

’ User Exit did not return plan for Empno: ’||

to_char(:Empno));

:CP_Plan := ’No Plan’;

return 1;

end;

Following is an example user exit. This user exit can be found in thefile ue_samp1.pc. For more information about the location ofue_samp1.pc, see the Developer/2000 Installation Guide for your operatingsystem.

EXEC SQL INCLUDE SQLCA;

/* Define some local variables to be used in the testexit routine

below. */

EXEC SQL BEGIN DECLARE SECTION;

varchar targetcol[250]; /* name of target OR col */

varchar empid[50]; /* value of Empno OR col */

varchar plan[250]; /* Plan string */

EXEC SQL END DECLARE SECTION;#include <string.h>

#include <ue.h>


/*––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––+

| ue_emp_plan:

| ––––––––––––

|

| This is a PCC user exit that is meant to demonstrate on a very

| simple level the interaction between a PCC user exit and an

| Oracle Reports document. It demonstrates the following

| functionality:

| * Reading an Oracle Reports Column from within a User Exit

| * Setting an Oracle Reports Column from within a User Exit

| * Returning an error to Oracle Reports

| The only assumptions it makes are that it is called

| from an Oracle Reports document having the following columns:

|

| empno NUMBER (Value read in User Exit)

|

| This (somewhat contrived) example looks up a predefined table

| ”ue_samp_plan”, which associates different employees with a

| text string that indicates their plans, a favorite quote or

| personal philosophy. For example,

| Employee # Plan

| –––––––––– ––––

| 7856 ”Vacationing in Hawaii until Jan 1, 1995”

|

| In this user exit, we get the Employee Id from the Oracle

| Reports col EMPNO, look up the ”ue_samp_plan” table, get the

| associated ”plan” and set the <target> column specified in the

| parameter string. To illustrate error handling, we’ll return

| an error if the Employee Id does not exist in our table.

|

| The parameter string to this user exit should specify exactly

| 1 identifier which specifies the Target (Oracle Reports) column

| into which the ”plan” is to be copied. (This ilustrates the

| use of EXEC IAF PUT with host variables)

|

| For e.g, SRW.USER_EXIT(’ue_emp_plan PLAN’) will result in

|

| + Oracle Reports col EMPNO will be read into ”Empld”

| + Oracle Reports col PLAN will be set with the ”plan” string

| associated with the EmpId value.

| + If no match found, we raise an error.

|

| The Employee Ids in ue_samp_plan table match those in the

| SCOTT/TIGER DEMO tables.

|

+––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––*/


typedef struct empplan

{

int empid;

char *plan;

} empplan;

empplan ue_samp_plan[] =

{

{ 7369, ”Vacationing in Hawaii from Jan 1, 1995”},

{ 7499, ”Say No to Guns!”},

{ 7521, ”Help starving musicians. Learn music!”},

{ 7566, ”Electrons are 100% recyclable.”},

{ 7654, ”Impress CHRISTIE BRINKLEY w/ witty repartee on

NP–Completeness”},

{ 7698, ”Working on Production”},

{ 7782, ”Desktop – Oracle 7 for Windows”},

{ 7788, ”Because Its There”},

{ 7839, ”Goal: Retire At 45”},

{ 7844, ”Go Badgers!”},

{ 7876, ”Famous Last Words – It Should Work!”},

{ 7900, ”Attending IOUW – send email”}

/* 7902 & 7934 not included to demonstrate error handling */

};

int ue_emp_plan(ue_options, ue_strlen)

char *ue_options; /* command line */

int *ue_strlen; /* length of cmd line */

{

int i;

char *sep = ” ”; /* Token separators for parsing ue_options */

char *token;

/*––––––––––––––––––––––––––––––––––––––––––––––––––––––––––+

| Set up name of target Oracle Report col into which we move

| plan string

|

| Parm string gives us this name

+–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––*/

token = strtok(ue_options, sep); /* Name of UE */

token = strtok((char*) 0, sep); /* Parameter – Target Col */

(void) strcpy(targetcol.arr, token);

targetcol.len = strlen(ue_options);

/*––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––+

| Get EMPNO value – EXEC IAF GET. Note: empid is declared a

| VARCHAR so implicit conversion of NUMBER to VARCHAR happens.

+–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––*/

EXEC IAF GET EMPNO INTO :empid;


/*–––––––––––––––––––––––––––––––––––––––––––––––––+

| Look up empid in ue_samp_plan table

+–––––––––––––––––––––––––––––––––––––––––––––––––*/

for (i=0; i<sizeof(ue_samp_plan)/sizeof(empplan); i++)

{

if (ue_samp_plan[i].empid == atoi(empid.arr))

{

/*

| Found the empid, copy plan into target column.

| Target col name is in host variable ”targetcol”

*/

plan.len = strlen(ue_samp_plan[i].plan);

(void) strcpy(plan.arr, ue_samp_plan[i].plan);

EXEC IAF PUT :targetcol VALUES (:plan);

return 0; /* successful return */

}

}

/*–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––+

| Error Case: We didn’t find a match

|

| Set SRWERB to raise SRW.USER_EXIT_FAILURE exception. See ue.h

| for explanation.

+–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––*/

(void) strcpy(SRWERB, ”Error – No Plan found”);

return 1; /* Unsuccessful return */

}

C H A P T E R

15T

15 – 1Call Interface

Call Interface

he call interface enables you to call Oracle Reports’ executablesfrom 3GL programs you write. You should know the following aboutthe call interface:

• definition and purpose of the call interface – 15 – 2

• steps to build a procedure call into your program – 15 – 2

• procedure call syntax – 15 – 3

• procedure call error checking – 15 – 4

• procedure call rules – 15 – 4

• example programs that contain a procedure call to the R25RUNexecutable – 15 – 5

Note: For more information on how to call your 3GL programsfrom a report, see “User Exit Interface” on page 14 – 1.



A call interface is a set of standard procedures that you can call in your3GL programs. Oracle Reports is shipped with several suchprocedures (written in C)—one for each of the following Oracle Reportsexecutables:

Executable Procedure Names

R25CONV RWCCON, RW2CON

R25MREP RWCMOV, RW2MOV

R25RUN (bit–mapped) RWCRRB, RW2RRB

R25RUN (character mode) RWCRUN, RW2RUN

R25DES (bit–mapped) RWCSRB, RW2SRB

R25ISV (Windows) RWCSRV, RW2SRV

For example, assume that you have written a Pro*FORTRAN programand you want it to run an Oracle Reports report (using the character–mode R25RUN executable). To do so, you add a RWCRUN orRW2RUN procedure call to your program. (Details on which of thetwo procedures to use is discussed in the syntax portion of thischapter.)

Note: To use the call interface, your program must be writtenwith one of the ORACLE Programmatic Interface hostlanguages (Ada, C, COBOL, FORTRAN, Pascal, or PL/l).When you invoke R25CONV and R25MREP with the callinterface, you will get whichever executable (bit–mapped orcharacter–mode) is shipped for your platform.

Steps to Build a Procedure Call

We suggest the following steps to produce a program that contains aprocedure call to Oracle Reports:

1. Write a program using one of the ORACLE Programmatic Interfacehost languages (Ada, C, COBOL, FORTRAN, Pascal, or PL/l).Include in your program one or more procedure calls. Details onthe procedure call syntax are in the next section.

2. Compile your program. This will create an object file.

Examples in C


3. Each Oracle Reports procedure call was written in C. Those Cprograms were compiled, and their resulting object files wereshipped with Oracle Reports. Link your program with the OracleReports object file(s) it references.

Procedure Call Syntax

There are two types of procedures that are shipped with OracleReports:

• those that take one parameter (a valid Oracle Reports commandline for the executable being called)

• those that take two parameters (a valid Oracle Reports commandline for the executable being called, and the length of that string)

(The procedures that take two parameters are useful if yourprogramming language does not handle null–terminated strings.)

Below are the names of the Oracle Reports C procedures:

Executable Ptoc (1 param) Proc (2 params)

R25CONV RWCCON RW2CON

R25MREP RWCMOV RW2MOV

R25RUN—bit–mapped RWCRRB RW2RRB

R25RUN—character mode RWCRUN RW2RUN

R25DES—bit–mapped RWCSRB RW2SRB

R25ISV—Windows RWCSRV RW2SRV

Examples of the R25RUN procedure calls are (illustrated here in C):

Executable Procedure Name Procedure Call Syntax

R25RUN(b d)

RWCRRB long rwcrrb( / h /)(bit–mapped)

g( /*_ char _*/)

R25RUN(character mode)

RWCRUN long rwcrun( /*_ char _*/ )

R25ISV(Windows)

RWCSRV long rwcsrv( /*_ char _*/ )

R25RUN(character mode)

RWCRUN long rwcrun( /*_ char _*/ )

One–Parameter Call

Two–Parameter Call


Executable Procedure Call SyntaxProcedure Name

R25RUN(b d)

RW2RRB long rw2rrb( / h l / )(bit–mapped)

g( /*_ char *, long * _*/ )

R25RUN( h d )

RW2RUN long rw2run( / h l / )(character mode)

g( /*_ char *, long * _*/ )

R25ISV(Windows)

RW2SRV long rw2srv( /*_ char *, long * _*/ )

An example Oracle Reports R25RUN procedure call (in a typical Cprogram) follows:

long ret, rwcrun ();

if (ret = rwcrun (”report=areport userid=scott/tiger

myparam=AB”) )

goto error;

long len, ret, rw2run ();

len = 44;

if (ret = rw2run (”report=areport userid=scott/tiger

myparam=AB”, &len) )

goto error;

Procedure Call Error Checking

If the procedure call encounters an error, it will return a positivenumber to your program; otherwise, it will return a zero.

Procedure Call Rules

1. If a userid and password is included on the command line, as inthe examples above, Oracle Reports will attempt to log on to thatORACLE account.

2. If the calling program has already logged on to ORACLE, a userid and password should not be included in the command line, so thatOracle Reports will use the logon that is already active.

3. Oracle Reports will log off ORACLE only if it logged on. If thecalling program had previously logged on, the logon will still beactive on return from Oracle Reports.


4. The ONSUCCESS and ONFAILURE keywords for R25DES andR25RUN determine whether Oracle Reports performs a COMMIT,a ROLLBACK, or nothing after a report runs or fails.

5. The procedure call may be a maximum of 2047 alphanumericcharacters.

6. The Oracle Reports procedure calls (e.g., RWCRUN) are written in C. Depending on your host language (Ada, C, COBOL,FORTRAN, Pascal, or PL/l) compiler, the way in which you passarguments from your program to a C subroutine may differ. Referto your compiler documentation for more details on interfacingwith C procedure calls.

7. Oracle Reports can share a database connection with anotherproduct (e.g., Oracle Graphics) when both are run as part of thesame process. Note, however, that if Oracle Reports is specificallyrun in the background (e.g., SRW.RUN_REPORT withBACKGROUND=YES), the database connection cannot be shared.

Example Programs that Call R25RUN (RWCRUN)

Below are six example programs that make a procedure call to OracleReports’ R25RUN executable. Each program is written in a differentORACLE Programmatic Interface host language:

• Ada – 15 – 6

• C – 15 – 6

• COBOL – 15 – 7

• FORTRAN – 15 – 7

• Pascal – 15 – 8

• PL/l – 15 – 8

These example programs were run on VMS using standard VAXcompilers, and linked with the Oracle Reports library. To determinethe library name on your machine, see the Developer/2000 InstallationGuide for your operating system.

Note: The exact syntax of your subroutine calls may differfrom those below, depending on your host language compiler.

Ada

C


Below is an example of an Ada program that calls R25RUN:

with TEXT_IO; use TEXT_IO ;

procedure srwada is

usr : STRING(1..11) := ”Scott/Tiger”;

S : STRING(1..160);

RES : STRING(1..10);

LEN : INTEGER;

function rwcrun ( S : string) return Integer;

pragma interface (C,rwcrun);

pragma import_function ( internal = RWCRUN ,

PARAMETER_TYPES = (STRING),

MECHANISM = (REFERENCE),

RESULT_MECHANISM = VALUE,

RESULT_TYPE = INTEGER);

package INT_IO is new INTEGER_IO (INTEGER); use INT_IO;

ret_code : INTEGER;

begin

S(1..79) := ”REPORT=T USERID=SCOTT/TIGER PARAMFORM=NO

DESNAME=ADA.TXT DESTYPE=FILE BATCH=YES”;

S(80) := standard.ASCII.nul; –– null terminating

–– the string

PUT_LINE (” About to call rwcrun #1 ”);

ret_code := rwcrun (S);

if ret_code = 0 then

PUT_LINE(” Rwcrun was called successfully ”);

else

PUT_LINE(” the returned code is ”);

put (ret_code);new_line;

PUT_LINE (” Error occurred when Runform was called”);

end if;

end srwada;

Below is an example of a C program that calls R25RUN:

#include <stdio.h>

long ret,

rwcrun (),

rwcsql ();

COBOL

FORTRAN


main()

{

char options[132];

long len;

strcpy(options,”userid=scott/tiger report=t batch=yes

paramform=no destype=file desname=report.txt”);

printf(”\nOptions are: %s”, options);

len=strlen (options);

ret=rw2run(options);

printf (”\nValue of return code is %d”, ret);

exit();

}

Below is an example of a COBOL program that calls R25RUN:

IDENTIFICATION DIVISION.

PROGRAM–ID. COBREP.

ENVIRONMENT DIVISION.

DATA DIVISION.

WORKING–STORAGE SECTION.

*

01 OPTIONS.

02 OPTION–TEXTPIC X(132) VALUE ”REPORT=SAMPLE1

USERID=SCOTT/TIGER BATCH=YES PARAMFORM=NO DESTYPE=FILE

DESNAME=SAMPLE1.TXT”.

02 FILLER PIC S9(4) COMP VALUE 0.

*

01 RETURN–CODE PIC S9(9) COMP.

PROCEDURE DIVISION.

MAIN–PROGRAM.

CALL ”RWCRUN”

USING BY REFERENCE OPTIONS

GIVING RETURN–CODE.

DISPLAY ”Return code after first call to rwcrun is ”

RETURN–CODE

STOP RUN.

Below is an example of a FORTRAN program that calls R25RUN:

program fortran

integer*4 status

integer*4 rwcrun

character*100 command

command = ’report=test userid=system/manager batch=yes

1 destype=file desname=fortran.txt paramform=no’

Pascal

PL/l


status = rwcrun (%REF(command))

write(*,1) status

1 format(1x,I4)

end

Below is an example of a Pascal program that calls R25RUN:

PROGRAM srwpas(input,output);

Type

short = [WORD] –32768..32767;

OptType = packed array[1..256] of char;

[external] function rwcrun (var options : OptType) :

short Extern;

Var

Options : OptType;

RetCode : short;

Begin

Options := ’USERID=SCOTT/TIGER BATCH=YES REPORT=PASCAL

PARAMFORM=NO’;

Options[56] := CHR(0);

RetCode := rwcrun(options);

Writeln (’Return code from first call is ’, RetCode);

End.

Below is an example of a PL/l program that calls R25RUN:

PLI: PROCEDURE OPTIONS(MAIN);

DECLARE OPTIONS CHAR(100),

PART1 CHARACTER(79) DEFINED OPTIONS,

ENDCHAR CHARACTER(1) DEFINED OPTIONS POSITION (100);

DECLARE RWCRUN ENTRY (CHARACTER(100)) RETURNS (FIXED

BINARY(15));

DECLARE RETCODE FIXED BINARY(15);

PART1=’USERID=SCOTT/TIGER BATCH=YES REPORT=T

DESNAME=PLI.TXT DESTYPE=FILE PARAMFORM=NO’;

ENDCHAR = LOW(1);

PUT SKIP EDIT(’Options are: ’, OPTIONS) (A,A);

RETCODE = RWCRUN(OPTIONS);

PUT SKIP EDIT(’Return Code is ’, RETCODE) (A, B(15));

PUT SKIP(2) LIST(’************’);

END PLI;

C H A P T E R

16O

16 – 1Integrating with Other Products

Integrating with OtherProducts

racle Reports can be used in conjunction with a number of otherproducts. You should know about Oracle Reports integration with thefollowing:

• ORACLE7 – 16 – 2

• connecting to ORACLE and other databases (SQL*Net) – 16 – 2

• OLE2 – 16 – 4

• PL/SQL – 16 – 5

• Oracle Forms (includes SQL*Menu) – 16 – 5

• Oracle Graphics – 16 – 6

• Oracle Mail – 16 – 10

• Oracle Terminal – 16 – 10

• user exits – 16 – 10

• call interface – 16 – 10

SQL*Net


ORACLE7 Server

Oracle Reports supports the ORACLE7 Server, including the followingnew features:

• Stored Procedures. You can reference stored procedures fromanyplace in Oracle Reports that accepts PL/SQL.

Note: Stored procedures cannot reference PL/SQL that isdefined within Oracle Reports (e.g., external PL/SQL librariesand the SRW package). Stored procedures also cannot return avalue to Oracle Reports.

• National Language Support. Oracle Reports retrieves anddisplays data in the format defined by the National LanguageSupport facilities of the ORACLE7 Server.

Connecting to ORACLE and Other Databases

Oracle Reports is fully integrated with ORACLE. All Oracle Reportsreports are based on data in ORACLE. This data resides in tableswithin the data dictionary.

Oracle Reports accesses data in the database you reference in yourqueries. You can connect to a local database, a remote database(through SQL*Net), or other databases (through SQL*Net withSQL*Connect). In addition to getting data from the database, OracleReports can store reports in the database, if specified. For moreinformation about File—>Connect, refer to your online help.

You can also connect to other databases using ODBC. For moreinformation about ODBC, see the Developer/2000 Installation Guide foryour operating system.

SQL*Net lets you run Oracle Reports and other Oracle applicationsrapidly and efficiently on machines that are remote from ORACLE.You can use the most appropriate hardware without sacrificing anyaccess. In many cases, more users can be supported and resourcesharing for departmental computing is easy.

SQL*Net is an extension of the ORACLE architecture using networkcommunications between processes. It connects the ”client” (theapplication) to the ”server” (ORACLE), allowing for multipleconcurrent connections. Utilities and user programs run identically,whether data is local or remote.

Examples:


Use SQL*Net to connect to a remote database in order to access data touse in Oracle Reports. You must have SQL*Net installed on yoursystem and configured for the TCP/IP system. The general syntax forusing SQL*Net from the command line is:

R25DES username password@database_string

The syntax of the database_string for the TCP/IP protocol is:

T:[hostname:system_id, buffer_size]

Square brackets [] indicate optional information. T is the networkprefix for TCP/IP and must always be specified. You can omit anyoptional parameter, but you must include comma separators for anyparameter you skip.

Your ORACLE user identification.

Your ORACLE password.

The network prefix. For TCP/IP systems, thisprefix is always T (or t).

The name or alias of the remote system (or host)you want to connect to. This name must bedefined in the hosts file on your client system. Thedefault node is identified by the alias ”sqlnet”.

A single character that represents the system ID ofthe database you want to access on the remotesystem. This character must be defined in thedatabase listing file on the remote system. Thisparameter is case sensitive.

The size (in bytes) of the context area used by thedriver to pass data between ORACLE and TCP/IP.This value may be between 4 and 4096; largervalues result in faster transfer of data arrays butconsume more memory. The default in 4096.

1. This example shows how to use TCP/IP to connect to the OracleReports account SCOTT/TIGER on the host ”boston.” Thedatabase in this example has an ORACLE system_id of ”A.”

$ R25DES scott/tiger@T:boston:A

2. This example shows how to specify a buffer size for passing databetween ORACLE and TCP/IP.

$ R25DES scott/tiger@T:boston:A,2000

username

password

net_prefix

hostname

system_id

buffer_size

Including OLE2Objects

Including OLE2 Objects inthe Data Model

Including OLE2 Objects inBoilerplate

Activating OLE2Objects


OLE2

Oracle Reports is an OLE2 container. You can include OLE2 objects inyour reports. The sections that follow describe:

• including OLE2 object

• activating OLE2 objects

You can include OLE2 objects in a report in one of two ways:

• in the data model

• in a boilerplate object

OLE2 objects can be stored in the database or the filesystem. To accessOLE2 objects in the database, you first select the appropriate column inyour query. In the Column property sheet, you then select OLE2 forFormat. To include the object in your layout, you default the layoutand a field or a button (e.g., for video) is created for it. (If you do notwant to redefault the layout, you can also just create a field or a buttonin the Layout editor and select the OLE2 column as its Source.)

You can access OLE2 objects in files through the data model if you havea database column that contains the filenames of the objects. You selectthe column in your query and, in the Column property sheet, you thencheck Read from File and select OLE2 for its format. This tells OracleReports to treat the column’s contents as pointers to OLE2 objects.When you default the layout, the behavior is the same as if the OLE2objects were stored directly in the database.

To create an OLE2 boilerplate object in your report layout, you can doeither of the following:

• Use the OLE2 Object tool and draw a rectangle.

• Select Edit—>Insert Object.

In either case, the standard OLE2 dialog box will be displayed. Fill inand accept the dialog box to define the type, source, and whether theobject is linked or embedded. Note that all of these items must bedefined to create an OLE2 object. If you cancel out of the dialog box,the object is not created.

To activate an OLE2 object in your report layout, move your cursorover the object, and click and hold the right mouse button. Thisdisplays a pop–up menu. From the pop–up menu, select the Objectitem. The Object menu item brings up a submenu of actions that can beperformed by the object’s server.


PL/SQL

Oracle Reports Version 2.5 supports PL/SQL Version 1.0. WithinOracle Reports you can enter PL/SQL in the following places:

• external libraries – 13 – 16 • formulas – 13 – 25

• attached libraries – 13 – 16 • validation triggers – 13 – 27

• report triggers – 13 – 17 • format triggers – 13 – 28

• local program units – 13 – 22 • action triggers – 13 – 32

• group filters – 13 – 23

Oracle Reports also provides an integrated PL/SQL DevelopmentEnvironment for creating, compiling, and debugging PL/SQL. OracleReports also provides packaged PL/SQL procedures, functions, andexceptions that you can reference within Oracle Reports. For moreinformation on the use of PL/SQL within Oracle Reports, see “PL/SQLin Oracle Reports” on page 13 – 15.

Oracle Forms

You can reference an Oracle Reports report from Oracle Forms. Whenyou reference a report from Oracle Forms you can:

• pass no data or parameters (i.e., just run the report)

• pass data from the form to the report

• pass parameters from the form to the report

For more information on calling a report from Oracle Forms, refer toyour Oracle Forms User’s Guide.

Rules:

1. When calling a report from Oracle Forms, you cannot populate adetail query with a record group. You can only populate masterqueries with record groups.

2. Oracle Reports can share a database connection with anotherproduct (e.g., Oracle Forms) when both are run as part of the sameprocess. Note, however, that if Oracle Reports is specifically run inthe background (e.g., SRW.RUN_REPORT withBACKGROUND=YES), the database connection cannot be shared.

Referencing a Display


Oracle Graphics

You can reference an Oracle Reports report from Oracle Graphics andan Oracle Graphics display from Oracle Reports. For more informationon calling a report from Oracle Graphics, see the Oracle GraphicsReference Manual.

When you reference a display from a report, you have the option ofpassing data and/or parameters from your report to the display. Thesections that follow describe:

• referencing an Oracle Graphics display – 16 – 6

• executing a display each time it is called – 16 – 7

• passing data – 16 – 7

• passing parameters – 16 – 9

To reference a display, you create an Oracle Graphics object in theLayout editor with the Oracle Graphics tool. As with any other layoutobject, where you place the object determines where and howfrequently it will print. For example, placing an Oracle Graphics objectinside a repeating frame causes it to print once for each instance of therepeating frame.

After you create the Oracle Graphics object, you need to fill out itsproperty sheet. At a minimum, you must supply Oracle Reports withthe name of the Oracle Graphics display you want to reference (DisplayName on the O.G. Display tab). For more information on the OracleGraphics property sheet, see “Oracle Graphics Properties” on page8 – 73.

When you run the report, the display is executed and the output fromthe display is placed in the Oracle Graphics object that you created inthe Layout editor. If you do not specify any report columns orparameters to be passed from the report to the display, the display willretrieve its data from the database.

Note: You do not explicitly need to specify a databaseconnection for Oracle Graphics in this case. Oracle Reportswill either share the database session with Oracle Graphics orhave Oracle Graphics establish a second database session usingthe same logon string. Oracle Reports can share a databaseconnection with another product when both are run as part ofthe same process. Note, however, that if Oracle Reports isspecifically run in the background (e.g., SRW.RUN_REPORTwith BACKGROUND=YES), the database connection cannot beshared.

Executing a Display

Passing Data


In Oracle Graphics Version 2.5, displays are automatically updatedwhen opened, unless you specify otherwise.

In Oracle Graphics Version 2.0, you must enter a PL/SQL proceduresimilar to the following in the Timer or Open Trigger to ensure that thequery is executed each time you call the display:

procedure ex_query is

the_chart_query og_query;

begin

/* query the database to get the most current data */

the_chart_query := og_get_query(’queryname’);

og_execute_query(the_chart_query);

/* only refresh the chart if the data has changed */

if og_data_changed(the_chart_query) then

og_update_chart(og_get_object(’chartname’),

og_ALL_CHUPDA);

end if;

end;

For more information on using PL/SQL in Oracle Graphics, see theOracle Graphics Developer’s Guide.

When you reference a display, you may want to pass data from thereport to the display for the following reasons:

• If the report filters the data, you can have that filtering reflectedin the display. For example, if you use a group filter in yourreport to restrict a group’s records, then you should pass thedata from the report to the display. Otherwise, the displayfetches the data itself and the data used in the display will notreflect the group filter in the report.

• If the report contains a summary, you can use that summary inthe display. For example, if your report contains a percent oftotal summary that you want to use in your display, you need topass that summary to the display. Otherwise, you wouldsomehow have to create the same summary in the display.

• If the data used in the display has already been fetched by thereport, you can save the display from having to retrieve the dataagain.

Creating Your DisplayQuery

Mapping the Data


In order to pass data between a report and a display, you must do twothings:

• In the query for your display, select columns that ”match” thecolumns or parameters you want to pass from the report.

• In the O.G. Query tab of the Oracle Graphics property sheet inyour report, specify Display Query, select a Source, and map thecolumns or parameters in the report to the columns in thedisplay.

In the query for your display, you need to have columns in yourSELECT list that correspond to the columns or parameters you want topass from your report. The columns in the SELECT list must be of thesame datatype as the columns or parameters you intend to pass fromthe report. For example, suppose you are creating a display that willuse the following three columns from your report:

• RW_ENAME is a database column.

• RW_SAL is a database column.

• RW_PCT_TOTAL is summary column that computes whatpercent each employee’s salary is of the total salaries in thedepartment.

In your Oracle Graphics display, you write a query named query0 withthe following SELECT statement:

SELECT ENAME, SAL, 1 PCT FROM EMP

Notice that for each column that you are going to be passing from thereport, you have a corresponding item of the same datatype in theSELECT list of the query (ENAME for RW_ENAME, SAL for RW_SAL,and PCT for RW_PCT_TOTAL).

In the Oracle Graphics property sheet, you need to map the columns orparameters in the report to the columns in the display query. You dothis as follows:

1. In Display Query on the O.G. Query tab, enter the name of thequery used by the Oracle Graphics display.

2. In Source, select the group (or one of its ancestors) that contains thecolumns that map to the display columns and parameters

3. In the list of columns and parameters under Report Column, selectthe columns and parameters you want to pass to the display’squery.

Passing Parameters


4. For each report column or parameter you select, enter the name ofits counterpart in the display under Display Column.

Based on the example used in ”Creating Your Display Query” above,you would enter query0 for Display Query and map report columns todisplay columns as follows:

Report Column Display Column

RW_ENAME ENAME

RW_SAL SAL

RW_PCT_TOTAL PCT

When the display is called, rather than retrieving the values ofENAME, SAL, and DEPTNO from the database, it will retrieve thevalues of RW_ENAME, RW_SAL, and RW_PCT_TOTAL from yourreport.

In your Oracle Graphics display, you may have parameters that modifythe display’s output depending upon the value entered at runtime. Forexample, suppose your display uses the following query:


WHERE DEPTNO = :DNUMBER

The value of DNUMBER is provided to the display at runtime. Tosupply a value for a display parameter from your report, you map avalue in your report to the parameter. You do this as follows:

1. In the list of columns and parameters under Report Column on theO.G. Query tab, select the columns and parameters you want topass to parameters in the display.

2. For each report column or parameter you select, enter the name ofthe parameter in the display to which you want it passed underDisplay Parameter.

Based on our example above, you would map the report column to thedisplay parameter as follows:

Report Column Display Parameter

DEPTNO DNUMBER

At runtime, the value of DEPTNO in the report will be substituted forDNUMBER in the display.


Oracle Mail

When you run an Oracle Reports report, you can send the output of toOracle Mail users. To do this, you specify Mail for the DESTYPEparameter and the usernames for the DESNAME parameter. For moreinformation on the DESTYPE and DESNAME parameters, see“Parameter Properties” on page 6 – 45.

When you send output to Mail, Oracle Reports invokes a command file(srw2mail.sh) to call the Oracle Mail ORASEND utility. The DBAshould ensure that this command file sets up the Oracle Mail databasebefore ORASEND is called and resets to the Oracle Reports databaseon return from ORASEND.

Note: You can call any mail system from the command file, butonly Oracle Mail is supported.

Oracle Terminal

Oracle Reports requires mappings—key mappings and terminaldefinitions—to determine how it should operate when you press keys,and how it should display its windows. To create these definitions,you use Oracle Terminal. For more information on Oracle Terminal,see “Printer and Terminal Definitions” on page B – 1.

User Exit Interface

Oracle Reports can access any precompiled routine that you create withVersion 1.3 of an ORACLE Precompiler or a later version. Specifically,Oracle Reports considers the routine a user exit. You invoke theroutine through the SRW.USER_EXIT packaged procedure. Dependingon the contents of the routine, Oracle Reports can pass values to a userexit and a user exit can pass values back to Oracle Reports.

For more information on user exits, see “User Exits” on page 14 – 1.

Call Interface

A call interface is a set of standard procedures that you can call in your3GL programs. Oracle Reports is shipped with several suchprocedures. For more information, see “Call Interface” on page 15 – 1.

P A R T

IV Internals

C H A P T E R

17Y

17 – 1Performance and Tuning

Performance andTuning

ou should know about the following performance topics:

• performance monitoring – 17 – 2

• design interface – 17 – 3

• data model – 17 – 5

• layout – 17 – 11

• PL/SQL – 17 – 13

• execution – 17 – 15

• system – 17 – 18

For more information on tuning reports converted fromSQL*ReportWriter Version 1.1, see the Reports Migration Manual.

Note: The information that follows makes suggestions on howto improve the performance of your reports in Oracle Reports.These suggestions are intended as general principles forperformance tuning. Oracle Corporation does not warrant thatimplementing these suggestions will result in improvedperformance in every possible case.

Oracle Reports Tracing

SQL TRACE


Performance Monitoring

Before you start tuning your reports, you should gather performancestatistics to determine what, if any, performance problems you have.There are two ways to monitor performance:

• Oracle Reports tracing – 17 – 2

• ORACLE’s SQL TRACE facility – 17 – 2

The advantage of Oracle Reports’ tracing is that it provides detailedinformation on where the report time is being spent (e.g., fetching fromthe database, formatting the report, etc.). The advantage of SQLTRACE is that it provides you with the exact query information, whichyou can use to tune your queries.

The best way to monitor your report’s performance is to use OracleReports’ tracing executable arguments. To do so, you do the following:

1. Specify a filename using the TRACEFILE keyword on thecommand line or Trace File in the Trace Settings dialog box (viaTools—>Trace).

2. Specify TRACE_APPEND/REPLACE using the TRACEMODEkeyword on the command line or Trace Mode in the Trace Settingsdialog box (via Tools—>Trace).

3. Specify TRACE_ALL or TRACE_PRF using the TRACEOPTSkeyword on the command line or check All or Profile Messages inthe Trace Settings dialog box (via Tools—>Trace).

4. Run the report for which you want the performance data.

The TRACE function provides you with the exact statements that arebeing parsed. Once you have them, you can time them in SQL*Plus,and multiply these times with the expected number of rows to retrievefrom the database. (Always compare apples to apples, i.e., send outputto a file—not to the screen. Do not change anything in the SQLstatements when moving it to SQL*Plus; even the slightest change inthe WHERE clause can make a big difference in the performance.)

There are two ways to trace your reports: on a user level, and a systemlevel. We recommend the user level (because you can find more easilythe information you need), although the steps for both methods arebelow. For more information on SQL TRACE, see the ORACLE7 ServerSQL Language Reference Manual.


Performing a User–level Trace

1. Open the report for which you want the performance data.

2. Create a report–level formula column names SQL–TRACE that hasthe following formula:

SRW.DO_SQL (’ALTER SESSION SET SQL_TRACE=TRUE’);return(1); ––Formulas must return a value.

Note: You could also call SQL TRACE from the Before Formtrigger.

3. Run the report. A new file, <some_number>.trc will be created ineither ORACLE_HOME/rdbms/log, or the destination indicatedby the init.ora parameter USER_DUMP_DEST. (The date stamp onthe file can help you determine which .trc file is yours.)

4. Use the TKPROF command to format the trace output file.

(If you issue more than one trace during a your R25DES session,the trace outputs are concatenated into one file.)

Performing a System–level Trace

1. Insert these statements into your init.ora file: SQL_TRACE=TRUE and

TIMED_STATISTICS=TRUE.

2. Shutdown, then restart your database.

Every interaction with the database will be traced, and theORACLE_HOME/rdbms/log is likely to grow very large.

Design Interface Suggestions

Poor performance while building your reports in the designer isnormally a result of a missing (or improperly set) operating–system ordatabase resource. For more information, see the Developer/2000Installation Guide for your operating system.

Within Oracle Reports, you can do the following to increase the speedof the designer reports faster:

• specify design–time preferences – 17 – 4

• create templates for your reports – 17 – 4

Design Preferences

Report Templates


Use the following preferences to speed your report development

• Disable PL/SQL Compilation

• Suppress List Retrieval on Dialog Box Entry

• Object Access (of File System)

Rationale: Disabling PL/SQL Compilation stops Oracle Reports fromcompiling PL/SQL every time you accept a property sheet or leave aPL/SQL field. Suppressing List Retrieval on Dialog Box Entry, reducesthe amount of time it takes to bring up a dialog box because OracleReports does not have to retrieve the lists in the dialog box. SettingObject Access to File or Database bypasses the Display dialog box whenyou access files, other modules, or database objects.

If certain report elements are repeated in many of the reports youcreate, you should consider creating ”templates” for your reports. Youcreate and use a template as follows:

1. Create a report definition with only the common report elements(e.g, some boilerplate text or images) in it.

2. Save the report definition.

3. When you need to create a new report, open the report definitionthat you created to be a template.

4. Modify the report definition and save it under a different name.

Note: When you create a default layout for a report that usesyour template, make sure that you use the Default Layout tool.If you create a default layout from the Tools menu, it willoverwrite everything in the Layout editor.

Rationale: Using templates saves time because you do not have toalways recreate the same objects and settings each time you build anew report.

Number of Queries


Data Model Suggestions

This section describes performance tuning suggestions for the datamodel of your report. It includes the following topics:

• number of queries – 17 – 5

• SQL statements – 17 – 6

• Oracle Reports query modifications – 17 – 6

• indexes – 17 – 7

• SRW.DO_SQL statements – 17 – 7

• CDE_MM.GET_REF – 17 – 7

• maximum rows and group filters – 17 – 8

• unused data model objects – 17 – 8

• break columns – 17 – 9

• multiple layouts from one source – 17 – 9

• matrices – 17 – 9

Reduce the number of queries in your report as much as possible. Ingeneral, the fewer queries you have, the faster your report will run.While multi–query data models are often easier to understand,single–query data models tend to execute more quickly.

The only times you should use multi–query data models are:

• when you’re fetching many large columns from the parent andonly a few small columns from the child

• when you’re trying to do things that SELECT does not supportdirectly (e.g., multi–way outer join)

• when you have complex views (e.g., distributed queries orGROUP BY queries)

• when you need but don’t have or want to use a view

Rationale: For a one–query report, Oracle Reports opens only onecursor to fetch all of the master and detail records. For a two–queryreport, Oracle Reports opens two cursors—one for each query—afterappending the detail query’s link to the WHERE clause of the detailquery. Therefore, for each master record fetched in the master query,Oracle Reports must rebind, execute, and fetch data from the detailquery.

SQL Statements Faster

Oracle Reports QueryModifications


Performing operations in SQL is faster than performing them in OracleReports or PL/SQL. The list below explains the most common caseswhere using SQL would improve performance:

• perform calculations directly in your query rather than in aformula or summary

• use a WHERE clause instead of a group filter or Format Triggerto exclude records

• use the SUBSTR function to truncate character strings instead oftruncating in Oracle Reports

Rationale: SQL can perform calculations more quickly than a summaryor formula. WHERE and SUBSTR can reduce unnecessary fetchingbecause they operate on the data during rather than after data retrieval.

Oracle Reports modifies your queries in the following cases:

• For each link you create, Oracle Reports will append a clause tothe child query as specified in the link. For example, supposeyou have the following query:

SELECT DEPTNO, ENAME, SAL FROM EMP WHERE SAL > 1000

If you create a link to this query using DEPTNO as the childcolumn, a SQL Clause of WHERE, and a Condition of = (equalto), then your query would be modified as follows:

SELECT DEPTNO, ENAME, SAL FROM EMP WHERE (SAL > 1000) AND (DEPTNO = :DEPTNO)

Note: This is not true for multi–query matrix report datamodels. For more information, see “Matrices” on page 17 – 9.

• For each database column with Break Order set, Oracle Reportswill prepend an ORDER BY clause to the query, For example,suppose you have the following query:

SELECT DEPTNO, ENAME, SAL FROM EMP ORDER BY SAL

If you create a break group with DEPTNO as the break column,then your query would be modified as follows:

SELECT DEPTNO, ENAME, SAL FROM EMP ORDER BY 1, SAL

Indexes

SRW.DO_SQLStatements

CDE_MM.GET_REF


These SQL statements will be sent to the database, and it is then the jobof the SQL optimizer to determine the optimal way to get the data fromthe database and return it to Oracle Reports. The optimizer willdetermine whether to use indexes, which table to use as the ’driving’table in the query, etc.

Refer to your ORACLE7 Server Application Developer’s Guide for moreinformation on tuning SQL statements. Refer to your ORACLE7 ServerConcepts Manual for more information about the SQL optimizer.

Have indexes on columns used in the SELECT statements’ WHEREclauses, on database key columns, and on the table(s) in the detailqueries. Indexes have little impact on master queries because thosequeries access the database only once. However, indexes significantlyimprove performance of master/detail reports. The lower the ratio ofmaster to detail records, the more important indexes on the detailquery becomes for two–query reports.

Rationale: Indexes are recommended for tables in the detail queries,because Oracle Reports implicitly creates a WHERE clause from theparent/child relationships and adds it to the detail query.

Use the packaged procedure SRW.DO_SQL only when necessary. Inthose cases where it is necessary, assign it to a group that fetches only afew records, or to a report–level object (which will parse, open a cursor,and execute only once). SRW.DO_SQL enables you to add any DDL orDML operation to your report. This functionality is very valuable, butit can also be very expensive if used unwisely.

Rationale: Just like queries, SRW.DO_SQL statements are parsed, opena cursor to the database, and execute the statement. Unlike queries,however, an SRW.DO_SQL statement will do those things each time itsowner (e.g., a group) fetches data. (For example, if your SRW.DO_SQLstatement is owned by a group that fetches 10 records, the statementwill be parsed 10 times, 10 cursors will be opened, and the statementwill be executed 10 times.) For this reason, computations (e.g., :sal +:com) should be performed within the query or PL/SQL, instead ofSRW.DO_SQL owned by a group.

Only use the packaged procedure CDE_MM.GET_REF when necessary.

Rationale: CDE_MM.GET_REF is intended to reduce the amount oftemporary space used by Oracle Reports. Oracle Reports will notcache a column retrieved via CDE_MM.GET_REF in a temporary file.While this reduces the need for temporary space, it slows performancebecause the column’s values must always be retrieved from thedatabase.

Maximum Rows andGroup Filters

Unused Data ModelObjects


Use the Maximum Rows property in the Query property sheet (or theSRW.SET_MAXROW packaged procedure) to reduce the number ofrecords retrieved by the report’s queries. When designing a report thatfetches many records or accesses information across a network withmuch traffic, you may want to restrict the amount of data retrieved sothe report will run more quickly during testing.

Rationale: Maximum Rows in the Query property sheet restricts thenumber of records fetched by the query. A group filter determineswhich records to include and which records to exclude. SinceMaximum Rows actually restricts the amount of data retrieved, it isfaster than a group filter in most cases. If you are using a Filter of Lastor Conditional, Oracle Reports must retrieve all of the records in thegroup before applying the filter criteria. As a result, Maximum Rowsor a Filter of First is faster.

When you specify a Filter of First n for a group, Oracle Reportsretrieves as many arrays as necessary to get the first n records of thegroup. The size of the array retrieved is determined by theARRAYSIZE parameter. As a result, a Filter of First may retrieve morerecords than necessary. For example, if you specify a Filter of First 5and an ARRAYSIZE such that each array contains 10 records, 5 recordsthat will not be used by the report will be retrieved. When you specifyMaximum Rows for a query, Oracle Reports only retrieves the numberof records that you specify. A Maximum Rows setting of 5 results inonly 5 records being retrieved.

Typically, Maximum Rows is faster than a Filter of First because it onlyretrieves as many records as needed. The performance difference,however, may vary depending upon the ARRAYSIZE you havespecified.

Note: You should be cautious when using Maximum Rows forqueries upon which a group depends. For example, if you setMaximum Rows to 5 on a child query, then a summary of thechild contained in the parent group will only use the fiverecords that are retrieved by the query.

Make sure that you remove or suppress any data model objects that arenot actually used in your report. If your data model includes a querythat is only used in certain cases (i.e., when a parameter is set to acertain value), you can conditionally suppress the query with theSRW.SET_MAXROW packaged procedure. SRW.SET_MAXROW(queryname, 0) will cause the query to fetch no records.

Rationale: Oracle Reports processes everything in the Data Modeleditor. This can unnecessarily slow down your report unless youremove or suppress any unnecessary queries.

Break Columns

Multiple Layouts, OneSource

Matrices


When you create a break group, place as few columns as possible in thegroup. Whenever possible, keep the number of break columns perbreak group to one.

In addition, you should try to ensure that the break column is as smallas possible. A break column that is shorter in length will typically givebetter performance than a break column that is longer. For larger breakcolumns, it may help performance to use the SUBSTR function toreduce the length of the column.

Rationale: For each break group, Oracle Reports prepends its breakcolumns to the ORDER BY clause of the query. (The only exception tothis rule is when the break column is a formula column.) Byminimizing the number of break columns in your break groups, youminimize the number of columns that are added to the ORDER BYclause. The fewer the columns added to the ORDER BY clause the lessthe processing that needs to be done when the query runs. The size ofthe key that Oracle Reports uses internally to build indices will also besmaller, resulting in better performance.

If you want to display the same data more than once in the output, usethe same data model object as the source for all of the layout objects.Oracle Reports can display data from a single source multiple times inthe report output.

For example, suppose you want to display all employees who aremaking $2000 or more in one list and all employees making less than$2000 in another. To accomplish this, you write one query that selectsall of the data. Then you create two separate layouts based on the samedata. In one layout, the repeating frame will contain a Format Triggerthat only displays instances when SAL is $2000 or more. In the other,the repeating frame will contain a Format Trigger that only displaysinstances when SAL is less than $2000.

Rationale: A report that fetches the data once and lays it out multipletimes runs faster than a report that retrieves the data once for eachdifferent layout of the data.

You can improve the performance of matrix reports with:

• fewer queries

• WHERE clauses

Note: Cross–product groups always cause ”fetching ahead.”The reason for this is that to cross–tabulate the data in across–product group, Oracle Reports must first fetch all of thedata.

Fewer Queries

WHERE Clauses


As with other types of reports, fewer queries are faster. If possible, youshould use one query for your matrix reports to improve performance.

Rationale: For a one–query report, Oracle Reports opens only onecursor to fetch all of the master and detail records. For a multi–queryreport, Oracle Reports opens multiple cursors.

Consider adding a WHERE clause for the matrix filler query in amulti–query data model. If you are using a multi–query data modeland your dimension queries are restricted by a WHERE clause, addinga WHERE clause to the matrix filler query ensures that you do notretrieve more records than are necessary. For example, suppose thatyou had the following queries for your dimensions:

Q_Dept: SELECT DEPTNO FROM DEPT

WHERE DEPTNO < 100

Q_Job: SELECT DISTINCT JOB FROM EMP

WHERE DEPTNO < 100

To ensure that your filler query only retrieves the records that arenecessary, you would write the following SELECT statement:

Q_Filler: SELECT DEPTNO, JOB, SUM(SAL) FROM EMP

WHERE DEPTNO IN (SELECT DEPTNO FROM DEPT

WHERE DEPTNO < 100) AND JOB IN (SELECT

DISTINCT JOB FROM EMP WHERE DEPTNO < 100)

GROUP BY DEPTNO, JOB

If you did not add the WHERE clause to this query, all rows would beretrieved from the database, regardless of what you selected in Q_Deptand Q_Job.

Note: If you added a WHERE clause that did not use thesubqueries (e.g., WHERE EMP.DEPTNO = DEPT.DEPTNO),the query would be executed once for each combination ofvalues in the cross–product. This can lead to excessiveexecution of the filler query, if the cross–product has a lot ofcombinations.

Unused Frames


Rationale: Oracle Reports does not add a WHERE clause on the fillerquery in a multi–query matrix data model. The reason for this is toensure that the filler query will only be executed once. (Otherwise, thequery would be executed once for each combination of values in thecross–product.) However, if your dimension queries significantlyrestrict the number of records retrieved, the lack of a WHERE clause onthe filler query could cause a large number of unnecessary records tobe fetched. To avoid this, you can add the WHERE clause yourself.Since this method does incur the added overhead of subqueries,though, you should only use it if it will prevent a large number ofunnecessary records from being retrieved.

Layout Suggestions

This section describes performance tuning suggestions for the layout ofyour report. It includes the following topics:

• unused frames – 17 – 11

• transparent objects – 17 – 12

• non–graphical layout objects sizing – 17 – 12

• graphical layout objects sizing – 17 – 12

• image resolution reduction – 17 – 12

• word wrapping – 17 – 12

• formatting attributes – 17 – 12

• Format Trigger – 17 – 13

• total number of pages – 17 – 13

• Oracle Graphics integration – 17 – 13

Remove any unnecessary frames from the layout. When OracleReports creates a default layout for you, it puts frames around virtuallyeverything. The reason for this is to protect the objects in the framesfrom being overwritten by other objects in the output. If you knowfrom experience that the objects in a frame are not in danger of beingoverwritten, you can eliminate the frame without adversely affectingyour report output.

Rationale: The fewer objects in the layout, the fewer objects OracleReports must format at runtime. As a result, performance is betterwhen you reduce the number of objects in the layout.

Transparent Objects

Sizing forNon–Graphical Objects

Sizing for GraphicalObjects

Reduce ImageResolution

Word Wrapping

Formatting Attributes


Give layout objects (e.g., frames and repeating frames) a transparentborder and fill pattern.

Rationale: Transparent objects do not need to be rendered in aPostScript file. As a result, processing is faster when objects aretransparent.

Make your non–graphical layout objects (e.g., boilerplate text or fieldswith text) fixed in size, i.e., Vertical and Horizontal Sizing of Fixed. Inparticular, making repeating frames and their contents fixed in size canimprove performance.

Rationale: Non–graphical objects that are variable in size require moreprocessing because Oracle Reports must determine their size beforeformatting them. Non–graphical objects that are fixed in size do notrequire this additional processing because their size is already known.

Make your graphical layout objects (e.g., images and Oracle Graphicsobjects) variable in size, i.e., Vertical and Horizontal Sizing of Variable.

Rationale: Graphical objects that are fixed in size usually need to havetheir contents scaled to fit inside of the object. Scaling an object’scontents requires more processing. If the object is variable in size, itcan grow or shrink with the contents, and scaling is not necessary.

Use Format—>Drawing Options—>Reduce Image Resolution onimage objects whose size you reduce Layout editor.

Rationale: When you reduce the size of an image, it requires lessinformation to display it than when it was larger. Reduce ImageResolution eliminates the unnecessary information and reduces theamount of space needed to store the image. This can be particularlyuseful for large, multi–colored images.

Make fields that contain text one line long and ensure that theircontents fit within their specified width (e.g., by using the SUBSTRfunction).

Rationale: If a field with text spans more than one line, then OracleReports must use its word–wrapping algorithm to format the field.Ensuring that a field only takes one line to format avoids the additionalprocessing of the word–wrapping algorithm.

Minimize the use of different formatting attributes (e.g., fonts) withinthe same field or boilerplate text.

Rationale: If text in a field or boilerplate object contains numerousdifferent formatting attributes, it requires longer to format.

Format Triggers

Total Number of Pages

Oracle GraphicsIntegration


Place PL/SQL in the Format Trigger of the object with the lowestfrequency possible. For example, PL/SQL in the Format Trigger of aframe instead of a field typically makes the report run faster.

Rationale: The PL/SQL in Format Trigger is executed for each instanceof its object. The lower the frequency of the object, the fewer times thePL/SQL will be executed and the faster the report will run.

Limit your use of total number of pages (e.g., Total Number of LogicalPages) as the source of fields.

Rationale: When you use a total number of pages field source, OracleReports must save all of the pages in temporary storage in order todetermine the total number of pages. This can significantly increase theamount of temporary disk space used by Oracle Reports and theadditional writing to files can slow performance.

If an Oracle Graphics display referenced by a report uses some or all ofthe same data as the report, pass the data from the report to thedisplay.

Rationale: If the report and the display use the same data, passing thedata reduces the amount of fetching that needs to be done. If you donot pass the data from the report to the display, the data is actuallyfetched twice: once for the report and once for the display. For moreinformation about passing data from a report to a display, see “OracleGraphics” on page 16 – 6.

PL/SQL

This section describes performance tuning suggestions for PL/SQL inyour report. It includes the following topics:

• PL/SQL versus user exits – 17 – 14

• PL/SQL versus SRW.DO_SQL – 17 – 14

• ORACLE7 stored procedures versus local PL/SQL – 17 – 14

• local PL/SQL versus external PL/SQL libraries – 17 – 15

• SRW.SET_ATTR – 17 – 15

PL/SQL Versus UserExits

PL/SQL VersusSRW.DO_SQL forDML

Stored ProceduresVersus Local PL/SQL


Depending upon the circumstances, PL/SQL or a user exit mayperform better. Following are the items you should consider whendeciding between PL/SQL and user exits:

• If you need to make many references to Oracle Reports objects,PL/SQL is typically faster.

• If the report needs to be portable, or if the action is executed onthe group or report level, then use PL/SQL.

• If a report does not need to be portable use user exits, instead ofPL/SQL, to perform DML.

• User exits are especially beneficial when the action is executedfor each record in a large report, or requires a large number ofcomplex computations.

Rationale: PL/SQL is highly recommended, because it allows the codeto be procedural and still portable. PL/SQL also offers performanceadvantages when referencing report–level objects. User exits willperform better, but they require linking and are not portable. It makessense to include a user exit if the action required will be executed forevery record in a very large report or performs numerous calculations.

A PL/SQL procedure makes more sense if the action is only for eachgroup or at the report level. Furthermore, not everything can be donein PL/SQL; some actions like controlling external devices have to bedone in a C program.

Note: If there is no performance tradeoff or other good reasonto use a user exit, you should use PL/SQL because it is easierand portable.

Use PL/SQL for DML, unless you want to pass parameters to yourDML statements.

Rationale: Writing DML statements in PL/SQL is faster than anSRW.DO_SQL call containing the same statement. The reason to useSRW.DO_SQL for DML statements is that it can concatenate bindparameters to construct the DML statement. For example, you canhave SRW.DO_SQL create a table whose name is determined by aparameter entered on the runtime parameter form:

SRW.DO_SQL (’CREATE TABLE’ || :tname || ’(ACOUNT NUMBER

NOT NULL PRIMARY KEY, COMP NUMBER (10,2))’);

Use stored procedures for PL/SQL that performs database operations.Use local PL/SQL for PL/SQL that does not involve databaseoperations.

Local PL/SQL VersusExternal PL/SQLLibraries

SRW.SET_ATTR

Executable Arguments


Rationale: Because stored procedures run in ORACLE, they canperform database operations more quickly than PL/SQL that is local toyour report.

Exceptions: If you are on a heavily loaded network with very slowresponse time, using stored procedures may not be faster for databaseoperations. Similarly, if your server is significantly faster than yourlocal machine, then using local PL/SQL may not be faster fornon–database operations.

Write your PL/SQL as ”locally” as possible. Use the Program Unitsnode of your report in the Object Navigator instead of an externalPL/SQL library.

Rationale: Local PL/SQL executes more quickly than a reference to aprocedure or function in an external PL/SQL library. As a result, youshould only use external PL/SQL libraries when the benefits of sharingthe code across many applications outweighs the performanceoverhead.

Minimize the number of calls to SRW.SET_ATTR by specifying multipleattributes in one call. You can specify multiple attributes per call toSRW.SET_ATTR instead of making a separate call for each attribute.For more information, see “SRW.SET_ATTR” on page 13 – 58.

Rationale: The fewer calls you make to SRW.SET_ATTR, the faster thePL/SQL will run.

Execution Suggestions

This section describes performance tuning suggestions for theexecution of your report. It includes the following topics:

• executable arguments – 17 – 15

• the Previewer – 17 – 17

Oracle Reports has a number of executable arguments that can affectperformance. These arguments are listed below:

• ARRAYSIZE

• LONGCHUNK

• PARAMFORM

• RUNDEBUG

ARRAYSIZE

LONGCHUNK

PARAMFORM


• COPIES

• MODE

These arguments can be entered from a command line or the RuntimeSettings dialog box.

For Oracle Reports’ ARRAYSIZE executable argument (e.g.,ARRAYSIZE=10), enter as value as large as you can, especially if youare using Oracle Reports in a client–server environment. The array sizeis measured in kilobytes, not rows. ARRAYSIZE means that OracleReports can use that number of kilobytes of memory per query inexecuting your report.

Oracle Reports uses ORACLE’s array processing which fetchesmultiple records in batches, instead of one record at a time. As a result,you can control the amount of data to be fetched by the batchprocesses.

Rationale: The larger the array size, the more rows that can be fetchedsimultaneously; therefore, fewer calls to the database will be made.The benefit of increasing the array size is further noticed in adistributed environment, where network traffic is usually thebottle–neck, and overhead associated with the number of packets sentover the network is significant.

For Oracle Reports’ LONGCHUNK executable argument (e.g.,LONGCHUNK=10), enter a value as large as you can. (Refer to yourInstallation and User’s Guide for the recommended amount for yourmachine.) LONGCHUNK determines the size of the increments inwhich Oracle Reports will retrieve a LONG value. The LONGCHUNKsize is measured in kilobytes.

Rationale: By increasing LONGCHUNK as much as possible, you canreduce the number of increments it takes Oracle Reports to retrieveLONG values.

If you do not want to change the parameters in a report, you should setPARAMFORM=NO. This causes Oracle Reports to bypass the RuntimeParameter Form when you run the report.

Rationale: By hiding the Runtime Parameter Form when you don’tneed it, you eliminate an unnecessary step in running the report.

RUNDEBUG

COPIES

MODE

Previewer


Turn off the RUNDEBUG executable argument. RUNDEBUG causesOracle Reports to perform more error checking when it runs yourreport. This extra error checking is useful when you are designing areport, but, when a report goes into production, you probably nolonger need extra error checking. For more information aboutRUNDEBUG, see “RUNDEBUG” on page 1 – 28.

Rationale: The extra error checking done by RUNDEBUG slows downthe report.

When printing to PostScript, specify COPIES=1.

Rationale: If COPIES is set to something greater than one for aPostScript report, Oracle Reports must save the pages in temporarystorage in order to collate them. This can significantly increase theamount of temporary disk space used by Oracle Reports and theadditional writing to files can slow performance.

Select a MODE of Character to produce character–mode output. Notethat on Windows, this causes Oracle Reports to format the report usingthe Oracle Reports ASCII driver.

Rationale: A MODE of Character means that the report will beformatted directly in ASCII (rather than being formatted in PostScriptand converted to ASCII). In addition, the Oracle Reports ASCII driveris faster than the Generic/Text Only Windows driver.

Avoid ”fetching ahead” when sending report output to the Previewer.Avoiding fetch–aheads causes the first page to display more quicklythan it otherwise would.

Rationale: The Previewer is sometimes slowed by things that requirefetching ahead. For example, if the total number of pages in a reportappears on the very first page of the report, then the entire report mustbe processed before the first page can be displayed in the Previewer.

The following items can all result in fetching ahead when referencedbefore the data on which they rely:

• total number of pages/panels

• grand totals

• break columns that are formulas

• break columns that have Value if Null specified

Cross–product groups also cause fetching ahead. In order tocross–tabulate the data in a cross–product group, Oracle Reports mustfirst fetch all of the data.

Storage

File or Database Storage


It should be noted that these items are not really performance”problems.” They slow down the Previewer, but they do no affectperformance when writing to a file or some other destination.

Note: A column can cause fetching ahead even if it is notdisplayed. For example, a grand total may not appear in thereport output, but, since it is in the report, fetching ahead maystill occur when Oracle Reports calculates it.

System Suggestions

Oracle Reports performance will be strongly affected by theperformance of your overall system. This section describes what youcan do to improve performance based on your system. It includes thefollowing topics:

• storage – 17 – 18

• operating system setup – 17 – 19

• client/server – 17 – 19

The location in which you store things and how you search for themcan also affect performance. The list below shows the storage issuesthat can affect performance:

• storage location (file or database)

• file searching

• table sharing

Store modules in files to enhance performance. Store modules in thedatabase for security. If you open a report from or save a report to adatabase, some Oracle Reports tables will be put into memory. As aresult, you need to ensure that you have enough resources to cache thetables. For more information, see the Developer/2000 Installation Guidefor your operating system.

Rationale: For modules, writing to and reading from files tends to bemuch faster than the database.

Exception: If you must use a busy network or slow machine to accessthe files, you may not realize performance gains from storing in files.

File Searching

Table Sharing

Operating–SystemSetup

Client/Server


Specify path variables to speed up file searching and creation/access oftemporary files. (Recall that Oracle Reports provides two environmentvariables, REPORTS25_PATH and REPORTS25_TMP, that governwhere to search for files and where to store temporary files.)

For REPORTS25_PATH, specify the path in which files referenced bythe report are located. For REPORTS25_TMP, specify a path that hassufficient free space for temporary files and is on a device with fastresponse time (e.g., a RAM disk).

Rationale: REPORTS25_PATH is the default path in which OracleReports will search for files (e.g., link file boilerplate). By specifyingthe path in which the files referenced by the report are located, you canreduce the amount of searching Oracle Reports needs to perform toretrieve the files. (By using REPORTS25_PATH instead of hard–codingthe paths in the report definition, you also maintain the portability ofyour report.) REPORTS25_TMP is the path in which Oracle Reportswill create its temporary files.

Use one set of tables for several report designers. ORACLE enablesseveral report designers to share one set of Oracle Reports tables.

Rationale: Sharing tables enables you to share reports amongdevelopers, and only caches one set of tables. This will provide betterperformance when opening a report from or saving a report to thedatabase, and save some memory.

If you invoke an Oracle Reports executable, your operating systemaccount should have enough system resources to do so. (Proceduresare available for checking if a process is missing a needed resource.)For more information, see the Developer/2000 Installation Guide for youroperating system.

If you have a powerful server and a fast network, you may want tohave Oracle Reports running on the server. If not or if you plan ondoing a lot of interactive reporting (e.g., drill down), consider havingOracle Reports on your local machine. You should contact your systemadministrator to find out which of these arrangements is best for you.

Rationale: In a client/server environment, the performance of OracleReports can be seriously affected by the following:

• speed and load of the client and server machines

• the network traffic

C H A P T E R

18Y

18 – 1Storage

Storage

ou should know the following about Oracle Reports storage:

• file storage

– Oracle Reports file storage – 18 – 2

– preferences files – 18 – 5

– importan files shipped with Oracle Reports – 18 – 5

– temporary files – 18 – 8

– Oracle Reports’ file security and restrictions – 18 – 9

– Oracle Reports’ file–searching method – 18 – 9

– Oracle Reports’ environment variables – 18 – 10

• database storage

– Oracle Reports database tables (includes descriptions ofOracle Reports–specific tables and integrated Oracle toolstables) – 18 – 12

– database storage requirements – 18 – 31

– database table security and restrictions – 18 – 31

• Oracle Reports’ memory and disk space requirements – 18 – 32


Oracle Reports File Storage

Some systems allow (or require) you to append extensions to the end offile names when you save them. On these systems, Oracle Reportssuggests the following extensions:

File Contents? Portable? When Used? When Created?

.afc AIFC sound(binary file)

– in Previewer, associat-ed with button

Not created

.aff AIFF sound(binary file)


Not created

.au AU sound(binary file)


Not created

.avi Windows video(binary file)


Not created

.cal CALS image(binary file)

– in layout, parameterform painter

Edit—>Export

.bmp BMP image(binary file)


Edit—>Export

.cgm CGM drawing(binary file)


Edit—>Export

.gif GIFF image(binary file)


Edit—>Export

.jfi JFIF image(binary file)


Edit—>Export

.moo Quicktime video(binary file)


Not created

.odf Oracle drawing(binary file)


Edit—>Export

.oif Oracle image(binary file)


Edit—>Export

.pal color palette(binary file)


Edit—>Export

.pcx PCX image(binary file)


Edit—>Export

.pic PICT image(binary file)


Edit—>Export

18 – 3Storage

File When Created?When Used?Portable?Contents?

.pld PL/SQL library(text file)

YES File—>Administra-tion—>Convert use-ful for source–control-ling, and viewingwhen debugging (seeCaution, below)

File—>Save,File—>Save As

.pll PL/SQL library(binary file withsource/P–code)

YES, becausePL/SQL is re–compiledwhen open/run

Edit—>Attach Li-braries, then can ref-erence in any PL/SQL


.prt character modeprinter definition(text file)

Yes by the DESTYPE pa-rameter

R25MREP or any texteditor

.ras Sun raster image(binary file)


Edit—>Export

.rdf report definition(binary file withsource/P–code)

YES, becausePL/SQL is re– compiledwhen open/

File—>Open,File—>Run,File—>Administra-tion—>Convert fastert f / t

File—>Save,File—>Save As,File—>Administra-tion—>Convertp

run to open from/save tothis format than thethis format than thedatabase

.rep report definition(binary file withonly P–code)

YES, when itdoesn’t havecompiled PL/SQL

File—>Run preventsusers from reading/modifying the defini-tion, and is smallerthan .rdf file

File—>Administra-tion—>Generate,File—>Administra-tion—>Convert

.rex one or more re-port definitions(text file)

YES File—>Administra-tion—>Convert use-ful for source–control-ling, and viewingwhen debugging (seeCaution, below)

File—>Administra-tion—>Convert

.sql query definition(text file) (also,see Note, below)

YES Query property sheet(external query), alsoFile—>Import


.snd SND sound(binary file)

– in Previewer,associated with but-ton

Not created

Other Oracle ReportsFiles


File When Created?When Used?Portable?Contents?

.tif TIFF image(binary file)

– in layout,parameter form paint-er

Edit—>Export

.wav WAVE sound(binary file)

– in Previewer,associated with but-ton

Not created

Note: SQL scripts shipped with Oracle Reports are also fileswith extension .sql. For more information, see “Using SQLScripts” on page 19 – 2.

Caution: Oracle Corporation does not support modules that havebeen modified by editing .rex or .pld files.

Caution: Printer definition files are only used at runtime by reportsrun in a character–mode environment or reports run with the OracleReports ASCII Driver. For reports that run on bit–mapped platforms,printer codes and printer definitions are ignored, as their function isreplaced by the settings available from the Format menu (e.g., font andweight).

Caution: When you export an object from Oracle Reports to CGM, theobject may be broken into multiple objects in CGM. For example, ifyou export a rectangle that has a fill pattern, this object will becometwo objects in CGM. One object is created for the rectangle itself andone object for the fill pattern.

OLE2 Objects OLE2 objects can be displayed by Oracle Reports. ForOLE2 objects stored in the database, set Format in the Column propertysheet to OLE2. For OLE2 objects stored in files, select Read from Fileand set Format to OLE2 in the Column property sheet (this assumesthat the database column contains the names of OLE2 objects).

Depending upon the options you specify, Oracle Reports may generateany of the following files:

• profiler log file

• error log file

• trace log file

• preferences file

• keystroke file (character mode only)

• Print Screen log file (character mode only)

18 – 5Storage

For more information on files created by Oracle Reports, see“Determining Which Files Are Being Used” on page 19 – 6. Thepreferences file is described below.

Preferences Files

The preferences that you set via Tools—>Tools Options are saved andretrieved from a preferences file. (This file contains preferences for allother Oracle tools products as well.)

If you do not have your own preferences file, Oracle Reports getspreferences from a global preferences file created during installation.When you edit the preferences and save them, Oracle Reports createsyour own local preferences file. Once you have your own preferencesfile, Oracle Reports will use that file instead of the global preferencesfile.

The exact names and locations of these files may be operatingsystem–dependent. For more information, see the Developer/2000Installation Guide for your operating system. The contents of thepreferences file are portable, but, if you move it to another operatingsystem, you must ensure that you place it in the correct location withthe correct name for that platform.

Important Files Shipped with Oracle Reports

Six types of files that are shipped with Oracle Reports are especiallyimportant for users. These files include:

• executables – 18 – 6

• installation scripts – 18 – 6

• demo scripts – 18 – 6

• administration scripts – 18 – 6

• printer definition files – 18 – 7

• terminal definition files – 18 – 7

• font mapping file – 18 – 7

Executable Files

Installation Files

Demo Files

Administration Files


Note: The file information below is provided to help you learnabout Oracle Reports file types and their intended usage. Theexact names and locations of these files may be operatingsystem–dependent. For the exact names and their locations,see the Developer/2000 Installation Guide for your operatingsystem.

Executables are binary files that you use to invoke Oracle Reports,convert and run reports, etc.. Executables are either one–word names,which you can type (along with keywords) at a command prompt; oricons that you invoke from a bit–mapped desktop. The executables arecommonly found in the bin subdirectory or folder.

The Oracle Reports executables are listed below:

• R25CONV

• R25MREP

• R25RUN

• R25DES

For more information on R25CONV, R25RUN, and R25DES, see“Executables” on page 1 – 1. For more information on R25MREP, seethe Reports Migration Manual.

Installation files are SQL scripts used to install Oracle Reports. Formore information on the files you will use to install Oracle Reports, seethe Developer/2000 Installation Guide for your operating system.

Demo files have two file formats: .rex files and .sql scripts. The reportdefinitions in text file format (files with an extension of .rex) contain thedefinitions of the introductory and advanced reports discussed in theBuilding Reports Manual. The script files (files with an extension of .sql)create the sample database tables used by the introductory andadvanced reports. These files are commonly found in the demosubdirectory or folder.

Administration files are .sql scripts with which you can performadministrative tasks more quickly and easily. These scripts arecommonly found in the admin subdirectory or folder.

For more information on .sql scripts, see “Using SQL Scripts” on page19 – 2.

Printer Definition andDriver Files

Terminal DefinitionFiles

Font Mapping File

18 – 7Storage

Printer definition files (files with an extension of .prt) are text files (e.g.,ASCII, EBCDIC) containing definitions (label and formatting codes) forone or more types of printers. There are several printer definition filesshipped with Oracle Reports which are commonly found in theORACLE_HOME/reports25/admin/printer subdirectory or folder.

Caution: Printer definitions are not necessary for reports that youplan to run on bit–mapped platforms. They are optionally used byreports designed to run in a character–mode environment.

There are two types of terminal files shipped with Oracle Reports:

Are text files with entries for the various terminaltypes and their key mappings.

Are binary files, created via the Oracle Terminalutility, that uniquely identify the various terminalsand their corresponding key mappings.

All of the terminal definition files are commonly found in either your$APIPATH or the ORACLE_HOME/reports25/admin/terminal directory orfolder. Installation on your platform may differ. For more information,see “Creating or Modifying Terminal Definitions” on page B – 15.

Caution: Terminal definition files are not necessary for reports thatyou plan to run on bit–mapped platforms. They are only necessary iffor reports designed to run in a character–mode environment.

Oracle Reports supports font aliases. The font mappings used byOracle Reports are defined in the file uifont.ali. You can alter thesemappings by editing this file. The location of this file varies accordingto your operating system. For more information on the files you willuse to install Oracle Reports, see the Developer/2000 Installation Guidefor your operating system.

Note: Oracle Reports will look for the font mapping file in the locationspecified via the environment variable TK2_FONTALIAS. IfTK2_FONTALIAS is not specified, Oracle Reports will look in thedefault location for your operating system.

Terminal/keydefinition files

Terminal/key files


Temporary Files

Oracle Reports creates the following temporary files during reportexecution:

• Swap files are created when you run a report that requiresmultiple passes to format (e.g., a report that has forwardreferences such as a field with Source of &Total Logical Pages).The swap file contains a first pass copy of each page of the reportthat Oracle Reports uses to determine the length of the reportand resolve any forward references. By the time all of the pageshave formatted, this file will be approximately twice the size ofthe final ouput. While developing a report, you should excludeforward referencing fields to cut down on testing time.

Swap files are named a unique identifier.

• Data cache files are used to cache all the data records fetchedfrom the database and the values of all summaries in the report.The size of this file reflects the amount of data in the report.Records are packed such that the space allocated for eachcolumn is just enough to contain the current value, not themaximum size for each column.

Data Cache files are named datXXXX, where XXXX is unique.

• Index files are used to track breaks in the report. This filecontains tree structures built to traverse the data according to therelationships defined in the report’s data model. The size of thisfile depends upon:

– the number of groups in the report

– the number of records in each group

– the size of the break column(s) of each group

– the depth of the group tree

Index files are named idxXXXXX, where XXXX is unique.

Additional Information: You can control where OracleReports places temporary files using REPORTS25_TMP. Formore information, see “REPORTS25_TMP” on page 18 – 11.

Temporary File Size

18 – 9Storage

Temporary files can grow very large for a number of reasons. To avoidhaving large temporary files, consider the following:

• Perform calculations in queries, if possible. This can reduce thesize of data caching file because the report does not need toretrieve as much data as it would if the calculations wereperformed in summary columns or formulas.

• Reduce the size and number of break columns per break group,if possible. This can reduce the size of the index file because itreduces the size of the tree structure in the file.

• Eliminate forward referencing (e.g., fields with Source of &TotalLogical Pages), if possible. This can eliminate the swap filebecause Oracle Reports does not have to save a copy of thereport output in the swap file before formatting.

File Security and Restrictions

Oracle Reports uses your operating system environment to determinethe security of modules stored in files. The way in which you acquirepermission to access modules stored in files is operatingsystem–dependent. For more information, refer to your operatingsystem manual.

File–Searching Method

When you reference a file in Oracle Reports, it searches for the file inthe following order:

1. The path prefixed to the filename (e.g., /home/jsmith), if any.

2. The path that your operating system considers the current path.

3. The path specified in the environment variable REPORTS25_PATH.

4. The path specified in the environment variable ORACLE_PATH.

5. Your location when you invoked Oracle Reports.

Note: If you do not enter an extension, Oracle Reportsappends one before performing the search. If the file is notfound, Oracle Reports then searches for the file without theextension.

For more information about printer and terminal definition searchorder, see “Printer and Terminal Definistions” on page 18 – 10.

Printer and TerminalDefinitions

Printer Definitions

Terminal Definitions

Icon Files


For more information icon file search order, see “Icon Files” on page18 – 10.

In character–mode environments, you may use printer and terminaldefinition files.

Printer definitions are searched for as follows:

1. The path that your operating system considers the current path.

2. The path specified in the environment variable REPORTS25_PATH.

3. The path specified in the environment variable ORACLE_PATH.

4. The ORACLE_HOME/reports25/admin/printer subdirectory or folder.

Terminal definitions are searched for as follows:

1. The path specified in the environment variableREPORTS25_TERMINAL.

2. The path specified in the environment variableORACLE_TERMINAL.

3. The ORACLE_HOME/reports25/admin/terminal subdirectory orfolder.

If you create a button in Oracle Reports, you can assign it an iconinstead of a label. If you do not specify the full path for the icon,Oracle Reports will search for it in the path defined by the TK21_ICONenvironment variable.

Oracle Reports Environment Variables

In addition to environment variables provided by ORACLE and yourbase operating system, Oracle Reports provides environment variablesyou can use to define default directories for various Oracle Reportsfiles. These environment variables are:

• REPORTS25_PATH – 18 – 11

• REPORTS25_TERMINAL – 18 – 11

• REPORTS25_TMP – 18 – 11

• TK21_ICON – 18 – 12

REPORTS25_PATH

REPORTS25_TERMINAL

REPORTS25_TMP

18 – 11Storage

Purpose: This environment variable is used to locate reports andexternal objects that you use in your reports, such as PL/SQL libraries,external queries, and external boilerplate. It enables you to createreports that are easily portable across operating systems by preventingthe need to hard–code directory paths.

Creation: Define REPORTS25_PATH in the same fashion you defineother environment variables on your operating system, keeping inmind such platform–specific rules as path length, etc..

In addition to directory paths, you can specify the keyword DB whenyou define REPORTS25_PATH. This instructs Oracle Reports to searchthe database to which you are currently connected.

Examples:

1. Suppose you specified the following on a Unix platform:

setenv REPORTS25_PATH

/home/tkostin/pay:/home/tkostin/receive:DB

Oracle Reports will first search the directory /home/tkostin/pay .If it cannot find the file in question, it will search/home/tkostin/receive . If it still cannot find the file, it will searchthe database to which you connected when you began your OracleReports session.

If you don’t define REPORTS25_PATH, Oracle Reports will firstsearch the current directory. If the file is not there, it will searchORACLE_HOME/reports25.

For more information about REPORTS25_PATH, see the Developer/2000Installation Guide for your operating system.

Purpose: This environment variable is used to locate terminaldefinitions that you use in your character–mode reports. The path youspecify for this variable takes precedence over theORACLE_TERMINAL environment variable.

Creation: Define REPORTS25_TERMINAL in the same fashion youdefine other environment variables on your operating system, keepingin mind such platform–specific rules as path length, etc..

Purpose: This environment variable establishes the directory in whichyou wish to store Oracle Reports temporary files. Oracle Reports willuse only one directory for this purpose; do not define more than one.

Creation: Define REPORTS25_TMP in the same fashion you defineother environment variables on your base operating system, keeping inmind such platform–specific rules as path length, etc.

TK21_ICON

Oracle Reports Tables


If you don’t define REPORTS25_TMP, it will default to the temporarydirectory used by your base operating system.

For more information about REPORTS25_TMP, see the Developer/2000Installation Guide for your operating system.

Purpose: This environment variable establishes the directory in whichyou wish to store icons used for buttons in your layout. Oracle Reportswill use only one directory for this purpose; do not define more thanone.

Creation: Define TK21_ICON in the same fashion you define otherenvironment variables on your base operating system, keeping in mindsuch platform–specific rules as path length, etc..

Database Table Storage

There are three sets of tables used with Oracle Reports:

Contain sample data used by the introductory andadvanced reports documented in Building ReportsManual.

Contain your own data.

Contain reports, external queries, and externalPL/SQL libraries.

Knowing about the Oracle Reports tables enables you to:

• modify the ”report on reports”, which are reports shipped withOracle Reports that run against the Oracle Reports tables

• create your own reports that run against the Oracle Reportstables

When you save a module to the database, its definition is stored in theOracle Reports tables. These tables comprise the following:

• Oracle Reports–specific tables – 18 – 13

• integrated Oracle product tables – 18 – 27

For security purposes, Oracle Reports provides a view of each of itstables. The descriptions that follow are of the views of these tables,except where noted.

Demo tables

Data tables

Oracle Reportstables

Oracle Reports–specific Tables

SRW2_ANCHOR

SRW2_BODY_LOCATION

18 – 13Storage

Caution: Oracle Corporation does not guarantee the functionality orintegrity of modules whose table definitions have been modified viaSQL*Plus (or another database tool) not specifically intended to modifythe Oracle Reports tables. Also, be aware that Oracle Corporationreserves the right to change the names or structures of its tables at anytime and without notice.

Oracle Reports–specific tables contain module and report–level objectdefinitions. These tables are used solely by Oracle Reports, and are notshared with other Oracle products. Through the use of views andpublic synonyms, users can see information about modules they ownor to which they have been granted access.

Name Null? Type Comment

OWNER NOT NULL VARCHAR(30) Report Owner

MODID NOT NULL DECIMAL(10) Report ID

ITEMID NULL DECIMAL(10) Anchor ID

TAG NULL DECIMAL(10) Display Tag

DISP_ORDER NULL DECIMAL(5) Anchor Display List Order

HEAD_ID NULL DECIMAL(10) Anchor Head ID

HEAD_EDGE NULL DECIMAL(2) Edge of Parent Object

HEAD_PCT NULL DECIMAL(8) Percent Across Parent Object Edge

TAIL_ID NULL DECIMAL(10) Anchor Tail ID

TAIL_EDGE NULL DECIMAL(2) Edge of Anchored Object

TAIL_PCT NULL DECIMAL(8) Percent Across AnchoredObject

NUM_POINTS NULL DECIMAL(2) Number of Points

POINTS NULL RAW(250) Anchor Points

COLLAPSE NULL DECIMAL(1) Collapsible Anchor




START_X NULL DECIMAL(10) Horizontal Starting Point

SRW2_BOILERPLATE


Name CommentTypeNull?

START_Y NULL DECIMAL(10) Vertical Starting Point

LOC_ORDER NULL DECIMAL(5) Location Order




ITEMID NULL DECIMAL(10) Boilerplate ID

NAME NULL VARCHAR(30) Boilerplate Name


DISP_ORDER NULL DECIMAL(5) Boilerplate Display ListOrder

FORMATFLAG NULL DECIMAL(10) Format Flags

PRE_CODE NULL VARCHAR(250) Before Object PrinterCode

POST_CODE NULL VARCHAR(250) After Object Printer Code

X NULL DECIMAL(10) Boilerplate X–Coordinate

Y NULL DECIMAL(10) Boilerplate Y–Coordinate

WD NULL DECIMAL(10) Boilerplate Width

HT NULL DECIMAL(10) Boilerplate Height

PAGE NULL DECIMAL(5) Page on which Object Appears

TYPE NULL DECIMAL(5) Polygon Type


POINTS NULL RAW(250) Boilerplate Points

POINTSLFID NULL DECIMAL(10) Pointer to LONG

CLOSE NULL DECIMAL(1) Closed Object

ARCFILL NULL DECIMAL(1) Fill Pattern for Arc

ARROWSTYLE NULL DECIMAL(1) Arrow End Style

ROTANGLE NULL DECIMAL(5) Rotation Angle

GRAPH_TYPE NULL DECIMAL(5) Type of Graphic Format

GRAPH_LFID NULL DECIMAL(10) Pointer to LONG

GRAPH_LEN NULL DECIMAL(10) Length of Graphic

LINKEDFILE NULL VARCHAR(250) Link File

SRW2_COLUMN

18 – 15Storage


MIN_WIDOWS NULL DECIMAL(5) Minimum Number of WidowLines

MIN_ORPHAN NULL DECIMAL(5) Minimum Number of OrphanLines

MAX_LINES NULL DECIMAL(5) Maximum Number of Lines

TEXT_WRAP NULL DECIMAL(2) Text Wrap Style

ALIGNMENT NULL DECIMAL(5) Boilerplate Alignment

SPACING NULL DECIMAL(10) Text Spacing

OLE_LFID NULL DECIMAL(10) Pointer to LONG

OLE_LEN NULL DECIMAL(10) Length of OLE object




ITEMID NULL DECIMAL(10) Column ID

NAME NULL VARCHAR(30) Column Name


DISP_ORDER NULL DECIMAL(5) Column Display Order

GROUP_ID NULL DECIMAL(10) Group ID

SOURCE NULL DECIMAL(2) Column Source Name

SOURCE_ID NULL DECIMAL(10) Column Source ID

COMPUTE_ID NULL DECIMAL(10) Compute Group (% of Totals)

RESET_ID NULL DECIMAL(10) Reset Group ID

PROD_ORDER NULL VARCHAR(250) Product Order

NULL_VALUE NULL VARCHAR(250) Value if Null

INPUT_MASK NULL VARCHAR(250) Format Mask

OPERATOR NULL DECIMAL(2) Aggregation Function

DATA_TYPE NULL DECIMAL(2) Column Datatype

FILE_TYPE NULL DECIMAL(2) File Type/Read rom File

WIDTH NULL DECIMAL(10) Maximum Value Width

FLAGS NULL DECIMAL(5) Column Flags

PRECISION NULL DECIMAL(5) Value Precision

SCALE NULL DECIMAL(5) Value Scale



X NULL DECIMAL(10) X–Coordinate

Y NULL DECIMAL(10) Y–Coordinate

WD NULL DECIMAL(10) Column Width

HT NULL DECIMAL(10) Column Height

DFLT_LBL NULL VARCHAR(250) Default Column Label

DFLT_WID NULL DECIMAL(5) Default Column Width

DFLT_HGT NULL DECIMAL(10) Default Column Height

DEREF_ID NULL DECIMAL(10) Development EnvironmentID

ODATA_TYPE NULL DECIMAL(2) ORACLE Datatype

PARA_TYPE NULL DECIMAL(2) Parameter Datatype

PLOV_RTYPE NULL DECIMAL(2) List of Values Type

PLOV_SLISTID NULL DECIMAL(10) LOV Listid

PLOV_SELECT NULL VARCHAR(250) LOV SELECT Statement

PLOV_COL NULL VARCHAR(250) LOV Column

REFDTYPE NULL DECIMAL(2) Reference Datatype

SRW2_DATA_MODEL

SRW2_DISPLAY_TAG

18 – 17Storage




ITEMID NULL DECIMAL(10) Data Model ID

SETTINGS NULL DECIMAL(10) Display Settings

DFLT_TYPE NULL DECIMAL(5) Default Type

ZOOMPOWER NULL DECIMAL(5) Magnification

WINDOW_X NULL DECIMAL(10) Horizontal Window Location

WINDOW_Y NULL DECIMAL(10) Vertical Window Location

WINDOW_WD NULL DECIMAL(10) Window Width

WINDOW_HT NULL DECIMAL(10) Window Height

UIFLAGS NULL DECIMAL(10) Painter Settings Flag

GRIDINTC NULL DECIMAL(10) Grid Spacing

GRIDSNPC NULL DECIMAL(10) Number of Snap Points PerGrid Spacing

HALIGN NULL DECIMAL(1) Horizontal Alignment

VALIGN NULL DECIMAL(1) Vertical Alignment

DECURREF_ID NULL DECIMAL(10) Reference ID Counter




ITEMID NULL DECIMAL(10) Display Tag ID

CM_TEXT NULL VARCHAR(250) Text Attributes

CM_FILL NULL VARCHAR(250) Fill Attributes

CM_BORD NULL VARCHAR(250) Border Attributes

PENWID NULL DECIMAL(10) Pen Width

ADD_FLAGS NULL DECIMAL(10) Flags for Image Information

TEXTPAT NULL DECIMAL(5) Text Pattern

TEXTFORE NULL DECIMAL(5) Text Foreground Color

TEXTBACK NULL DECIMAL(5) Text Background Color

SRW2_ELEMENT



LINEPAT NULL DECIMAL(5) Line Pattern

LINEFORE NULL DECIMAL(5) Line Foreground Color

LINEBACK NULL DECIMAL(5) Line Background Color

FILLPAT NULL DECIMAL(5) Fill Pattern

FILLFORE NULL DECIMAL(5) Fill Foreground Color

FILLBACK NULL DECIMAL(5) Fill Background Color

FONTFACE NULL DECIMAL(5) Font Type

FONTSIZE NULL DECIMAL(5) Font Size

FONTSTYLE NULL DECIMAL(5) Font Style

FONTWEIGHT NULL DECIMAL(5) Font Boldness

CHARSET NULL DECIMAL(5) Character Set

CHARWIDTH NULL DECIMAL(5) Width of Characters

BASELINE NULL DECIMAL(5) Baseline

KERNING NULL DECIMAL(5) Text Kerning

DASHSTYLE NULL DECIMAL(5) Dash Appearance

CAPSTYLE NULL DECIMAL(5) Line End Style

JOINSTYLE NULL DECIMAL(5) Joined Line Style

TRANSMODE NULL DECIMAL(5) Object Creation Style




ITEMID NULL DECIMAL(10) Element ID

ALIAS NULL VARCHAR(250) Alias

EXPR NULL VARCHAR(250) Expression

DESC_EXPR NULL VARCHAR(250) Expression Description

QUERYID NULL DECIMAL(10) Pointer to Query

SEL_ORDER NULL DECIMAL(5) SELECT Order

DATA_TYPE NULL DECIMAL(2) Element Datatype

WIDTH NULL DECIMAL(10) Element Width

SCALE NULL DECIMAL(5) Element Scale

PRECISION NULL DECIMAL(5) Element Precision

ODATA_TYPE NULL DECIMAL(2) ORACLE Datatype

SRW2_FIELD

18 – 19Storage




ITEMID NULL DECIMAL(10) Field ID

NAME NULL VARCHAR(30) Field Name


DISP_ORDER NULL DECIMAL(5) Field Display Order




X NULL DECIMAL(10) Field X–Coordinate

Y NULL DECIMAL(10) Field Y–Coordinate

WD NULL DECIMAL(10) Field Width

HT NULL DECIMAL(10) Field Height


PGN_FLAGS NULL DECIMAL(5) Page Numbering Flags

PGN_START NULL DECIMAL(5) Page Numbering Start Value

PGN_INCR NULL DECIMAL(5) Page Numbering IncrementValue

PGN_RESET NULL DECIMAL(10) Page Numbering Reset Value

SOURCE_ID NULL DECIMAL(10) Field Source ID

CONTINUED NULL DECIMAL(10) Field Continued From

ALIGNMENT NULL DECIMAL(5) Field Alignment

TEXT_WRAP NULL DECIMAL(2) Text Wrap Style

MIN_WIDOWS NULL DECIMAL(5) Minimum Number of WidowedLines

MIN_ORPHAN NULL DECIMAL(5) Minimum Number of Orphaned Lines

MAX_LINES NULL DECIMAL(5) Maximum Number of Linesper Page

MASK NULL VARCHAR(250) Field Format Mask

SRW2_FRAME



NULL_VALUE NULL VARCHAR(250) Format if Null

SPACING NULL DECIMAL(10) Text Spacing




ITEMID NULL DECIMAL(10) Frame ID

NAME NULL VARCHAR(30) Frame Name


DISP_ORDER NULL DECIMAL(5) Frame Display Order




X NULL DECIMAL(10) Frame X coordinate

Y NULL DECIMAL(10) Frame Y coordinate

WD NULL DECIMAL(10) Frame Width

HT NULL DECIMAL(10) Frame Height

PAGE NULL DECIMAL(5) Page on which Frame Ap-pears

GROUP_ID NULL DECIMAL(10) Associated Group

CONTINUED NULL DECIMAL(10) Group Continued From

DIRECTION NULL DECIMAL(5) Frame Print Direction

MIN_WIDOWS NULL DECIMAL(5) Minimum Number of WidowedLines

MIN_ORPHAN NULL DECIMAL(5) Minimum Number of Or-phaned Lines

MAX_LINES NULL DECIMAL(5) Maximum Number of Linesper Page

BETWEEN_X NULL DECIMAL(10) Between Record Area X Di-mension

BETWEEN_Y NULL DECIMAL(10) Between Record Area Y Di-mension

RESERVED NULL DECIMAL(10) Space Reserved for Ma-trices

SRW2_GROUP

18 – 21Storage




ITEMID NULL DECIMAL(10) Group ID

NAME NULL VARCHAR(30) Group Name


DISP_ORDER NULL DECIMAL(5) Group Display Order

PTAG NULL DECIMAL(10) Display Tag for Points

QUERY_ID NULL DECIMAL(10) Query this Group ComesFrom

PARENT_ID NULL DECIMAL(10) Parent Group (0 if TopGroup)

QLF_TYPE NULL DECIMAL(2) Query–level Filter

QLF_ARG NULL DECIMAL(5) Query–level Filter Argu-ment

QLF_COLUMN NULL DECIMAL(10) Query–level Filter Column

GLF_TYPE NULL DECIMAL(2) Group–level Filter

GLF_ARG NULL DECIMAL(5) Group–level Filter Argu-ment

GLF_COLUMN NULL DECIMAL(10) Group–level Filter Column

RLF_TYPE NULL DECIMAL(2) Row–level Filter

RLF_ARG NULL DECIMAL(5) Row–level Filter Argument

RLF_COLUMN NULL DECIMAL(10) Row–level Filter Column

CROSS_PROD NULL DECIMAL(1) Cross Product Flag

PRODUCT_ID NULL DECIMAL(10) Cross Product Parent ID


POINTS NULL RAW(250) Incoming Line from Pre-vious Group


Y NULL DECIMAL(10) Y–Coordinate

WD NULL DECIMAL(10) Group Width

HT NULL DECIMAL(10) Group Height

DFLT_DIR NULL DECIMAL(5) Default Direction

SRW2_LAYOUT





ITEMID NULL DECIMAL(10) Layout ID

SETTINGS NULL DECIMAL(10) Display Settings

ZOOMPOWER NULL DECIMAL(5) Magnification

UNITS NULL DECIMAL(2) Units of Measurement

ORIENT NULL DECIMAL(2) Orientation, Page PrintOrder

UNITS_WID NULL DECIMAL(10) Width in Units

UNITS_HGT NULL DECIMAL(10) Height in Units

CHAR_WID NULL DECIMAL(10) Character Width

CHAR_HGT NULL DECIMAL(10) Character Height

BODY_WID NULL DECIMAL(10) Body Width

BODY_HGT NULL DECIMAL(10) Body Height

PAGE_WID NULL DECIMAL(10) Page Width

PAGE_HGT NULL DECIMAL(10) Page Height

PRINT_WID NULL DECIMAL(10) Printable Area Width

PRINT_HGT NULL DECIMAL(10) Printable Area Height

X_PANELS NULL DECIMAL(10) X–Coordinate

Y_PANELS NULL DECIMAL(10) Y–Coordinate

HEADERS NULL DECIMAL(5) Number of Header Pages

TRAILERS NULL DECIMAL(5) Number of Trailer Pages

WINDOW_X NULL DECIMAL(10) Horizontal Window Location

WINDOW_Y NULL DECIMAL(10) Vertical Window Location

WINDOW_WD NULL DECIMAL(10) Window Width

WINDOW_HT NULL DECIMAL(10) Window Height

RUN_FLAGS NULL DECIMAL(5) Runtime Flags

TITLE NULL VARCHAR(250) Previewer Title

HINT NULL VARCHAR(250) Previewer Hint

STATUS NULL VARCHAR(250) Previewer Status

MAXHEADERS NULL DECIMAL(5) Maximum Header Pages

MAXTRAILERS NULL DECIMAL(5) Maximum Trailer Pages

SRW2_LAYOUT_ GROUP

18 – 23Storage


MAXBODY_ACR NULL DECIMAL(5) Maximum Body Width

MAXBODY_DWN NULL DECIMAL(5) Maximum Body Height

INTERN_VER NULL DECIMAL(2) SRW Development

INTERN_VER2 NULL DECIMAL(4) Future Expansion

APPLSTATE NULL DECIMAL(6) Future Expansion

UIFLAGS NULL DECIMAL(10) Painter Settings Flag

GRIDINTC NULL DECIMAL(10) Grid Spacing

GRIDSNPC NULL DECIMAL(10) Number of Snap Points PerGrid Spacing

HALIGN NULL DECIMAL(1) Horizontal Alignment

VALIGN NULL DECIMAL(1) Vertical Alignment

RRECTCNR_WD NULL DECIMAL(10) Horizontal Corner Radiusof Rounded Rectangle

RRECTCNR_HT NULL DECIMAL(10) Vertical Corner Radius of

Rounded Rectangle

SPACING NULL DECIMAL(10) Line Spacing Setting

JUSTIFIC NULL DECIMAL(5) Justification Setting

ARROWSTYLE NULL DECIMAL(1) Arrow Style Setting

UITAG NULL DECIMAL(10) Painter Settings DisplayTag

NEXTLISTID NULL DECIMAL(10) Next List ID

IDROLESLIST NULL DECIMAL(10) ID of Roles List




ITEMID NULL DECIMAL(10) Layout ID

DISP_ORDER NULL DECIMAL(5) Display Order

FORMATFLAG NULL DECIMAL(10) Format Flag

NCHILDREN NULL DECIMAL(10) Number of Children

SRW2_LINK

SRW2_MATRIX

SRW2_MODULE





ITEMID NULL DECIMAL(10) Link ID


DISP_ORDER NULL DECIMAL(5) Link Display Order

PARENT_ID NULL DECIMAL(10) Parent Group ID

P_COLUMN NULL DECIMAL(10) Parent Column ID

CHILD_ID NULL DECIMAL(10) Child Group ID

C_COLUMN NULL DECIMAL(10) Child Column ID

CLAUSE NULL DECIMAL(2) SQL Clause

OPERATOR NULL DECIMAL(2) Link Operator


POINTS NULL RAW(250) Link Points




ITEMID NULL DECIMAL(10) Matrix ID

NAME NULL VARCHAR(30) Matrix Name


DISP_ORDER NULL DECIMAL(5) Matrix Display Order


DOWN_ID NULL DECIMAL(10) Vertical Frame

ACROSS_ID NULL DECIMAL(10) Horizontal Frame

GROUP_ID NULL DECIMAL(10) Group

SRW2_MODULE is a view on TOOL_MODULE.


OWNER NOT NULL VARCHAR(30) Module Owner

MODID NOT NULL DECIMAL(10) Module ID

MODNAME NULL VARCHAR(61) Module Name

SRW2_OG_DOCUMENT

SRW2_OGD_COLUMN_MAP

18 – 25Storage


MODTYPE NULL NUMBER Module Type

PRODUCT NULL NUMBER Product




ITEMID NULL DECIMAL(10) Object ID

NAME NULL VARCHAR(30) Object Name


DISP_ORDER NULL DECIMAL(5) Document Display Order




X NULL DECIMAL(10) Document X coordinate

Y NULL DECIMAL(10) Document Y coordinate

WD NULL DECIMAL(10) Document Width

HT NULL DECIMAL(10) Document Height

PAGE NULL DECIMAL(5) Page on which DocumentAppears

OG_DNAME NULL VARCHAR(250) Document Name

OG_QNAME NULL VARCHAR(250) Query Name

OG_SLOC NULL DECIMAL(5) Storage Location

GROUP_ID NULL DECIMAL(10) Associated Group




ITEMID NULL DECIMAL(10) Parameter Form ID

SRW_COLID NULL DECIMAL(10) Report Column ID

SRW2_QUERY

SRW2_TEXT_ SEGMENT



OG_COLTYPE NULL DECIMAL(5) Display Column Type

OG_COLNAME NULL VARCHAR(250) Display Column Name




ITEMID NULL DECIMAL(10) Query ID

NAME NULL VARCHAR(30) Query Name


DISP_ORDER NULL DECIMAL(5) Query Display Order

EXT_QUERY NULL VARCHAR(250) External Query Name

NET_LOGON NULL VARCHAR(250) SQL*Net Logon

TEMP_TABLE NULL VARCHAR(30) Temporary Table Name

TEMP_FLAGS NULL DECIMAL(5) Temporary Table Flags

EXEC_FREQ NULL DECIMAL(2) Execution Frequency

MAX_ROWS NULL DECIMAL(10) Maximum Number of Rows toFetch


Y NULL DECIMAL(10) Y–<+>Coordinate

WD NULL DECIMAL(10) Query Width

HT NULL DECIMAL(10) Query Height

QUERYLFID NULL DECIMAL(10) Pointer to SELECT State-ment Text




ITEMID NULL DECIMAL(10) Text Segment ID


SEG_TEXT NULL VARCHAR(250) Text Segment

SEG_ORDER NULL DECIMAL(5) Text Segment Order

TOOL_ACCESS

TOOL_COMMENT

TOOL_DEPEND

18 – 27Storage

Integrated Oracle Product Tables and Other Objects

Integrated Oracle product tables contain module definitions, and maybe shared with other Oracle products. Through the use of databaseviews and public synonyms, users can see information about modulesthey own or to which they have been granted access.


PRODUCT NULL VARCHAR(30) Product Name



GRANTEE NULL VARCHAR(30) User to Whom AccessGranted




ITEMID NULL DECIMAL(10) Item (comment) ID

OBJECT_ID NULL DECIMAL(10) ID of Commented Object

CMTLFID_S NULL DECIMAL(10) LONG Field ID (sound com-ment)

CMTLFID_T NULL DECIMAL(10) LONG Field ID (text com-ment)

Name Null? Type Commen



ITEMID NULL DECIMAL(10) Item ID (optional)

DEP_MODID NULL DECIMAL(10) Module Dependent On

DEP_ITEMID NULL DECIMAL(10) Item Dependent On (op-tional)

DEP_TYPE NULL VARCHAR(250) Dependency Type (productdefined)

DEPCHANGED NULL VARCHAR(1) Dependent–Object Has–Changed

TOOL_LIBRARY

TOOL_LRAW

TOOL_LRAW_ID

TOOL_LTEXT






LIBNAME NULL VARCHAR(255) Name of Library




ID NULL DECIMAL(10) Long Field ID

LPAGEID NULL DECIMAL(10) LONG RAW Page ID

LFLEN NULL DECIMAL(10) LONG RAW Field ID

N NULL DECIMAL(5) LONG Field Sequence Num-ber

DATALEN NULL DECIMAL(10) LONG Field Length

DATA NULL LONG RAW Long RAW Data Chunk

TOOL_LRAW_ID is a sequence that is used to generate LONG RAWdata IDs.

Name Type Comment

ID NUMBER(10) Next LONG RAW ID to Use




ID NULL DECIMAL(10) LONG Field ID

LPAGEID NULL DECIMAL(10) LONG Page ID

LFLEN NULL DECIMAL(10) LONG Field Length

N NULL DECIMAL(5) LONG Field Sequence Num-ber

DATALEN NULL DECIMAL(10) LONG Field Length

DATA NULL LONG LONG Text Chunk

TOOL_LTEXT_ID

TOOL_MODID

TOOL_MODULE

18 – 29Storage

TOOL_LTEXT_ID is a sequence that is used to generate LONG textIDs.

Name Type Comment

ID NUMBER(10) Next LONG ID to Use

TOOL_MODID is a sequence that is used to generate module IDs.

Name Type Comment

MODID NUMBER(10) Next Module ID to Use



MODTYPE NULL VARCHAR(30) Module Type


NEXT_ITEMID NULL DECIMAL(10) Next Available InternalID


MODNAME NULL VARCHAR(30) Module Name

CREATOR NULL VARCHAR(30) User Who Created the Module

CREATE_DATE NULL DATE Creation Date

CREATE_VER NULL DECIMAL(8) Product Version CreatedWith

MODIFIER NULL VARCHAR(30) User Who Last Modifiedthe Module

MOD_DATE NULL DATE Modification Date

MOD_VER NULL DECIMAL(8) Product Version ModifiedWith

COPYRIGHT NULL VARCHAR(250) Module Copyright Notice

REQ_ROLE NULL VARCHAR(30) Role Required to Run thisModule

TCS_VER NULL DECIMAL(8) Version of TCS

VGS_VER NULL DECIMAL(8) Version of VGS

TOOL_PLSQL

ROSSTRINGS



DE_VER NULL DECIMAL(8) Version of DE

ROS_VER NULL DECIMAL(8) Version of ROS




ITEMID NULL DECIMAL(10) Item (program unit) ID

OBJECT_ID NULL DECIMAL(10) Associated Object ID (op-tional)

TYPE NULL DECIMAL(4) Type of Program Unit (op-tional, product defined)

NAME NULL VARCHAR(30) Name of Program Unit

PLSLFID_ST NULL DECIMAL(10) LONG Field ID of PL/SQLSource Text

PLSLFID_EP NULL DECIMAL(10) LONG Field ID of PL/SQLEncoded Program Unit


OWNER NOT NULL VARCHAR(30) User


GROUPID NOTNULL DECIMAL(10) Group ID

STRINGID NOT NULL DECIMAL(10) ID for String Instancesin Module

LFID NOT NULL DECIMAL(10) For ROS Use

LEN NOT NULL DECIMAL(10) Data (String) Length

CS NOT NULL DECIMAL(10) Character Set

STR LONG RAW Data (String)

Controlling Access toOracle Reports

Controlling Access toOther Users’ Modules

18 – 31Storage

Establishing Database Security and Restrictions

There are three types of restrictions you can place on Oracle Reportsusers:

• prevent them from running Oracle Reports – 18 – 31

• prevent them from accessing other users’ external queries,external PL/SQL libraries, and reports – 18 – 31

Oracle Reports’ security mechanism supplements ORACLE’s GRANTand REVOKE commands, providing extra measures of control. Allrestrictions placed through GRANT and REVOKE still apply.

A user will be unable to access Oracle Reports unless the user isgranted access to Oracle Reports tables by running the srw2grnt.sqlscript. To revoke a user’s access to Oracle Reports, run the srw2rvke.sqlscript.

Users may access another user’s module stored in the database. To dothis, the module creator must grant other users access to it by firstensuring the other users have access to the tables in which the modulesare stored, then doing the following:

1. Select File—>Administration—>Module Access to display theModule Access List dialog box.

2. Enter a username (or PUBLIC) in the Module Access List dialogbox. If you type PUBLIC, all users that have been granted access tothe system–owned tables will have access to the module.

Note: Only a module’s creator can grant access to that moduleto other users. Also, only an module’s creator can modify themodule, even if the creator has granted access to others.

Database Storage Requirements

Oracle Reports tables require approximately one megabyte of storagewhen empty. When using Oracle Reports with ORACLE, only one setof tables is created and therefore only one megabyte is needed initiallyper installation. As you create modules and run reports, the databasespace requirements will naturally increase.


Note: Because this information can vary from system tosystem and across dissimilar hardware, this information is onlyprovided to give you a general idea of database storagerequirements. For more information, see the Developer/2000Installation Guide for your operating system.

Memory and Disk Space Requirements

Oracle Reports has the following memory requirements:

Item Memory Disk Space

Runtime Engine 5–6 meg 26 meg

Designer Engine 7 meg 26 meg

As you create modules and run reports, these memory and diskrequirements will naturally increase.

In particular, complex reports that use many images and graphics cansignificantly increase disk and RAM requirements. If you use a totalnumber of pages in your report (e.g., &Total Logical Pages), OracleReports needs to keep its temporary files in order to determine the totalnumber of pages in the report. This can also significantly increase yourdisk space and RAM requirements.

Note: Because this information can vary from system tosystem and across dissimilar hardware, the table above is onlyprovided to give you a general idea of memory requirements.For more information, see the Developer/2000 Installation Guidefor your operating system.

P A R T

V Administration

C H A P T E R

19I

19 – 1Administration

Administration

f you are responsible for administering Oracle Reports, youshould know about the following:

• using SQL scripts – 19 – 2

• installing tables – 19 – 3

• granting user privileges – 19 – 4

• revoking user privileges – 19 – 4

• upgrading from previous versions of Oracle Reports – 19 – 5

• dropping Version 1.1 tables – 19 – 5

• moving reports between the file system and the database –19 – 5

• deleting reports – 19 – 5

• documenting reports – 19 – 6

• determining which files Oracle Reports is using – 19 – 6

SQL ScriptDescriptions


Using SQL Scripts

Oracle Reports is shipped with several SQL scripts, with which you canquickly perform some database administration that might otherwiserequire significantly more time. To run any of the SQL scripts, you logon to SQL*Plus and then type the following:

START script_name

where:

Is the name of the script you would like to run.

For more information about SQL scripts, see “SQL Script Descriptions”on page 19 – 2.

For details on how to log on or use SQL*Plus, refer to your SQL*PlusUser’s Guide and Reference Manual.

Below is an alphabetized list of each SQL script and its purpose. Thesescripts should initially appear in the admin subdirectory. For moreinformation, see the Developer/2000 Installation Guide for your operatingsystem.

Note: All of these scripts, with the exception of srw2drop.sql,should only be used by DBAs.

Deletes the Oracle Reports–specific tables.

Deletes one report.

Grants privileges to the specified user(s) so theycan create and modify modules stored in theOracle Reports–specific tables.

Installs the Oracle Reports–specific tables.

Limits at once the number of output pages that thespecified user(s) may print for a report. Thisprevents loss of many pages when a report isimproperly designed.

Creates the PRODUCT_PROFILE andUSER_PROFILE tables for ORACLE Version 6. Italso creates two views on these tables, which iswhat users (non–DBAs) see.

Creates the PRODUCT_PROFILE andUSER_PROFILE tables for ORACLE7. It alsocreates two views on these tables, which is whatusers (non–DBAs) see.

script_name

srw2drop.sql

droprep.sql

srw2grnt.sql

srw2bild.sql

srw2lmt.sql

srw2pup.sql

srw2pup7.sql


Revokes privileges of the specified user(s) so theycannot create and modify modules stored in theOracle Reports–specific tables.

Deletes the integrated Oracle tools tables.

Grants privileges to the specified user(s) so theycan create and modify modules stored in theintegrated Oracle tools tables.

Installs the integrated Oracle tools tables.

Revokes privileges of the specified user(s) so theycannot create and modify modules stored in theintegrated Oracle tools tables.

Deletes the VGS tables.

Grants privileges to the specified user(s) so theycan modify the VGS tables.

Installs the VGS tables.

Revokes privileges of the specified user(s) so theycannot modify the VGS tables.

Deletes the ROS tables.

Grants privileges to the specified user(s) so theycan modify the ROS tables.

Installs the ROS tables.

Installing Tables

To install the Oracle Reports tables, do the following using SQL*Plus

1. Run the toolbild.sql script to create the integrated Oracle toolstables.

2. Run the ros.sql script to create the ROS tables.

3. Run the vgbild.sql script to create the VGS tables.

4. Run the srw2bild.sql script to create the Oracle Reports–specifictables.

Caution: These tables must be created in the order specified above.

srw2rvke.sql

tooldrop.sql

toolgrnt.sql

toolbild.sql

toolrvke.sql

vgdrop.sql

vggrnt.sql

vgbild.sql

vgrvke.sql

rosdrp.sql

rosgnt.sql

ros.sql


Granting User Privileges

To grant a user privileges to create and modify modules stored in thedatabase, do the following in SQL*Plus:

1. Run the toolgrnt.sql script. You are prompted to specify theusername(s) to whom you wish to grant privileges.

• Enter PUBLIC to grant privileges to all present and future users.

• Enter one or more usernames to grant privileges to only thoseusers.

2. Run the rosgnt.sql script. You are prompted to specify theusername(s) to whom you wish to grant privileges.



3. Run the vggrnt.sql script. You are prompted to specify theusername(s) to whom you wish to grant privileges.



4. Run the srw2grnt.sql script. You are asked to specify the user(s) towhom you wish to grant privileges.



Revoking User Privileges

To revoke a user’s privileges to create and modify modules stored inthe database, do the following in SQL*Plus:

1. Run the srw2rvke.sql script. You are asked to specify the user(s)whose privileges you wish to revoke.

• Enter PUBLIC to revoke the privileges of all present and futureusers.

• Enter one or more usernames to revoke the privileges of onlythose users.


Upgrading from Previous Versions of Oracle Reports

To upgrade from a previous version of SQL*ReportWriter to OracleReports, you need to run the R25MREP executable. For moreinformation, see the Reports Migration Manual.

Dropping Version 1.1 Tables

After you’ve installed Oracle Reports and its accompanying tables, andconverted all of your reports using R25MREP, you’ll want to drop yourSQL*ReportWriter Version 1.1 tables. To do this, do the following inSQL*Plus:

1. Run the Version 1.1 .sql script: srw_dcen.sql or srw_dloc.sql.

Moving Reports Between the File System and the Database and Vice–versa

To move reports that are stored in operating system files to thedatabase or the reverse, you can do one of the following:

• Open the report and then select File—>Save As.... Save thereport to the database or a file. If desired, you can then deletethe original version of the report using operating systemcommands (for files) or File—>Administration—>Delete (forthe database).

• Use R25CONV. For more information, see “R25CONV” on page1 – 9.

Deleting Modules

To delete modules stored in operating system files, delete the filesusing the appropriate operating system commands.

To delete modules from the database, you can do any of the following:

• Select File—>Administration—>Delete..., then select themodule (report, external query, or external PL/SQL library) youwant to delete.

• Use the droprep.sql script to delete a report from the database.

Files You Create


Documenting Reports

To print documentation about one or more reports, selectFile—>Administration—>Report Doc. This will run a report on yourreports stored in the database. When the Runtime Parameter Formappears, you can enter a full or partial report name to indicate forwhich report(s) you want the report to be run. % or _ can be used aswildcards to indicate the report(s) for which you want information.

Determining Which Files Are Being Used

Oracle Reports uses and/or creates several different files, dependingupon the executable you invoked and the operation you’re performing.The sections that follow cover the following topics:

• files you create – 19 – 6

• files Oracle Reports creates – 19 – 7

The table below shows what files you must provide to Oracle Reportsas input, depending upon the executable being used and operationbeing performed:

FILETYPE R25DES R25RUN R25CONV R25MREP

report definition file<report name>.rdf

RUN/PRINTAND

ALWAYSNEEDS THIS

FOR SOURCE,IF STYPE

––<report name>.rdf AND

CONVERT, IF STYPE

NEEDS THISFILE OR

REP FILE

IF STYPE IS RDFFILE

IF STYPEIS RDFFILE

. REP FILE

report runfile <report name>.rep

–– ALWAYSNEEDS THIS

–– ––<report name>.rep NEEDS THIS

FILE OR.RDF FILE

report text file CONVERT, –– FOR SOURCE, FOR SOURCE,report text file <filename>.rex

CONVERT, IF STYPEIS REXFILE

FOR SOURCE,IF STYPE IS REXFILE

FOR SOURCE,IF STYPE IS REXFILE

fIS REXFILE IS REXFILE IS REXFILE

terminal descriptionfile character mode only

ALWAYS IF BATCHIS NO

–– ––

keystroke file character mode only

IF KEYIN ISSPECIFIED

IF KEYIN ISSPECIFIED

–– ––

V2.0 printer RUN ALWAYS –– ––V2.0 printer description file<dflt>

RUN ALWAYSp

<dflt>

Files Created By OracleReports


FILETYPE R25MREPR25CONVR25RUNR25DES

V1.1 printerdefinition file

–– –– –– ALWAYSdefinition file<printdef.dat>

The table below shows what files Oracle Reports creates, dependingupon the executable being used and operation being performed:

FILETYPE R25DES R25RUN R25CONV R25MREP

report definition file<report name>.rdf

SAVE, SAVEAS, OR

–– FOR DEST,IF DTYPE

FOR DEST,IF DTYPE<report name>.rdf AS, OR

CONVERT, IF DTYPE

IF DTYPE IS RDFFILE

IF DTYPE IS RDFFILE

IF DTYPE IS RDFFILE

report runfile <report name> rep

GENERATE OR CONVERT


FOR DEST,IF DTYPE

p<report name>.rep OR CONVERT,

IF DTYPE IF DTYPE IS REPFILE

IF DTYPE IS REPFILEIF DTYPE

IS REPFILEIS REPFILE IS REPFILE

report text file <filename>.rex

SAVE, SAVEAS, OR


FOR DEST,IF DTYPE<f lename>.rex AS, OR

CONVERT, IF DTYPE

IF DTYPE IS REXFILE

IF DTYPE IS REXFILE

IF DTYPE IS REXFILE

report output file<report name>.lis

RUN/PRINT,IF DESTYPEIS FILE

IF DESTYPEIS FILE

–– ––

profiler log file IF PROFILER IF PROFILER –– ––p g<temp> IS YES IS YES

error log file <temp>

IF ERRFILEIS SPECI -

IF ERRFILEIS SPECI -

–– ––<temp> IS SPECI-

FIEDIS SPECI-FIED

trace log filetrace.dat

IFTRACEFILEIS SPECI-FIED

IFTRACEFILEIS SPECI-FIED

printer output file RUN/PRINT,IF DESTYPEIS PRINTER

IF DESTYPEIS PRINTER

–– ––

keystroke file character–mode only

IF KEYOUTIS SPECI-FIED

IF KEYOUTIS SPECI-FIED

–– ––

Print Screen log filecharacter–mode only

PRINTSCREEN

PRINTSCREEN

–– ––


FILETYPE R25MREPR25CONVR25RUNR25DES

V2.0 printer –– –– –– ALWAYSV2.0 printer description file<dflt>

ALWAYSp

<dflt>

record caching filesidx<number> anddat<number> in<temp>

RUN/PRINT RUN/PRINT –– ––

memory swap files RUN/PRINT RUN/PRINT –– IF NEEDEDmemory swap files(only created if

d d) <t >

RUN/PRINT RUN/PRINT IF NEEDEDDURING CONVERSION

yneeded) <temp> CONVERSION

P A R T

VI Appendixes

A P P E N D I X

AW

A – 1Environment and GUI Differences

Environment and GUIDifferences

hen you invoke Oracle Reports, it provides you with the nativelook–and–feel and functionality that your environment or GUIsupports. For example, Oracle Reports provides image support whenyour environment supports images (i.e., in bit–mapped environments);otherwise, it cannot (e.g., in character–mode).

As a result, if you are designing a report in an environment or GUIother than the one in which it will be run, you need to be aware of thethe following:

• differences of environments and GUIs – A – 2

• report design for character–mode environments – A – 3

• report conversion across GUIs – A – 4

EnvironmentDifferences

Bit–MappedEnvironments

Character–ModeEnvironments

GUI Differences

A – 2 Reports Reference ManualGUI Version

Environment and GUI Differences Overview


• environment differences

• GUI differences

There are two types of environments in which you can run OracleReports:

• bit–mapped

• character–mode

A bit–mapped environment has a unit of Pixel, and typically supports amouse. Interaction with the host computer is continuous. As a result,a user’s work is immediately validated. An advantage of bit–mappedenvironments is that they are graphical; a disadvantage is that theyincrease network traffic. GUIs run in bit–mapped environments, only.

A character–mode environment has a unit of Character, typically 80x24,and infrequently supports a mouse. Interaction with the host computeroccurs at the field level; i.e., a field of information is sent to the hostcomputer when a user navigates from a field. Character–modeenvironments require less network traffic than bit–mappedenvironments, but more than block–mode environments; they validatea user’s work more frequently than block–mode environments, but lessfrequently than bit–mapped environments.

Oracle Reports is supported on the following GUIs of the bit–mappedenvironment: Macintosh, Motif System, and Microsoft Windows.Although these GUIs have fairly similar functionality, you need to beaware of their differences if you are building reports on a GUI otherthan the one on which users will run them. Below are two categories ofGUI differences:

• those that do not affect a report’s portability

• those that affect a report’s portability

Examples of GUI differences that do not affect a report’s portability arethe appearance of interface elements (e.g., check boxes are not squareson all GUIs), the contents and operation of the file dialog box, thecontents and operation of the Windows menu, the methodology forinvoking help, etc.


Differences that do affect a report’s portability are available systemfonts and their associated attributes (such as weight, style, etc.), colors,and the dots–per–inch (DPI) used to display your GUI. For moreinformation on how these differences are translated between the GUIs,see “Report Conversion Across GUIs” on page A – 4.

Designing Reports for Character Mode

To design a report in a GUI version of Oracle Reports so that it can berun in character mode, you can use the following settings/menu items:

• Page Height/Width

• Report Width x Height

• Use Character Units in Designer

• Convert Bit–mapped Objects to Boxes

• Convert Borders

• Rulers

• Grid Snap

• Horizontal/Vertical Interfield

• Horizontal/Vertical Gap

• Font

• Size

• Weight

Rules:

Caution: Whenever you move a report to a new environment, youmust recompile the PL/SQL in the report before running it.

1. When displaying a character mode report in the bit–mappedPreviewer of the designer, Oracle Reports uses Report Width xHeight to choose the font to display. The font may be slightlylarger or smaller than the actual character cell size. As a result,when you run a report designed for character mode in thebit–mapped Previewer, you may see some truncation.

For more information about designing reports for character mode, see“Create Character–Mode Reports” in Chapter 8 of Building ReportsManual.


Report Conversion Across GUIs

If you move a report from one GUI to another, be aware of how thefollowing GUI differences may affect the report: fonts, colors, anddots–per–inch (DPI).

Fonts A font (i.e., a font type, style, size, etc.) that is found in your GUImight not be available in the target GUI. You can handle this in one oftwo ways:

• Use a font that you know exists on the target GUI or one thatmaps well to the default font of the target GUI.

• Modify the font mapping file, uifont.ali, to ensure that the fontsmap correctly. For more information about uifont.ali, see “FontMapping File” on page 18 – 7. For more information about fontmapping, see “Font Mapping” on page A – 5.

Colors A color found in your GUI might not be available in the targetGUI. If possible, use a color that you know exists on the target GUI;otherwise, use one that maps well to the default color of the target GUI.Following are some examples of colors that typically are available onmany platforms:

• blue

• magenta

• red

• cyan

• green

• yellow

DPI The dots–per–inch (DPI) that your monitor uses may not be thesame as the DPI used by the person who runs the report—this is trueeven if you both use the same GUI. The DPI only affects howalpha–numeric characters word–wrap on the screen. As a result, if youdesign a report that may be displayed in the Previewer, then try to usethe same DPI as the people who will run it. For this reason, you mayalso want to avoid giving layout objects fixed sizing. When DPI isdifferent, fixed sizing may cause text to word wrap differently.

Font Mapping


To define the font aliases used by Oracle Reports, you edit uifont.ali.For each font that you want to alias, you make the following entry inthe file:

source_font = destination_font

For each font, you can specify the following attributes:

<face >.< size >.< style >.< weight >.< width >.< character_set >

The <face> must be the name (string/identifier) of a font face. The <style>,<weight>, <width>, and <character_set> may either be a numericvalue or apredefined identifier/string. For example, both US7ASCII and 1 are validvalues, and refer to the same character set. The <size> dimension must be anexplicit size, in points.

The following is a list of recognized names and their numericequivalents:

Styles Numeric Value

plain 0

italic 1

oblique 2

underline 4

outline 8

shadow 16

inverted 32

overstrike 64

blink 128

Weights Numeric Value

ultralight 1

extralight 2

light 3

demilight 4

medium 5

demibold 6

bold 7

extrabold 8

ultrabold 9

Font MappingVerification


Widths Numeric Value

ultradense 1

extradense 2

dense 3

semidense 4

normal 5

semiexpand 6

expand 7

extraexpand 8

ultraexpand 9

Styles can be combined using the plus sign (+). For example:

Arial..Italic+Overstrike = Helvetica.12.Italic.Bold

All strings are case–insensitive in mapping. Font faces are likely to becase–sensitive on lookup, depending on the platform and surface, socare should be taken with names used on the right–hand side; but theywill be mapped case–insensitively.

The backslash (\) is used as a continuation character. Comments canbe included as follows:

/* comment */

# comment

; comment

To verify that your uifont.ali file is correct, you can use fontchk. Thisprogram will check your file to ensure there are no errors. Enter thefollowing to parse your font mapping file:

fontchk filename

Font MappingExample


Below is a sample font mapping file that could be used with OracleReports.

[ Global ] # Put mappings for all surfaces here.

# Mapping from MS Windows

Arial = helvetica

”Courier New” = courier

”Times New Roman” = times

Modern = helvetica

”MS Sans Serif” = helvetica

”MS Serif” = times

”Small Fonts” = helvetica

# Mapping from Macintosh

”New Century Schlbk” = ”new century schoolbook”

“New York” = “times”

[ Printer ] # Put mappings for all printers here.

[ Printer:PostScript1 ] /* Put mappings for PostScript

level 1 printers here. */


Roman = palatino

Script = ”itc zapf chancery”

FixedSys = courier

System = helvetica


”Avant Garde” = ”itc avant garde gothic”

# Mapping from Motif display

fixed = courier

clean = times

lucidatypewriter = courier

lucidabright = times

# Sample Kanji font mappings

courier...Medium..JEUC = \

”Ryumin–Light–83pv–RKSJ–H”...Light..JEUC

courier...Bold..JEUC = \

”GothicBBB–Medium–83pv–RKSJ–H”...Medium..JEUC

courier...Medium..SJIS = \



courier...Bold..SJIS = \


times...Medium..JEUC = \


times...Bold..JEUC = \


times...Medium..SJIS = \


times...Bold..SJIS = \


helvetica...Medium..JEUC = \


helvetica...Bold..JEUC = \


helvetica...Medium..SJIS = \


helvetica...Bold..SJIS = \


[ Printer:PostScript2 ] /* Put mappings for PostScript

level 2 printers here. */


Roman = palatino

Script = ”itc zapf chancery”

FixedSys = courier

System = helvetica


”Avant Garde” = ”itc avant garde gothic”

# Mapping from Motif display

fixed = courier

clean = times

lucidatypewriter = courier

lucidabright = times

# Sample Kanji font mappings

courier...Medium..JEUC = \


courier...Bold..JEUC = \


courier...Medium..SJIS = \


courier...Bold..SJIS = \



times...Medium..JEUC = \


times...Bold..JEUC = \


times...Medium..SJIS = \


times...Bold..SJIS = \


helvetica...Medium..JEUC = \


helvetica...Bold..JEUC = \


helvetica...Medium..SJIS = \


helvetica...Bold..SJIS = \


[ Display ] # Put mappings for all display surfaces here.

[ Display:Motif ] # Put mappings for Motif displays here


Courier = courier

Roman = lucida

Script = lucidabright

FixedSys = fixed

System = lucida


”Avant Garde” = helvetica

”Bookman” = times

[ Display:CM ] # Put mappings for all CM displays here.

# These are DEC–specific, and may need localization

*..Blink = Blinking

*..Inverted+Underline.Bold = ReverseBoldUnderline

*..Inverted+Underline. = UnderlineReverse

*..Underline.Bold = UnderlineBold

*..Inverted.Bold = ReverseBold

*...Bold = Bold

*..Underline = Underline

*..Inverted = Reverse

* = Plain # The font of last resort

A P P E N D I X

BI

B – 1Printer and Terminal Definitions

Printer and TerminalDefinitions

f you are planning to run a report on a character mode platform,you should be aware of the following:

• purpose of printer definitions – B – 2

• packaged printer definitions – B – 2

• creating or modifying printer definitions – B – 3

• printer definition file syntax – B – 3

• printer definition rules – B – 8

• referencing printer definitions – B – 13

• purpose of terminal definitions – B – 14

• packaged terminal definitions – B – 2

• creating or modifying terminal definitions – B – 15

• terminal definition rules – B – 21

• referencing terminal definitions – B – 21

Caution: Printer and terminal definitions are only needed when oncharacter–mode platforms. They are not needed on bit–mappedplatforms. This information is provided here only for the convenienceof those who are designing reports in bitmap for use in character mode.

Descriptions

B – 2 Reports Reference ManualGUI Version

Purpose of Printer Definitions

A printer definition file acts like a translator for the printer: it tells theprinter how to handle bolding, underlining, printing graphicalcharacters used in lines/boxes, etc. Unlike Version 1.1, printerdefinition files are text files (e.g., ASCII, EBCDIC) that do not requireany additional compressing or compiling before they can be used.

Packaged Printer Definitions

You need to know the following about packaged printer definitions:

• descriptions – B – 2

• location – B – 3

Oracle Reports is shipped with several printer definitions, some ofwhich are described below:

Is a generic printer file for most DEC printers thatsupports 66x80 page sizes for the LN03, LPS40,LP05, and LA50 printers.

Is a generic printer file that prints in landscapemode and supports 66x132 page sizes.

Is the same as dec, but supports 66x132 page sizes.

Is the same as decland, but supports 66x180 pagesizes.

Is a generic printer file that ignores highlightingattributes and supports 66x80 page sizes.

Is a generic printer file for the HP LaserJet printerthat supports 66x80 page sizes.

Is the same as hpl, but supports 66x132 page sizes.

Is a PostScript printer file that prints in a landscapemode and supports 110x51 pages sizes.

Is a PostScript printer file that prints in a landscapemode and supports 132x66 pages sizes.

Is a PostScript printer file that prints in a portraitmode and supports 85x66 pages sizes.

Is a PostScript printer file that prints in a portraitmode and supports 132x120 pages sizes.

dec.prt

decland.prt

decwide.prt

dec180.prt

dflt.prt

hpl.prt

hplwide.prt

pslan110.prt

pslan132.prt

psport85.prt

pspor132.prt

Location


Is a generic printer file that ignores highlightingattributes and supports 66x132 page sizes.

Is the same as wide, but supports 66x180 page sizes.

Note: You might not have all of the printer definitionsdescribed above, and you may have others. This is because theset of printer definitions shipped with Oracle Reports issystem–specific. See your Installation and User’s Guide fordetails on the printer definitions you have.

For more information about the location of packaged printer definitionfiles, see the Developer/2000 Installation Guide for your operating system.

Creating or Modifying Printer Definitions

To create or modify a printer definition, you can do one of thefollowing:

• create a new printer definition file from scratch

• copy an existing printer definition file and modify it as needed

• modify the existing printer definition file

Because printer definition files are text files (e.g., EBCDIC, ASCII), youcan create or modify them using any text editor. Remember to save thefiles as text when you are through. Then, to use the new or modifiedprinter definition, specify it using the DESFORMAT keyword. Formore information, see “Referencing Printer Definitions” on page B – 13.

To create or modify a printer definition, it is critical that youunderstand the required syntax of the file. Its syntax is described in thesection below.

Printer Definition File Syntax

There are many printer code names (e.g., after report) that may be usedto define a printer definition. Some printer code names are used forboth character mode and PostScript printer definitions. Others aremeaningful only for character– or PostScript–based output. The codenames are listed below. The italicized words are described after thelists.

wide.prt

wide180.prt

Common for Characterand PostScript Codes

Character–specificCodes


Code Name and Syntax Usage

after report gen_string Is the gen_string to be sent to the printer after the report has finishedprinting. This code is typically used toensure that the next print job starts on anew page of paper.

before report gen_string Is like AFTER REPORT, only gen_stringis sent before the report begins to print.

after page gen_string Is the gen_string to be sent to the print-er after each physical page (i.e., eachprinter page), including the last.

between page gen_string Is the gen_string to be sent to the print-er after each physical page (i.e., eachprinter page), except the last.

code *string* gen_string Is a user–defined or Oracle Reports–recognized code. See *string* below.

height integer Is the height of the report, in characters.

printer string Is the name of the printer.

width integer Is the width of the report, in characters.


automargin Specifies that a carriage retun not be added at the end of the file when thecharacter in the last column is not null.

autopage Specifies that a formfeed not be executed at the end of a page on whichthe last row is not blank.

box bottom centeri

Is the string to be used to draw the cen-h b d b ( )gen_string

gter of the bottom edge of a box (8).

box bottom lefti

Is the string to be used to draw theb l b ( )gen_string

gbottom–left corner of a box (7).

box bottom righti

Is the string to be used to draw the b h b ( )

ggen_string

gbottom–right corner of a box (9).



box center centeri

Is the string to be used to draw the b ( )gen_stringg

center of a box (5).

box center left gen_string Is the string to be used to draw the center of the left edge of a box (4).

box center righti

Is the string to be used to draw the h h d b ( )

ggen_string

gcenter of the right edge of a box (6).

box horizontal gen_string Is the string to be used to draw the topand bottom edges of a box.

box top center gen_string Is the string to be used to draw the center of the top edge of a box (2).

box top left gen_string Is the string to be used to draw the top–left corner of a box (1).

box top right gen_string Is the string to be used to draw the top–right corner of a box (3).

box vertical gen_string Is the string to be used to draw the leftand right edges of the box.

hilight backspacegen_string

Prints a bold or underlined character byprinting the character, backing up,andthen reprinting the character. The backing up is done according tothegen_string (e.g., esc ”[0m”).

hilight overstrike Simulates bold/underline by prinitngthe line and then reprinting items to bebold or underlining items as appropriate.

landscape gen_string Is the gen_string to be used to make theprinter print in landscape mode.

linefeed gen_string Is the gen_string to be used at the endof each line of a page.

return string gen_string Is the gen_string to be used to put theprinter back at the beginning of the current line.

PostScript–specificCodes



postscript Is the indicator that the printer defini-tion file is for a PostScript printer.

where:

Is an integer, without quotes.

For character printers, is a combination of thefollowing in any order:

• string, e.g., ”abc”

• integer, e.g., 10

• dec(decimal_number), e.g., dec(10)

• oct(octal_number), e.g., oct(10)

• hex(hex_number), e.g., hex(1A)

• ^control_character, e.g., ^L

• control(control_character), e.g., control(L)

• esc escape_string, e.g., esc ”abc”

For PostScript printers, is a combination of thefollowing, in any order, that must be surroundedby double quotes:

• BOLD, i.e., switches to bold

• BOLDFONT, i.e., switches to bold font

• BOLDOBLIQUE, i.e., switches to bold italics

• BOLDOBLIQUEFONT, i.e., switches to bolditalic font

• BOTTOMMARGIN, i.e., switches the bottommargin

• BOX, i.e., switches to box font

• FONTSIZE, i.e., switches the font size

• LANDSCAPE, i.e., switches to landscape mode

• LEFTMARGIN, i.e., sets the size of thenon–printable margin

• MONOSPACE, i.e., switches to monospacespacing (enforce character matrix)

integer

gen_string


• NORMAL, i.e., switches to normal

• NORMALFONT, i.e., switches to normal font

• OBLIQUE, i.e., switches to italics

• OBLIQUEFONT, i.e., switches to italic font

• PAGEHT, i.e., sets the number of characters to befitted on the page vertically

• PAGEWD, i.e., sets the number of characters tobe fitted on the page horizontally

• PAPERHT, i.e., sets the paper height in inches

• PAPERWD, i.e., sets the paper width in inches

• PORTRAIT, i.e., switches to portrait mode

• PROPORTIONAL, i.e., switches to proportionalspacing (don’t enforce character matrix)

• RIGHTMARGIN, i.e., sets the width of the rightmargin

• ROTATE2, i.e., prints two pages per page rotated

• TOPMARGIN, i.e., sets width of top margins

• UNDERLINE, i.e., switches to underlining

• UNDERLINESTOP, i.e., switches off underlining

Is one or more alpha–numeric characters, includingpunctuation, that must be surrounded bydouble–quotes.

Is one of two types of code names: user–created,and Oracle Reports–recognized. A user–definedcode name is any code that you create. Apackaged code is a code name that Oracle Reportswill use when you select an attribute (e.g., BOLD)from a layout object’s Display Sheet dialog box.

• bold off

• bold on

• bold italic underline off

• bold italic underline on

• bold underline off

• bold underline on

string

*string*


• italic off

• italic on

• italic underline off

• italic underline on

• plain off

• plain on

• underline off

• underline on

Note: If you create a printer code and want Oracle Reports touse a user–created generalized string on an object, instead of apackaged string, do one of the following:

• select the Printer Code tab for the layout object, then type yourprinter code name in the Before or After Printer Code field

• use the PL/SQL packaged procedures SRW.DEFAULT_BEFORE_CODE and SRW.DEFAULT_AFTER_CODE

Printer Definition Rules

1. Only one printer definition may be found in each printer definitionfile.

2. Codes may appear in any order; for example, the code named,”HEIGHT,” may be the last code in the file.

3. Codes must be separated by spaces or returns; therefore, multiplecodes may appear on the same line.

4. New lines and spaces are treated identically; that is, if you put areturn at the end of the line, the return will be interpreted as aspace. Exception: When a return is placed within a string, thereturn is interpreted as a return.

5. When specifying printer codes, extra spaces, capitalization, andorder are ignored. For example, all of the following would beconsidered identical:

bold underline off bold UNDERLINE OfF Underline Bold Off


6. Some operating systems may require single–quotes, instead ofdouble–quotes for strings. Also, your printer definition file may becase–sensitive.

7. Like Version 1.1, printer codes with leading zeros are consideredthe same; for example, codes 001 and 1 are identical.

8. If you enter a blank string (””) for the after page code, linefeedswill be inserted until a new page is started.

9. The HILIGHT OVERSTRIKE and HILIGHT BACKSPACE codes aremutually exclusive. In addition, if a recognized printer sequence(e.g., BOLD ON or BOLD OFF) is specified in a file with theHILIGHT codes, the recognized printer sequence will takeprecedence.

10. When you specify a printer definition file for DESFORMAT, OracleReports will search for the file as follows:

• Oracle Reports looks for the file in the path specified inDESFORMAT or the current directory, if no path is specified.

• If the previous attempt fails, Oracle Reports appends the prtextension and looks for the file in the path specified inDESFORMAT or the current directory, if no path is specified.

• If the previous attempt fails, Oracle Reports looks for the file inthe directory containing printer definition files shipped withOracle Reports. For that location, see the Developer/2000Installation Guide for your operating system.

• If the previous attempt fails, Oracle Reports appends the prtextension and looks for the file in the directory containingprinter definition files shipped with Oracle Reports.

If none of these steps is successful, an error is raised.

Printer Definition Examples

The following are examples of five complete driver definitions:

Example of dflt.prt:

printer ”dflt”

height 66

width 80

after report control(L)


after page control(L)

return ””

linefeed control(J)

Example of declno3.prt:

printer ”dec LNO3”

height 66

width 80

return ””

linefeed 10



box horizontal ”–”

box vertical ”|”

box top left ”+”

box top center ”+”

box top right ”+”

box center left ”+”

box center center ”+”

box center right ”+”

box bottom left ”+”

box bottom center ”+”

box bottom right ”+”

code ”box on” ””

code ”box off” ””

code ”bold on” esc ”[1m”

code ”bold off” esc ”[0m”

code ”underline on” esc ”[4m”

code ”underline off” esc ”[0m”

code ”500” esc ”[2N”

Example of dec180.prt:

printer ”dec180”

height 66


width 180

before report control(L)



return ””

linefeed control(J)

code ”bold on” esc ”[1m”

code ”bold off” esc ”[0m”

code ”underline on” esc ”[4m”

code ”underline off” esc ”[0m”

Example of hplwide.prt:

printer ”hplwide”

height 66

width 132

before report esc ”(s0P” esc ”&k2S” esc ”&17.27c66F”



return ””

linefeed control(J)

code ”bold on” esc ”(s7B”

code ”bold off” esc ”(s0B”

code ”underline on” esc ”&dD”

code ”underline off” esc ”&d@”

Example of psport85.prt: The following is a fully–commentedpostscript printer description file. Be aware, however, that the dashesare not supported as comment indicators. Only the percent signs (%)can be used to indicate comments in a PostScript file.

printer ”postscript portrait” –– set printer type

postscript –– declare this a PostScript printer

height 66 –– height of the page in characters

width 85 –– width of the page in characters

return ”” –– unnecessary for PostScript

linefeed ”” –– unnecessary for PostScript


The following portion of the printer definition file sets up the printer bysending PostScript function calls to it.

before report ”

PORTRAIT %% set portrait mode

12 FONTSIZE %% pick a suitable font size

8.5 PAPERWD %% 8.5 x 11 paper size

11 PAPERHT %%

66 PAGEHT %% each page is 80 x 66

85 PAGEWD %%

0.2 LEFTMARGIN %% leave small border

0.2 RIGHTMARGIN %%

0.2 TOPMARGIN %%

0.2 BOTTOMMARGIN %%

NORMAL %% set up normal Courier font

after report ”” –– unnecessary for PostScript

after page ”” –– unnecessary for PostScript

The following codes are box character mappings used by OracleReports for line drawing. Do not modify them.

box horizontal ”a”

box vertical ”b”

box top left ”c”

box top center ”d”

box top right ”e”

box center left ”f”

box center center ”g”

box center right ”h”

box bottom left ”i”

box bottom center ”j”

box bottom right ”k”


The following section sets up the postscript printer codes. These aremuch like other printer codes except that they are plain text codes. Thecodes are inserted directly into the PostScript output stream.

code ”box on” ”BOX”

code ”box off” ”NORMAL”

code ”bold on” ”BOLD”

code ”bold off” ”NORMAL”

code ”underline on” ”UNDERLINE”

code ”underline off” ”UNDERLINESTOP”

code ”italic on” ”OBLIQUE”

code ”italic off” ”NORMAL”

code ”bold italic on” ”BOLDOBLIQUE”

code ”bold italic off” ”NORMAL”

code ”bold underline on” ”BOLD UNDERLINE”

code ”bold underline off” ”NORMAL UNDERLINESTOP”

code ”italic underline on” ”OBLIQUE UNDERLINE”

code ”italic underline off” ”NORMAL UNDERLINESTOP”

code ”bold italic underline on” ”BOLDOBLIQUE UNDERLINE”

code ”bold italic underline off” ”NORMAL UNDERLINESTOP”

code ”1” ” PROPORTIONAL /Times–Bold 14 SETFONT ”

code ”2” ” MONOSPACE NORMAL ”

–– End of printer description file.––

Referencing Printer Definitions

To use a printer definition other than the default, dflt, it is important toknow what the following keywords mean: DESTYPE, DESNAME, andDESFORMAT. DESTYPE is the type of device to which the reportoutput will be sent (e.g., a printer). DESNAME is name of the device towhich the report will be output (e.g., myprinter). DESFORMAT is thefile name that contains the printer definition you want to use.

Command LineExample

Parameter PropertiesRuntime Parameter

Form


You can specify arguments for the aforementioned keywords in threeplaces: the command line, Parameter Form property sheet, and theRuntime Parameter Form. Examples of how to do so are below. Theexamples assume that your printer’s name is HQFLOOR1, and yournew printer definition file is named NEWDEF.

R25DES MYNAME/MYPASS DESTYPE=PRINTER DESNAME=HQFLOOR1DESFORMAT=NEWDEF

Name Value

DESTYPE printer

DESNAME HQFLOOR1

DESFORMAT newdef

Purpose of Terminal Resources

Terminal resources are a collection of related data that specify yourterminal’s capabilities. They contain terminal definitions to describethe attributes of different terminals (e.g., screen width and height,graphics capabilities, etc.) to Oracle Reports. In addition, terminalresources associate application functions with specific terminal keys,using what are known as key bindings. These resources are stored interminal resource files.

Packaged Terminal Resource Files

This section is divided into two parts: a description of some theterminal resource files shipped with Oracle Reports, and the location ofthe terminal resource files.

You need to know the following about packaged terminal resource files:

• descriptions – B – 15

• location – B – 15

Descriptions

Location


Oracle Reports is shipped with several terminal resource files, some ofwhich are described below:

Is a generic resource file that provides a minimumof key bindings and resources. It is used if noresource file is specified at invocation of OracleReports.

Is a resource file that contains the definition andkey bindings for a Sun4 terminal.

Is a resource file that contains the definition andkey bindings for Sun10 terminal.

Is a resource file that contains the definition andkey bindings for a VT100 terminal.



Note: You might not have all of the terminal resource filesdescribed above, and you may have others. This is because theset of terminal resource files shipped with Oracle Reports issystem–specific. See your Developer/2000 Installation Guide fordetails on the terminal resource files you have.

For more information about the location of packaged terminaldefinition files, see the Developer/2000 Installation Guide for youroperating system.

Creating or Modifying Terminal Resources

Resource files for Oracle Reports are created and maintained using atool called Oracle Terminal. In order to modify your terminal resourcefiles, you need access to the Oracle Terminal resource editor ot.

dflt.res

sun4.res

sun10.res

vt100.res

vt220.res

vt320.res


You can only use the Oracle Terminal resource editor to configureterminal resources for an application if the application was built withOracle Terminal support. For Oracle Reports, this means you cannotconfigure terminal resources for the bitmapped version. In addition,the character–mode resources you can configure are restricted to thefollowing:

• key bindings

• terminal definitions

You cannot change the appearance of the runtime interface (dialogboxes, etc.)

We recommend that when you modify terminal resources for charactermode terminals, you use the character–mode ot executable, asdescribed below. Although you can edit resources for any platform onany platform, you must generate key bindings on the platform forwhich they will be used.

Since you’ll be using character–mode executables, you need to knowthe character–mode notational convention for representing functionkeys. Function keys for both Oracle Reports and Oracle Terminal arerepresented by the name of the function enclosed in square brackets(e.g., [Next Page]). You can refer to a keypad diagram or the ShowKeys screen (accessible through Help) for a mapping of these functionkeys to physical keys on your keyboard.

Note: It is beyond the scope of this documentation toexhaustively cover Oracle Terminal’s capabilities. Nor can weprovide a tutorial for Oracle Terminal. Be aware that thisdiscussion is limited to the aspects of Oracle Terminal thatrelate to Oracle Reports. In addition, the following examplesdo not include certain tasks, such as adding devices to the listof devices recognized by Oracle Reports, that can moreproperly be considered administrative in nature.

For more information on Oracle Terminal and the different types ofresources you can edit with it, see your Oracle Terminal User’s Guide.

Oracle Terminal replaces the SQL*ReportWriter V1.1 utility TERMDEF.

Modifying KeyBindings


You can modify key bindings—the designations that ”attach” certainkeys to certain functions—but Oracle Reports defines the functions towhich you can bind keys.

Steps to Modify Key Bindings Use your operating system copycommand to copy the resource file containing the key bindings youwant to modify, and save the file under a unique name. (You aregenerally not allowed write–access to files used by Oracle Reports; thiswill provide you with a file to edit.)

Invoking Oracle Terminal To invoke the Oracle Terminal resource editor,do the following:

1. At the operating system prompt, type the command:

ot

and press Return.

2. A file selection dialog appears. Select the resource file you want tomodify.

Note: You can also include the name of the resource file inyour command–line invocation of ot, as follows:

ot resfile

where resfile is the name of the resource file (the extension,where applicable, is optional). Include all path informationnecessary to precisely locate the resource file.

The ot Main Window The resource editor’s main window appears.Use this window to choose the product (e.g., Oracle Reports), thedevice, or terminal, whose resources you want to modify (e.g., VT100,Sun4, etc.), and the type of action you want to take.

3. With the cursor on the Product field, press [List]. A list of valuesappears, displaying all the products whose resources you canmodify using ot. Select Oracle Reports from the list.

4. Press [Next Field] until the cursor is positioned at the field next toDevice. Press [List]. A list of values appears, displaying the namesof all the terminals with available terminal resource files. Selectyour terminal type from this list.

5. Press [Invoke Menu] to access the main menu, then selectFunction—>Edit Keys.

The Key Binding Editor The ot key binding editor is displayed. Usingthis editor, you can change any key binding for your application.


6. Select a component by pressing [Next Field] until you reach theComponent list, then pressing [Select] with the cursor positionedon the component you want to modify.

Note: If a component has further subcomponents, pressing[Select] will not select the component. Instead, it will cause thenext lower level in the hierarchy of components to be displayedin the component list.

A component in this case represents a part of OracleReports—either a location, such as the Runtime Parameter Form orthe Previewer, or a class of actions, such as navigation—for which agrouping of key bindings is valid. Global key bindings are validfrom anywhere in the runtime engine. Common key bindings arevalid not only in Oracle Reports, but in other Oracle tools as well.

Notice that when you select a component, the Edit Key Bindings...button is highlighted.

7. Press [Next Field] until the cursor is positioned at Edit Key Bindings..., then press [Accept].

The Key Binding Definition Table The key binding editor displays the keybinding definition table. This table shows all the actions that are a partof the selected component and the keys to which the actions are bound.

8. Press [Next Field] once to position the cursor in the list of bindings,then press [Next Item] until you reach the binding you want tochange. Replace the name of the key to which the action iscurrently bound with the name of the key you want to use.

9. Once you have made the desired changes, select OK.

The main window is displayed. Here you can apply or cancel yourmodifications, as desired. If you wish to cancel your modifications,press [Invoke Menu], then select File—>Close, or File—>Quit, anddo not save your file. If you want to save your modifications,continue to the next step.

Saving Your Modifications

10. Press [Invoke Menu], then select File—>Save.

At this point you have not saved a modified version of yourresource file. Instead, you have saved the changes you want tomake to the resource file. To actually incorporate the new keybindings into your resource file you need to regenerate it.

11. Press [Invoke Menu], then select Function—>Generate.

This generates a new resource file, incorporating the changes youmade to the key binding.

Modifying TerminalDefinitions


An alert appears, telling you that your resources file has beensuccessfully generated. Accept the alert.

Note: If you receive an error message instead, consult yourOracle Terminal User’s Guide.

12. Press [Invoke Menu], then select File—>Save.

Though you seem to be duplicating step 11, you are actually savinga very different file in this step. You are saving the resource file,and can now use it to determine the key bindings your terminaluses for Oracle Reports.

13. To exit ot , press [Invoke Menu], then select File—>Quit.

Testing Your Changes To test your new key bindings, invoke the OracleReports character–mode runtime engine and display the Show Keysscreen.

14. Enter the following on the command line, once again including allnecessary path information:

r25run term=resfile

In the command above, the argument term=resfile serves twopurposes: it tells Oracle Reports which terminal resource file youwant to use, and this, in turn, identifies your terminal to OracleReports. In order to use the new key bindings you just created, theresfile portion of the argument must refer to the resource file youjust generated. To ensure that Oracle Reports uses the correct file,include the appropriate path information.

15. Display the Show Keys screen and examine the keys listed. Theyshould reflect the changes you made to the key bindings.

Terminal definition file contain information about the capabilities ofdifferent terminal types. They apply only to character–mode andblock–mode terminals, and any terminals emulating such devices.Oracle Reports ships several terminal definition files for such standardterminals as the DEC family of VT100, VT220, and VT320 terminals. Ifnecessary, you can modify any one of these to provide a definition for anon–standard terminal.

Terminal definitions, unlike key bindings, describe a terminal’s intrinsiccapabilities. Therefore, the following steps show where and how tochange terminal definition, but make no actual changes. Werecommend that you do not change the terminal definition unless youare creating a new definition for a non–standard terminal and areprovided with all necessary specifications by your terminal’sdocumentation.


Steps to Modify a Terminal Definition

1. Invoke Oracle Terminal. For more information on how to do this,see “Invoking Oracle Terminal” on page B – 17. Specify a resourcefile.

2. Once in the main window, specify Oracle Reports as the product.For information on how to do this, see “The ot Main Window” onpage B – 17. Then press [Invoke Menu] and select Function—>EditDevices....

The Device Class Editor The device class editor is displayed. The deviceclass editor displays all devices included in the specified product (inthis case, Oracle Reports). It also shows all ancestor classes of thedevices (i.e., for a VT220 terminal, an ancestor class might be”character mode”). Use this editor to select the specific device whoseterminal definition you want to modify. If you need to add a definitionfor a non–standard terminal, it is generally easier to select a similarterminal and modify its terminal definition, then save the modificationsunder a new name.

3. Press [Next Field] until the cursor is positioned in the list of devices(”This Class”). If the designation for your terminal does notappear, your terminal may be on a lower level in the devicehierarchy.

To the right of the class list is a graphical representation of thedevice hierarchy. Use this to trace your terminal’s ancestry. Whenyou find its ancestor, position the cursor on that device in the classlist and press [Accept]. Follow the class levels down until thedesignation for your terminal appears in the class list. Position thecursor on the terminal name and press [Select].

4. Edit Device... is highlighted. Press [Next Field] until the cursor islocated on the Edit Device button, then press [Accept].

The Device Display Definition Screen The device display definition screenis shown. This is a list of device characteristics that Oracle Reportsrefers to when communicating with your terminal. Change any ofthese values by pressing [Next Field] until the cursor is located at theappropriate field and entering the desired value.

The buttons, Attributes..., Modifiers..., Standard Keys..., and UserKeys... lead to further dialogs that enable you to modify other aspectsof the terminal definition. See your Oracle Terminal User’s Guide formore information on these dialogs.


Unless you specifically intend to create a new terminal definition filefor a non–standard terminal, do not change any of these values. Theyare fixed according to device, and not user–definable.

If you are creating a new terminal definition file for a non–standardterminal, refer to the documentation for your terminal for the propervalues to use.

5. When you are finished modifying the file, press [Invoke Menu] andselect Windows, then select the main window, which is identifiedby the name of the resource file you are editing. Exit out of OracleTerminal without saving, or save, generate, and save your resourcefile. For more information on saving, see “Saving YourModifications” on page B – 18.

In this case, however, you may wish to use Save As... so you do notoverwrite the original file.

Terminal Definition Rules

1. Some operating systems may require single–quotes, instead ofdouble–quotes for strings. Also, your terminal resource file may becase–sensitive. See your Installation and User’s Guide for details.

2. When you specify a terminal resource file, Oracle Reports willsearch for the file first in the path specified, then in the currentdirectory, if no path is specified, and finally in the directoryallocated by Oracle Reports for the terminal resource files. Thelocation of this directory is installation–specific. For moreinformation about the location of files, see the Developer/2000Installation Guide for your operating system.

Referencing Terminal Resource Files

To use a terminal resource file other than the default, specify it with theterm keyword on the command line when you invoke thecharacter–mode runtime executable, as follows:

R25RUN MYNAME/MYPASS TERM=VT220

Make sure to specify all necessary path information.

A P P E N D I X

CW

C – 1National Language Support

National LanguageSupport

ith National Language Support (NLS), you can do the following:

• specify the language in which the Oracle Reports executablesshould display and accept input

• create modules that can be translated easily

• specify the language in which to run a Oracle Reports module, sothat its result (output) is in the language you specify—even if thedata in ORACLE is in a different language, and even if themodule was built in a different language

You should know the following about NLS:

• definition and purpose – C – 2

• specifying – C – 2

• overriding defaults – C – 3

• translating reports – C – 7

• bidirectional support – C – 8

C – 2 Reports Reference ManualGUI Version

Definition and Purpose of NLS

NLS is a product of Oracle Corporation, which enables you to interactwith its products, such as Oracle Reports and ORACLE, in your nativelanguage.

NLS provides support for the following:

• processing data in the various character encoding schemes usedby computer hardware

– it supports both single–byte and multi–byte characterencoding schemes

– it supports the client and server using different characterencoding schemes, and transparently converts data betweenthem

• operating language–dependent Oracle Tools

– it displays error messages and hints in multiple languages

– it formats dates and numbers using language and territoryconventions

– it sorts character data according to alphabetic conventions

– it enables you to specify language–dependent operations foreach session

• designing a module (e.g., a report) that runs in multiplelanguages

Specifying NLS_LANG, DEV_NLS_LANG, and USER_NLS_LANG

NLS_LANG is an environment variable. If you want to use any NLSfeature, you must set this environment variable so that Oracle Reportscan locate the NLS components. Define NLS_LANG in the samefashion you define other environment variables on your base operatingsystem, keeping in mind such platform–specific rules as path length,etc..

For the purposes of bi–directional support, you can also set thefollowing environment variables:

• DEV_NLS_LANG specifies the language for the Oracle Reportsdesigner.

• USER_NLS_LANG specifies the language for Oracle Reportsruntime.

Using ALTERSESSION


Overriding NLS Defaults

This section describes how you can override NLS defaults by doing thefollowing:

• using ALTER SESSION

• using DATE and NUMBER format masks

• using NLS parameters/functions in SQL functions

• using CONVERT to convert data

• using NLSSORT to sort character data

You can use the ALTER SESSION SQL command, to override the NLSdefaults. An ideal place to do this is in the After Form trigger. Forexample, suppose you create some parameters (such as language,territory, etc.), and a user specifies values for them on the RuntimeParameter Form: you could then alter the session as they specified.

Caution: If NLS_LANG is not defined, an ALTER SESSION statementis not executed.

As a reminder, you can specify the following NLS parameters for theALTER SESSION command:

Parameter Description

NLS_LANGUAGE language used by ORACLE to returnmessages and errors

NLS_TERRITORY territory used for default date andcurrency masks

NLS_DATE_FORMAT default format used for dates

NLS_DATE_LANGUAGE default language used for dates

NLS_NUMERIC_CHARACTERS

decimal character and group separa-tor

NLS_ISO_CURRENCY ISO international currency symbol

NLS_CURRENCY local currency symbol

NLS_SORT character sort sequence

For details on these parameters, see the ORACLE7 SQL LanguageReference Manual.

Using Date andNumber Formats


The following formats are meaningful for NLS:

Date Element What Is Returned

D digit for the day (1–7)

DY name of the day (abbreviated)

DAY name of the day (padded with blanks tolength of 9 characters)

WW digit for the week, calculated by the algorithm int((day–jan1)/7)

IW digit(s) of the ISO week

MON name of the month (abbreviated)

MONTH name of the month (padded with blanks tothe length of 9 characters)

RM character for the Roman numeral month

I, IY, IYY, IYYY last 1, 2, or 3 digit(s) of the ISO year

BC, AD, B.C., A.D. BC or AD indicator (with or without periods)

AM, PM., A.M., P.M. AM or PM indicator (with or without periods)

For more information on ISO and its date format masks, see theORACLE7 SQL Language Reference Manual.

Number Element What Is Returned

D character that separates the integer and decimal portions of a number

G character that separates groups in the integer portion of a number

L local currency symbol

C ISO currency symbol

Using NLSParameters/Functionsin SQL Functions

Using CONVERT toConvert Data

Using NLSSORT toSort Character Data


Wherever you use SQL, you can use the following NLS parameters tooverride default NLS behavior.

SQL Function NLS Parameter

TO_DATE NLS_DATE_LANGUAGE

TO_NUMBER NLS_NUMERIC_CHARACTERS,

NLS_CURRENCY,

NLS_ISO_CURRENCY

TO_CHAR NLS_DATE_LANGUAGE,

NLS_NUMERIC_CHARACTERS,

NLS_CURRENCY,

NLS_ISO_CURRENCY

NLS_UPPER NLS_SORT

NLS_LOWER NLS_SORT

NLS_INITCAP NLS_SORT

NLSSORT NLS_SORT

For details on these parameters, see the ORACLE7 SQL LanguageReference Manual.

You can use the SQL function CONVERT to sort convert data. Thisfunction converts the binary representation of a character string in onecharacter set to another. For a complete description of CONVERT, seethe ORACLE7 SQL Language Reference Manual.

You can use the SQL function NLSSORT to sort character data. Thisfunction replaces a character string with the equivalent sort string usedby the sort mechanism. For a binary sort, the sort string is the same asthe input string.

The linguistic sort technique operates by replacing each character stringwith some other binary values, chosen so that sorting the resultingstring produces the desired sorting sequence. When a linguistic sort isbeing used, NLSSORT returns the binary values used to replace theoriginal string.

This section covers the following:

• comparing strings in a WHERE clause

• controlling an ORDER BY clause

Comparing Strings in aWHERE Clause

Controlling an ORDER BYClause


Character strings in a WHERE clause are compared using thecharacters’ binary values: a character is ’greater than’ another if it hasa higher binary value in the database character set. Because thesequence of characters based on their binary values may not match thealphabetic sequence for a language, the comparisons often do notfollow alphabetic conventions.

Examples: Suppose you have a column (COL1) that contains the valuesABC, ABZ, BCD and A umlaut BC in the ISO 8859/1 8–bit characterset. Suppose also, that you wrote the following query:

SELECT COL1 FROM TAB1 WHERE COL1 > ’B’

The query would return both BCD and BC since A umlaut has a highernumeric value than B.

As a result, you can perform linguistic comparisons using NLSSORT inthe WHERE clause, as follows:

WHERE NLSSORT(column) operator NLSSORT(string)

Notice that NLSSORT has to be used on both sides of the comparisonoperator.

Examples:

SELECT COL1 FROM TAB1 WHERE NLSSORT(COL1) > NLSSORT(’B’)

If a German linguistic sort is being used, this will not return stringsbeginning with A umlaut, because A umlaut comes before B in theGerman alphabet. If a Swedish linguistic sort is being used, thosestrings would be returned, because A umlaut comes after Z in theSwedish alphabet.

If a linguistic sorting sequence is in use, then NLSSORT is implicitlyused on each character item in the ORDER BY clause. As a result, thesort mechanism (linguistic or binary) used for an ORDER BY istransparent to the application.

However, if the NLSSORT function is explicitly specified for a characteritem in an ORDER BY item, then the implicit NLSSORT is not done. Inother words, the NLSSORT linguistic replacement is only applied once,not twice.


The NLSSORT function is generally not needed in an ORDER BYclause, when the default sort mechanism is a linguistic sort. However,when the default sort mechanism is BINARY, then a query such as:

SELECT ENAME FROM EMP

ORDER BY ENAME

will use a binary sort. A linguistic sort (for German in the examplebelow) can be obtained using:

SELECT ENAME FROM EMP

ORDER BY NLSSORT(ENAME, ’NLS_SORT = GERMAN’)

Translating Reports

When you save a report, Oracle Reports stores all strings specially, sothat you can translate them. If your report is stored in an .rdf file, thestrings are in ui_strings. If your report is stored in the database, thestrings are in a public synonym called ROSSTRINGS.

After the strings are translated, the report will run normally, unless thetranslated strings occupy more space than before they were translated.If they do, and layout objects are Fixed or Contracting, the strings maybe truncated, or overflow to the next page. (Recall that text and dataoverflow; images and graphics are truncated if their layout object isFixed or Contracting and is smaller than what it is trying to format.)

Translation tools will be available with NLS*Workbench to assist thetranslation of applications. For a complete description of theNLS*WorkBench and its features, refer to the NLS*WorkBench ReferenceGuide.


Printer Definitions and NLS

When using NLS in character mode, you should define the physicalpage width of the report as one character less than the page widthdefined in the printer definition. Otherwise, multibyte charactersmight start on the last character space of a line and have to overflow tothe next line in order to complete. For example, if the physical pagewidth is 80 characters and the width in the printer definition is 80characters, a multibyte character might start on the 80th character.Since multibyte characters may not be separated, the line would haveto overflow to an 81st character in order to complete the multibytecharacter. To avoid this, the physical page width should be set to 79 forthe report.

Bidirectional Support

NLS support for Middle–Eastern and North African languagesincludes bidirectional support for languages whose natural writingdirection is right–to–left.

Bidirectional support allows developers to control:

• layout direction, which includes displaying items with labels atthe right of the item and correct placement of check boxes andradio buttons

• reading order, which includes right–to–left (RTL) or left–to–right(LTR) text direction

• alignment, which includes switching point–of–origin from upperleft to upper right

In addition to the NLS_LANG environment variable, bidirectionalapplications may use two additional NLS_LANG environmentvariables:

• DEVELOPER_NLS_LANG

• USER_NLS_LANG

Four properties are used to specify the appearance of objects inbidirectional applications:

• Align

• Direction (for an object)

• Direction (for the report)


The bidirectional properties are added to objects in the followinghierarchy:

Module

Boilerplate

Field

External Boilerplate

Button

Parameter Form Biolerplate

Objects not in this list either do not require bi–directional support (e.g.,images) or they are automatically defaulted from one of the aboveobject’s properties.

A P P E N D I X

DW

D – 1Naming Conventions

Naming Conventions

hen working with modules and report–level objects in OracleReports, you must follow certain naming conventions. You shouldknow the naming conventions for the following:

• modules – D – 2

• data model objects – D – 2

• layout objects – D – 3

• parameter form objects – D – 3

Database Objects

Files

D – 2 Reports Reference ManualGUI Version

Module Naming Conventions

When working with modules, you must follow certain namingconventions. The conventions you follow depend upon whether themodule is stored in the database or an operating system file.

The naming conventions for Oracle Reports modules stored in thedatabase are similar to the SQL naming standards. Specifically, modulenames:

• can be up to 30 bytes long

• must begin with a letter

• are not case–sensitive

• can contain letters, numbers, and the special characters $, #, @,and _

• cannot duplicate the name of another object of the same type(e.g., two reports cannot have the same name)

When naming objects that are stored in operating system files, youmust follow the naming conventions for database objects (see previoussection) plus the file naming conventions of your operating system. Ifyou are saving an object as an operating system file, it is stored inASCII format with an extension of:

• .rex (for a report)

• .sql (for an external query)

• .pls (for an external PL/SQL library)

Data Model Object Naming Conventions

The naming conventions for data model objects are the same as theSQL naming standards. Specifically, data model object names:





• cannot duplicate the name of another data model object of thesame type in the same report

Parameter NameRestrictions

D – 3Naming Conventions

In addition to the above data model object naming conventions,parameter names must not be the same as any Oracle Reports objectname or R25RUN command line keywords. For more information onthe R25RUN command line keywords, see “R25RUN” on page 1 – 17.

Layout Object Naming Conventions

The naming conventions for layout objects are the same as the SQLnaming standards. Specifically, layout object names:





• cannot duplicate the name of another layout object of the sametype in the same report

Parameter Form Object Naming Conventions

When working with parameter form objects, you must follow certainnaming conventions. The naming conventions are the same as the SQLnaming standards. Specifically, parameter form object names:





• cannot duplicate the name of another parameter form object ofthe same type in the same report

D – 4 Reports Reference ManualGUI Version

A P P E N D I X

ET

E – 1SQL Topics

SQL Topics

o make creating and maintaining external and report–level querieseasier, you should know about the following:

• using the Tables and Columns dialog box – E – 2

• using aliases – E – 2

• inserting comments – E – 2

• reviewing SELECT statement errors – E – 3

• referencing columns and parameters – E – 3

• using Data Manipulation Language (DML) and Data DefinitionLanguage (DDL) – E – 9

For more information on SQL, see the ORACLE7 Server SQL LanguageReference Manual.

Aliases and Parameters

E – 2 Reports Reference ManualGUI Version

Using the Tables and Columns Dialog Box

To make building a SELECT statement for your external or report–levelquery, you can select Tables/Columns from the Tools menu. Thisdisplays the Tables and Columns dialog box. From this dialog box, youcan construct a SELECT statement without writing any SQL yourself.

Using Aliases

You can use aliases in your query SELECT statement as you would inany other SELECT statement. For more information on aliases, see theORACLE7 Server SQL Language Reference Manual. If you use an alias fora column, that alias becomes the name of the column in Oracle Reports.

When using an alias in conjunction with a parameter, you must becautious about changing the column associated with the alias. Forexample, suppose you created the following SELECT statement foryour query:

SELECT &NAME NAME, &PAY PAY FROM EMP

Assume that when you initially build the report, &NAME is the nameof a CHAR column and &PAY is the name of a NUMBER column. If atruntime you enter the name of a column for the &NAME parameterthat is not a CHAR column, you will get an error. Because the name ofthe alias is unchanged, Oracle Reports assumes that the column has thesame datatype as when you built the report (i.e., CHAR).

Inserting Comments

You can insert comments directly into your SELECT statement usingOracle’s standard SQL comment delimiters (e.g., /* comment */).Refer your ORACLE7 Server SQL Language Reference Manual.

Note: You can also use the Comment button in the Queryproperty sheet to enter comments.

E – 3SQL Topics

Reviewing SELECT Statement Errors

The SELECT statement for an external or report–level query is parsedwhen you accept or attempt to perform an operation that would closethe property sheet. If you have made a SQL error, an error message isdisplayed in a dialog box. A pointer (==>) will appear in the errormessage at the point where the error occurred. After you accept theerror message, your cursor will be placed at the error.

Referencing Columns and Parameters

In SQL or PL/SQL, you can reference Oracle Reports columns andparameters. When you run the report, the values of the Oracle Reportscolumns and parameters are substituted for their references in the SQLor PL/SQL. In Oracle Reports, there are two types of references:

• bind – E – 4

• lexical – E – 5

Rules:

1. When using bind and lexical references in a query, you need tospecify an Initial Value or Value If Null for the parameter orcolumn, respectively, if the query will not parse correctly withoutthe value. For example, a query must have a FROM clause. If youcreate a query that uses a lexical reference for the FROM clause, theparameter corresponding to the lexical reference must have anInitial Value (e.g., EMP) so that the SELECT statement is valid.

2. Parameters with a Datatype of Character are not padded, unlessyou explicitly pad them in a SQL statement.

3. If an Oracle Reports column is a summary with a Reset At settingof Page, the column cannot be referenced (via bind or lexicalreference) in a query. For example, if AVG_SAL is a summarycolumn that computes the average salary for each page of yourreport, the following bind reference would be invalid:

SELECT SAL FROM EMP WHERE SAL > :AVG_SAL

Bind References

SELECT Clause

WHERE Clause


4. A query can only contain references to columns with a Type ofDatabase belonging to a group above the query (i.e., a group that isa parent or an ancestor of the query). For example, suppose groupG_1 contains a database column named SAL and belongs to queryQ_1. Group G_1 owns another query named Q_2. You couldreference SAL in Q_2 but not in Q_1.

5. A query can only contain references to a summary or formulacolumn whose source column is below the query. For example,suppose you create a summary column named SUM_SAL in groupG_1. SUM_SAL summarizes the column named SAL, which is alsoin group G_1. G_1 belongs to query Q_1 and owns another querynamed Q_2. Therefore, query Q_1 can contain a reference toSUM_SAL, but query Q_2 cannot contain such a reference.

6. If a reference is made to a parameter with a Datatype of Date isused in an expression, a TO_DATE function should be used.

Bind references are used to replace a single value in SQL or PL/SQL,such as a character string, number, or date. Specifically, bind referencesmay be used to replace expressions in SELECT, WHERE, GROUP BY,ORDER BY, HAVING, CONNECT BY, and START WITH clauses ofqueries. Bind references may not be referenced in FROM clauses or inplace of reserved words or clauses.

You create a bind reference by entering a colon (:) followedimmediately by the column or parameter name. If you do not create acolumn or parameter before making a bind reference to it in a SELECTstatement, Oracle Reports will create a parameter for you by default.

Rules:

1. Bind references must not be the same name as any reserved SQLkeywords. For more information, see the ORACLE7 Server SQLLanguage Reference Manual.

Following are some examples of bind references:

SELECT CUSTID, NVL(COMMPLAN, :DFLTCOMM) COMMPLAN

FROM ORD

The value of DFLTCOMM replaces null values of COMMPLAN in the rowsselected.

SELECT ORDID, TOTAL

FROM ORD WHERE CUSTID = :CUST

The value of CUST is used to select a single customer.

GROUP BY Clause

HAVING Clause

ORDER BY Clause

CONNECT BY andSTART WITH Clauses

PL/SQL

Lexical References

E – 5SQL Topics

SELECT NVL(COMMPLAN, :DFLTCOMM) COMMPLAN, SUM(TOTAL) TOTAL

FROM ORD GROUP BY NVL(COMMPLAN, :DFLTCOMM)

All non–aggregate expressions such as NVL(COMMPLAN, :DFLTCOMM) inthe SELECT clause must be replicated in the GROUP BY clause.

SELECT CUSTID, SUM(TOTAL) TOTAL

FROM ORD GROUP BY CUSTID

HAVING SUM(TOTAL) > :MINTOTAL

The value of MINTOTAL is used to select customers with a minimumtotal of orders.

SELECT ORDID, SHIPDATE, ORDERDATE, TOTAL

FROM ORD ORDER BY DECODE(:SORT, 1, SHIPDATE, 2, ORDERDATE)

The value of SORT is used to select either SHIPDATE or ORDERDATE asthe sort criterion. Note that this is not the same as ORDER BY 1

because :SORT is used as a value rather than to identify the position ofan expression in the SELECT list.

References in CONNECT BY and START WITH clauses are used in thesame way as they are in the WHERE and HAVING clauses.

procedure double is

begin;

:my_param := :my_param*2;

end;

The value of myparam is multiplied by two and assigned to myparam.

Lexical references are placeholders for text that you embed in aSELECT statement. You can use lexical references to replace the clausesappearing after SELECT, FROM, WHERE, GROUP BY, ORDER BY,HAVING, CONNECT BY, and START WITH.

You cannot make lexical references in a PL/SQL statement. You can,however, use a bind reference in PL/SQL to set the value of aparameter that is then referenced lexically in SQL. Look at the examplebelow.


You create a lexical reference by entering an ampersand (&) followedimmediately by the column or parameter name. A default definition isnot provided for lexical references. Therefore, you must do thefollowing:

• Before you create your query, define a column or parameter inthe data model for each lexical reference in the query. Forcolumns, you must enter Value if Null, and, for parameters, youmust enter Initial Value. Oracle Reports uses these values tovalidate a query with a lexical reference.

• Create your query containing lexical references.

Rules:

1. You cannot make lexical references in a PL/SQL statement.

2. If a column or parameter is used as a lexical reference in a query, itsDatatype must be Character.

3. If you want to use lexical references in your SELECT clause, youshould create a separate lexical for each column you will substitute.In addition, you should assign an alias to each lexical reference.This enables you to use the same layout field and boilerplate labelfor whatever value you enter for the lexical on the RuntimeParameter Form. See the example below.

4. If you use lexical references in your SELECT clause, you mustspecify the same number of items at runtime as were specified inthe report’s data model. In addition, each value you specify foryour lexical references at runtime must have the same datatype asits Initial Value. Look at the example below.

5. An Oracle Reports link should not depend upon a lexical reference.That is, neither the child column of a link or its table name shouldbe determined by a lexical reference. To achieve this functionality,you need to create a link with no columns specified and then enterthe SQL clause (e.g., WHERE) for the link directly in the query. Forexample, your parent and child queries might be written asfollows:

Parent Query: SELECT DEPTNO FROM EMP Child Query: SELECT &PARM_1 COL_1, &PARM2 COL_2 FROM EMP WHERE &PARM_1 = :DEPTNO

Note how the WHERE clause makes a bind reference to DEPTNO,which was selected in the parent query. Also, this exampleassumes that you have created a link between the queries in theData Model editor with no columns specified.

SELECT Clause

FROM Clause

WHERE Clause

GROUP BY Clause

E – 7SQL Topics

6. A lexical reference cannot be used to create additional bindvariables after the After Form trigger fires. For example, supposeyou have a query like the following (note that the WHERE clause isreplaced by a lexical reference):


&where_clause

If the value of the WHERE_CLAUSE parameter contains areference to a bind variable, you must specify the value in the AfterForm trigger or earlier. You would get an error if you supplied thefollowing value for the parameter in the Before Report trigger:

WHERE SAL = :new_bind

If you supplied this same value in the After Form trigger, the reportwould run.

Following are some examples of lexical references:

SELECT &P_ENAME NAME, &P_EMPNO ENO, &P_JOB ROLE

FROM EMP

P_ENAME, P_EMPNO, and P_JOB can be used to change the columnsselected at runtime. For example, you could enter DEPTNO as the valuefor P_EMPNO on the Runtime Parameter Form. Note that in this case,you should use aliases for your columns. Otherwise, if you change thecolumns selected at runtime, the column names in the SELECT list willnot match the Oracle Reports columns and the report will not run.

SELECT ORDID, TOTAL FROM &ATABLE

ATABLE can be used to change the table from which columns areselected at runtime. For example, you could enter ORD for ATABLE atruntime. If you dynamically change the table name in this way, youmay also want to use lexical references for the SELECT clause (look atthe previous example) in case the column names differ between tables.

SELECT ORDID, TOTAL

FROM ORD WHERE &CUST

CUST can be used to restrict records retrieved from ORD. Any form ofthe WHERE clause can be specified at run–time.

SELECT NVL(COMMPLAN, DFLTCOMM) CPLAN, SUM(TOTAL) TOTAL

FROM ORD GROUP BY &NEWCOMM

The value of NEWCOMM can be used to define the GROUP BY clause.

HAVING Clause

ORDER BY Clause

CONNECT BY andSTART WITH Clauses

Multiple Clauses

PL/SQL and SQL


SELECT CUSTID, SUM(TOTAL) TOTAL

FROM ORD GROUP BY CUSTID

HAVING &MINTOTAL

The value of MINTOTAL could, for example, be used to select customerswith a minimum total of orders.

SELECT ORDID, SHIPDATE, ORDERDATE, TOTAL

FROM ORD ORDER BY &SORT

The value of SORT can be used to select SHIPDATE, ORDERDATE, ORDID, orany combination as the sort criterion. It could also be used to add onto the query, for example to add a CONNECT BY and START WITHclause.

Parameters in CONNECT BY and START WITH clauses are used in thesame way as they are in the WHERE and HAVING clauses.

SELECT &COLSTABLE

COLSTABLE could be used to change both the SELECT and FROMclauses at runtime. For example, you could enter DNAME ENAME,LOC SAL FROM DEPT for COLSTABLE at runtime.

SELECT * FROM EMP &WHEREORD

WHEREORD could be used to change both the WHERE and ORDER BYclauses at runtime. For example, you could enter WHERE SAL > 1000ORDER BY DEPTNO for &WHEREORD at runtime.

SELECT &BREAK_COL C1, MAX(SAL)

FROM EMP

GROUP BY &BREAK_COL

BREAK_COL is used to change both the SELECT list and the GROUP BYclause at runtime. The Initial Value of the parameter &BREAK_COL isJOB. At runtime, the user of the report can provide a value for aparameter called GROUP_BY_COLUMN (of Datatype Character). Inthe Validation Trigger for GROUP_BY_COLUMN, you call thefollowing PL/SQL procedure and pass it the value ofGROUP_BY_COLUMN:

E – 9SQL Topics

procedure conv_param (in_var IN char) is

begin

if upper(in_var) in (’DEPTNO’,’EMPNO’,’HIREDATE’) then

:break_col := ’to_char(’||in_var||’)’ ;

else

:break_col := in_var;

end if;

end;

This PL/SQL ensures that, if necessary, a TO_CHAR is placed aroundthe break column the user chooses. Notice how in SQL, you make alexical reference to BREAK_COL. In PL/SQL, you must make a bindreference to BREAK_COL because lexical references are not allowed inPL/SQL.

Using DML or DDL

If you want to use DML or DDL in your PL/SQL, you should use theSRW.DO_SQL packaged function. Note that SRW.DO_SQL shouldonly be used for DML and DDL, you should not use it to fetch data.For more information on the syntax of SRW.DO_SQL, see“SRW.DO_SQL” on page 13 – 43. For more information on DML andDDL, see the ORACLE7 Server SQL Language Reference Manual.

Because of Oracle Reports’ processing model, it is recommended thatyou only use DDL in the Before Report and After Report triggers. Formore information on these report triggers, see “Trigger Properties” onpage 13 – 17.

DML can be entered from any field that takes PL/SQL.

Note: The use of SRW.DO_SQL adds some overhead to therunning of the report.

A P P E N D I X

FO

F – 1Pattern and Color Palette

Pattern and ColorPalette

racle Reports is shipped with the following palettes:

• pattern – F – 2

• color – F – 4

F – 2 Reports Reference ManualGUI Version

Pattern Palette

This section describes the Oracle Reports pattern palette. A sample ofeach pattern in the palette, along with its name, appears below:

Default Color Palette


Color Palettes

Oracle Reports is shipped with the following types of color palettes:

• default color palette

• supplemental color palette

The default color palette is the one Oracle Reports uses if you do notspecify another one in your preferences. The color palette file is namedvgid.ros. For more information about the location of this file on yoursystem, see the Developer/2000 Installation Guide for your operatingsystem.

The default color palette is defined by the following rules:

1. The upper–left region of the palette contains 16 commonly usedcolors with the following names:

black white green darkgreen

gray darkgray cyan darkcyan

red darkred blue darkblue

yellow darkyellow magenta darkmagenta

2. The lower–left region of the palette contains eight empty cells intowhich you can place custom defined colors.

3. The next five columns are composed of varying shades of gray.Each color is named ’gray<value>’, according to its percentage grayvalue. The values range from 4 to 96, in increments of 4. Forexample, valid color names include ’gray96’, ’gray92’, and ’gray4’.

4. The remainder of the palette contains colors specified by varyingpercentages of red, green, and blue (RGB) components:

– The percentage values for each red or green component are:0, 25, 50, 75, 88, or 100

– The percentage values for each blue component are:0, 50, 75, 88, or 100.

Each color is named ‘r<value>g<value>b<value>’, according to itsRGB values (e.g., the color that is composed of 100% red, 88% blue,and 0% green is named ‘r100b88g0’).

Except for the the color cells described above, the palette iscomposed of five major regions, each containing 36 colors in a 6x6arrangement. These colors are defined by the following rules:

Supplemental ColorPalette

Grayscale


– The red value increases as the colors progress from left toright within each major region.

– The green value increases as the colors progress from top tobottom within each major region.

– The blue value increases as the major regions progress fromleft to right, with all of the colors in a single region using thesame blue value.

Oracle Reports is shipped with the following color palettes that you canimport into a display, or specify in the Tools Options dialog, thusoverriding the default color palette:

• grayscale color palette

• Oracle CDE1 color palette

For more information about the location of these color palette files, seethe Developer/2000 Installation Guide for your operating system.

The grayscale color palette is composed entirely of varying shades ofgray. It is defined by the following rules:

1. The first two colors are named ‘black’ and ‘white’.

2. The remainder of the palette contains colors specified by varyingpercentages of gray. Each color is named ‘gray<value>’, accordingto its gray value. These colors are defined by the following rules:

– The gray value of the first gray color (to the right of ‘white’)is 100%, and is named ‘gray100’.

– As the colors progress from left to right across the palette(and wrapping from the rightmost cell in one row to theleftmost cell in the next), the gray value for each color is .5less than the one before it.

– After ‘gray12.5’, the gray value for each color is .25 less thanthe one before it.

– The gray values continue to decrease to the last color in thepalette, named ‘gray0’.

Oracle CDE1


The Oracle CDE1 color palette was the default color palette in OracleReports 2.0. It is defined by the following rules:

1. The first two columns in the palette contain:

– commonly used colors, named ‘blue’, ‘magenta’, ‘red’,‘cyan’, ‘green’, and ‘yellow’

– shades of gray, named ‘black’, ‘gray60’, ‘gray45’, ‘gray30’,‘gray15’, and ‘white’

2. The remainder of the palette contains colors specified by varyingpercentages of red, green, and blue (RGB) components. Thepercentage value for each component is: 0, 40, 55, 70, 85, or 100.

Each color is named ‘r<value>g<value>b<value>’, according to itsRGB values (e.g., the color that is composed of 100% red, 40% blue,and 0% green is named ‘r100b40g0’).

Except for the first two columns, the palette is composed of sixmajor regions, each containing 36 colors in a 6x6 arrangement.These colors are defined by the following rules:

– The red value increases as the colors progress from left toright within each major region.

– The green value increases as the colors progress from top tobottom within each major region.

– The blue value increases as the major regions progress fromleft to right, with all of the colors in a single region using thesame blue value.

Glossary – 1

Glossary

Aalert An interface element that notifies you of

a condition that occurred because of yourlast action. You must respond to an alert.

alias A secondary name used in a SQLstatement to reference a table, view, orcolumn.

alignment (Field Properties) The methodused to position data within a field; i.e., tothe left, right, center, flush/left, flush/right,or flush/center of the defined width of afield.

ancestor group A group that owns anothergroup, either directly or indirectly.

anchor A layout object used to fix a spot onone object to a spot on another object,ensuring the position of the first object inrelation to the second object.

anchored object The object, known as thechild object, which is anchored or attachedto another object, known as the parentobject.

anchoring object The object, known as theparent object, to which another object,known as the child object, is anchored orattached.

argument 1. An expression within theparentheses of a function, supplying a valuefor the function to operate on. Forexample, in the expression f(x) , x is theargument.2. Clauses containing Oracle Reportsexecutable keywords and their specifiedvalues. For example, DESTYPE=FILE is anargument.

Arrange menu The menu with which youorganize the graphical objects in the editorand specify attributes for the editorcomponents.

ASCII Acronym for American NationalStandard Code for Information Interchange.

attribute See setting.

Bbind reference A reference to a bind

parameter. See bind parameter.bind parameter A parameter used to replace

a single literal value (e.g., a character string,number, or date) appearing anywhere in aSELECT statement.

Glossary – 2 Reports Reference Manual

body A report region that contains the bulkof the report layout (text, graphics, data,and computations). The report bodyappears between the report header andtrailer pages.

boilerplate Text and/or graphics that appearin a report every time it is run. In someproducts this is called ”constant” text orgraphics.

border A user–defined outline around alayout object, usually used to highlight itscontents. Oracle Reports draws borderssuch that half the width of the border liesoutside the edge of the object, and halfinside the edge, as shown below. See alsoedge.

break column A column assigned to a breakgroup.

break group A group used to categorize, orbreak, the records contained in a report intosets. It does this by establishing a hierarchyfor the fetched data. All data in columnsbelonging to a break group are above thedata in columns belonging to other groups.This causes each record fetched for a breakgroup, to only display once, while multiplerelated records in other groups can bedisplayed.

break order (Column Properties) A settingthat indicates the order in which to displaya break column’s data. Valid options areAscending and Descending.

break report A report containing a breakgroup.

button 1. An interface element used to selectan action item, display a dialog box, oracknowledge the current condition.2. A user–created layout object that onlyappears in the Previewer, and, whenpressed, executes a user–specified action.

Ccall interface An interface that enables you

to invoke Oracle Reports executables fromother Oracle products, such as OracleForms, or a user–written 3GL program.

canvas See editor.CGM An acronym for character graphics

metafile.check box An interface element that can be

toggled on or off. See also toggle.child query See detail query.Clipboard A memory buffer. An object

remains in the Clipboard until you cut orcopy another object, or until you quitOracle Reports.

CMDFILE An argument that allows you tospecify a file that contains a set ofarguments for R25DES or R25RUN.

column 1. A data model object createdautomatically for each column expressionin a query’s SELECT list, or createdmanually to perform summaries, formulas,or act as a placeholder.2. A vertical list of data contained in adatabase table. A column has a columnname and a specific data type.

column expression An expression in aSELECT statement that defines whichdatabase column(s) are retrieved. It may bea column name or a valid SQL expressionreferencing a column name.

Glossary – 3

column heading See label.command line An operating–system

command line. Oracle Reports can beinvoked from a command line using anumber of parameters. Not found on allplatforms.

comment A multi–line field in which you canenter explanatory information about anOracle Reports object.

commit To make changes to data (INSERTs,UPDATEs, DELETEs) in the databasepermanent. Before changes are stored, boththe old and new data exist so that changescan be stored or the data can be restored toits prior state.

compile To translate a PL/SQL constructinto binary, executable format. In OracleReports, PL/SQL constructs must becompiled before they are executed.

computation (Column Properties) A settingused to perform runtime calculations ondata fetched from the database. Thesecalculations are a superset of the kinds ofcalculations that can be done directly with aSELECT statement. See also formulacolumn, summary column.

computed column See computation.condition (Query/Link Properties) An

operator that defines the parent query’srelationship to the child query in aparent–child relationship.

Confine mode Layout editor mode thatprevents child objects from being moved orresized on or outside their parent objects.

connect To log on to a database. You mustconnect if you want to create or modifyqueries or run a report.

construct A PL/SQL code structure. Thereare two types of constructs: non–valueconstructs do not return a value; valueconstructs return a value.

coordinates (x,y) The location points forobjects appearing in an editor. x and ycoordinates determine the horizontal (X)and vertical (Y) placement of layout objects.

copy To store a replica of a selected object inthe Clipboard, so that it may be pastedelsewhere in an editor if desired.

cross product Group that owns two or moreother groups and performs a mathematicalcross product (i.e., correlates valuesbetween them).

crosstab See matrix cell.cursor 1. A small icon representing the

mouse pointer. The shape of the cursor willvary, depending on the tool you haveselected in the designer.2. A work area in which ORACLE storesthe current SQL statement, and if thestatement is a query, the result’s columnheadings and one row of the result.

cut To delete one or more Oracle Reportsobjects and store them in the Clipboard, sothat they may be pasted elsewhere in aneditor if desired.

DDatatype (Column and Field Properties) A

setting that specifies the type of datacontained in a column, parameter, or field.May be Character, Number, Date, Long,Long Raw, or Raw.

data model A relational model that defineswhat data should be fetched from thedatabase, what values should be computed,and how data should be ordered in areport. Oracle Reports objects that definethe data model are queries, groups,columns, parameters, and links.


database A set of dictionary tables and usertables that are treated as a unit. Also calleda server.

database cursor See cursor.DATE An ORACLE datatype. A date

column may contain a date and timebetween January 1, 4712 BC and December31, 4712 AD.

default A value that Oracle Reports assignsto a setting if you do not specify one. Also,an Oracle Reports object (such as a group,field, frame, etc.) that Oracle Reportscreates so that you do not need to create ityourself.

DESFORMAT An argument that specifiesthe characteristics of the report’s outputdevice named in DESNAME.

designer The interface, invoked by R25DES,through which you define a module.

DESNAME An argument that specifies thename of the output device to which thereport will be sent.

DESTYPE An argument specifying the kindof output device to which the report will besent (e.g., printer, file, mail).

detail query When defining a master/detailreport, the detail query retrieves all relatedrecords for each record retrieved by themaster, or parent, query.

dialog box A partial screen or window thatprompts you to enter some piece(s) ofinformation necessary to complete anoperation. Dialog boxes are accessedextensively via the various menus.

disabled An interface element state thatmeans a menu item, button, etc., cannot beused in the current context; i.e., it does notrespond to keyboard or cursor/mouseinput.

display format See format mask.

EEBCDIC Acronym for Extended

Binary–Coded Decimal Interchange Code.edge The boundary of a layout object.Edit menu A menu that lists a set of

operations to perform on objects in aneditor (e.g., cut, copy, paste, etc.).

editing region The area of a editor in whichyou can create, modify, position, or deleteobjects while viewing their graphicalrepresentations.

editor A work area in which you define thedata model (Data Model editor), the layout(Layout editor), and the Runtime ParameterForm (Parameter Form editor) for yourreport.

enabled An interface element state thatmeans that a menu item, button, etc., can beused in the current context, that is, itresponds to keyboard or cursor/mouseinput.

enclosing object An object that containsanother object. An object is considered tobe enclosed by another object only if all ofthe following are true: both objects belongto the same region (Body, Margin, Header,or Trailer); the outermost of the two objectsis a frame or repeating frame; theoutermost of the two objects is behind theother object; the innermost of the twoobjects lies entirely within the borders ofthe other object.

execute See run.export To store a copy of the selected text or

image in an editor to a file.expression A PL/SQL value construct

combining variables, constants, literals, andoperations on their values.

Glossary – 5

external PL/SQL library A PL/SQL package,function, or procedure that can bereferenced by the same or multiple reportsand by other Oracle products, any numberof times. These are executed on the moduleside, not the database or server side.

external query ANSI–standard SQL SELECTstatement that can be referenced within thesame or multiple reports, and by otherOracle products, any number of times.These are executed by the database orserver.

Ffield 1. An interface element in which you

enter, edit, or delete data that either definesan object or makes a processing choice.Fields appear in property sheets, dialogboxes, and lists of values.2. A layout object that defines theappearance of a column’s data.

field label See label.file column A column whose value is a

filename. Each file column will displayeither the filename or the actual contents ofthe file (e.g., ASCII and CGM files) basedupon the Link setting in the column’sproperty sheet. If you specify that youwant to link to the file, its contents willappear. If you do not want to link to thefile, only its filename will appear.

File menu A menu that lists a set ofoperations to perform on the selectedmodule.

fill area The area within an object to which afill (color or pattern) should be applied.Each object has two fill areas: inside theobject’s border, and inside the object’s edge.

filter See group filter.

Flex mode Layout editor mode thatautomatically resizes or shrinks parentobjects when child objects are moved orresized, and adjusts the positions of otherlayout objects that might otherwise beaffected by the repositioning or resizing ofthe objects.

foreign key A value or column in one tablethat refers to a primary key in anothertable.

form layout A default layout style in whichlabels appear to the left of fields, and eachrecord prints on a separate logical page.

form letter layout A default layout style thatintermixes boilerplate and fields, wrappinglines at ”word” breaks.

format mask (Field Properties) A settingthat defines the appearance of the value ofa field. For example, a format mask is usedto specify the display of currency amountsand dates.

Format menu The menu used to specifyattributes affecting the appearance ofobjects in the editor.

format trigger A PL/SQL function executedbefore the object to which it is associated isprinted, allowing you to dynamicallychange the formatting attributes of thatobject.

formula column A user–created column thatgets its data from a PL/SQL function orexpression, a user exit, a SQL statement, orany combination of these.

frame A layout object used to enclose otherlayout objects and control the formatting,frequency, and positioning of severalobjects simultaneously.

FROM A required clause of the SQL SELECTstatement that identifies the tables or viewsfrom which data is selected.


function 1. (Column Properties) A settingwith which you specify which operation(e.g., First, Last, Sum, % of Total, etc.) youwant to use to compute the value of asummary column.2. A PL/SQL value construct that requiresa name and the full PL/SQL syntax,including declarations and the BEGIN andEND keywords.

Ggenerate (File menu) To translate the report

definition into a binary, executable file.grant To give a user access to a module.

Only a module’s creator can grant its accessto other users.

group A data model object that is createdautomatically to contain all the columnsselected by a query, or created by the userto modify the hierarchy of the dataappearing in a report; it is used primarilyfor creating breaks in a report, as well as forresetting computations.See also break group.

GROUP BY An optional clause of a SELECTstatement which identifies the level ofsummarizing to be performed beforefetching data from the database.

group filter A PL/SQL function that restrictsthe data fetched by a group.

group name (Group Properties) The name ofa group. Groups are named so they can bereferenced by other objects.

group’s query The query that selects data forthe group.

GUI An acronym for graphical userinterface.

Hheader An optional report region that can

contain introductory material for the report,including text, graphics, data, andcomputations. The report header appearsfirst, before the body and trailer.

heading node A node in the ObjectNavigator denoting a type of object whichcan be contained within or associated witha report. Selecting a heading node does notselect an object in the report.See also node, Object Navigator.

Help menu A menu that lists various waysto access Oracle Reports’ online helpsystem.

hidden (Field Properties) A property thatspecifies whether Oracle Reports willsuppress the indicated field at its locationin the layout. If Hidden is specified, thefield’s value will appear only wherereferenced in text objects (using&fieldname).

horizontal sizing (Layout objects) A settingthat determines how the horizontal size ofthe layout object will change at runtime toaccommodate the objects or data within it.Valid options are Contract, Expand, Fixed,and Variable.

horizontal spacing (Repeating FrameProperties) The amount of space thatshould appear horizontally betweeninstances of a repeating frame.

Iicon A graphic representation of a window

or tool.import To add to your report definition text

or graphics stored in the database, server,or in files. You can import into the editorsboth text and graphics, but you may importonly text into single– and multi–line fields.

Glossary – 7

index An optional structure associated witha table that is used by ORACLE or anotherserver or database to locate rows of thetable quickly, and (optionally) to guaranteethat every row is unique.

Insert mode A mode in which each characteryou type is inserted into your text at thecursor, without overtyping adjacentcharacters. The opposite of Replace mode.

Jjoin Combining data from two (or more)

tables in a single SELECT statement.justification See alignment.

Llabel A heading created for each field

appearing in a report layout. Labels areboilerplate objects.

layout A formatting model that uses layoutobjects to define the positioning andappearance of the data in your report.Layout objects are frames, repeatingframes, fields, boilerplate, anchors, andbuttons.

lexical reference A reference to a lexicalparameter. See also lexical parameter.

lexical parameter A parameter used toreplace a clause in a SELECT statement(e.g., GROUP BY, ORDER BY, etc.),enabling you to specify a value for theclause at runtime.

link file The name of a file to which aboilerplate object is associated. At runtime,Oracle Reports imports the file’s contentsinto your report layout.

link A data model object used to define amaster/detail (parent–child) relationshipbetween a group and a query.

list of values A list of valid options for afield in the designer or a parameter in theRuntime Parameter form.

logical page One page of your actual report(it may be displayed on one or morephysical pages).

login account A username and password toaccess ORACLE or another server ordatabase. This account is usually separatefrom an operating system account.

Mmailing label layout A default layout that

displays records in one or more columns onthe page. Fields appear directly beneatheach other in a single repeating frame.

margin An optional report region thatappears at the top and bottom of eachlogical page in the body region. The marginmay include any layout object, but typicallycontains boilerplate and fields (for pagenumbers, page totals, grand totals, andcurrent date and time).

master/detail layout A default layout inwhich the detail records appear below themaster records. Master records appear inform layout style, while detail recordsappear in tabular layout style.

matrix cell A repeat direction that displayseach record of a repeating frame as a cell ofa matrix. See also matrix report.


matrix layout A default layout, resembling agrid, that formats the four sets of datanecessary for a matrix report; one set ofdata displays as a row of labels, one as acolumn of labels, one set creates the grid,and one set fills the cells of the grid. Seealso matrix report.

matrix report A cross–tabulation of four setsof data: one set of data displays across thepage; one set of data displays down thepage; one set of data is the cross–product,determining all possible locations in whichthe across and down data relate andplacing a cell in those locations; and one setof data displays as the ”filler” of the cells.

menu A list of available choices from whichyou can choose what action to take next orwhat interface element to access next.

module An object that can be shared bymore than one report, as well as by otherOracle products. Reports, external queries,and external PL/SQL libraries constituteOracle Reports modules.

multi–line field A field in the designer thatextends for several lines, allowing you toscroll vertically through the information.

Nnested matrix Matrix report in which either

the across and/or down dimensioncontains one or more master/detailrelationships. There is no limit to theamount of nesting allowed.

NOCACHE A datatype indicating that thedata will be fetched when the page onwhich it appears is formatted (instead offetched and cached until formatted).

node A line in the Object Navigator. A nodedenotes either one object in a report or onetype of object which can be containedwithin or associated with a report. Nodescan optionally contain such informationabout an object as whether it has associatedPL/SQL, is anchored to another object, etc.See also heading node, Object Navigator.

non–caching column A report column thatreferences a database column of datatypeNOCACHE.

non–value construct A PL/SQL codestructure that does not return a value.Non–value constructs include proceduresand packages.

NULL value The absence of a value. A nullvalue should mean only that nothing isknown about the value.

Oobject An item that defines one portion of a

module (e.g., a column object defines allinformation about the column: itsdatatype, width, name, etc.). Most objectshave property sheets, with which you canmodify their definitions.

Object Navigator The Oracle Reportswindow containing a list of objects in allcurrently opened reports. The list appearsin outline form, and enables the user toaccomplish several tasks related tomanaging reports; e.g., editing propertysheets, renaming objects, and deletingobjects.See also node, heading node.

Glossary – 9

OLE2 Object Linking and Embedding V2. Formore information, see your Microsoftdocumentation.

ORDER BY An optional clause used in aSQL SELECT statement to specify the orderin which the results of a query are to befetched.

Oracle Reports Server A batch reportexecutable found only on MicrosoftWindows. The executable is loaded oncewhen a report is launched by anotherDeveloper/2000 tool and remains inmemory. It enables you to manage theexecution of reports; e.g., cancel a report,reposition a report in the queue, etc.

output The results of a report at runtime.Output can be displayed on a screen, storedin a file, printed on paper, or sent to otherusers via Oracle*Office.

overflow When an object’s contents cannotfit on the current logical page. In the eventof overflow, some of the contents aremoved to the next logical page.

Ppackaged function 1. A PL/SQL function,

shipped with Oracle Reports, that can bereferenced anywhere in a report or externalPL/SQL library.2. See function.

palette An interface element that displays alltools, colors, and patterns available in aneditor.

page break (Layout objects) A setting thatcontrols whether to move the current objectand its children to the next logical page.You can set page breaks to occur before orafter the current object appears in thereport output.

page–dependent reference A value in thereport that relies on the formatting of thereport. For example, the Total Number ofLogical Pages and a summary with ResetAt of Page are page dependent references.

page height (Report Properties) The heightof the physical page.

page width (Report Properties) The width ofthe physical page.

panel The number of physical pages neededto print one logical page.

parameter A variable that you can change atruntime.

parent group (Query Properties) A groupthat owns a query or another group.

parent/child relationship Way in which todefine a ”primary key to foreign key”relationship between two different tables.See also link.

paste To place the contents of the Clipboard(cut or copied Oracle Reports objects) at thecurrent cursor location.

paste buffer See Clipboard.pattern A graphical property of certain

layout objects, such as frames, repeatingframes, fields, and boilerplate.

physical page The size of a page that isoutput by your printer.

PL/SQL A procedural extension of SQL thatprovides programming constructs such asblocks, conditionals, and procedures.

.pll file A file with an extension of .pll thatcontains an external PL/SQL library inbinary format.

preference A setting that affects the behaviorof the design or runtime interface.


Previewer The interface with which youview and scroll through report outputonline.

primary key A column in a database tablewhose members consist of unique valuesthat can be used to identify a row in a table.

print condition (Layout objects) A settingthat defines how frequently an OracleReports object is printed relative to otherOracle Reports objects.

print direction (Repeating Frame Properties)The direction in which each instance of arepeating frame prints relative to the priorinstance. The valid options are Across,Across/Down, Down, and Down/Across.

printer control code In a printer definitionfile, an escape sequence to which youassign a printer code that can be referencedin a report.

procedure A PL/SQL non–value constructthat requires a name and the full PL/SQLsyntax, including declarations and theBEGIN and END keywords.

product order (Column Properties) Theorder in which groups are evaluated in thecross product when computing summaries.

property See setting.property sheet A rectangular area that

appears in a window, displaying all of theinformation for one object (e.g., a query).

protocol A string you can enter whenconnecting to a database or server thatallows you to connect to a remote databaseor server.

.prt file A file with an extension of .prt thatcontains a printer definition in text (e.g.,ASCII or EBCDIC) format.

Qquery A SQL SELECT statement that

specifies the data you wish to fetch for thereport.

query name (Query and Group Properties) Asetting that identifies a query.

quit (File menu) An option that terminatesan Oracle Reports session and returns theuser to the operating system. On somesystems, Quit is Exit.

RR25CONV An executable command that

converts a report definition from onestorage format (i.e., database, .rdf file, .repfile, .rex file) to another.

R25DES An executable command thatinvokes Oracle Reports’ designer, withwhich you can define and run reports.

R25MREP An executable command thatconverts Version 1.1 reports to Version 2.5reports, stored either in database tables orfiles.

R25RUN An executable command that runsa previously defined report(s).

radio button A two–choice list (similar to acheck box), appearing in sets of two ormore, only one of which may be either ”on”or ”off” at any given time.

.rdf file A file with an extension of .rdf thatcontains a single report definition in binaryformat. .rdf files are used to both run andedit reports.

read consistency The ability to query thedata at a single point in time. This ensuresthat all the data in a report is internallyconsistent.

record One row fetched by a SQL SELECTstatement.

Glossary – 11

region The area in a report that owns theobjects being defined. Valid regions areHeader, Body/Margin, and Trailer.

rename (File menu) A menu option used tochange the name of a module.

.rep file A file with an extension of .rep thatcontains a single report definition in binaryformat. .rep files are used solely to runreports; you cannot edit a .rep file.

repeating frame A layout object used todisplay rows of data that are fetched for agroup.

Replace mode A mode in which eachalphanumeric character you type replacesthe current character at the cursor. Theopposite of Insert mode.

report A module that defines all of theinformation about itself, including itshistory, page size, references to othermodules, and use of report–level objects.

report–level objects The objects that areused to define a report’s data model andlayout. Report–level objects are assigned toa single report, and cannot be shared byother reports or other Oracle products.Oracle Reports objects include reports,queries, external queries, external PL/SQLlibraries, groups, columns, parameters,links, frames, repeating frames, fields,boilerplate, and anchors.

reset (Column Properties) A setting thatspecifies the group at which the value of acolumn summary is to be reset to 0.

revert (File menu) An option enabling you toreset the current module definition to themost recently saved state.

.rex file A file with an extension of .rex thatcontains a report definition stored in text(e.g., ASCII or EBCDIC) format. .rex filesare used to port reports from one platformto another.

row 1. One set of fields in a table; forexample, the fields representing oneemployee in the example table EMP.2. One set of fields in the output of a query.

run (File menu) To produce the reportoutput.

runfile See .rep file.running summary A column summary

which returns cumulative values of thefunction between reset points.

Runtime Parameter Form A screen orwindow appearing optionally at runtime inwhich a user can modify print options andparameters prior to report execution.

runtime The time during which OracleReports is running a report.

Sscript A file containing SQL statements that

you can run in SQL*Plus to quickly performdatabase administration. Several SQLscripts are shipped with Oracle Reports.

scroll region See multi–line field.SELECT statement A SQL statement that

specifies which rows and columns to fetchfrom one or more tables or views.

session In R25DES, the period betweeninvoking Oracle Reports and quittingOracle Reports. In R25RUN, the periodbetween running a report and quitting it.

setting An attribute of an object thatdetermines the effect or presentation of thatobject. Examples of properties includeVertical Sizing, Page Width and Datatype.

sibling An object that is at the same level asanother object in a hierarchy, either directlyor indirectly.


source (Column and Field Properties) Forcolumns, the name of the column whosevalues will be summarized. For fields, thecolumn or parameter whose data will bedisplayed in the field.

SQL A standard interface for storing andretrieving information in a relationaldatabase or server. SQL is an acronym for”Structured Query Language.”

.sql file A file with an extension of .sql thatcontains a query stored in text (e.g., ASCIIor EBCDIC) format. Any report you createcan reference any query you create or towhich you have been granted access.

SQL statement A SQL instruction toORACLE. A SELECT statement is one typeof SQL statement.

subprogram A named PL/SQL construct.Packages, functions, and proceduresconstitute subprograms.

subtotal See summary column.summary column A column, with a type of

summary, which computes subtotals, grandtotals, running totals, and other summariesof the data in a report, using one of thepackaged summary functions provided byOracle Reports.

system variable One of the variables that areprovided with Oracle Reports (e.g.,&Logical Page, DESTYPE).

Ttabbed property sheet See property sheet.table A named collection of related

information, stored in a relational databaseor server, in a two–dimensional grid that ismade up of rows and columns.

tabular A default layout displaying labels atthe top of the page and rows of dataunderneath the labels.

TERM An argument that enables you tospecify a file that describes the terminalfrom which you are using R25DES orR25RUN.

text See boilerplate.text item See field.TIFF Acronym for Tagged Image Format

File.title bar The horizontal area at the top of a

window that displays the name of theapplication or interface element thatappears in that window.

title page See header.toggle A setting that can be turned either on

or off. For example, you can togglebetween insert and replace mode whentyping data.

tool An icon that appears in an OracleReports editor. Tools are used to performactions on objects in a report.

toolbar Portion of an Oracle Reports editorcontaining tools that serve as shortcuts forcommon menu selections (e.g.,File—>Save, Edit—>Cut, etc.).

Tool palette Portion of an Oracle Reportseditor containing tools that provide ameans of creating, deleting, or modifyingreport objects via interaction with thegraphical user interface (e.g., drawing tools,text tool, query tool, etc.) They do not havemenu equivalents.

Tools menu A menu that provides access toseveral tools for use in building reports;e.g., the Default Layout and Parameterforms, several editors, the PL/SQLInterpreter, debugging tools, etc.

trailer A optional report region that cancontain closing material for the report,including text, graphics, data, andcomputations. The report trailer appearslast, following the header and body.

Glossary – 13

transaction A sequence of SQL statementsthat ORACLE treats as a single unit.

trigger A PL/SQL construct that is executed,or ”fired,” at a specific time during theformatting of a report.

UUSERID An argument which allows you to

specify your ORACLE username andpassword with an optional SQL*Netaddress.

user exit A way in which to pass control(and possibly arguments) from OracleReports to another Oracle product or 3GL,and then return control (and possiblyarguments) back to Oracle Reports.

Vvalue construct A PL/SQL code structure

that returns a value. Value constructsinclude functions and expressions.

vertical sizing (Layout objects) A setting thatdetermines how the vertical size of thelayout object will change at runtime toaccommodate the objects or data within it. Valid options are Contract, Expand, Fixed,and Variable.

vertical spacing (Repeating FrameProperties) The amount of space thatshould appear vertically between instancesof a repeating frame.

view A virtual table whose rows do notactually exist in the database. A virtualtable is based on a table that is physicallystored in the database.

View menu A menu that lists choices forcustomizing the features provided by thethe Oracle Reports editors; e.g., whether todisplay the rulers, the grid, the toolbar, etc.

Wwidth (Column and Parameter Properties,

layout objects) The width of a column,parameter, or layout object.

Windows menu A menu that lists all of theOracle Reports windows that are open oriconized.

Index – 1

Index

Symbols.pld, 18 – 3.pll, 18 – 3.rdf, 18 – 3.rep, 18 – 3.rex, 18 – 3.sql, 18 – 3&Current Date, 8 – 56&Logical Page Number, 8 – 56&Panel Number, 8 – 57&Physical Page, 8 – 57&SQL. See DDL or DML&Total Logical Pages, 8 – 57&Total Panels, 8 – 57&Total Physical Pages, 8 – 57#user_exit. See user exits% of total, summary function, 6 – 32+ or – in Object Navigator, 12 – 5* in fields, 8 – 24, 8 – 49*Default, print condition algorithm for layout

objects, 2 – 47*UNDEFINED* source, for summary columns,

6 – 40*Undefined* source

for button, 8 – 83for field, 8 – 58

Numbers3GL programs. See call interface (3GL calls

Oracle Reports’ executables); user exits (re-port calls the 3GL)

AACCESS keyword for R25DES, 1 – 46Accessing multimedia objects in the

Previewer, 11 – 8Action

for button, 8 – 81triggers, 13 – 32

Ada, Pro*Ada, 14 – 3Add to parameter LOV, 6 – 51Additional default layout tool, 7 – 15Administration

access to other users’ modules, 18 – 31controlling access to Oracle Reports, 18 – 31deleting reports, 19 – 5determining which files are used, 19 – 6documenting reports, 19 – 6establishing database security, 18 – 31granting user privileges, 19 – 4moving reports between files and the data-

base, 19 – 5revoking user privileges, 19 – 4upgrading from previous versions, 19 – 5

Index – 2 Reports Reference Manual

Aliasfont, 18 – 7in SELECT statement, E – 2with parameters, E – 2

All but first print condition, 8 – 16All but last print condition, 8 – 16All print condition, 8 – 16Anchor information, 12 – 7Anchor properties, 8 – 62

% down/across object edge, 8 – 69% down/across parent edge, 8 – 69collapse horizontally, 8 – 69collapse vertically, 8 – 70object, 8 – 69object edge, 8 – 69parent, 8 – 69parent edge, 8 – 69

Anchorsexamples, 8 – 63implicit algorithm, 2 – 43rules, 8 – 67tool, 7 – 14

Arguments. See executables, arguments; userexit, passing values

Arrange menu. See online help systemARRAYSIZE

keyword for R25DES, 1 – 37keyword for R25RUN, 1 – 20performance, 17 – 16

ASCII driverinvoking, 1 – 31performance advantages, 17 – 17

Attached libraries, 13 – 16Attributes, changing

via PL/SQL: SRW.SET_ATTR, 13 – 58via PL/SQL: SRW.SET_ATTR, character–

mode only, 13 – 61via PL/SQL: SRW.SET_ATTR, TEXT, 13 – 61via PL/SQL: SRW.SET_ATTR, WEIGHT, 13 –

61Automatic login, 1 – 7Average, summary function, 6 – 32

BBACKGROUND

keyword for R25DES, 1 – 46keyword for R25RUN, 1 – 31

Backward compatibility, stored program unitstubs, 13 – 34

BATCHkeyword for R25CONV, 1 – 15keyword for R25RUN, 1 – 26

Bidirectional support, C – 8Bind parameters. See bind referencesBind references, E – 4

creating, E – 4examples, E – 4in PL/SQL constructs, 13 – 32rules, E – 4

Bit–mapped environmentdefinition of, A – 2GUI differences, A – 2report conversion across GUIs, A – 4

Block types. See PL/SQL, construct typesBody, 7 – 5Boilerplate

See also boilerplate properties; parameterform boilerplate

attributes via PL/SQL: SRW.SET_ATTR,TEXT, 13 – 61

attributes via PL/SQL: SRW.SET_ATTR,WEIGHT, 13 – 61

font color via PL/SQL: SRW.SET_ATTR,FACE, 13 – 60

font face via PL/SQL: SRW.SET_ATTR,FACE, 13 – 59

font style via PL/SQL: SRW.SET_ATTR,STYLE, 13 – 60

names, D – 3suppressing for detail records, 13 – 29

Boilerplate properties, 8 – 59comment, 8 – 27format, 8 – 60format trigger, 13 – 28horizontal sizing, 8 – 4

Index – 3

keep with anchoring object, 8 – 6link file, 8 – 60minimum widow lines, 8 – 62name, 8 – 8page break after, 8 – 9page break before, 8 – 11page protect, 8 – 12print condition, 8 – 15printer codes, 8 – 26vertical sizing, 8 – 20

Borders, 7 – 16 conditional color via PL/SQL:

SRW.SET_ATTR, BBCOLOR, 13 – 59via PL/SQL: SRW.SET_ATTR, BORDER-

WIDTH, 13 – 59via PL/SQL: SRW.SET_ATTR,

BORDPATT, 13 – 59via PL/SQL: SRW.SET_ATTR,

FBCOLOR, 13 – 59BREAK. See PL/SQL packaged procedures,

SRW.BREAKBreak order, 6 – 18

adds to the ORDER BY clause, 17 – 6default, 6 – 18examples, 6 – 19options, 6 – 18performance of break columns, 17 – 9rules, 6 – 20

BUFFERSkeyword for R25DES, 1 – 42keyword for R25RUN, 1 – 26

Built–in packages, in Object Navigator, 12 – 8Button properties

action, 8 – 81action trigger, 13 – 32label, 8 – 83name, 8 – 8text string, 8 – 83

Buttonsrules, 8 – 80tool, 7 – 14

CC, Pro*C, 14 – 3Call interface

definition of, 15 – 2error checking, 15 – 4examples, 15 – 5, 15 – 6, 15 – 7, 15 – 8rules, 15 – 4steps to call Oracle Reports from a

3GL, 15 – 2syntax, 15 – 3

Cautions.rex files, 18 – 4boilerplate, 8 – 60cgm files, 18 – 4converting reports, must recompile, A – 3DDL and DML, PL/SQL, 13 – 44DDL and DML, R25DES, 1 – 42DDL and DML, R25RUN, 1 – 25DDL and DML, report triggers, 13 – 20format trigger, 13 – 30global defaulting rule, 2 – 41installing tables, 19 – 3KEYIN, R25RUN, 1 – 30KEYOUT, R25RUN, 1 – 30NLS_LANG, C – 3Oracle Reports tables, 18 – 13overflow, 8 – 23parameter form editor, 9 – 5print condition, 8 – 18printer codes, 8 – 26printer definitions, B – 1R25RUN, no compile, 1 – 18READONLY, EXEC ORACLE, 14 – 8READONLY, EXEC SQL, 14 – 5READONLY, PL/SQL, 13 – 44READONLY, R25DES, 1 – 42READONLY, R25RUN, 1 – 25READONLY, report triggers, 13 – 20references in PL/SQL, 13 – 33terminal definitions, B – 1user exits, 13 – 72

CDE_MM, 13 – 40CDE_MM.GET_REF, 13 – 40Centering objects

horizontally, 8 – 63vertically, 8 – 64


Central tables, Oracle Reports tables. SeeOracle Reports tables

Character datatype, 6 – 20Character mode

designing for, A – 3environment, A – 2ouput, 1 – 31output, performance advantage, 17 – 17

Character setsconverting, C – 5sorting, C – 5support of multiple, C – 2

Characters per page, runtime setting, 4 – 14Child column, 6 – 12

rules, 6 – 12Child query, 6 – 12

rules, 6 – 12CMDFILE

keyword for R25CONV, 1 – 14keyword for R25DES, 1 – 36keyword for R25RUN, 1 – 19

COBOL, Pro*COBOL, 14 – 3Collapse, anchors

examples, 8 – 65, 8 – 66horizontally, 8 – 69vertically, 8 – 70

Colorsconversion across GUIs, A – 4palette, F – 4via PL/SQL: SRW.SET_ATTR,

BBCOLOR, 13 – 59, 13 – 62via PL/SQL: SRW.SET_ATTR,

BFCOLOR, 13 – 59, 13 – 62via PL/SQL: SRW.SET_ATTR,

FBCOLOR, 13 – 59, 13 – 62via PL/SQL: SRW.SET_ATTR,

FFCOLOR, 13 – 60, 13 – 62Column heading. See labelColumn mode, 8 – 29

example, 8 – 31rules, 8 – 32

Column properties, 6 – 17break order, 6 – 18comment tab, 6 – 27compute at, 6 – 29datatype, 6 – 20

format, 6 – 21formula, 13 – 25function, 6 – 32name, 6 – 22product order, 6 – 33read from file, 6 – 23reset at, 6 – 39source, 6 – 40summary, 6 – 32value if null, 6 – 24width, 6 – 25

ColumnsSee also column propertiesbind references, E – 4child, 6 – 12lexical references, E – 5parent, 6 – 13properties, 6 – 17view by hierarchy, 12 – 11view by type, 12 – 12

Command line interfaceparameter validation, 13 – 18R25CONV for converting report

definitions, 1 – 9R25DES for creating/modifying

reports, 1 – 35R25RUN for running generated

reports, 1 – 18Commands, SQL commands in user

exits, 14 – 5Comment tab

column property sheet, 6 – 27group property sheet, 6 – 17parameter property sheet, 6 – 52query property sheet, 6 – 8

Commentsfor layout objects, 8 – 27for parameter form boilerplate, 10 – 5for parameter form fields, 10 – 3, 10 – 5for report, 4 – 15

COMMITONFAILURE for R25DES, 1 – 45ONFAILURE for R25RUN, 1 – 29ONSUCCESS for R25DES, 1 – 44ONSUCCESS for R25RUN, 1 – 29READONLY for R25DES, 1 – 41READONLY for R25RUN, 1 – 24

Index – 5

Common layout properties, 8 – 2rules, 8 – 2

CompilingSee also user exitsPL/SQL, compiling, 13 – 37

Compute at, 6 – 29default, 6 – 29examples, 6 – 29rules, 6 – 31

Conditions, filter, 13 – 23example, 13 – 24rules, 13 – 24

Conditions, link, 6 – 12default, 6 – 13options, 6 – 12

Confine mode, 7 – 9Constrained mode, 7 – 8Constructs

definition of, 13 – 2restrictions, 13 – 33types supported in Oracle Reports, 13 – 2which are valid for different objects, 13 – 15

CONTEXT_FAILURE. See PL/SQL packagedexceptions, SRW.CONTEXT_FAILURE

Contract sizing, 8 – 20Control key, for flex mode, 7 – 9CONVERT function, C – 5Converting

between report formats with R20CONV, 1 – 9

between reports in files and the database, 19 – 5

from V1.1 to 2.0 user exits, 14 – 16NLS, C – 7reports from V1.1 to V2.5, 19 – 5

COPIESkeyword for R25DES, 1 – 39keyword for R25RUN, 1 – 23performance, 17 – 17

Count, summary function, 6 – 32Creating

See also DDLbind references, E – 4database security, 18 – 31lexical references, E – 5

Cross product groupsfor matrix, 8 – 72performance, 17 – 9rules, 2 – 35tool, 5 – 6

CURRENCYkeyword for R25DES, 1 – 40keyword for R25RUN, 1 – 23

Current date, field source, 8 – 56Customizing function keys, B – 17

DData

converting via CONVERT function, C – 5sorting via NLSSORT function, C – 5

Data Definition Language, E – 9Data Manipulation Language, E – 9Data model

defaulting, 2 – 2performance, 17 – 5

Data model editoraccessing, 5 – 3components, 5 – 3definition and purpose, 5 – 2painting region, 5 – 3pop–up menu, 5 – 7status line, 5 – 7

Data model objectscolumn properties, 6 – 17database column properties, 6 – 27formula column properties, 6 – 41group properties, 6 – 14if unused, 17 – 8link properties, 6 – 8parameter properties, 6 – 45placeholder column properties, 6 – 42query properties, 6 – 2summary column properties, 6 – 27

Data/Selection tab, parameter properties, 6 – 50

Databaseautomatic login, 1 – 7explicit login, 1 – 7objects in Object Navigator, 12 – 8


remote login, 1 – 8storage requirements, 18 – 31

Database column properties, 6 – 27general tab, 6 – 17rules, 6 – 27

Datatype of column, 6 – 20character, 6 – 20date, 6 – 20long, 6 – 20long raw, 6 – 20number, 6 – 20options, 6 – 20raw, 6 – 20REF, 6 – 20rules, 6 – 21Varchar, 6 – 21Varchar2, 6 – 21

Datatype of field, 8 – 42rules, 8 – 42

Datatype of parameter, 6 – 47default, 6 – 47options, 6 – 47rules, 6 – 47

Datatype of parameter form field, 10 – 2Date

datatype, 6 – 20field source, 8 – 56format masks, 8 – 44

DDE package, definition of, 13 – 39DDL, E – 9

caution with SRW.DO_SQL, 13 – 44SRW.DO_SQL, syntax of, 13 – 43via PL/SQL packaged procedure,

SRW.DO_SQL, 13 – 2DEBUG package, definition of, 13 – 39Debugger. See Oracle Procedure BuilderDECIMAL


Default parameter values. See initial valueDefault parameters. See packaged parametersDefault print condition, 8 – 16Defaulting, 2 – 1

data model, 2 – 2implicit anchor algorithm for layout

objects, 2 – 43

layout, 2 – 4parameter form, 2 – 47print condition algorithm for layout

objects, 2 – 47Deleting

See also DDLpages, layout, 7 – 20pages, parameter form, 9 – 9reports, 19 – 5

Depressed appearance of buttons, rules, 8 – 82DESFORMAT


DESNAMEkeyword for R25DES, 1 – 38keyword for R25RUN, 1 – 21

DEST keyword for R25CONV, 1 – 13DESTYPE


Details, suppressing labels when no records, 13 – 29

DEV_NLS_LANG, C – 2Development environment. See Oracle Proce-

dure BuilderDevice type for output. See destination typeDialog boxes, page numbering, 8 – 52Dimension repeating frames, in Object Naviga-

tor, 12 – 8Disable

host, character mode runtime setting, 4 – 13split, character mode runtime setting, 4 – 13zoom, character mode runtime setting, 4 – 13

Disk space requirements, 18 – 32Display, Oracle Graphics

name, 8 – 76query, 8 – 79

Displaying reportsas PostScript output via R25DES, 1 – 37in PostScript format via R25RUN, 1 – 20

DML, E – 9via PL/SQL, 13 – 2

DO_SQL. See PL/SQL packaged procedures,SRW.DO_SQL

Index – 7

DO_SQL_FAILURE. See PL/SQL packaged ex-ceptions, SRW.DO_SQL_FAILURE

Documentation set, iiDocumenting reports, 19 – 6DPI affect in word–wrapping, A – 4Dropping Version 1.1 tables, 19 – 5droprep.sql script, 19 – 2DTYPE keyword for R25CONV, 1 – 12Dummy variable, placeholders. See placehold-

ersDUNIT keyword for R25CONV, 1 – 15

EEdit menu. See online help systemEditors

accessing, 9 – 5icon in Object Navigator, 12 – 6

Empty string for executable arguments, 1 – 5Enclosing object, 8 – 15

determining, 2 – 43Environment variables, 18 – 10

REPORTS_TMP, 18 – 11REPORTS25_PATH, 18 – 11REPORTS25_TERMINAL, 18 – 11setting NLS_LANG, C – 2TK21_ICON, 18 – 12

Environments. See bit–mapped environment;block–mode environment; character–modeenvironment

ERRFILEkeyword for R25DES, 1 – 45keyword for R25RUN, 1 – 30

ErrorsSee also PL/SQL, exceptionschecking for and defining user exit

errors, 14 – 13for the call interface, 15 – 4messages you raise via PL/SQL, 13 – 50raising from user exits, 14 – 9

Establishing database security, 18 – 31Examples

alignment, conditional, 13 – 61anchor, 8 – 63

attributes changed via PL/SQL,SRW.SET_ATTR, 13 – 61

borders, conditional, 13 – 61, 13 – 62break order, 6 – 19call to R20RUN written in Ada, 15 – 6call to R20RUN written in C, 15 – 6call to R20RUN written in COBOL, 15 – 7call to R20RUN written in FORTRAN, 15 – 7call to R20RUN written in Pascal, 15 – 8call to R20RUN written in PL/l, 15 – 8colors, conditional, 13 – 62, 13 – 63column mode, 8 – 31compute at, 6 – 29DDL via PL/SQL, 13 – 45faces, conditional, 13 – 63field values changed via

PL/SQL, 13 – 64, 13 – 65filter condition, 13 – 24filter type, 6 – 16fonts, conditional, 13 – 63format masks, conditional, 13 – 61, 13 – 62format trigger, 13 – 28formula, 13 – 25hidden, 8 – 50horizontal sizing, 8 – 5justification, conditional, 13 – 63keep with anchoring object, 8 – 7link, 6 – 10logical page size, 4 – 3matrix, 8 – 71maximum records per page, 8 – 34minimum widow lines, 8 – 51minimum widow records, 8 – 34page numbering, 8 – 54page numbers via PL/SQL, 13 – 48page protect, 8 – 12patterns, conditional, 13 – 61PL/SQL function, 13 – 5PL/SQL procedure, 13 – 8PL/SQL SRW.PROGRAM_ABORT, 13 – 53PL/SQL SRW.SET_ATTR,

AFTCODE, 13 – 61PL/SQL SRW.SET_ATTR,

BBCOLOR, 13 – 62PL/SQL SRW.SET_ATTR, BEFCODE, 13 – 61PL/SQL SRW.SET_ATTR, BFCOLOR, 13 – 62PL/SQL SRW.SET_ATTR, BORDERWIDTH,

13 – 61, 13 – 62


PL/SQL SRW.SET_ATTR, BORDPATT, 13 – 62

PL/SQL SRW.SET_ATTR, CUSTOM, 13 – 63PL/SQL SRW.SET_ATTR, FACE, 13 – 63PL/SQL SRW.SET_ATTR, FBCOLOR, 13 – 62PL/SQL SRW.SET_ATTR, FFCOLOR, 13 – 62PL/SQL SRW.SET_ATTR,

FILLPATT, 13 – 61, 13 – 62PL/SQL SRW.SET_ATTR,

FORMATMASK, 13 – 61, 13 – 62PL/SQL SRW.SET_ATTR, GCOLOR, 13 – 63PL/SQL SRW.SET_ATTR,

GSPACING, 13 – 63PL/SQL SRW.SET_ATTR,

HJUST, 13 – 61, 13 – 63PL/SQL SRW.SET_ATTR, STYLE, 13 – 63PL/SQL SRW.SET_ATTR, SZ, 13 – 63PL/SQL SRW.SET_ATTR,

TEXT, 13 – 61, 13 – 63PL/SQL SRW.SET_ATTR, WEIGHT, 13 – 63PL/SQL subprogram, 13 – 22PL/SQL, SRW.CONTEXT_FAILURE, 13 – 43PL/SQL, SRW.DO_SQL, 13 – 45PL/SQL, SRW.DO_SQL_FAILURE, 13 – 46PL/SQL, SRW.GET_PAGE_NUM, 13 – 48PL/SQL, SRW.GETERR_RUN, 13 – 47PL/SQL, SRW.INTEGER_ERROR, 13 – 48PL/SQL, SRW.MAXROW_INERR, 13 – 49PL/SQL, SRW.MAXROW_UNSET, 13 – 50PL/SQL, SRW.MESSAGE, 13 – 51PL/SQL, SRW.NULL_ARGUMENTS, 13 – 52PL/SQL, SRW.RUN_REPORT, 13 – 55PL/SQL, SRW.RUN_REPORT_

BATCHNO, 13 – 57PL/SQL, SRW.RUN_REPORT_

FAILURE, 13 – 58PL/SQL, SRW.SET_FIELD_CHAR, 13 – 64PL/SQL, SRW.SET_FIELD_DATE, 13 – 65PL/SQL, SRW.SET_FIELD_

NUMBER, 13 – 65PL/SQL, SRW.SET_MAXROW, 13 – 66PL/SQL, SRW.TRUNCATED_

VALUE, 13 – 70PL/SQL, SRW.UNKNOWN_QUERY, 13 – 71PL/SQL, SRW.UNKNOWN_USER_

EXIT, 13 – 71PL/SQL, SRW.USER_EXIT, 13 – 72

PL/SQL, SRW.USER_EXIT_FAILURE, 13 – 74

placeholder column, 6 – 43print condition, 8 – 17printer codes, conditional, 13 – 61product order, 6 – 34queries, 6 – 5raising messages via PL/SQL, 13 – 51read from file, 6 – 23reducing query fetch via PL/SQL, 13 – 66reset at, 6 – 39SELECT statement, 6 – 5send portions of a report to different recipi-

ents, 13 – 55source for field, 8 – 57spacing, conditional, 13 – 63style, conditional, 13 – 63text color, conditional, 13 – 63text size, conditional, 13 – 63text spacing, conditional, 13 – 63user exit call, 13 – 54, 13 – 72, 14 – 22user exit call passing a value, 13 – 54, 13 – 72user exit error checking, 13 – 72, 14 – 22user exit program, 14 – 22user exit, complete, 14 – 21vertical sizing, 8 – 21

Exceptions, PL/SQL exceptions, 13 – 12EXEC IAF GET, 14 – 6EXEC IAF PUT, 14 – 6EXEC ORACLE statements, 14 – 7

avoid with READONLY=YES, 14 – 8EXEC SQL statements, 14 – 5

avoid with READONLY=YES, 14 – 5Executables

arguments, 1 – 3brief explanation of each executable, 1 – 2how to omit keywords, 1 – 6how to view command line options, 1 – 3invoking, 1 – 3names, 1 – 3syntax rules, 1 – 4

Expand sizing, 8 – 21Explicit login, 1 – 7External PL/SQL libraries, deleting, 19 – 5

Index – 9

External queriesdeleting, 19 – 5field in query property sheet, 6 – 3

External query properties, SQL SELECT State-ment errors, E – 3

FFace, conditional example, 13 – 63Fetching

reducing via Maximum Rows, 17 – 8reducing via WHERE clause, 17 – 10setting ARRAYSIZE for, 17 – 16

Field properties, 8 – 41comment, 8 – 27datatype, 8 – 42format mask, 8 – 42format trigger, 13 – 28hidden, 8 – 49horizontal sizing, 8 – 4keep with anchoring object, 8 – 6minimum widow lines, 8 – 51name, 8 – 8page break after, 8 – 9page break before, 8 – 11page numbering, 8 – 52page protect, 8 – 12print condition, 8 – 15printer codes, 8 – 26source, 8 – 56vertical sizing, 8 – 20

FieldsSee also field properties; parameter form

fieldsnames, D – 3placing in layout editor, 8 – 41rules, 8 – 41tool, 7 – 14

File Menu. See online help systemFiles

administration files, 18 – 6ASCII output, 1 – 31being used by Oracle Reports, 19 – 6demo files, 18 – 6executable files, 18 – 6file–searching method, 18 – 9

formats supported, 18 – 2generated by Oracle Reports, 19 – 7important files shipped with Oracle

Reports, 18 – 5installation files, 18 – 6printer definition files, 18 – 7security and restrictions, 18 – 9sending reports via R25DES, 1 – 37sending reports via R25RUN, 1 – 20temporary, 18 – 8terminal definition files, 18 – 7

Fill pattern, via PL/SQL: SRW.SET_ATTR,FILLPATT, 13 – 60

Fillscolor tool, 7 – 15via PL/SQL: SRW.SET_ATTR,

BFCOLOR, 13 – 59via PL/SQL: SRW.SET_ATTR,

FFCOLOR, 13 – 60Filters, group, 6 – 15

condition, 13 – 23type, 6 – 15

Firstgroup filter type, 6 – 16print condition, 8 – 16summary function, 6 – 32

Fixed sizing, 8 – 21Flex mode, 7 – 9Font

aliases, 18 – 7color via PL/SQL: SRW.SET_ATTR,

FACE, 13 – 60conditional, example, 13 – 63face via PL/SQL: SRW.SET_ATTR,

FACE, 13 – 59style via PL/SQL: SRW.SET_ATTR,

STYLE, 13 – 60Font, conversion across GUIs, A – 4Footers. See MarginsForm height for Runtime Parameter

Form, 4 – 10Form letter reports, possible truncation

in, 2 – 41Form width for Runtime Parameter

Form, 4 – 10


Formatattributes, performance cost, 17 – 12files supported, 18 – 2for boilerplate, 8 – 60

Format masks, 8 – 42adding to list of values, 8 – 42examples, 8 – 47for dates, 8 – 44for numbers, 8 – 45rules, 8 – 49via PL/SQL: SRW.SET_ATTR, FORMAT-

MASK, 13 – 60Format menu. See online help systemFormat triggers, 13 – 28

example, 13 – 28options, 13 – 28performance, 17 – 13rules, 13 – 30

FORMSIZE keyword for R25CONV, 1 – 16Formula column properties, 6 – 41

general tab, 6 – 41rules, 6 – 41

Formulas, 13 – 25examples, 13 – 25options, 13 – 25rules, 13 – 26tool, 5 – 6

FORTRAN, Pro*FORTRAN, 14 – 3Forward references. See page–dependent refer-

encesFrame properties, 8 – 28

comment, 8 – 27format trigger, 13 – 28horizontal sizing, 8 – 4keep with anchoring object, 8 – 6name, 8 – 8page break after, 8 – 9page break before, 8 – 11page protect, 8 – 12print condition, 8 – 15printer codes, 8 – 26vertical sizing, 8 – 20

FramesSee also frame propertiesif unused, 17 – 11names, D – 3

select tool, 7 – 10tool, 7 – 13

Frequencyin Object Navigator, 12 – 8print condition, 8 – 80

Function calls, call interface. See call interfaceFunctions. See PL/SQL, functionsFunctions, column, 6 – 32

options, 6 – 32rules, 6 – 32

GGeneral tab

database column property sheet, 6 – 17formula column property sheet, 6 – 41group properties, 6 – 15parameter properties, 6 – 47placeholder column property sheet, 6 – 44query property sheet, 6 – 2summary column property sheet, 6 – 28

GET. See EXEC IAF GETGET_PAGE_NUM. See PL/SQL packaged pro-

cedures, SRW.GET_PAGE_NUMGETERR_RUN. See PL/SQL packaged func-

tions, SRW.GETERR_RUNGlobal variables, 13 – 8

See also placeholdersGrant, using SQL scripts, 19 – 4Graphics

boilerplate, 8 – 80format, boilerplate, 8 – 60format, column, 6 – 21image, boilerplate, 8 – 60image, column, 6 – 23link file, boilerplate, 8 – 60read from file, 6 – 23

Group properties, 6 – 14comment tab, 6 – 17filter, 6 – 15filter condition, 13 – 23filter performance, 17 – 8filter type, 6 – 15general tab, 6 – 15name, 6 – 16

Index – 11

GroupsSee also group propertiesparent, 6 – 13rules, 6 – 15view by hierarchy, 12 – 11view by type, 12 – 12

GUIsdifferences, A – 2differences affecting report conversion, A – 4

HHAVING clauses

added by Oracle Reports, 17 – 6option for links, 6 – 13

Headers. See MarginsHeading, label. See labelHeadings, in Object Navigator, 12 – 7Help menu. See online help systemHidden, 8 – 49

example, 8 – 50Hide first column for parameter LOV, 6 – 52Hierarchical views

columns by group, 12 – 11columns by type, 12 – 12group by structure, 12 – 11group by type, 12 – 12in Object Navigator, 12 – 10layout objects by structure, 12 – 13layout objects by type, 12 – 14

Horizontal frame for matrix, 8 – 8Horizontal sizing, 8 – 4

examples, 8 – 5rules, 8 – 23to enhance performance, 17 – 12

Horizontal spacing, 8 – 33default, 8 – 33rules, 8 – 33

Host languages, 14 – 3Host, disabling for character mode, 4 – 13

IIcons, search path, 18 – 10Image

accessing, 11 – 10boilerplate in Object Navigator, 12 – 9in buttons, 11 – 10

Image viewermagnify tool, 11 – 11panning tool, 11 – 11

Imagesformats supported, 18 – 2resolution performance cost, 17 – 12

Indexes, 17 – 7Initial value, parameter, 6 – 48

rules, 6 – 48Input mask, rules, 6 – 49Input mask for parameters, 6 – 48

default, 6 – 49Inserting. See DMLInstalling

integrated Oracle tools tables, 19 – 3Oracle Reports tables, 19 – 3

Instances, keeping together, minimum widowrecords for repeating frames, 8 – 34

INTEGER_ERROR. See PL/SQL packaged ex-ceptions, SRW.INTEGER_ERROR

Integrated Oracle product tablesdescription, 18 – 27installing, 19 – 3TOOL_ACCESS, 18 – 27TOOL_COMMENT, 18 – 27TOOL_DEPEND, 18 – 27TOOL_LIBRARY, 18 – 28TOOL_LRAW, 18 – 28TOOL_LRAW_ID, 18 – 28TOOL_LTEXT, 18 – 28TOOL_LTEXT_ID, 18 – 29TOOL_MODID, 18 – 29TOOL_MODULE, 18 – 29TOOL_PLSQL, 18 – 30TOOL_ROSSTRINGS, 18 – 30


IntegrationSee also Oracle Reports calls to 3GLs3GL calls to Oracle Reports, 15 – 1call interface, 16 – 10connecting to ORACLE and other

databases, 16 – 2OLE, 16 – 4ORACLE, 16 – 2Oracle Graphics, 16 – 6Oracle Mail, 16 – 10Oracle Terminal, 16 – 10PL/SQL, 13 – 1, 16 – 5SQL*Net, 16 – 2user exit interface, 16 – 10

InterfacesSee also call interface; PL/SQLuser exits, 14 – 1with other products, 16 – 1

Interpreter, 13 – 35Invoking executables, 1 – 3Invoking Oracle Terminal, B – 17

JJustification

conditional, example, 13 – 61, 13 – 62, 13 – 63via PL/SQL: SRW.SET_ATTR,

HJUST, 13 – 60

KKeep with anchoring object, 8 – 6

examples, 8 – 7rules, 8 – 7rules for conflicting properties, 8 – 2

Keeping objects togetherkeep with anchoring object, 8 – 6minimum widow records, 8 – 34page protect, 8 – 12

Key bindingsdefinition, B – 17modifying, B – 17steps to edit, B – 17, B – 19

Keystroke captureKEYIN, 1 – 30KEYOUT, 1 – 30

Keywordshow to omit them on the command

line, 1 – 6how to view command line options, 1 – 3

LLabel, 8 – 83

controlling printing, 8 – 15suppressing when no detail records, 13 – 29

Label for buttons, rules, 8 – 83Language, NLS, C – 7Languages

Host languages, 14 – 3PL/SQL, 13 – 1

Lastgroup filter type, 6 – 16print condition, 8 – 17summary function, 6 – 32

Layout defaulting, 2 – 4implicit anchor algorithm, 2 – 43print condition algorithm, 2 – 47

Layout editor, 7 – 1accessing, 7 – 3components, 7 – 3definition and purpose, 7 – 2margins, 7 – 21navigation, 7 – 20painting region, 7 – 3pop–up menu, non–OLE2

objects, 7 – 18, 9 – 7pop–up menu, OLE2 objects, 7 – 19report regions, 7 – 4status line, 7 – 17

Layout objectscommon properties, 8 – 2making transparent for performance, 17 – 12view by hierarchy, 12 – 13view by type, 12 – 14

Layout properties, common, 8 – 2comment, 8 – 27format trigger, 13 – 28horizontal sizing, 8 – 4keep with anchoring object, 8 – 6page break after, 8 – 9page break before, 8 – 11

Index – 13

page protect, 8 – 12print condition, 8 – 15printer codes, 8 – 26rules, 8 – 2vertical sizing, 8 – 20

Leadingvia PL/SQL: SRW.SET_ATTR,

CUSTOM, 13 – 60via PL/SQL: SRW.SET_ATTR,

GSPACING, 13 – 60Lexical parameters. See lexical referencesLexical references, E – 5

creating, E – 5examples, E – 7rules, E – 6

Lines, color tool, 7 – 16Lines in Object Navigator. See NodesLines, minimum widow

for boilerplate, 8 – 62 for field, 8 – 51

Link file for boilerplatefield, 8 – 60tool, 7 – 14

Link properties, 6 – 8child query, 6 – 12examples, 6 – 10parent column, 6 – 13parent group, 6 – 13SQL clause, 6 – 13

Linking, call interface, 15 – 3Links, data model

description, 6 – 8rules, 6 – 11tool, 5 – 6without columns specified, 6 – 13

LIST package, definition of, 13 – 39Literal references, 13 – 33Local tables. See Oracle Reports tablesLOGFILE

keyword for R25CONV, 1 – 14keyword for R25RUN, 1 – 25

Logical pagedefinition, 11 – 4number, field source, 8 – 56

size, 4 – 3Login

automatic, 1 – 7explicit, 1 – 7remote, 1 – 8

Long datatype, 6 – 20setting retrieval size, 1 – 30, 1 – 45

Long raw datatype, 6 – 20LONGCHUNK

keyword for R25DES, 1 – 45keyword for R25RUN, 1 – 30performance, 17 – 16

MMagnify

previewer, 11 – 7tool, data model editor, 5 – 6tool, layout editor, 7 – 11

Mailsending parts of reports to different

users, 13 – 54sending reports to Oracle*Mail via

R25DES, 1 – 37sending reports to Oracle*Mail via

R25RUN, 1 – 21Mailing label layout style, possible truncation

in, 2 – 41Main menu in the Previewer, 11 – 3Maintaining reports, R25DES, 1 – 35Mappings, font, 18 – 7Margins, 7 – 5, 7 – 21

in Object Navigator, 12 – 9overflowing, 7 – 21

Mask. See PL/SQL packaged procedures,SRW.SET_ATTR

Masks, format, 8 – 42format masks, 8 – 80

Master/Detailkeeping details with master, 8 – 13keeping instances together, 8 – 34

Matrix objects, names, D – 3


Matrix propertiescross product group, 8 – 72example, 8 – 71horizontal frame, 8 – 8rules, 8 – 71vertical frame, 8 – 73

Matrix reports, 2 – 27data model requirements, 2 – 27layout defaulting, 2 – 27performance, 17 – 9rules, 2 – 35

Maximum body pages for report, 4 – 5Maximum header pages for report, 4 – 5Maximum records per page, 8 – 33

examples, 8 – 34rules for conflicting properties, 8 – 2

Maximum rows, query, 6 – 4default, 6 – 4options, 6 – 4performance, 17 – 8rules, 6 – 4

Maximum trailer pages for report, 4 – 6Maximum, summary function, 6 – 32MAXROW_INERR. See PL/SQL packaged ex-

ceptions, SRW.MAXROW_INERRMAXROW_UNSET. See PL/SQL packaged ex-

ceptions, SRW.MAXROW_UNSETMemory requirements, 18 – 32Menu item selection, vMenus, 3 – 1MESSAGE. See PL/SQL packaged procedures,

SRW.MESSAGEMessages. See errorsMinimum widow lines, boilerplate, 8 – 62

rules, 8 – 62Minimum widow lines, field, 8 – 51

examples, 8 – 51Minimum widow records for repeating

frame, 8 – 34examples, 8 – 34rules, 8 – 35

Minimum, summary function, 6 – 32Minus/plus in Object Navigator, 12 – 5MLSLABEL, 6 – 21

MODEkeyword for R25DES, 1 – 46keyword for R25RUN, 1 – 31performance, 17 – 17

Modifying key bindings, invoking Oracle Ter-minal, B – 17

Modifying reports, R25DES, 1 – 35MODULE


Modulesdeleting, 19 – 5naming conventions, D – 2stored in files, 18 – 2

Multimedia, accessing in Previewer, 11 – 8

NNames

for boilerplate objects, 8 – 8for buttons, 8 – 8for columns, 6 – 22for executables, 1 – 3for fields, 8 – 8for frames, 8 – 8for groups, 6 – 16for OLE2 objects, 8 – 8for Oracle Graphics displays, 8 – 8for parameter form boilerplate, 10 – 4for parameter form fields, 10 – 2for parameters, 6 – 49for queries, 6 – 5for repeating frames, 8 – 8

Naming conventionsbuttons, D – 3for boilerplate objects, D – 3for columns, D – 2for executables, 1 – 3for fields, D – 3for frames, D – 3for groups, D – 2for matrix objects, D – 3for modules, D – 2for parameter form boilerplate, D – 3for parameter form fields, D – 3for parameters, D – 2

Index – 15

for queries, D – 2for repeating frames, D – 3OLE2 objects, D – 3Oracle Graphics displays, D – 3

National language supportbidirectional support, C – 8converting data, C – 5definition of, C – 2overriding defaults, C – 3sorting data, C – 5specifying NLS_LANG, C – 2translating reports, C – 7using ALTER SESSION, C – 3using format masks, C – 4using NLS parameters/functions, C – 5

Navigation in the Previewer, 11 – 5Navigator menu. See online help systemNLS_CURRENCY, C – 3NLS_DATE_FORMAT, C – 3NLS_DATE_LANGUAGE, C – 3NLS_ISO_CURRENCY, C – 3NLS_LANG, C – 2NLS_LANGUAGE, C – 3NLS_NUMERIC_CHARACTERS, C – 3NLS_SORT, C – 3NLS_TERRITORY, C – 3NLSSORT function, C – 5Nodes

editor icon, 12 – 6format, 12 – 5heading, 12 – 7in Object Navigator, 12 – 5object icon, 12 – 6PL/SQL icon, 12 – 6plus/minus, 12 – 5types of, 12 – 7

Non–ORACLE user exits, 14 – 3non–value constructs, PL/SQL, non–value

constructs, 13 – 6NULL_ARGUMENTS. See PL/SQL packaged

exceptions, SRW.NULL_ARGUMENTS

Number datatype, 6 – 20Number format masks, 8 – 45Number of pages for parameter form, 4 – 11Numbering, page, 8 – 52

OObject Navigator

accessing, 12 – 2components, 12 – 3definition and purpose, 12 – 2hierarchical views in, 12 – 10nodes in, 12 – 5object tree, 12 – 3pop–up menu, 12 – 4view data model by structure, 12 – 11view data model by type, 12 – 12view layout by structure, 12 – 13view layout by type, 12 – 14

Object of print condition, 8 – 15default, 8 – 15options, 8 – 15rules, 8 – 19

Object tree, in Object Navigator, 12 – 3Objects, Oracle Reports

See also changing attributes via PL/SQL,SRW.SET_ATTR

referencing in PL/SQL, 13 – 32referencing in user exit calls, 14 – 10size via PL/SQL: SRW.SET_ATTR,

FACE, 13 – 60OCI user exits, 14 – 3OLE objects, property sheet, 8 – 84OLE2 object properties, name, 8 – 8OLE2 objects

activating, 16 – 4boilerplate in the layout, 16 – 4columns in the data model, 16 – 4integration with Oracle Reports, 16 – 4pop–up menu, 7 – 19show object types, 7 – 19tools, 7 – 15

OLE2 package, definition of, 13 – 39ONFAILURE



ONSUCCESSkeyword for R25DES, 1 – 44keyword for R25RUN, 1 – 29

OPS$ ID, 1 – 8ORA_FFI package, definition of, 13 – 39ORA_NLS package, definition of, 13 – 39ORA_PROF package, definition of, 13 – 39ORACLE

Call Interface user exits, 14 – 3integration with Oracle Reports, 16 – 2Non–ORACLE user exits, 14 – 3Precompiler Interface user exits, 14 – 3

Oracle Graphicsintegration with Oracle Reports, 16 – 6performance with Oracle Reports, 17 – 13tool, 7 – 14

Oracle Graphics display, 8 – 73placing in Layout painter, 8 – 75

Oracle Graphics display propertiesdisplay column, 8 – 78display name, 8 – 76display parameter, 8 – 77display query, 8 – 79name, 8 – 8report column, 8 – 79report column, for display parameters, 8 – 77source, 8 – 80

Oracle Procedure Builder, 13 – 35interpreter, 13 – 35packages, 13 – 39program unit editor, 13 – 35

Oracle Programmatic InterfaceSee also call interfacesupported host languages, 15 – 2

Oracle Reports Server, invoked by R25RUNBACKGROUND=YES, 1 – 31

Oracle Reports tablesdescription, 18 – 12installing, 19 – 3

Oracle*Mail. See MailORDER BY clauses, added to by Oracle Re-

ports, 17 – 6

ORIENTATIONkeyword for R25DES, 1 – 46keyword for R25RUN, 1 – 30

Output device type. See destination typeOVERWRITE keyword for R25CONV, 1 – 14

PPackaged user exits. See user exits, packagedPackages. See PL/SQL, packagesPage break after, 8 – 9

rules, 8 – 9rules for conflicting properties, 8 – 2

Page break before, 8 – 11rules, 8 – 11rules for conflicting properties, 8 – 2

Page dimensions for report, character modedefault, 4 – 14options, 4 – 14

Page height for report, 4 – 6default, 4 – 6, 4 – 10options, 4 – 6, 4 – 10rules, 4 – 6, 4 – 10

Page numbering, 8 – 52dialog box, 8 – 52example of changing via PL/SQL, 13 – 48examples, 8 – 54include, 8 – 53increment by, 8 – 54reset at, 8 – 54rules, 8 – 56start at, 8 – 54

Page protect, 8 – 12examples, 8 – 12rules, 8 – 14rules for conflicting properties, 8 – 2

Page size, character mode setting, 4 – 14Page width for report, 4 – 7

default, 4 – 7options, 4 – 7rules, 4 – 7

Page, maximum records, 8 – 33examples, 8 – 34

Page–dependent references, 8 – 25

Index – 17

Pagescreating layout, 7 – 20creating parameter form, 9 – 9deleting layout, 7 – 20deleting parameter form, 9 – 9using as field source, 8 – 57

Pages, keeping objects together onkeep with anchoring object, 8 – 6minimum widow records, 8 – 34page protect, 8 – 12

PAGESIZEkeyword for R20CONV, 1 – 15keyword for R25DES, 1 – 42keyword for R25RUN, 1 – 27

Palettescolor, F – 4pattern names, F – 2

Panel number, field source, 8 – 57Panel print order, 4 – 7

default, 4 – 8options, 4 – 8

PARAMkeyword for R25DES, 1 – 47keyword for R25RUN, 1 – 32

Parameter form boilerplate properties, 10 – 4name, 10 – 4type, 10 – 5

Parameter Form defaulting, 2 – 47Parameter form editor, 9 – 1

components, 9 – 5definition and purpose, 9 – 4navigation, 9 – 8objects, 9 – 5pages, 9 – 5, 9 – 8painting region, 9 – 5pop–up menu, 9 – 7

Parameter form field properties, 10 – 2datatype, 10 – 2name, 10 – 2source, 10 – 3

Parameter form propertiesform height, 4 – 10form width, 4 – 10number of pages, 4 – 11previewer title, 4 – 11

Parameter form, runtime, 9 – 2

Parameter properties, 6 – 45add to list of values, 6 – 51comment tab, 6 – 52data/selection tab, 6 – 50datatype, 6 – 47general tab, 6 – 47hide first column, 6 – 52initial value, 6 – 48input mask, 6 – 48name, 6 – 49remove from list of values, 6 – 51restrict list to predetermined values, 6 – 51SELECT statement, 6 – 51static list, 6 – 51validation trigger, 13 – 27value, 6 – 52width, 6 – 49

Parameter references, E – 3bind, E – 4lexical, E – 5rules, E – 3

Parametersreplacing multiple values via lexical, E – 5system, 6 – 45user, 6 – 45

PARAMFORMkeyword for R25DES, 1 – 36keyword for R25RUN, 1 – 19performance, 17 – 16

Parent columns, 6 – 13Parent group, 6 – 13Parent–child relationships. See links, data mod-

elParsing, 6 – 6Pascal, Pro*Pascal, 14 – 3Passing arguments. See user exits, passing val-

uesPatterns

names of, F – 2via PL/SQL: SRW.SET_ATTR,

BORDPATT, 13 – 59Performance

ARRAYSIZE, 17 – 16ASCII driver, 17 – 17break columns, 17 – 9CDE_MM.GET_REF, 17 – 7


COPIES, 17 – 17data model suggestions, 17 – 5design interface suggestions, 17 – 3design preferences, 17 – 4external libraries, 17 – 15file searching, 17 – 19format triggers, 17 – 13formatting attributes, 17 – 12image resolution, 17 – 12indexes, 17 – 7local PL/SQL, 17 – 14LONGCHUNK, 17 – 16matrix reports, 17 – 9maximum rows and group filters, 17 – 8MODE, 17 – 17monitoring, 17 – 2number of queries, 17 – 5Oracle Graphics integration, 17 – 13Oracle Reports query modifications, 17 – 6PARAMFORM, 17 – 16PL/SQL, 17 – 13previewer, 17 – 17report templates, 17 – 4RUNDEBUG, 17 – 17runtime, 17 – 15sizing, 17 – 12SQL statements faster, 17 – 6SQL TRACE, 17 – 2SRW.DO_SQL, 17 – 7, 17 – 14SRW.SET_ATTR, 17 – 15storage, 17 – 18stored procedures, 17 – 14system suggestions, 17 – 18table sharing, 17 – 19total number of pages, 17 – 13tracing, 17 – 2transparent objects, 17 – 12unused frames, 17 – 11word wrapping, 17 – 12

Physical pagedefinition, 11 – 4number, field source, 8 – 57

PL/l, Pro*PL/l, 14 – 3PL/SQL, 13 – 1

See also PL/SQL packaged exceptions, func-tions, procedures

column and parameter references, E – 3compiling, error messages, 13 – 38

compiling, multiple constructs, 13 – 37compiling, single constructs, 13 – 37construct types, 13 – 2description of, 13 – 2development environment. See Oracle Proce-

dure Builderediting in Program Unit editor, 13 – 35errors, trapping with exceptions, 13 – 11exceptions, manually created, 13 – 11exceptions, packaged, 13 – 11, 13 – 12functions, definition of, 13 – 4functions, examples of, 13 – 5functions, syntax of, 13 – 4global variables, advantage of, 13 – 8icon in Object Navigator, 12 – 6interpreter, 13 – 35non–value constructs, definition of, 13 – 6non–value constructs, types of, 13 – 6objects with, 13 – 15overview, 13 – 2package, definition of, 13 – 41packages, examples of, 13 – 9packages, syntax of, 13 – 9performance, 17 – 13procedures, definition of, 13 – 6procedures, examples of, 13 – 8procedures, syntax of, 13 – 7purpose of, 13 – 2referencing Oracle Reports objects in, 13 – 32restrictions within Oracle Reports, 13 – 33rules, 13 – 33SRW package and its contents, 13 – 41SRW package, overview of, 13 – 41stored program unit stubs, 13 – 34supported versions, 13 – 33trapping success or failure in, 13 – 11types of, 13 – 2usage of, 13 – 2user–created packages, definition of, 13 – 8valid constructs for each object, 13 – 15value constructs, definition of, 13 – 4value constructs, types of, 13 – 4

PL/SQL exceptionsdefinition of, 13 – 11example of packaged one, 13 – 13packaged with Oracle Reports, 13 – 12packaged with PL/SQL, 13 – 12packaged, definition of, 13 – 11

Index – 19

PL/SQL function, used as a formula, 13 – 25PL/SQL packaged exceptions

descriptions of, 13 – 41SRW.CONTEXT_FAILURE, 13 – 42SRW.DO_SQL_FAILURE, 13 – 46SRW.INTEGER_ERROR, 13 – 48SRW.MAXROW_INERR, 13 – 48SRW.MAXROW_UNSET, 13 – 49SRW.NULL_ARGUMENTS, 13 – 51SRW.PROGRAM_ABORT, 13 – 52SRW.RUN_REPORT_BATCHNO, 13 – 57SRW.RUN_REPORT_FAILURE, 13 – 57SRW.TRUNCATED_VALUE, 13 – 70SRW.UNKNOWN_QUERY, 13 – 70SRW.UNKNOWN_USER_EXIT, 13 – 71SRW.USER_EXIT_FAILURE, 13 – 73

PL/SQL packaged functionsdefinition of, 13 – 41SRW.GETERR_RUN, 13 – 47

PL/SQL packaged proceduresCDE_MM.GET_REF, 13 – 40definition of, 13 – 41SRW.BREAK, 13 – 41SRW.DO_SQL, 13 – 43SRW.GET_PAGE_NUM, 13 – 47SRW.MESSAGE, 13 – 50SRW.REFERENCE, 13 – 53SRW.RUN_REPORT, 13 – 54SRW.SET_ATTR, 13 – 58SRW.SET_FIELD_CHAR, 13 – 64SRW.SET_FIELD_DATE, 13 – 64SRW.SET_FIELD_NUM, 13 – 65SRW.SET_MAXROW, 13 – 66SRW.TRACE_ADDOPTION, 13 – 67SRW.TRACE_END, 13 – 67SRW.TRACE_REMOPTION, 13 – 68SRW.TRACE_START, 13 – 68SRW.USER_EXIT, 13 – 71SRW.USER_EXIT20, 13 – 73

PL/SQL subprograms, 13 – 22PL/SQL text example, 13 – 22

Placeholder column properties, 6 – 42example, 6 – 43general tab, 6 – 44rules, 6 – 44

Placeholders, tool, 5 – 6Placement

of fields, 8 – 41of Oracle Graphics display, 8 – 75of repeating frames, 8 – 28

Plus/minus, in Object Navigator, 12 – 5PostScript, printer definitions, B – 2Preferences, file, 18 – 5Preview

formatting screen output via R25DES, 1 – 37formatting screen output via R25RUN, 1 – 20

PreviewerSee also previewer runtime settingsaccessing, 11 – 3accessing multimedia objects in, 11 – 8components, 11 – 3definition and purpose, 11 – 2magnifying the contents, 11 – 7modifying components, 11 – 4moving from section to section, 11 – 5navigation, 11 – 5performance, 17 – 17splitting the viewing region, 11 – 6title, 11 – 4viewing region, 11 – 4

Previewer runtime settingscharacters per page, 4 – 14disable host, 4 – 13disable split, 4 – 13disable zoom, 4 – 13hint line, 4 – 13start in zoom, 4 – 15status line, 4 – 14suppress previewer title, 4 – 15title, 4 – 11use character units in designer, 4 – 15

Print condition, 8 – 15algorithm for *Default for layout

objects, 2 – 47examples, 8 – 17rules, 8 – 18rules for conflicting properties, 8 – 2type, 8 – 15


Print direction, 8 – 35default, 8 – 36examples, 8 – 36options, 8 – 35rules, 8 – 39

Printersending parts of a report to different

ones, 13 – 54sending previewer output to, 11 – 11sending reports to via R25RUN, 1 – 20

Printer codes, 8 – 26after, 8 – 27before, 8 – 27conditional, example, 13 – 61examples, 8 – 26tab, 8 – 26via PL/SQL: SRW.SET_ATTR,

AFTCODE, 13 – 59via PL/SQL: SRW.SET_ATTR,

BEFCODE, 13 – 59Printer definitions

creating or modifying, B – 3description of, B – 2example of, B – 9file syntax of, B – 3file–searching method, 18 – 10packaged with Oracle Reports, B – 2

Printer name, destination name. See destina-tion type

Printing, controlling frequency, 8 – 15AUTOCOMMIT


PRINTJOBkeyword for R25DES, 1 – 47keyword for R25RUN, 1 – 32

Privilegesgranting to users, 19 – 4revoking from users, 19 – 4

Pro*Adacall interface, 15 – 6user exits, 14 – 3

Pro*Ccall interface, 15 – 6user exits, 14 – 3

Pro*COBOLcall interface, 15 – 7user exits, 14 – 3

Pro*FORTRANcall interface, 15 – 7user exits, 14 – 3

Pro*Pascalcall interface, 15 – 8user exits, 14 – 3

Pro*PL/lcall interface, 15 – 8user exits, 14 – 3

Procedure calls. See call interfaceProcedures. See PL/SQL, proceduresProduct order, 6 – 33

examples, 6 – 34rules, 6 – 38

PROFILESee also Tracingkeyword for R25DES, 1 – 43keyword for R25RUN, 1 – 28

Program Unit editor, 13 – 35name list, 13 – 36object list, 13 – 36type list, 13 – 36

PROGRAM_ABORT. See L/SQL packaged ex-ceptions, SRW.PROGRAM_ABORT

Propertiesdata, 6 – 1layout, 8 – 1

Property sheet navigation, vProperty sheets

boilerplate, 8 – 59column, 6 – 17database column, 6 – 27field, 8 – 41formula column, 6 – 41frame, 8 – 28group, 6 – 14OLE object, 8 – 84Oracle Graphics display, 8 – 73parameter, 6 – 45parameter form boilerplate, 10 – 4parameter form field, 10 – 2

Index – 21

placeholder column, 6 – 42query, 6 – 2repeating frame, 8 – 28report trigger, 13 – 17summary column, 6 – 27

PUT. See EXEC IAF PUT

QQueries

See also query propertiesreducing fetch via PL/SQL,

SRW.SET_MAXROW, 13 – 66referencing columns and parameters, E – 3tool, 5 – 6

Query properties, 6 – 2child column, 6 – 12comment tab, 6 – 8condition, 6 – 12external query, 6 – 3general tab, 6 – 2maximum rows, 6 – 4name, 6 – 5SELECT statement, 6 – 5SELECT statement example, 6 – 5SELECT statement rules, 6 – 6

RR25CONV

BATCH keyword, 1 – 15CMDFILE keyword, 1 – 14definition of, 1 – 9DEST keyword, 1 – 13DTYPE keyword, 1 – 12DUNIT keyword, 1 – 15FORMSIZE keyword, 1 – 16LOGFILE keyword, 1 – 14OVERWRITE keyword, 1 – 14PAGESIZE keyword, 1 – 15SOURCE keyword, 1 – 11STYPE keyword, 1 – 11USERID keyword, 1 – 7, 1 – 10USERID rules, 1 – 10, 1 – 11

R25DESACCESS keyword, 1 – 46ARRAYSIZE keyword, 1 – 37

AUTOCOMMIT keyword, 1 – 49BACKGROUND keyword, 1 – 46BUFFERS keyword, 1 – 42CMDFILE keyword, 1 – 36COPIES, 1 – 39COPIES keyword, 1 – 39CURRENCY keyword, 1 – 40DECIMAL keyword, 1 – 40definition of, 1 – 35DESFORMAT keyword, 1 – 39DESNAME keyword, 1 – 38DESTYPE keyword, 1 – 37displaying reports as PostScript output

via, 1 – 37ERRFILE keyword, 1 – 45LONGCHUNK keyword, 1 – 45MODE keyword, 1 – 46MODULE keyword, 1 – 36ONFAILURE keyword, 1 – 45ONSUCCESS keyword, 1 – 44ORIENTATION keyword, 1 – 46PAGESIZE keyword, 1 – 42PARAM keyword, 1 – 47PARAMFORM keyword, 1 – 36PRINTJOB keyword, 1 – 47PROFILE keyword, 1 – 43READONLY keyword, 1 – 41REPORT keyword, 1 – 36RUNDEBUG keyword, 1 – 44sending reports to files via, 1 – 37sending reports to Oracle*Mail users

via, 1 – 37sending reports to printers via, 1 – 37sending reports to the screen via, 1 – 37THOUSANDS keyword, 1 – 40TRACEFILE keyword, 1 – 48TRACEMODE keyword, 1 – 48TRACEOPTS keyword, 1 – 48USERID keyword, 1 – 7

R25MPRT. See Oracle Reports Migration GuideR25MREP. See Oracle Reports Migration GuideR25RUN

ARRAYSIZE keyword, 1 – 20AUTOCOMMIT keyword, 1 – 34BACKGROUND keyword, 1 – 31BATCH keyword, 1 – 26BUFFERS keyword, 1 – 26CMDFILE keyword, 1 – 19


COPIES keyword, 1 – 23CURRENCY keyword, 1 – 23DECIMAL keyword, 1 – 24definition of, 1 – 17DESFORMAT keyword, 1 – 22DESNAME keyword, 1 – 21DESTYPE keyword, 1 – 20displaying reports in PostScript format

via, 1 – 20ERRFILE keyword, 1 – 30KEYIN keyword, 1 – 30KEYOUT keyword, 1 – 30LOGFILE keyword, 1 – 25LONGCHUNK keyword, 1 – 30MODE keyword, 1 – 31MODULE keyword, 1 – 18ONFAILURE keyword, 1 – 29ONSUCCESS keyword, 1 – 29ORIENTATION keyword, 1 – 30PAGESIZE keyword, 1 – 27PARAM keyword, 1 – 32PARAMFORM keyword, 1 – 19PRINTJOB keyword, 1 – 32PROFILE keyword, 1 – 28READONLY keyword, 1 – 24REPORT keyword, 1 – 18RUNDEBUG keyword, 1 – 28sending reports to files via, 1 – 20sending reports to Oracle*Mail users

via, 1 – 21sending reports to printers via, 1 – 20sending reports to the screen via, 1 – 20TERM keyword, 1 – 20THOUSANDS keyword, 1 – 23TRACEFILE keyword, 1 – 33TRACEMODE keyword, 1 – 33TRACEOPTS keyword, 1 – 33USERID keyword, 1 – 7

Raw datatype, 6 – 20RAW MLSLABEL, 6 – 21RDF file. See .rdfRead from file, 6 – 23

examples, 6 – 23rules, 6 – 24

READONLYavoid with EXEC ORACLE, 14 – 8avoid with EXEC SQL, 14 – 5

avoid with SRW.DO_SQL, 13 – 44keyword for R25DES, 1 – 41keyword for R25RUN, 1 – 24

Recordsmaximum per page for repeating

frame, 8 – 33minimum widow for repeating frame, 8 – 34

REF, datatype of column, 6 – 20REFERENCE. See PL/SQL packaged proce-

dures, SRW.REFERENCEReferences

to external PL/SQL libraries, 13 – 16to external queries, 6 – 3

References to parameters and columns, E – 3bind, E – 4lexical, E – 5rules, E – 3

Referencing terminal resource files, B – 21Remote login, 1 – 8Remove from parameter LOV, 6 – 51Rep file, .rep. See .repRepeating frame properties, 8 – 28

column mode, 8 – 29comment, 8 – 27format trigger, 13 – 28horizontal sizing, 8 – 4horizontal spacing, 8 – 33keep with anchoring object, 8 – 6maximum records per page, 8 – 33minimum widow records, 8 – 34name, 8 – 8page break after, 8 – 9page break before, 8 – 11page protect, 8 – 12print condition, 8 – 15print direction, 8 – 35printer codes, 8 – 26source, 8 – 39vertical sizing, 8 – 20vertical spacing, 8 – 40

Repeating framesSee also repeating frame propertiesnames, D – 3placing in layout editor, 8 – 28tool, 7 – 13

Index – 23

REPORTkeyword for R25DES, 1 – 36keyword for R25RUN, 1 – 18

Reportquery properties, 6 – 2regions, 7 – 4

Report body. See bodyReport margins. See marginsReport properties

character–mode settings, 4 – 11comment, 4 – 15for parameter form, 4 – 11for report, 4 – 7, 4 – 9for report header, 4 – 5for report length, 4 – 5for report trailer, 4 – 6for Runtime Parameter Form, 4 – 10form height, 4 – 10form width, 4 – 10logical page size, 4 – 3maximum body pages, 4 – 5maximum header pages, 4 – 5maximum trailer pages, 4 – 6page height, 4 – 6page width, 4 – 7panel print order, 4 – 7previewer title, 4 – 11runtime settings, 4 – 11unit of measurement, 4 – 9

Report templates, 17 – 4Report triggers, 13 – 17

when trigger fires, 13 – 17Reports

converting (R25CONV) via call from 3GLprogram, 15 – 2, 15 – 3

converting report definitions, 1 – 9creating printer definitions for, B – 3creating terminal definitions for, B – 15defining and maintaining, 1 – 35deleting, 19 – 5designing (R25DES) via call from 3GL pro-

gram, 15 – 2, 15 – 3documenting, 19 – 6modifying key bindings for, B – 17moving between files and the

database, 19 – 5on reports, 19 – 6

running (R25ISV) via call from 3GL program,15 – 2, 15 – 3

running multiple, 13 – 54upgrading (R25MREP) via call from 3GL

program, 15 – 2, 15 – 3upgrading from previous versions, 19 – 5

REPORTS_TMP, 18 – 11REPORTS25_PATH, 18 – 11REPORTS25_TERMINAL, 18 – 11Reset at, 6 – 39

example, 6 – 39options, 6 – 39rules, 6 – 40

Reset group. See reset; reset atReshaping tool, 7 – 11Restricting parameter values

format of, 6 – 48to list of values, 6 – 51via validation trigger, 13 – 27

Restrictions. See rulesRevoking access, using SQL scripts, 19 – 4Rex file. See .rexRight mouse button, in Object

Navigator, 12 – 4ros.sql script, 19 – 3rosdrop.sql script, 19 – 3rosgnt.sql script, 19 – 3Rotating

rules, 7 – 10tool, 7 – 10

Rulesfor bind references, E – 4for break order, 6 – 20for call interface, 15 – 4for child columns in a link, 6 – 12for child query in a link, 6 – 12for column datatype, 6 – 21for column format, 6 – 22for column functions, 6 – 32for column width, 6 – 26for compute at, 6 – 31for database columns, 6 – 27for designing character mode reports, A – 3for executable syntax, 1 – 4for external queries, 6 – 3


for filter conditions, 13 – 24for formula columns, 6 – 41for formulas, 13 – 26for groups, 6 – 15for initial value, 6 – 48for input mask, 6 – 49for lexical references, E – 6for links, 6 – 11for maximum rows, 6 – 4for parameter datatype, 6 – 47for parent groups in a link, 6 – 13for PL/SQL, 13 – 33for placeholder columns, 6 – 44for product order, 6 – 38for read from file, 6 – 24for reset at, 6 – 40for searching in Object Navigator, 12 – 16for SELECT statement, 6 – 6for SQL clause, 6 – 14for summary source, 6 – 40for type of filter, 6 – 16for user exits, 14 – 12for validation triggers, 13 – 27for value if null, 6 – 25for width of parameter, 6 – 50logical page size, 4 – 5report column, for display column, 8 – 79report column, for display parameter, 8 – 77

rules for terminal definitions, B – 21RUN_REPORT. See PL/SQL packaged proce-

dures, SRW.RUN_REPORTRUN_REPORT_BATCHNO. See PL/SQL pack-

aged exceptions, SRW.RUN_RE-PORT_BATCHNO

RUN_REPORT_FAILURE. See PL/SQL pack-aged exceptions, SRW.RUN_RE-PORT_FAILURE

RUNDEBUGkeyword for R25DES, 1 – 44keyword for R25RUN, 1 – 28performance, 17 – 17

Runfile. See .repRunning reports

displaying as PostScript via R25DES, 1 – 37

displaying as PostScript via R25RUN, 1 – 20from the command line, 1 – 18multiple, 13 – 54sending portions to different mailids, 13 – 54sending portions to different printers, 13 – 54sending to files via R20RUN, 1 – 20sending to files via R25DES, 1 – 37sending to Oracle*Mail users via

R20RUN, 1 – 21sending to Oracle*Mail users via

R25DES, 1 – 37sending to printers via R20RUN, 1 – 20sending to printers via R25DES, 1 – 37sending to the screen via R20RUN, 1 – 20sending to the screen via R25DES, 1 – 37via call from 3GL program, 15 – 2, 15 – 3

Running summary, 6 – 39Runtime parameter form, 9 – 2

access, 9 – 2definition and purpose, 9 – 2pages, 9 – 8

Runtime settingscharacters per page, 4 – 14convert bit–mapped objects to boxes, 4 – 12convert borders, 4 – 13disable host, 4 – 13disable split, 4 – 13disable zoom, 4 – 13previewer hint line, 4 – 13previewer status line, 4 – 14previewer title, 4 – 11start in zoom, 4 – 15suppress previewer title, 4 – 15use character units in designer, 4 – 15

RWEATS user exitdescription of, 14 – 16syntax, 14 – 16

RWECAT user exitsyntax, 14 – 20V2.0 & V1.1 packaged user exit, 14 – 20

RWECPF user exitdescription of, 14 – 20syntax, 14 – 20

Index – 25

RWECTY user exitdescription of, 14 – 20syntax, 14 – 21

RWENOP. See placeholdersRWEPLS user exit, description of, 14 – 21

SScaling, performance cost, 17 – 12Screen

sending reports to via R25DES, 1 – 37sending reports to via R25RUN, 1 – 20

Scriptsdroprep.sql, 19 – 2ros.sql, 19 – 3rosdrop.sql, 19 – 3rosgnt.sql, 19 – 3srw2bild.sql, 19 – 2srw2drop.sql, 19 – 2srw2grnt.sql, 19 – 2srw2lmt.sql, 19 – 2srw2pup.sql, 19 – 2srw2pup7.sql, 19 – 2srw2rvke.sql, 19 – 3toolbild.sql, 19 – 3tooldrop.sql, 19 – 3toolgrnt.sql, 19 – 3toolrvke.sql, 19 – 3using in Oracle Reports, 19 – 2vgbild.sql, 19 – 3vgdrop.sql, 19 – 3vggrnt.sql, 19 – 3vgrvke.sql, 19 – 3

Searching in Object Navigator, 12 – 16Secure systems datatypes, 6 – 21Security, database, establishing, 18 – 31SELECT statement

bind references, E – 4errors, E – 3for parameter LOV, 6 – 51lexical references, E – 5parameter and column references, E – 3query, 6 – 5

Selectingtool, layout editor, 7 – 9tool, data model editor, 5 – 6

Sending reportsto files via R25DES, 1 – 37to files via R25RUN, 1 – 20to Oracle*Mail users via R25DES, 1 – 37to Oracle*Mail users via R25RUN, 1 – 21to printers via R25DES, 1 – 37to printers via R25RUN, 1 – 20to the screen via R25DES, 1 – 37

SET TRANSACTION READONLY. SeeSRW.DO_SQL

SET_ATTR. See PL/SQL packaged procedures,SRW.SET_ATTR

SET_FIELD_CHAR. See PL/SQL packagedprocedures, SRW.SET_FIELD_CHAR

SET_FIELD_DATE. See PL/SQL packaged pro-cedures, SRW.SET_FIELD_DATE

SET_FIELD_NUM. See PL/SQL packaged pro-cedures, SRW.SET_FIELD_NUM

SET_MAXROW. See PL/SQL packaged proce-dures, SRW.SET_MAXROW

Shift key, for constrained mode, 7 – 8Show object types (OLE2), 7 – 19Size

conditional text, example, 13 – 63rules, 8 – 23via PL/SQL: SRW.SET_ATTR, SZ, 13 – 60

Skip, hidden, 8 – 80Sound

accessing, 11 – 8in buttons, 11 – 8

Sound dialogforward, 11 – 8options, 11 – 9play, 11 – 9record, 11 – 9rewind, 11 – 9slidebar, 11 – 9stop, 11 – 9

Source for field, 8 – 56example, 8 – 57options, 8 – 56rules, 8 – 57

Source for Oracle Graphics display, 8 – 80Source for parameter form field, 10 – 3

rules, 10 – 3


Source for repeating frame, 8 – 39Source for summary column, 6 – 40

rules, 6 – 40SOURCE keyword for R25CONV, 1 – 11Spacing

horizontal, 8 – 33vertical, 8 – 40vertical via PL/SQL: SRW.SET_ATTR, CUS-

TOM, 13 – 60vertical via PL/SQL: SRW.SET_ATTR,

GSPACING, 13 – 60Special characters, asterisks in

fields, 8 – 24, 8 – 49Split function in previewer

horizontally, 11 – 6vertically, 11 – 6

SQLscripts packaged with Oracle Reports, 19 – 2statements in user exits, 14 – 5TRACE, 17 – 2using NLS, C – 3, C – 5

SQL clause, 6 – 13default, 6 – 13options, 6 – 13rules, 6 – 14

SQL SELECT statement errors, E – 3SQL*Net, 16 – 2SRW2_ANCHOR, 18 – 13SRW2_BODY_LOCATION, 18 – 13SRW2_BOILERPLATE, 18 – 14SRW2_COLUMN, 18 – 15SRW2_DATA_MODEL, 18 – 17SRW2_DISPLAY_TAG, 18 – 17SRW2_ELEMENT, 18 – 18SRW2_FIELD, 18 – 19SRW2_FRAME, 18 – 20SRW2_GROUP, 18 – 21SRW2_LAYOUT, 18 – 22SRW2_LAYOUT_GROUP, 18 – 23SRW2_LINK, 18 – 24SRW2_MATRIX, 18 – 24SRW2_MODULE, 18 – 24

SRW2_OG_DOCUMENT, 18 – 25SRW2_OGD_COLUMN_MAP, 18 – 25SRW2_QUERY, 18 – 26SRW2_TEXT_SEGMENT, 18 – 26srw2bild.sql script, 19 – 2srw2drop.sql script, 19 – 2srw2grnt.sql script, 19 – 2srw2lmt.sql script, 19 – 2srw2pup.sql script, 19 – 2srw2pup7.sql script, 19 – 2srw2rvke.sql script, 19 – 3SRWERB

for raising user exit errors, 14 – 9User exits, SRWERB, 14 – 9

Standard deviation, summary function, 6 – 32Start in zoom, runtime setting, 4 – 15START WITH clauses

added by Oracle Reports, 17 – 6option for data links, 6 – 13

Static list, for parameter LOV, 6 – 51Status line

in data model editor, 5 – 7in layout editor, 7 – 17

Storage, 18 – 1Stored program units, stubs, 13 – 34String, empty, 1 – 5Style, conditional text, example, 13 – 63STYPE keyword for R25CONV, 1 – 11Sum, summary function, 6 – 32Summary, tool, 5 – 6Summary column properties, 6 – 27, 6 – 32

compute at, 6 – 29function, 6 – 32general tab, 6 – 28product order, 6 – 33reset at, 6 – 39source, 6 – 40

Supported file formats, 18 – 2Suppress

boilerplate labels (headers), 13 – 29previewer title, runtime setting, 4 – 15

Index – 27

Syntaxcall interface, 15 – 3EXEC IAF GET, 14 – 6EXEC IAF PUT, 14 – 7EXEC SQL, 14 – 5how to view command line options, 1 – 3PL/SQL compiler errors, 13 – 38PL/SQL function, 13 – 4PL/SQL procedure, 13 – 7, 13 – 9rules for executables, 1 – 4RWEATS packaged user exit, call to, 14 – 16RWECAT packaged user exit, call to, 14 – 20RWECPF packaged user exit, call to, 14 – 20RWECTY packaged user exit, call to, 14 – 21user exit call, 14 – 8, 14 – 10

System output device, sending reports to de-fault devices via R25RUN, 1 – 21

System parameters, 6 – 45

TTables

data tables, 18 – 12demo tables, 18 – 12dropping Version 1.1 tables, 19 – 5integrated, 18 – 27Oracle Reports, 18 – 13Oracle Reports tables, 18 – 12SRW2_ANCHOR, 18 – 13SRW2_BODY_LOCATION, 18 – 13SRW2_BOILERPLATE, 18 – 14SRW2_COLUMN, 18 – 15SRW2_DATA_MODEL, 18 – 17SRW2_DISPLAY_TAG, 18 – 17SRW2_ELEMENT, 18 – 18SRW2_FIELD, 18 – 19SRW2_FRAME, 18 – 20SRW2_GROUP, 18 – 21SRW2_LAYOUT, 18 – 22SRW2_LAYOUT_GROUP, 18 – 23SRW2_LINK, 18 – 24SRW2_MATRIX, 18 – 24SRW2_MODULE, 18 – 24SRW2_OG_DOCUMENT, 18 – 25SRW2_OGD_COLUMN_MAP, 18 – 25

SRW2_QUERY, 18 – 26SRW2_TEXT_SEGMENT, 18 – 26TOOL_ACCESS, 18 – 27TOOL_COMMENT, 18 – 27TOOL_DEPEND, 18 – 27TOOL_LIBRARY, 18 – 28TOOL_LRAW, 18 – 28TOOL_LRAW_ID, 18 – 28TOOL_LTEXT, 18 – 28TOOL_LTEXTID, 18 – 29TOOL_MODID, 18 – 29TOOL_MODULE, 18 – 29TOOL_PLSQL, 18 – 30TOOL_ROSSTRINGS, 18 – 30

Templates, report, 17 – 4Temporary files, 18 – 8

minimizing size, 18 – 9TERM, keyword for R25RUN, 1 – 20Terminal definitions

description of, B – 14file–searching method, 18 – 10modifying, B – 19packaged with Oracle Reports, B – 14specifying on command line via

R25RUN, 1 – 20Terminal resource files

how to reference, B – 21rules for usage, B – 21

Terminal resourcescreating or modifying, B – 15modifying key bindings, B – 17modifying terminal definition, B – 19

Textcolor tool, 7 – 17conditional color, example, 13 – 63conditional spacing, example, 13 – 63tool, 7 – 13

Text string, 8 – 83TEXT_IO package, definition of, 13 – 39THOUSANDS


Title, Previewer, 11 – 4TK21_ICON, 18 – 12


Tool palettedata model editor, 5 – 5layout editor, 7 – 7parameter form editor, 9 – 6

TOOL_ACCESS, 18 – 27TOOL_COMMENT, 18 – 27TOOL_DEPEND, 18 – 27TOOL_ENV package, definition of, 13 – 39TOOL_ERR package, definition of, 13 – 39TOOL_LIBRARY, 18 – 28TOOL_LRAW, 18 – 28TOOL_LRAW_ID, 18 – 28TOOL_LTEXT, 18 – 28TOOL_LTEXT_ID, 18 – 29TOOL_MODID, 18 – 29TOOL_MODULE, 18 – 29TOOL_PLSQL, 18 – 30TOOL_RES package, definition of, 13 – 39TOOL_ROSSTRINGS, 18 – 30Toolbar, in Object Navigator, 5 – 5, 7 – 7, 9 – 6,

12 – 3toolbild.sql script, 19 – 3tooldrop.sql script, 19 – 3toolgrnt.sql script, 19 – 3toolrvke.sql script, 19 – 3Tools menu. See online help systemTotal logical pages

field source, 8 – 57performance, 17 – 13

Total panels, field source, 8 – 57Total physical pages

field source, 8 – 57performance, 17 – 13

TRACEFILEkeyword for R25DES, 1 – 48keyword for R25RUN, 1 – 33

TRACEMODEkeyword for R25DES, 1 – 48keyword for R25RUN, 1 – 33

TRACEOPTSkeyword for R25DES, 1 – 48keyword for R25RUN, 1 – 33

Tracingperformance monitoring, 17 – 2system–level, 17 – 3user–level, 17 – 3

Trailer page, 7 – 6Tranlsation, NLS, C – 7Transparent objects, performance improve-

ment, 17 – 12Triggers

action, 13 – 32format, 13 – 28report, 13 – 17validation, 13 – 27which report trigger to use, 13 – 17

Truncationpackaged exception to handle successfully,

13 – 70possible in form letter reports, 2 – 41possible in mailing label reports, 2 – 41

Trusted ORACLE datatypes, 6 – 21Type of filter, 6 – 15

examples, 6 – 16options, 6 – 16rules, 6 – 16

Type of parameter form boilerplate, 10 – 5Type of print condition, 8 – 15


Typographic conventions, v

Uuifont.ali, 18 – 7Unit of measurement, 4 – 9


UNKNOWN_QUERY. See PL/SQL packagedexceptions, SRW.UNKNOWN_QUERY

UNKNOWN_USER_EXIT. See PL/SQL pack-aged exceptions,SRW.UNKNOWN_USER_EXIT

Updating. See DML

Index – 29

Upgrading reports from previous versions, 19 – 5

Use character units in designer, 4 – 15User exits, 14 – 1

See also placeholders (for RWENOP); userexits, packaged

call, syntax when passed, 14 – 8calling from Oracle Reports, 14 – 10DDL, avoid with READONLY, 14 – 5definition of, 14 – 2error checking, example, 14 – 22error messages, defining with

SRW.MESSAGE, 14 – 14errors, checking via SRW.USER_EXIT_FAIL-

URE, 14 – 13errors, raising from the exit, 14 – 9errors, raising in PL/SQL, 14 – 13example call, 14 – 22example, call with PL/SQL error checking,

14 – 14, 14 – 15example, call without error checking, 14 – 11example, complete, 14 – 21EXEC IAF GET, 14 – 6EXEC IAF PUT, 14 – 7EXEC ORACLE, 14 – 7EXEC SQL, 14 – 5implementing, 14 – 9non–ORACLE, 14 – 3OCI (ORACLE Call Interface), 14 – 3ORACLE commands, performing, 14 – 7Oracle Precompiler Interface, 14 – 3performance, 17 – 14READONLY, avoid with DDL, 14 – 5screen I/O, performing, 14 – 4SQL commands, performing, 14 – 5SRWERB buffer, 14 – 9steps to build, 14 – 3supported functions, 14 – 5syntax, call, 14 – 10syntax, call when passed, 14 – 8types, 14 – 2values from Oracle Reports, passing, 14 – 6values to Oracle Reports, passing, 14 – 6writing the program, 14 – 4

User exits, packagedRWEATS, 14 – 16

RWECAT, 14 – 20RWECPF, V2.0 and V1.1, 14 – 20RWECTY, 14 – 20RWEPLS, 14 – 21

User–defined buttonsaccessing images, 11 – 10accessing sound, 11 – 8accessing video, 11 – 10

USER_EXIT. See PL/SQL packaged proce-dures, SRW.USER_EXIT

USER_EXIT_FAILURE. See PL/SQL packagedexceptions, SRW.USER_EXIT_FAILURE

USER_NLS_LANG, C – 2USERID

keyword for R25CONV, 1 – 7, 1 – 10keyword for R25DES, 1 – 7keyword for R25RUN, 1 – 7rules for R25CONV, 1 – 10, 1 – 11

Usersgranting them privileges, 19 – 4parameters, 6 – 45revoking their privileges, 19 – 4

VValidation

command line parameters, 13 – 18trigger for parameters, 13 – 27

Value, for parameter LOV, 6 – 52Value constructs, PL/SQL, value constructs, 13

– 4Value if null, column property, 6 – 24

rules, 6 – 25Varchar, 6 – 21Varchar2, 6 – 21Variable sizing, 8 – 21Variables, placeholders. See placeholdersvariables, global. See global variablesVariance, summary function, 6 – 32Version 1.1 tables, dropping, 19 – 5Vertical frame for matrix, 8 – 73


Vertical sizing, 8 – 20default, 8 – 21examples, 8 – 21options, 8 – 20rules, 8 – 23to enhance performance, 17 – 12

Vertical spacing, 8 – 40default, 8 – 40rules, 8 – 40

vgbild.sql script, 19 – 3vgdrop.sql script, 19 – 3vggrnt.sql script, 19 – 3vgrvke.sql script, 19 – 3Video

accessing, 11 – 10in buttons, 11 – 10

Video dialogmute, 11 – 10play, 11 – 10stop, 11 – 10slidebar, 11 – 10sound, 11 – 10

View menu. See online help systemViewing region, Previewer, 11 – 4

WWHERE clauses

added by Oracle Reports, 17 – 6adding to matrix query, 17 – 10for performance, 17 – 6option for data links, 6 – 13

Widow lines, minimum for boilerplate, 8 – 62 for field, 8 – 51

Widow records, minimum for repeating frame, 8 – 34

examples, 8 – 34rules, 8 – 35rules for conflicting properties, 8 – 2

Width of column, 6 – 25default, 6 – 25options, 6 – 25rules, 6 – 26

Width of layout object border, via PL/SQL:SRW.SET_ATTR, BORDERWIDTH, 13 – 59

Width of parameter, 6 – 49default, 6 – 50options, 6 – 49rules, 6 – 50

Window menu. See online help systemWord wrapping, 8 – 41

performance cost, 17 – 12

ZZoom

See also magnifydisable for character mode, 4 – 13start in for character mode, 4 – 15

Packaged Procedures, Functions,Exception

Description Pg.

SRW.BREAK Stops report execution. 13 – 41

SRW.CONTEXT_ FAILURE Stops report when a program unit is run from the wrong context. 13 – 42

SRW.DO_SQL Executes a specified SQL statement. 13 – 43

SRW.DO_SQL_FAILURE Stops report when a failure occurs in SRW.DO_SQL. 13 – 46

SRW.GETERR_RUN Returns an error message if a failure occurs in SRW.RUN_REPORT. 13 – 47

SRW.GET_PAGE_NUM Returns the current page number. 13 – 47

SRW.INTEGER_ERROR Stops report when an invalid integer argument is passed. 13 – 48

SRW.MAXROW_INERR Stops report when a failure occurs in SRW.SET_MAXROW. 13 – 48

SRW.MAXROW_UNSET Stops report when a failure occurs setting the maximum rows for a query. 13 – 49

SRW.MESSAGE Displays a specified message and message number. 13 – 50

SRW.NULL_ARGUMENTS Stops report when a required argument is missing. 13 – 51

SRW.PROGRAM_ABORT Stops report when you raise it. 13 – 52

SRW.REFERENCE Adds the specified object to the dependency list of a program unit. 13 – 53

SRW.RUN_REPORT Executes the specified R25RUN command. 13 – 54

SRW.RUN_REPORT_BATCHNO Stops report when SRW.RUN_REPORT used with BATCH=NO. 13 – 57

SRW.RUN_REPORT_FAILURE Stops report when a failure occurs in SRW.RUN_REPORT. 13 – 57

SRW.SET_ATTR Applies attribute settings to layout objects. 13 – 58

SRW.SET_FIELD_CHAR Sets the value of a character field. 13 – 64

SRW.SET_FIELD_DATE Sets the value of a date field. 13 – 64

SRW.SET_FIELD_NUM Sets the value of a number field. 13 – 65

SRW.SET_MAXROW Sets the maximum number of rows to be retrieved by the specified query. 13 – 66

SRW.TRACE_ADD_OPTION Applies the trace options mask. 13 – 67

SRW.TRACE_END Stops the logging of trace information. 13 – 67

SRW.TRACE_REM_OPTION Removes trace options. 13 – 68

SRW.TRACE_START Begins the logging of trace information. 13 – 68

SRW.TRUNCATED_VALUE Stops report when a value is truncated. 13 – 70

SRW.UNKNOWN_QUERY Stops report when a query name is not found by SRW.SET_MAXROW. 13 – 70

SRW.UNKNOWN_USER_EXIT Stops report when user exit not found by SRW.USER_EXIT or SRW.USER_EXIT20. 13 – 71

SRW.USER_EXIT Calls the specified user exit with two arguments. 13 – 71

SRW.USER_EXIT20 Calls the specified user exit with five arguments. 13 – 73

SRW.USER_EXIT_FAILURE Stops report execution when a user exit fails. 13 – 73

Chapter Number and Name Description

Chapter 1, Executables Describes executables and their command line arguments.

Chapter 2, Defaulting Describes the defaulting mechanism of Oracle Reports.

Chapter 3, Menus Menus are described in the online help system.

Chapter 4, Report Properties Describes the report property sheet.

Chapter 5, Data Model Editor Describes the components of the Data Model editor.

Chapter 6, Data Model Properties Describes the property sheets of the following: – query 6 – 2 – link 6 – 8 – group 6 – 14 – database column 6 – 27 – summary column 6 – 27 – formula column 6 – 41 – placeholder column 6 – 42 – parameter 6 – 45

Chapter 7, Layout Editor Describes the components of the Layout Editor.

Chapter 8, Layout Properties Describes the property sheets of the following: – repeating frame 8 – 28 – frame 8 – 28 – field 8 – 41 – boilerplate 8 – 59 – anchor 8 – 62 – matrix 8 – 70 – Oracle Graphics 8 – 73 – user–defined button 8 – 80 – OLE2 object 8 – 84

Chapter 9, Parameter Form Editor Describes the components of the parameter form editor.

Chapter 10, Parameter Form Properties Describes the property sheets of parameter form fields and boilerplate.

Chapter 11, Previewer Describes the components of the Previewer.

Chapter 12, Object Navigator Describes the components of the Object Navigator.

Chapter 13, PL/SQL Interface Describes the usage of PL/SQL in Oracle Reports.

Chapter 14, User Exit Interface Describes how to create and implement user exits.

Chapter 15, Call Interface Describes the interface for calling Oracle Reports from 3GL programs.

Chapter 16, Integrating with Other Products Describes using Oracle Reports with other products.

Chapter 17, Performance and Tuning Describes tips for improving report performance.

Chapter 18, Storage Describes how Oracle Reports uses files and databases.

Chapter 19, Administration Describes how to administer Oracle Reports.

Reader’s Comment Form

Name of Document: Reports Reference ManualPart No. A32489–1

Oracle Corporation welcomes your comments and suggestions on the quality and usefulnessof this publication. Your input is an important part of the information used for revision.

• Did you find any errors?

• Is the information clearly presented?

• Do you need more information? If so, where?

• Are the examples correct? Do you need more examples?

• What features did you like most about this manual?

If you find any errors or have any other suggestions for improvement, please indicate the topic, chapter,and page number below:

Please send your comments to:

Oracle Reports Documentation ManagerOracle Corporation500 Oracle ParkwayRedwood City, CA 94065 U.S.A.Fax: (415) 506–7200

If you would like a reply, please give your name, address, and telephone number below:

Thank you for helping us improve our documentation.

��

A32489–1

��

��

Oracle Reports Reference Manual 2.5

Documents

Transcript of Oracle Reports Reference Manual 2.5