Oracle Reports Reference Manual 2.5

Reports Reference Manual
Release 2.5

Release 2.5
Part No. A324891
Oracle Reportst Reference Manual, Release 2.5 Part No. A324891, April 1995 Copyright E Oracle Corporation 1984, 1988, 1995 All rights reserved. Printed in the U.S.A. Contributing Author: Frank Rovitto Contributors: Per Brondum, Alex Hsieh, YuehHong Lin, Karen Denchfield Masterson, Ashok Natesan, Boris Protasov, Ingrid Snedecor, Gene Sohn, Atul Suklikar, Lori Ann White, Simon Wong This software was not developed for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It is the customers responsibility to take all appropriate measures to ensure the safe use of such applications if the programs are used for such purposes. This software/documentation contains proprietary information of Oracle Corporation; it is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software is prohibited. If this software/documentation is delivered to a U.S. Government Agency of the Department of Defense, then it is delivered with Restricted Rights and the following legend is applicable: Restricted Rights Legend Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of DFARS 252.2277013, 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 not within the Department of Defense, then it is delivered with Restricted Rights, as defined in FAR 52.22714, Rights in Data General, including Alternate III (June 1987). The information in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is errorfree. ORACLE, Pro*COBOL, Pro*FORTRAN, Pro*Pascal, Pro*PL/I, SQL*Connect, SQL*Net, SQL*Plus, and SQL*ReportWriter are registered trademarks of Oracle Corporation. Developer/2000, ORACLE7, Oracle Book, Oracle Forms, Oracle Graphics, Oracle Help, Oracle*Mail, Oracle Reports, PL/SQL, and Pro*C are trademarks of Oracle Corporation. All other products or company names are used for identification purposes only, and may be trademarks of their respective owners.
Read This First

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

audience Oracle Reports documentation and related information how to use this book how to contact Oracle about documentation and product comments
Read This First
Audience
The information in this manual is intended for application developers who want to create reports. Readers should have a working knowledge 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 several programming languages. Sometimes, knowledge of these other products is necessary. The following map is provided to help you determine any additional documentation you may need.
ii
Reports Reference Manual GUI Version
Oracle Reports Documentation
The following books are included in the Oracle Reports documentation set:

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, contains information 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 of Oracle Reports concepts as well as many example reports. Reports Reference Manual Version 2.5, Part No. A32489, contains detailed reference information about all aspects of Oracle Reports. It is intended primarily to answer specific questions that you might have about using Oracle Reports. Reports Messages and Codes Manual Version 2.5, Part No. A32490, contains all Oracle Reports messages with cause and action descriptions. Reports Runtime Manual Version 2.5, Part No. A32493, contains information for end users (i.e., those who only run reports). It contains a tutorial and reference information about the Oracle Reports runtime executable. Reports Migration Manual Version 2.5, Part No. A32491, contains all information that you need to convert SQL*ReportWriter Version 1.1 reports and printer definitions to Oracle Reports Version 2.5. The online help system consists of the Reports Reference Manual, Reports Messages and Codes Manual, and procedural information in online format.
Each Oracle Reports manual is also shipped as an Oracle Book document. For the names and locations of the document files, see your Developer/2000 Installation Guide.
Related Information
As an application designer using Oracle Reports Version 2.5, you may need to refer to some or all of the documents listed below. Please see the document in question for information on its specific purpose and usage.
Read This First
iii
Developer/2000 Installation Guide or System Release Bulletin. This document is different for each hardware/software platform. Ask your sales representative for the appropriate part number. ORACLE7 Server Documentation Set, Part No. 503070 ORACLE7 Server Documentation Set V7.1, Part No. A12383 Oracle Network Products Messages Manual, Part No. A16263 MultiProtocol Interchange Administrators Guide, Part No. A10157 PL/SQL Users Guide and Reference, Version 1.0, Part No. 800V1.0 PL/SQL Users Guide and Reference, Version 2.0, Part No. 80020 Programmers 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 Administrators Guide, Part No. A16264
How to Use this Book

This book provides comprehensive information about Oracle Reports presented in concise modules. Before you use this book, we recommend that you read the first three chapters of the Building Reports Manual.
Major Sections of this Book
The Reports Reference Manual consists of the following major sections, or parts: PART I PART II PART III PART IV PART V PART VI Executables Externals Integration Internals Administration Appendixes
iv
Notational Conventions
You should be familiar with the notational conventions listed in the following table. Convention File>New>Report Data/Selection:Repeat
Font Change
Explanation Indicates a selection of submenu item Report from the New submenu of the File menu. Indicates a selection of Repeat from the Data/Selection tab of a property sheet. Indicates text to be entered exactly as shown. Indicates command, column, parameter, field, boilerplate, and anchor names. Indicates table, menu, query, group, frame, and repeating frame names, as well as property sheet names. Indicates items within a menu, buttons, or tabs on a property sheet. 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 enclosed items must be entered. If the braces are surrounded by brackets, then all of the enclosed items are optional. Do not enter the curly braces. Is used to separate options within brackets and braces. You must enter one, and only one, of the options separated by the vertical bar. Do not enter the vertical bars. Indicates that the underlined text is the default.
UPPERCASE Initial Caps
Bold Italics [] {}
Read This First
Your Comments Are Welcome

We value and appreciate your comments as an Oracle user. As we write, revise, and evaluate our work, your opinions are the most important input we receive. At the back of this manual is a Readers Comment Form. We encourage you to use this form to tell us both what you like and dislike about this (or other) Oracle manuals. If the form is gone, or you would like to contact us, please use the following addresses and phone numbers. For documentation questions/comments, contact: Oracle Reports Documentation Manager Oracle Corporation 500 Oracle Parkway Box 659412 Redwood Shores, California 940655028 (415) 5067000 (415) 5067200 (fax)
For product questions/comments, contact: Oracle Reports Product Manager Oracle Corporation 500 Oracle Parkway Box 659412 Redwood Shores, California 940655028 (415) 5067000 (415) 5067200 (fax)
vi
Contents
PART I Chapter 1
EXECUTABLES Executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help on Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keyword Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Explicit Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Automatic Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remote Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R25CONV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R25RUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R25DES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXTERNALS Defaulting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Model Defaulting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Layout Defaulting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Defaulting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Defaulting For Each Layout Style . . . . . . . . . . . . . . . . . 21 22 24 24 26 11 12 13 13 13 14 16 17 17 17 18 19 1 17 1 35
PART II Chapter 2
Contents
vii
Tabular Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mailing Label Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form Letter Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Master/Detail Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Matrix Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global Layout Defaulting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rules About Summaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implicit Anchoring Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header/Body/Trailer Algorithm . . . . . . . . . . . . . . . . . . . . . . . Margin Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Print Condition Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header/Margin/Body/Trailer Algorithm . . . . . . . . . . . . . . . Parameter Form Defaulting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Defaulting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26 2 12 2 15 2 17 2 20 2 27 2 41 2 42 2 43 2 43 2 46 2 47 2 47 2 47 2 47
Chapter 3
Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1
Chapter 4
Report Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Tab of Report Property Sheet . . . . . . . . . . . . . . . . . . . . . . . . Direction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical Page Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Body Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Header Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Trailer Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Height . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Panel Print Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unit of Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Form Tab of Report Property Sheet . . . . . . . . . . . . . . . Form Height . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Number of Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Previewer Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Character Mode Tab of Report Property Sheet . . . . . . . . . . . . . . . Comment Tab of Report Property Sheet . . . . . . . . . . . . . . . . . . . . .
41 42 43 43 45 45 46 46 47 47 49 4 10 4 10 4 10 4 11 4 11 4 11 4 15
viii
Chapter 5
Data Model Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Painting Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tool Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Status Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PopUp Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Model Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Query Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Query Property Sheet . . . . . . . . . . . . . . . . . . . . . . . External Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SELECT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tables/Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comment Tab of Query Property Sheet . . . . . . . . . . . . . . . . . . . . . Link Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Child Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Child Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parent Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parent Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Group Property Sheet . . . . . . . . . . . . . . . . . . . . . . . Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comment Tab of Group Property Sheet . . . . . . . . . . . . . . . . . . . . . Common Column Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Column Property Sheets . . . . . . . . . . . . . . . . . . . . . Break Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Datatype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Read from File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Value If Null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51 52 53 53 53 55 55 57 57 61 62 62 63 64 64 65 65 67 68 68 6 12 6 12 6 12 6 13 6 13 6 13 6 14 6 15 6 15 6 15 6 16 6 17 6 17 6 17 6 18 6 20 6 21 6 22 6 23 6 24 6 25
Chapter 6
Contents
ix
Comment Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Column Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary Column Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Summary Column Property Sheet . . . . . . . . . . . . Compute At . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Product Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reset At . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formula Column Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Formula Column Property Sheet . . . . . . . . . . . . . . Formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Product Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Placeholder Column Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Placeholder Column Property Sheet . . . . . . . . . . . Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Parameter Property Sheet . . . . . . . . . . . . . . . . . . . . Datatype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initial Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data/Selection Tab of Parameter Property Sheet . . . . . . . . . . . . . Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restrict List to Predetermined Values . . . . . . . . . . . . . . . . . . . SELECT Statement/Static Values . . . . . . . . . . . . . . . . . . . . . . . Hide First Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comment Tab of Parameter Property Sheet . . . . . . . . . . . . . . . . . . Chapter 7 Layout Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Painting Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tool Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Status Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PopUp Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6 27 6 27 6 27 6 28 6 29 6 32 6 33 6 39 6 40 6 41 6 41 6 42 6 42 6 42 6 44 6 45 6 45 6 47 6 47 6 48 6 48 6 48 6 49 6 49 6 50 6 51 6 51 6 51 6 51 6 52 6 52 6 52 71 72 73 73 73 77 77 7 17 7 18
Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 20 Defining Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 20 Margins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 21
Chapter 8
Layout Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Layout Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . General Layout Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Horizontal Sizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keep with Anchoring Object . . . . . . . . . . . . . . . . . . . . . . . . . . . Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Break After . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Break Before . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Protect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Print Condition Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Print Condition Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vertical Sizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Codes Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . After . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comment Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Frame Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Repeating Frame Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Tab of Repeating Frame Property Sheet . . . . . . . . . . . . . . . Column Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Horizontal Spacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Records per Page . . . . . . . . . . . . . . . . . . . . . . . . . . . Minimum Widow Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . Print Direction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vertical Spacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Tab of Field Property Sheet . . . . . . . . . . . . . . . . . . . . . . . . . . Datatype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Minimum Widow Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Boilerplate Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
81 82 83 84 84 86 88 89 8 11 8 12 8 15 8 15 8 20 8 26 8 27 8 27 8 27 8 28 8 28 8 29 8 29 8 33 8 33 8 34 8 35 8 39 8 40 8 41 8 41 8 42 8 42 8 49 8 51 8 52 8 56 8 59
Contents
xi
Object Tab of Boilerplate Property Sheet . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Minimum Widow Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Anchor Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . % (Child) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . % (Parent) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Edge (Child) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Edge (Parent) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Horizontally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vertically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Matrix Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Matrix Property Sheet . . . . . . . . . . . . . . . . . . . . . . . Cross Product Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Horizontal Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vertical Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Graphics Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . O.G. Display Tab of Oracle Graphics Property Sheet . . . . . . . . . . Display Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Column (for Display Parameter) . . . . . . . . . . . . . . . . O.G. Query Tab of Oracle Graphics Property Sheet . . . . . . . . . . . Display Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Column (for Display Column) . . . . . . . . . . . . . . . . . . . Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UserDefined Button Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Tab of Button Property Sheet . . . . . . . . . . . . . . . . . . . . . . . . Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Text String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OLE2 Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 9 Parameter Form Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Runtime Parameter Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8 59 8 60 8 60 8 62 8 62 8 69 8 69 8 69 8 69 8 69 8 69 8 69 8 70 8 70 8 70 8 72 8 72 8 73 8 73 8 75 8 76 8 77 8 77 8 77 8 78 8 78 8 79 8 79 8 80 8 80 8 81 8 81 8 83 8 83 8 84 91 92 92 92 92 94
xii
Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Painting Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tool Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Status Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PopUp Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Form Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 10 Parameter Form Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Form Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . General Tab of Parameter Form Field Property Sheet . . . . . . . . . Datatype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comment Tab of Parameter Form Field Property Sheet . . . . . . . . Parameter Form Boilerplate Properties . . . . . . . . . . . . . . . . . . . . . General Tab of Parameter Form Boilerplate Property Sheet . . . . Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comment Tab of Parameter Form Boilerplate Property Sheet . . Previewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Character Mode Previewing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Multimedia Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing from the Previewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
95 95 95 96 96 97 97 98 98 99 10 1 10 2 10 2 10 2 10 2 10 3 10 3 10 4 10 4 10 4 10 5 10 5 11 1 11 2 11 3 11 3 11 3 11 4 11 4 11 5 11 6 11 6 11 6 11 7 11 8 11 8 11 10 11 10 11 11
Chapter 11
Contents
xiii
Chapter 12
Object Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Module List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Find Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PopUp Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Node Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Node Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hierarchical Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Navigation Within the Object Navigator . . . . . . . . . . . . . . . . . Navigation to Other Report Objects . . . . . . . . . . . . . . . . . . . . . INTEGRATION PL/SQL Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Types and Usage of PL/SQL Constructs . . . . . . . . . . . . . . . . . Value Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Nonvalue Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UserCreated Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Packaged Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exception Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL in Oracle Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . External PL/SQL Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . Attached Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Program Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Group Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Action Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12 1 12 2 12 2 12 3 12 3 12 3 12 3 12 3 12 4 12 5 12 5 12 7 12 10 12 15 12 15 12 17
PART III Chapter 13
13 1 13 2 13 2 13 2 13 4 13 6 13 6 13 8 13 11 13 11 13 11 13 14 13 15 13 16 13 16 13 17 13 22 13 23 13 25 13 27 13 28 13 32
xiv
Oracle Reports References in PL/SQL . . . . . . . . . . . . . . . . . . . . . . Bind References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Literal References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL Restrictions within Oracle Reports . . . . . . . . . . . . . . . . . Oracle Procedure Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compiling Single Program Units . . . . . . . . . . . . . . . . . . . . . . . Batchcompiling Program Units . . . . . . . . . . . . . . . . . . . . . . . . Compiler Error Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Procedure Builder Packages . . . . . . . . . . . . . . . . . . . . . . . . . The Developer/2000 PL/SQL Package: CDE_MM . . . . . . . . . . . CDE_MM.GET_REF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Oracle Reports PL/SQL Package: SRW . . . . . . . . . . . . . . . . . SRW.BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.CONTEXT_FAILURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.DO_SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.DO_SQL_FAILURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.GETERR_RUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.GET_PAGE_NUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.INTEGER_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.MAXROW_INERR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.MAXROW_UNSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.MESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.NULL_ARGUMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.PROGRAM_ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.RUN_REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.RUN_REPORT_BATCHNO . . . . . . . . . . . . . . . . . . . . . . . SRW.RUN_REPORT_FAILURE . . . . . . . . . . . . . . . . . . . . . . . . . SRW.SET_ATTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.SET_FIELD_CHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.SET_FIELD_DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.SET_FIELD_NUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.SET_MAXROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.TRACE_ADD_OPTION . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.TRACE_END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.TRACE_REM_OPTION . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.TRACE_START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.TRUNCATED_VALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.UNKNOWN_QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.UNKNOWN_USER_EXIT . . . . . . . . . . . . . . . . . . . . . . . .
13 32 13 32 13 33 13 33 13 35 13 37 13 37 13 37 13 38 13 39 13 40 13 40 13 41 13 41 13 42 13 43 13 46 13 47 13 47 13 48 13 48 13 49 13 50 13 51 13 52 13 53 13 54 13 57 13 57 13 58 13 64 13 64 13 65 13 66 13 67 13 67 13 68 13 68 13 70 13 70 13 71
Contents
xv
SRW.USER_EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 71 SRW.USER_EXIT20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 73 SRW.USER_EXIT_ FAILURE . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 73
Chapter 14
User Exit Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Types of User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORACLE Precompiler User Exits . . . . . . . . . . . . . . . . . . . . . . OCI (ORACLE Call Interface) User Exits . . . . . . . . . . . . . . . . NonORACLE User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . Steps to Build a User Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing a User Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax of a Passed User Exit Call . . . . . . . . . . . . . . . . . . . . . . . Raising Errors from the User Exit . . . . . . . . . . . . . . . . . . . . . . . Implementing User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying the Sample Source File . . . . . . . . . . . . . . . . . . . . . . Calling a User Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing a User Exit Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checking for and Defining User Exit Errors in PL/SQL . . . Packaged Oracle Reports User Exits . . . . . . . . . . . . . . . . . . . . . . . . Complete User Exit Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Exit Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example User Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14 1 14 2 14 2 14 3 14 3 14 3 14 3 14 4 14 5 14 8 14 9 14 9 14 9 14 10 14 10 14 13 14 16 14 21 14 22 14 22
Chapter 15
Call Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Steps to Build a Procedure Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure Call Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure Call Error Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure Call Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example Programs that Call R25RUN (RWCRUN) . . . . . . . . . . . Ada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C ................................................... COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FORTRAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pascal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/l . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15 1 15 2 15 2 15 3 15 4 15 4 15 5 15 6 15 6 15 7 15 7 15 8 15 8
xvi
Chapter 16
Integrating with Other Products . . . . . . . . . . . . . . . . . . . . . . . . . . ORACLE7 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting to ORACLE and Other Databases . . . . . . . . . . . . . . . SQL*Net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OLE2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Including OLE2 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activating OLE2 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing a Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executing a Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Passing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Passing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Exit Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Call Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16 1 16 2 16 2 16 2 16 4 16 4 16 4 16 5 16 5 16 6 16 6 16 7 16 7 16 9 16 10 16 10 16 10 16 10
PART IV
INTERNALS
Chapter 17
Performance and Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Reports Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL TRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Design Interface Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Design Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Model Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Number of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL Statements Faster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Reports Query Modifications . . . . . . . . . . . . . . . . . . . . Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SRW.DO_SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CDE_MM.GET_REF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Rows and Group Filters . . . . . . . . . . . . . . . . . . . . . Unused Data Model Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . Break Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multiple Layouts, One Source . . . . . . . . . . . . . . . . . . . . . . . . . . Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17 1 17 2 17 2 17 2 17 3 17 4 17 4 17 5 17 5 17 6 17 6 17 7 17 7 17 7 17 8 17 8 17 9 17 9 17 9
Contents
xvii
Layout Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unused Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transparent Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sizing for NonGraphical Objects . . . . . . . . . . . . . . . . . . . . . . Sizing for Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . Reduce Image Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Word Wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formatting Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Total Number of Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Graphics Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL Versus User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PL/SQL Versus SRW.DO_SQL for DML . . . . . . . . . . . . . . . . . Stored Procedures Versus Local PL/SQL . . . . . . . . . . . . . . . . Local PL/SQL Versus External PL/SQL Libraries . . . . . . . . . SRW.SET_ATTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execution Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Previewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OperatingSystem Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client/Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 18 Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Reports File Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preferences Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Important Files Shipped with Oracle Reports . . . . . . . . . . . . . . . . Executable Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Demo Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Definition and Driver Files . . . . . . . . . . . . . . . . . . . . . . Terminal Definition Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Font Mapping File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Temporary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Security and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FileSearching Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer and Terminal Definitions . . . . . . . . . . . . . . . . . . . . . . . Icon Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Reports Environment Variables . . . . . . . . . . . . . . . . . . . . . .
17 11 17 11 17 12 17 12 17 12 17 12 17 12 17 12 17 13 17 13 17 13 17 13 17 14 17 14 17 14 17 15 17 15 17 15 17 15 17 17 17 18 17 18 17 19 17 19 18 1 18 2 18 5 18 5 18 6 18 6 18 6 18 6 18 7 18 7 18 7 18 8 18 9 18 9 18 10 18 10 18 10
xviii
Database Table Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Reports Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Reports specific Tables . . . . . . . . . . . . . . . . . . . . . . . . . Integrated Oracle Product Tables and Other Objects . . . . . . . . . . Establishing Database Security and Restrictions . . . . . . . . . . . . . Controlling Access to Oracle Reports . . . . . . . . . . . . . . . . . . . Controlling Access to Other Users Modules . . . . . . . . . . . . . Database Storage Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory and Disk Space Requirements . . . . . . . . . . . . . . . . . . . . .
18 12 18 12 18 13 18 27 18 31 18 31 18 31 18 31 18 32
PART V
ADMINISTRATION
Chapter 19
Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using SQL Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL Script Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Granting User Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Revoking User Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrading from Previous Versions of Oracle Reports . . . . . . . . . Dropping Version 1.1 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving Reports Between the File System and the Database and Viceversa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Documenting Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Which Files Are Being Used . . . . . . . . . . . . . . . . . . . Files You Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files Created By Oracle Reports . . . . . . . . . . . . . . . . . . . . . . . .
19 1 19 2 19 2 19 3 19 4 19 4 19 5 19 5 19 5 19 5 19 6 19 6 19 6 19 7
PART VI
APPENDIXES
Appendix A
Environment and GUI Differences . . . . . . . . . . . . . . . . . . . . . . . . Environment and GUI Differences Overview . . . . . . . . . . . . . . . . Environment Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GUI Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Designing Reports for Character Mode . . . . . . . . . . . . . . . . . . . . . Report Conversion Across GUIs . . . . . . . . . . . . . . . . . . . . . . . . . . .
A1 A2 A2 A2 A3 A4
Contents
xix
Appendix B
Printer and Terminal Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . Purpose of Printer Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Packaged Printer Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating or Modifying Printer Definitions . . . . . . . . . . . . . . . . . . . Printer Definition File Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Definition Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Definition Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing Printer Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . Purpose of Terminal Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . Packaged Terminal Resource Files . . . . . . . . . . . . . . . . . . . . . . . . . . Creating or Modifying Terminal Resources . . . . . . . . . . . . . . . . . . Modifying Key Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying Terminal Definitions . . . . . . . . . . . . . . . . . . . . . . . . Terminal Definition Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing Terminal Resource Files . . . . . . . . . . . . . . . . . . . . . . . .
B1 B2 B2 B2 B3 B3 B3 B8 B9 B 13 B 14 B 14 B 15 B 17 B 19 B 21 B 21
Appendix C
National Language Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition and Purpose of NLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying NLS_LANG, DEV_NLS_LANG, and USER_NLS_LANG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overriding NLS Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using ALTER SESSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Date and Number Formats . . . . . . . . . . . . . . . . . . . . . . . Using NLS Parameters/Functions in SQL Functions . . . . . . Using CONVERT to Convert Data . . . . . . . . . . . . . . . . . . . . . . Using NLSSORT to Sort Character Data . . . . . . . . . . . . . . . . . Translating Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Definitions and NLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bidirectional Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C1 C2 C2 C3 C3 C4 C5 C5 C5 C7 C8 C8
Appendix D
Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Module Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Model Object Naming Conventions . . . . . . . . . . . . . . . . . . . . Layout Object Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . Parameter Form Object Naming Conventions . . . . . . . . . . . . . . . .
D1 D2 D2 D2 D2 D3 D3
xx
Appendix E
SQL Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Tables and Columns Dialog Box . . . . . . . . . . . . . . . . . . Using Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inserting Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reviewing SELECT Statement Errors . . . . . . . . . . . . . . . . . . . . . . . Referencing Columns and Parameters . . . . . . . . . . . . . . . . . . . . . . Bind References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lexical References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using DML or DDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E1 E2 E2 E2 E3 E3 E4 E5 E9
Appendix F
Pattern and Color Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pattern Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Color Palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Color Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplemental Color Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . Glossary Index
F1 F2 F4 F4 F5
Contents
xxi
xxii
PART
Executables
CHAPTER
Executables
E 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
Executables
11
Executable Overview
The names and purposes of the four Oracle Reports executables are listed below: R25CONV Converts your report definitions from one storage format (i.e., database, .rdf file, .rep file, .rex file) to another, or from one unit of measurement (i.e., character, centimeter, inch, point) to another. For more information on file formats, see Oracle Reports File Storage on page 18 2. If the conversion is run in interactive mode, the Convert dialog box will appear. If the conversion is run in batch mode, the Convert dialog box will not appear. Converts your SQL*ReportWriter Version 1.1 reports and printer definition files to Oracle Reports. For more information on this executable, see the Reports Migration Manual. Runs your report in either batch or interactive mode. If the report is run in interactive mode, the root window from which you can run reports appears. If the report is run in batch mode, this window will not appear. If you wish to enter values for runtime parameters, but you want to run a report in batch mode, either enter the parameters on the command line or create a command file. R25DES Invokes the designer (that is, the root window and painters in which you build and maintain reports).
R25MREP
R25RUN
12
Executable Names
Letters are appended to the executable names listed above to indicate if the GUI mode of the executable is something other than the native GUI. For example, a indicates a GUI mode of Apple MacIntosh and m a GUI mode of Motif. (No added letter means the executables GUI mode is the native GUI.) In addition, an x is used to indicate if user exits are linked to the executable. For more information, see the Developer/2000 Installation Guide for your operating 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 Reports executable, you can enter executable arguments that govern how the executable behaves. If you invoke the executable via command line, you enter the executable arguments on the command line after the executable 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 for the executable arguments or you may need to use the Runtime Settings or Runtime Parameters tab on the Tools Options dialog box (Tools>Tools Options) for executable arguments. For more information, see the Developer/2000 Installation Guide for your operating system. The syntax and executable arguments for R25CONV, R25RUN, and R25DES are described in the sections that follow.
Help on Command Line Options

If you are on a command line, you can view an executables command line options by typing the executables name, then a space and a question mark, and then pressing Return. For example, r25conv ?.
Executables
13
Note: Some operating systems require quotes around the question mark. For more information, see the Developer/2000 Installation Guide for your operating system. For example, to view the command line options for the R25DES executable in the UNIX C shell, you need to enter r25des ?.
Executable Syntax Rules

When you enter an executable on the command line, it generally has the 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 for the executable arguments or you may need to use the Runtime Settings or Runtime Parameters tab on the Tools Options dialog box (Tools>Tools Options) for executable arguments. For more information, see the Developer/2000 Installation Guide for your operating system. Each keyword=value is called an executable argument. Because it would be cumbersome to enter the keywords each time, they may be omitted. For more information on keywords, see Keyword Usage on page 1 6. The following syntax rules apply to all Oracle Reports executables: Rules: 1. 2. 3. No spaces should be placed before or after the equal sign of an argument. Separate arguments with one or more spaces; do not use commas to separate arguments. Values of arguments may be in single or double quotes. The effect of single or double quotes is operating systemspecific. For more information, see the Developer/2000 Installation Guide for your operating system.
14
4.
The keyword= part of all arguments is not case sensitive. The value portion of the SOURCE, DEST, CMDFILE, TERM, DESNAME, DESFORMAT, DNAME, and SNAME arguments may be case sensitive, depending on your operating system. The value portion of all other arguments is not case sensitive. For more information, see the Developer/2000 Installation Guide for your operating system. Keywords may sometimes be omitted. For more information on keywords, see Keyword Usage on page 1 6. To give an argument an empty string as its value, you enter keyword= or keyword=. If you enter an empty string in this way, the Runtime Parameter Form will display an empty string for the argument instead of its Initial Value. Full pathnames are supported for all file references (e.g., desname=/revenues/q1/nwsales). If you do not specify the full path, Oracle Reports will use its file path search order to find the file. For more information about file path search order, see File Searching Method on page 18 9. Note: To help ensure the portability of your reports, you can use the Oracle Reportsspecific environment variable REPORTS25_PATH for referencing reports, external queries, external PL/SQL libraries, text files, graphics, etc. REPORTS25_PATH enables you to access files stored outside of Oracle Reports without hardcoding directory paths into your report. For more information on these variables, see File Searching Method on page 18 9. For more information on how to set these environment variables, see the Developer/2000 Installation Guide for your operating system.
5. 6.
7.
8.
Values entered from the Runtime Parameter Form override those entered on the command line. For example, if you specified R25RUN on the command line with COPIES equal to 1, but, in the Runtime Parameter Form, specified COPIES equal to 2, then two copies of the report would be generated. Similarly, values entered on the command line override values specified in command files. For example, suppose that you specify R25RUN from the command line with COPIES equal to 1 and CMDFILE equal to RUNONE (a command file). In RUNONE, COPIES is set to 2 by a R25RUN command. Only one copy of the report would be generated in this case.
Executables
15
You can specify values for DESTYPE, DESNAME, DESFORMAT, ORIENTATION, and COPIES in a number of different places in Oracle Reports. The following list shows the order of precedence for the places where you specify these values. The first item in the list takes precedence over all others, the second takes precedence over 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 the arguments are entered in the order specified by the syntax. If you skip one of the arguments, you must use keywords after the skipped argument. If an executable has four arguments and you want to specify only the first, second, and fourth arguments, you can specify the first two without 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 all subsequent arguments use keywords, too. Once you have entered a keyword, the rest of the arguments on the command line must also use keywords. Examples (Invalid): 2. Below are examples of invalid command line sequences:
r25des paramform=no scott/tiger destype=mail desname=rmiller
16
The sequence above is invalid because scott/tiger has been typed out of order and without the USERID keyword.
r25des scott/tiger mail rmiller no
The sequence above is invalid because the value NO has been entered out of order and without the PARAMFORM keyword.
Database Login
When invoking the R25CONV, R25RUN, and R25DES executables or using the R25DES designer, you can connect to a database in the following ways:

explicit login 1 7 automatic login 1 7 remote login 1 8
Explicit Login
You explicitly login to the database by using the USERID keyword for R25CONV, R25RUN, and R25DES or by selecting File>Connect in the R25DES designer and R25RUN runtime engine. The USERID keyword is described below. Is your ORACLE username and password with an optional SQL*Net address (not the SYSTEM account). If you omit your password, a logon screen is provided. For more information about the optional SQL*Net address, see Remote Login on page 1 8. For more information about automatic login, see Automatic Login on page 1 7. Options: The logon definition must be in one of the following forms and cannot exceed 512 bytes in length:
username username@node username/password username/password@node
USERID
Automatic Login
The ORACLE automatic login feature allows you to connect to Oracle Reports without explicitly stating a username and password. You can use the automatic login feature with all Oracle Reports executables that have the USERID keyword. For more information on how to employ this feature, see the ORACLE7 Server Administrators Guide.
Executables
17
When you connect in this way, ORACLE uses a default logon (e.g., OPS$) to associate your ORACLE username to your operating system username. To invoke an automatic login procedure, do one of the following:

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 press the Return key twice when the logon form appears. Note: When logging on in this way, you can access a remote login by typing @node after the slash.
For more information on default logons, see the ORACLE7 Server SQL Language Reference Manual.
Remote Login
Through SQL*Net, you can specify a remote database (i.e., one not on your computer). When you use the remote login feature, the remote database is transparent to youOracle Reports behaves the same whether it is accessing a node across the country or accessing the database on your computer. Syntax
@driver_name:node_name[:db_name]
Arguments
driver_name
Is the driver you want to use to access the remote database (e.g., @t:, @d:). The default setting is system dependent. Is the remote network node that contains the target database (e.g., london). Is the name of the database (e.g., :rds). Unless you specify a database, you will log in to the default database on the specified node.
node_name db_name
For more information on SQL*Net, see the SQL*Net Users Guide. Examples: 1. To run the order_entry report on the default database of the london node, you might type the following:
r25run order_entry scott/tiger@D:london
2.
To run the ORDER_ENTRY report on a specific database (rds) of the LONDON node, you might type the following:
r25run order_entry scott/tiger@D:london:rds
18
Rules: 1. To perform a remote connect, you must have an account on the remote computer node where the target database resides.
R25CONV
R25CONV enables you to convert one or more report definitions or PL/SQL libraries from one storage format to another. Syntax:
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
Description:
Use the R25CONV executable to convert one or more report definitions or PL/SQL libraries from one storage format to another. (This executable 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 a database report convert a report stored in a .rex file into a database report, .rdf file, or .rep file
Executables
19
The following PL/SQL library conversions can be performed using R25CONV:

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 File Storage 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 by selecting File>Administration>Convert.... Rules: 1. In some cases, Convert will automatically compile the reports PL/SQL as part of the conversion process. Provided that your conversion Destination is not a .rex file, PL/SQL is automatically compiled under the following conditions:
You try to create a .rep file using Convert. If there are compile errors, an error message is displayed and the .rep file is not created. You use a .rex file as the Source report. If there are compile errors, a warning is displayed, but the conversion continues. You use a report that was created on another platform as the Source report. If there are compile errors, a warning is displayed, but the conversion continues.
In all other situations, you must compile the reports PL/SQL yourself (e.g., File>Compile). Note: To avoid compilation problems during conversion, compile the Source reports PL/SQL using File>Compile before you try to convert it. 2. USERID Fonts are mapped when a report is opened by Oracle Reports runtime or designer. Fonts are not mapped during the conversion.
Is your database login. For more information, see Database Login on page 1 7.
1 10
Rules: 1. STYPE The USERID keyword is only needed if STYPE or DTYPE is database.
Is the format of the report(s) or libraries to be converted. Options: database means that the source report(s) are stored in ORACLE. plldb means that the source PL/SQL libraries are stored in the database. pldfile means that the source PL/SQL libraries are stored in files in ASCII format. pllfile means that the source PL/SQL libaries are stored in files containing source code and Pcode. rdffile means that the source report(s) are stored in one or more report definition files (files with an extension of .rdf). rexfile means that the source report(s) are stored in one or more text files (files with an extension of .rex). Default: database
SOURCE
Is the report/library or list of reports/libraries to be converted. R25CONV requires that you specify a source report or library. Options: Any valid report/library name or filename (e.g.,
qanda).
A list of valid report/library names or filenames enclosed by parentheses with a comma separating the names (e.g., (qanda,test,dmast)).
Note: SQL wildcard characters (% and _) may be used for reports or libraries that are stored in the database. For example, R% would fetch all reports stored in the database that begin with R. All reports that match will be converted. Rules: 1. A list of report/library names or filenames must be enclosed in parentheses with commas separating the names. For example:
(qanda,test,dmast) (qanda, test, dmast)
Executables
1 11
2. 3.
Wildcard characters are invalid for reports/libraries stored in files (i.e., with extensions of .rdf, .rep, .rex, .pld, .pll). The argument(s) for this keyword may be operating systemspecific. For more information, see the Developer/2000 Installation Guide for your operating system. If you are converting reports/libraries stored in ORACLE and are using systemowned Oracle Reports tables, you may list reports/libraries of other users, for example:
SOURCE=(sday.qanda,dsmith.test,dmast.sal)
4.
5.
If you are using userowned Oracle Reports tables, reports/libraries from multiple users must be converted for each user individually. You must have created the reports/libraries, or have been granted access to the ones you did not create, in order to convert them. If no userid is prefixed to the report/library name, the userid is assumed to be the current user. If you are converting from database to file and the database report/library name is too long to be a filename, Oracle Reports prompts you to provide a filename of the correct length for your operating system.
6.
7.
DTYPE
Is the format to which to convert the reports or libraries . Options: database means that the converted reports will be stored in ORACLE. plldb means that the converted PL/SQL libraries will be stored in the database. pldfile means that the converted PL/SQL libraries will be stored in files in ASCII format. pllfile means that the converted PL/SQL libaries will be stored in files containing source code and Pcode. rdffile means that the converted reports will be stored in one or more report definition files (files with an extension of .rdf). repfile means that the converted reports will be stored in one or more binary runfiles (files with an extension of .rep).
1 12
rexfile means that the converted reports will be stored in one or more text files (files with an extension of .rex). Default: Rules: 1. When you try to create a .rep file using R25CONV, the source reports PL/SQL is automatically compiled. If there are compile errors, an error message is displayed and the .rep file is not created. To avoid this problem, make sure you compile the source reports PL/SQL using File>Compile before you try to create a .rep file. DEST Is the name(s) of the converted reports or libraries, if they are stored in the database, or the names of the files. Options: Any valid report/library name or filename (e.g.,
qanda).
rexfile
A list of valid report/library names or filenames enclosed by parentheses with a comma separating the names (e.g., (qanda,test,dmast)). Default: If the DEST keyword is not specified, R25CONV uses the following default names:

If DTYPE is database or plldb, then DEST is SOURCE. If DTYPE is pldfile, then DEST is SOURCE with the .pld extension. If DTYPE is pllfile, then DEST is SOURCE with the .pll file extension. If DTYPE is rdffile, then DEST is SOURCE with the .rdf extension. If DTYPE is repfile, the DEST is SOURCE with the .rep extension. If DTYPE is rexfile, then DEST is expdat.rex.
Rules: 1. A list of report/library names or filenames must be enclosed in parentheses with commas separating the names. For example:
(qanda,test,dmast) (qanda, test, dmast)
Executables
1 13
2.
If you have more destination names than there are source names, the extra destination names are ignored. If you have fewer destination names than there are source names, default names will be used after the destination names run out. The argument(s) for this keyword may be operating systemspecific. For more information, see the Developer/2000 Installation Guide for your operating system.
3.
CMDFILE
Is a file that contains arguments for the R25CONV command. This option enables you to convert a report/library without having to specify a large number of arguments each time you invoke R25CONV. Options: Rules: 1. 2. 3. A command file may reference another command file. Command file syntax for R25CONV arguments is identical to that used on the command line. Values entered on the command line override values specified in command files. For example, suppose that you specify R25RUN from the command line with COPIES equal to 1 and CMDFILE equal to RUNONE (a command file). In RUNONE, COPIES is set to 2. Only one copy of the report would be generated in this case. For more information, see Command Line Syntax Rules on page 1 4. The argument(s) for this keyword may be operating systemspecific. For more information, see the Developer/2000 Installation Guide for your operating system. Any valid command file.
4.
LOGFILE
Is the name of the file to which status and error output is sent. Options: Default: Any valid filename. dfltrep.log in the current directory.
OVERWRITE
Is whether to overwrite existing files or database objects with the converted files or objects. Options: YES means automatically overwrite any existing files or database objects of the same name. NO means not to convert reports if there are existing files or database objects of the same name and display a warning message.
1 14
PROMPT means to prompt you before overwriting any existing or database objects. Default: BATCH NO
Suppresses all terminal input and output, in order to convert reports/libraries without user intervention. Options: YES suppresses all terminal input and output. NO allows special terminal input and output. The Convert dialog box is displayed and, when you accept the dialog box, the conversion is performed. Default: NO
DUNIT
Is the destination unit of measurement to which the report should be converted. If specified, DUNIT must differ from the SOURCE reports unit of measurement. If left blank, the SOURCE reports unit of measurement is used as the DEST reports unit of measurement. Options: centimeter means that the converted reports will initially use centimeters as the unit of measurement. character means that the converted reports will initially use characters as the unit of measurement. inch means that the converted reports will initially use inches as the unit of measurement. point means that the converted reports will initially use points as the unit of measurement. Default: Blank
PAGESIZE
Is the size of a logical page for the converted reports in terms of destination unit of measurement (specified using the DUNIT keyword). Options: Default: Any valid value in the unit of measurement and of the form width x height. For bitmap, 8.5 x 11 inches. For character mode, 80 x 66 characters. If the report was designed for character mode and is being run or converted on bitmap, the following formula is used to determine page 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 bitmapped page size would be: (8.5 * 80)/80 x (11 * 20)/66 = 8.5 x 3.33.
Executables
1 15
Rules: 1. FORMSIZE For noncharacter DUNITs, you can use a decimal to specify fractions (e.g., 8.5 x 11).
Is the size of the Runtime Parameter Form for the converted report in terms of destination unit of measurement (specified using the DUNIT keyword). Options: Rules: 1. For noncharacter DUNITs, you can use a decimal to specify fractions (e.g., 8.5 x 11). Any valid value in the unit of measurement and of the form width x height.
1 16
R25RUN
R25RUN runs a report (i.e., .rdf or .rep file) interactively or in batch. Syntax:
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}
Executables
1 17
Description:
Use the R25RUN executable to execute a report from the operating system. With R25RUN, you can also execute a report in batch mode, that is, without user intervention. You must have created a runfile before 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 before running 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 any PL/SQL is uncompiled when you run the report, you will get an error and the report will not execute. Use File>Compile... to compile all PL/SQL in an .rdf file beforehand. There are two versions of R25RUN:

The charactermode executable is for users who are running reports from charactermode machines (e.g., VT220). The GUI executable is for users who are running reports from bitmapped machines (e.g., a PC running Windows).
It is important to note that with either executable, you can run charactermode or bitmapped reports. The only limiting factor is the output device (e.g., you could not run a bitmapped report to the screen of a vt220). MODULE/REPORT Is the report to run. (REPORT is allowed for backward compatibility.) Options: 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 with extension .rep, then extension .rdf, and then no extension. Oracle Reports will use its file path search order to find the file. For more information about file path search order, see File Searching Method on page 18 9.
Rules: 1. If you specify a runfile using MODULE/REPORT, the R25RUN root window is not raised and File>Run, File>Print, and Edit>Runtime Settings are disabled. (This behavior provides seamless entry into R25RUN from other applications.) If you do not specify a runfile using MODULE/REPORT and you specify BATCH=NO, a window is opened that enables you to run reports interactively.
1 18
2.
If you run a charactermode report via bitmapped R25RUN, Oracle Reports displays a warning, then runs the report using a page size of 8.5 x 11 and a form size of 7 x 6.
USERID PARAMFORM
Is your database login. For more information, see Database Login on page 1 7. Displays the Runtime Parameter Form when you execute a report. For more information on the Runtime Parameter Form, see Runtime Parameter Form on page 9 2. Options: YES means to display the Form. NO means to suppress the Form. Default: Rules: 1.
PARAMFORM=YES is incompatible with BATCH=YES because it is not
YES
meaningful to have the Runtime Parameter Form appear in batch mode. CMDFILE Is a file that contains arguments for the R25RUN command. This option enables you to run a report without having to specify a large number of arguments each time you invoke R25RUN. Options: Rules: 1. 2. 3. A command file may reference another command file. Command file syntax for R25RUN arguments is identical to that used on the command line. Values entered on the command line override values specified in command files. For example, suppose that you specify R25RUN from the command line with COPIES equal to 1 and CMDFILE equal to RUNONE (a command file). In RUNONE, COPIES is set to 2. Only one copy of the report would be generated in this case. For more information, see Command Line Syntax Rules on page 1 4. The argument(s) for this keyword may be operating systemspecific. For more information, see the Developer/2000 Installation Guide for your operating system. Any valid command file.
4.
Executables
1 19
TERM
Is the terminal definition file that describes the terminal from which you are using R25RUN. In turn, this file determines which keys correspond to which Oracle Reports functions. TERM is useful for the Runtime Parameter Form and Previewer only. This keyword is only used in character mode. Options: Default: Rules: 1. The argument(s) for this keyword may be case sensitive, depending on your operating system. For more information, see the Developer/2000 Installation Guide for your operating system. Any valid terminal definition file. Installation dependent. (See your System Administrator for a compatible definition.)
ARRAYSIZE
Is the size of the array in kilobytes for use with ORACLE array processing. Generally, the larger the arraysize, the faster the report will run. Options: A number from 1 through 9,999. This means that Oracle Reports can use this number of kilobytes of memory per query in your report. The default arraysize is 10K. For details about the ORACLE array processing, see the ORACLE7 Server Administrators Guide.
Default:
DESTYPE
Is the type of destination device that will receive the report output. Options: Screen routes the output to the Previewer for interactive viewing. This value is valid only when the BATCH=NO. File saves the output to a file named in DESNAME (the next keyword discussed). Printer routes the output to the printer named in DESNAME (the next keyword discussed). Preview also routes the output to the Previewer for interactive viewing. However, Preview causes the output to be formatted as PostScript output. The Previewer will use DESNAME to determine which printers fonts to use to display the output.
1 20
Mail sends the output to the Oracle*Mail users specified in DESNAME. If your system does not have Oracle*Mail installed, or is not an Oracle*Mail node, an error will be returned. The report can be sent as part of the message or as an attached file. For more information, see Integrating with Other Products on page 16 1. Sysout sends the output to your operating systems default output device. This value is valid only when BATCH=YES. Default: Taken from the Initial Value field of the Parameter property sheet for the DESTYPE parameter. For more 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 box will appear after you accept the Runtime Parameter Form, unless it is suppressed. After you accept the Print Job dialog box, the report is executed and the output is sent to the printer (specified in File>Choose Printer), file, or mail id. If DESTYPE is something other than Printer, File, or Mail, then the report is executed after you accept the Runtime Parameter Form. The appearance of the dialog box varies between operating systems. For more information, see the Developer/2000 Installation Guide for your operating system. 2. In some cases, this parameter may be overridden by your operating system. For more information, see the Developer/2000 Installation Guide for your operating system. All DESTYPE values are not supported on every operating system. For more information, see the Developer/2000 Installation Guide for your operating system.
3.
DESNAME
Is the name of the file, printer, or Oracle*Mail username (or distribution list) to which the report output will be sent. To send the report output to an Oracle*Mail user, specify the username as you do in Oracle*Mail. You can specify multiple usernames by enclosing the names in parentheses and separating them by commas (e.g., (<name>, <name>, . . .<name>)).
Executables
1 21
Options:
Any valid filename, printer name, or Oracle*Mail userid not to exceed 1K in length. For printer names, you can optionally specify a port. For example:
DESNAME=<printer_name>,LPT1: DESNAME=<printer_name>,FILE:
Default:
Taken from the Initial Value field of the Parameter property sheet for the DESNAME parameter. If DESTYPE=FILE and DESNAME is an empty string, it defaults to <reportname>.lis at runtime. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Rules: 1. 2. 3. This keyword is ignored if DESTYPE is Screen or Sysout. If DESTYPE is Preview, Oracle Reports uses DESNAME to determine which printers fonts to use to display the output. The argument(s) for this keyword may be case sensitive, depending on your operating system. For more information, see the Developer/2000 Installation Guide for your operating system. In some cases, this parameter may be overridden by your operating system. For more information, see the Developer/2000 Installation Guide for your operating system.
4.
DESFORMAT
In bitmapped environments, specifies the printer driver to be used when DESTYPE is File. In charactermode environments, specifies the characteristics of the printer named in DESNAME. Options: Any valid destination format not to exceed 1K in length. Examples of valid values for this keyword are hpl, hplwide, dec, decwide, decland, dec180, dflt, wide, etc. Ask your System Administrator for a list of valid destination formats. Taken from the Initial Value field of the Parameter property sheet for the DESFORMAT parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45. For bitmapped Oracle Reports, if DESFORMAT is blank or dflt, then the current printer driver selected in Choose Printer is used. If nothing has been selected in Choose Printer, then Postscript is used by default.
Default:
1 22
Rules: 1. 2. This keyword is ignored if DESTYPE is Screen or Sysout. The argument(s) for this keyword may be case sensitive, depending on your operating system. For more information, see the Developer/2000 Installation Guide for your operating system.
COPIES
Is the number of copies of the report to print. Options: Default: Any valid integer from 1 through 9,999. Taken from the Initial Value field of the Parameter property sheet for the COPIES parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Rules: 1. 2. CURRENCY This keyword is ignored if DESTYPE is not Printer. If COPIES is left blank on the Runtime Parameter Form, it defaults to one.
Is the currency character to be used in number formats. Options: Default: Any valid alphanumeric string not to exceed 1K in length. The default for ORACLE is determined by the ORACLE National Language Support facilities. You can also set a default of up to four characters in the Initial Value field of the Parameter property sheet for the CURRENCY parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45. Rules: 1. A CURRENCY value entered on the Runtime Parameter Form will override any CURRENCY value entered on the command line.
THOUSANDS
Is the thousands character to be used in number formats. Options: Any valid alphanumeric character.
Executables
1 23
Default:
The default for ORACLE is determined by the ORACLE National Language Support facilities. You can also set a default in the Initial Value field of the Parameter property sheet for the THOUSANDS parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Rules: 1. A THOUSANDS value entered on the Runtime Parameter Form will override any THOUSANDS value entered on the command line.
DECIMAL
Is the decimal character to be used in number formats. Options: Default: Any valid alphanumeric character. The default for ORACLE is determined by the ORACLE National Language Support facilities. You can also set a default in the Initial Value field of the Parameter property sheet for the DECIMAL parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Rules: 1. READONLY A DECIMAL value entered on the Runtime Parameter Form will override any DECIMAL value entered on the command line.
Requests read consistency across multiple queries in a report. When accessing data from ORACLE, read consistency is accomplished by a SET TRANSACTION READ ONLY statement (refer to your ORACLE7 Server SQL Language Reference Manual for more information on SET TRANSACTION READ ONLY). Options: YES requests read consistency. NO means do not provide read consistency. Default: 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). NO
1 24
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 via the READONLY argument or setting). 1.7 The report is executed and the Between Page trigger fires for each page except the last one. (Note that data can be fetched at any time while the report is being formatted.) Note: COMMITs can occur during this time due to any of the followinguser exit with DDL, SRW.DO_SQL with DDL, or if ONFAILURE=COMMIT, and the report fails. 1.8 COMMIT is executed (if READONLY is specified) to end the transaction. 1.9 After Report trigger is fired. 1.10COMMIT/ROLLBACK/NOACTION is executed based on what was specified via the ONSUCCESS argument or setting. Caution: In steps 1.4 through 1.8, avoid DDL statements that would modify the tables on which the report is based. Step 1.3 takes a snapshot of the tables and the snapshot must remain valid throughout the execution of the report. In steps 1.6 through 1.8, avoid DML statements that would modify the contents of the tables on which the report is based. Queries may be executed in any order, which makes DML statements unreliable (unless performed on tables not used by the report). Caution: If you specify READONLY, you should avoid DDL altogether. When you execute a DDL statement (e.g., via SRW.DO_SQL or a user exit), a COMMIT is automatically issued. If you are using READONLY, this will prematurely end the transaction begun by SET TRANSACTION READONLY. 2. This keyword is only useful for reports using multiple queries, because ORACLE automatically provides read consistency, without locking, for single query reports.
LOGFILE
Is the name of the file to which File>Print Screen output is sent. If the specified file already exists, output will be appended to it. This keyword is only used in character mode. Options: Default: Any valid filename. dfltrep.log in the current directory.
Executables
1 25
BUFFERS
Is the size of the virtual memory cache in kilobytes. Note: You should tune this setting to ensure that you have enough space to run your reports, but not so much that you are using too much of your systems resources. Options: A number from 1 through 9,999. For some operating systems, the upper limit may be lower. For more information, see the Developer/2000 Installation Guide for your operating system. 640K
Default: Rules: 1. BATCH
If this setting is changed in the middle of your session, the change does not take effect until the next time the report is run.
Suppresses all terminal input and output, in order to run reports without user intervention. BATCH=YES enables you to run the report without bringing up the R25RUN interface. To run reports in the background, see BACKGROUND on page 1 31. Options: YES suppresses all terminal input and output. NO allows special terminal input and output. Default: Rules: 1. 2. 3. If BATCH=YES, error messages are sent to Sysout. For more information on Sysout, see DESNAME on page 1 21. If BATCH=YES, PARAMFORM=YES is invalid because it is not meaningful to have the Runtime Parameter Form appear in batch mode. When BATCH=NO and you are using the charactermode R25RUN, bitmapped reports cannot be run. (It is not possible to run a bitmapped report to the screen of a charactermode device.) When BATCH=YES, MODE=BITMAP, and you are using the charactermode R25RUN, you cannot run a charactermode report. NO
4.
1 26
PAGESIZE
Is the dimensions of the physical page (i.e., the size of the page that the printer outputs). Options: Any valid page dimensions of the form: page width x page height, where page width and page height are zero or more. The maximum width/height depends upon the unit of measurement. For inches, the maximum width/height is 512 inches. For centimeters, it is 1312 centimeters. For picas, it is 36,864 picas. Note that the page must be large enough to contain the report. For example, if a frame in a report expands to a size larger than the page dimensions, the report will not run. Default: For bitmap, 8.5 x 11 inches. For character mode, 80 x 66 characters. If the report was designed for character mode and is being run or converted on bitmap, the following formula is used to determine page 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 bitmapped page size would be: (8.5 * 80)/80 x (11 * 20)/66 = 8.5 x 3.33.
Rules: Caution: On some printers the printable area of the physical page is restricted. For example, the sheet of paper a printer takes may be 8.5 x 11 inches, but the printer might only be able to print on an area of 8 x 10.5 inches. If you define a page width x page height in Oracle Reports that is bigger than the printable area your printer allows, clipping may occur in your report output. To avoid clipping, you can either increase the printable area for the printer (if your operating system allows it) or you can set the page width x page height to be the size of the printable area of the page. 1. 2. If this keyword is used, its value overrides the page dimensions of the report definition. A PAGESIZE value entered on the Runtime Parameter Form will override any PAGESIZE value entered on the command line.
Executables
1 27
PROFILE
Is the name of a file in which you want to store performance statistics on report execution. If you specify a filename, Oracle Reports calculates statistics on the elapsed and CPU time spent running the report. PROFILE calculates the following statistics:
TOTAL ELAPSED TIME is the amount of time that passes between when you issue R25RUN and when it finishes running the report. TOTAL ELAPSED TIME is the sum of Oracle Reports Time and ORACLE Time. Oracle Reports Time is the amount of time spent in Oracle Reports. ORACLE Time is the amount of time spent in the database and is composed of the following: UPI is the amount of time spent to do such things as connect 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 running the report. Note: For some operating systems, the Oracle Reports time includes the database time because the database is included in Oracle Reports process. For more information, see the Developer/2000 Installation Guide for your operating system.
Options: RUNDEBUG
Any valid filename in the current directory.
Is whether you want extra runtime checking for logical errors in the report. RUNDEBUG checks for things that are not errors but might result in undesirable output. RUNDEBUG checks for the following:
frames or repeating frames that overlap but do not enclose another object. This can lead to objects overwriting other objects in the output. layout objects with pagedependent references that do no have fixed sizing. Oracle Reports will make such objects fixed in size regardless of the Vertical and Horizontal Sizing properties. For more 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 is the opposite. YES means perform extra runtime error checking.
Options:
1 28
NO means do not perform extra runtime error checking. Default: ONSUCCESS NO
Is whether you want a COMMIT or ROLLBACK performed when the report is finished executing. Options: COMMIT means perform a COMMIT when the report is done. ROLLBACK means perform a ROLLBACK when the report is done. NOACTION means do nothing when the report is done. Default: 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 after the After Report trigger fires. Other COMMITs and ROLLBACKs can occur prior to this one. For more information, see READONLY on page 1 24.
ONFAILURE
Is whether you want a COMMIT or ROLLBACK performed if an error occurs and the report fails to complete. Options: COMMIT means perform a COMMIT if the report fails. ROLLBACK means perform a ROLLBACK if the report fails. NOACTION means do nothing if the report fails. Default: ROLLBACK, 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 ONFAILURE is performed after the report fails. Other COMMITs and ROLLBACKs can occur prior to this one. For more information, see READONLY on page 1 24.
Executables
1 29
KEYIN
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 only relevant when runnning in a charactermode environment. Options: Any valid key filename in the current directory.
KEYOUT
Is the name of a keystroke file in which you want Oracle Reports to record all of your keystrokes. You can then use KEYIN to execute the keystroke file. KEYOUT and KEYIN are useful when you have certain keystrokes that you want to do each time you run a report. They are also useful for debugging purposes. Caution: Since KEYOUT is used to create a keystroke file, it is only relevant when running reports in a charactermode environment. Options: Any valid filename.
ERRFILE
Is the name of a file in which you want Oracle Reports to store all error messages that are issued during the execution of your report. Options: Any valid filename.
LONGCHUNK
Is the size (in kilobytes) of the increments in which Oracle Reports retrieves a LONG column value. When retrieving a LONG value, you may want to retrieve it in increments rather than all at once because of memory size restrictions. LONGCHUNK applies only to ORACLE7. Options: A number from 1 through 9,999. For some operating systems, the upper limit may be lower. For more information, see the Developer/2000 Installation Guide for your operating system. 10K
Default: ORIENTATION
Controls the direction in which the pages of the report will print. Options: DEFAULT means use the current printer setting for orientation. LANDSCAPE PORTRAIT Default: DEFAULT
1 30
Rules: 1. If ORIENTATION=LANDSCAPE for a charactermode report, you must ensure that your printer definition file contains a landscape clause. For more information, see Printer Definition File Syntax on page B 3.
BACKGROUND
Specifies whether the report should be run in the background. When BACKGROUND is YES, another process is spawned. This option is useful when you want to work on something else in the foreground while the report runs. Additional Information: On Windows, specifying BACKGROUND=YES means that the report will go into the Oracle Reports Server queue. Options: YES NO Default: Rules: 1. 2. BACKGROUND=YES is not supported for BATCH=YES, DESTYPE=SCREEN or PREVIEW, or R25DES. If you run a report from Oracle Reports Runtime (i.e., not the command line or SRW.RUN_REPORT), you should commit database changes you make in the Before Form, After Form, and Validation triggers before the report runs. When running in this way, these triggers will share the parent process database connection. When the report is actually executed, however, it will establish its own database connection. NO
MODE
Specifies whether to run the report in character mode or bitmap. This enables you to run a charactermode report from bitmapped Oracle Reports or vice versa. For example, if you want to send a report to a Postscript printer from a terminal (e.g., a vt220), you could invoke charactermode R25RUN and run the report with MODE=BITMAP. Additional Information: On Windows, specifying MODE=CHARACTER means that the Oracle Reports ASCII driver will be used to produce editable ASCII output. Options: BITMAP DEFAULT means to run the report in the mode of the current executable being used. CHARACTER
Executables
1 31
Default: PRINTJOB
DEFAULT
Specifies whether the Print Job dialog box should be displayed before running a report. Options: NO YES Default: 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 as R25DES), the Print Job dialog box will not appear, regardless of PRINTJOB. When DESTYPE=MAIL, the Print Job dialog box will not appear, regardless of PRINTJOB. YES
2. <PARAM>
Is a parameter that is part of the reports definition. The value you specify is used for that parameters value. Options: Default: Any valid value for that parameter. Taken from the Initial Value field of the Parameter property sheet for the parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Examples: 1. Following is an example of R25RUN specifying a parameters value:

r25run scott/tiger myparam1=100 yourparam=Stratford theirparam=10DEC93
Rules: 1. You can override the default value on the Runtime Parameter Form. For more information, see Runtime Parameter Form (on page 9 2). Values of arguments may be in single or double quotes. The effect of single or double quotes is operatingsystem specific. For more information, see the Developer/2000 Installation Guide for your operating system. If you specify runfile(s) using the REPORT keyword, the PARAM values will be validated using the settings specified for each parameter (e.g., Input Mask, Validation Trigger) in the report(s).
2.
3.
1 32
4.
If you do not specify runfile(s) using the REPORT keyword, the PARAM value is not parsed, or validated, because the parameters may refer to those that have not yet been defined.
TRACEFILE
Is the name of the file in which Oracle Reports logs trace information. Options: Default: Rules: 1. 2. Trace information can only be generated when running a .rdf file. You cannot specify logging when running a .rep file. If you specify LOGFILE or ERRFILE as well as TRACEFILE, all of the trace information will be placed in the most recently specified file. For example, suppose you specify the following:
r25run MODULE=order_entry USERID=scott/tiger TRACEFILE=trace.log LOGFILE=mylog.log ERRFILE=err.log
Any valid filename. trace.dat
In this case, all of the specified trace information would be placed in err.log because it is the last file specified in the R25RUN command. TRACEMODE Indicates whether Oracle Reports should add the trace information to the file or overwrite the entire file. Options: TRACE_APPEND adds the new information to the end of the file. TRACE_REPLACE overwrites the file. Default: Rules: 1. TRACEOPTS Trace information can only be generated when running a .rdf file. You cannot specify logging when running a .rep file. TRACE_APPEND
Indicates the tracing information that you want to be logged in the trace file. Options: A list of options in parentheses means you want all of the enlcosed options to be used. For example, TRACE_OPTS=(TRACE_APP, TRACE_PRF) means you want TRACE_APP and TRACE_PRF applied. TRACE_ALL means log all possible trace information in the trace file.
Executables
1 33
TRACE_APP means log trace information on all the report objects in the trace file. TRACE_ERR means list error messages and warnings in the trace file. TRACE_PLS means log trace information on all the PL/SQL objects in the trace file. TRACE_PRF means log performance statistics in the trace file. TRACE_SQL means log trace information on all the SQL in the trace file. TRACE_TMS means enter a timestamp for each entry in the trace file. Default: Rules: 1. AUTOCOMMIT Trace information can only be generated when running a .rdf file. You cannot specify logging when running a .rep file. TRACE_ALL
Specifies whether database changes (e.g., CREATE) should be automatically committed to the database. Note that some nonORACLE databases (e.g., SQL Server) require that AUTOCOMMIT=YES. Options: YES NO Default: NO
NONBLOCKSQL
On Windows, specifies whether to allow other programs to execute while Oracle Reports is fetching data from the database. This keyword is ignored on platforms other than Windows (e.g., Motif). Options: YES NO Default: YES
1 34
R25DES
R25DES invokes Oracle Reports designer, to create/maintain reports. Syntax
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}
Executables
1 35
MODULE/REPORT
Is a module (report, external query, or external PL/SQL library) that you want to open in the designer. (REPORT is allowed for backward compatibility.) If you do not specify a report using MODULE/REPORT, Oracle Reports will start up with a new report definition open. Options: Any valid report, external query, or external PL/SQL library name. Oracle Reports will look in the location specified with the ACCESS keyword for the module. If ACCESS is not specified, Oracle Reports will use its file path search order to find the file. For more information about file path search order, see File Searching Method on page 18 9. If the module is not found, Oracle Reports will start up without opening the specified module.
Rules: 1. If you open a character mode report via bitmapped R25DES, Oracle Reports displays a warning, then opens the report using a page size of 8.5 x 11 and a form size of 7 x 6.
USERID PARAMFORM
Is your database login. For more information, see Database Login on page 1 7. Displays the Runtime Parameter Form when you execute a report. For more information on the Runtime Parameter Form, see Runtime Parameter Form on page 9 2. Options: yes means to display the Form. no means to suppress the Form. Default: yes
CMDFILE
Is a file that contains arguments for the R25DES command. This option enables you to run a report without having to specify a large number of arguments each time you invoke R25DES. Options: Rules: 1. 2. A command file may reference another command file. Command file syntax for R25DES arguments is identical to that used on the command line. Any valid command file.
1 36
3.
Values entered on the command line override values specified in command files. For example, suppose that you specify R25DES from the command line with COPIES equal to 1 and CMDFILE equal to RUNONE (a command file). In RUNONE, COPIES is set to 2. Only one copy of the report would be generated in this case. For more information, see Command Line Syntax Rules on page 1 4. The argument(s) for this keyword may be operating systemspecific. For more information, see the Developer/2000 Installation Guide for your operating system.
4.
ARRAYSIZE
Is the size of the array in kilobytes for use with ORACLE array processing. Options: A number from 1 through 9,999. This means that Oracle Reports can use this number of kilobytes of memory per query in your report. The default arraysize is 10. For details on ORACLE array processing, see the ORACLE7 Server Administrators Guide.
Default:
DESTYPE
Is the type of destination device that will receive the report output. Options: 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 in DESNAME (the next keyword discussed). Preview also routes the output to the Previewer for interactive viewing. However, Preview causes the output to be formatted as PostScript output. The Previewer will use DESNAME to determine which printers fonts to use to display the output. Mail sends the output to the Oracle*Mail users specified in DESNAME. If your system does not have Oracle*Mail installed, or is not an Oracle*Mail node, an error will be returned. The report is sent as an attached file, not directly as a mail message. Default: Taken from the Initial Value field of the Parameter property sheet for the DESTYPE parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Executables
1 37
Rules: 1. 2. Sysout is not a valid option for DESTYPE while using R25DES. Sysout can only be used with R25RUN when BATCH=YES. If you set DESTYPE to Printer, File, or Mail, the Print Job dialog box will appear after you accept the Runtime Parameter Form, unless it is suppressed. After you accept the Print Job dialog box, the report is executed and the output is sent to the printer (specified in File>Choose Printer), file, or mail id. (If DESTYPE is something other than Printer, File, or Mail, then the report is executed after you accept the Runtime Parameter Form.) The appearance of the dialog box varies between operating systems. For more information, see the Developer/2000 Installation Guide for your operating system. In some cases, this parameter may be overridden by your operating system. For details, see the Developer/2000 Installation Guide for your operating system. All DESTYPE values are not supported on every operating system. For more information, see the Developer/2000 Installation Guide for your operating system.
3.
4.
DESNAME
Is the file, printer, or Oracle*Mail userid (or distribution list) to which the report output will be sent. To send the report output to an Oracle*Mail user, specify the username as you do in Oracle*Mail. You can specify multiple usernames by enclosing the names in parentheses and separating them by commas (e.g., (<name>, <name>, . . .<name>)). Options: Any valid filename, printer name, or Oracle*Mail userid not to exceed 1K in length. For printer names, you can optionally specify a port. For example:
DESNAME=<printer_name>,LPT1: DESNAME=<printer_name>,FILE:
Default:
Taken from the Initial Value field of the Parameter property sheet for the DESNAME parameter. If DESTYPE=FILE and DESNAME is an empty string, it defaults to <reportname>.lis at runtime. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Rules: 1. 2. This keyword is ignored if DESTYPE is Screen. If DESTYPE is Preview, Oracle Reports uses DESNAME to determine which printers fonts to use to display the output.
1 38
3.
The argument(s) for this keyword may be case sensitive, depending on your operating system. For more information, see the Developer/2000 Installation Guide for your operating system. In some cases, this parameter may be overridden by your operating system. For more information, see the Developer/2000 Installation Guide for your operating system.
4.
DESFORMAT
In bitmapped environments, specifies the printer driver to be used when DESTYPE is File. In character mode environments, specifies the characteristics of the printer named in DESNAME. Options: Any valid destination format not to exceed 1K in length. Examples of valid values for this keyword are hpl, hplwide, dec, decwide, decland, dec180, dflt, wide, etc. Ask your System Administrator for a list of valid destination formats. Taken from the Initial Value field of the Parameter property sheet for the DESFORMAT parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45. For bitmapped Oracle Reports, if DESFORMAT is blank or dflt, then the current printer driver selected in Choose Printer is used. If nothing has been selected in Choose Printer, then Postscript is used by default.
Default:
Rules: 1. 2. This keyword is ignored if DESTYPE is Screen. The argument(s) for this keyword may be case sensitive, depending on your operating system. For more information, see the Developer/2000 Installation Guide for your operating system.
COPIES
Is the number of copies of the report to print. Options: Default: Any valid integer from 1 through 9,999. Taken from the Initial Value field of the Parameter property sheet for the COPIES parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Rules: 1. 2. This keyword is ignored if DESTYPE is not Printer. If COPIES is left blank on the Runtime Parameter Form, it defaults to one.
Executables
1 39
CURRENCY
Is the currency character to be used in number formats. Options: Default: Any valid alphanumeric string not to exceed 1K in length. The default for ORACLE is determined by the ORACLE National Language Support facilities. You can also set a default of up to four characters in the Initial Value field of the Parameter property sheet for the CURRENCY parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Rules: 1. THOUSANDS A CURRENCY value entered on the Parameter property sheet will override any CURRENCY value entered on the command line.
Is the thousands character to be used in number formats. Options: Default: Any valid alphanumeric character. The default for ORACLE is determined by the ORACLE National Language Support facilities. You can also set a default of up to four characters in the Initial Value field of the Parameter property sheet for the THOUSANDS parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Rules: 1. A THOUSANDS value entered on the Parameter property sheet will override any THOUSANDS value entered on the command line.
DECIMAL
Is the decimal character to be used in number formats. Options: Default: Any valid alphanumeric character. The default for ORACLE is determined by the ORACLE National Language Support facilities. You can also set a default in the Initial Value field of the Parameter property sheet for the DECIMAL parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45
1 40
Rules: 1. READONLY A DECIMAL value entered on the Parameter property sheet will override any DECIMAL value entered on the command line.
Requests read consistency across multiple queries in a report. When accessing data from ORACLE, read consistency is accomplished by a SET TRANSACTION READ ONLY statement (refer to your ORACLE7 Server SQL Language Reference Manual for more information on SET TRANSACTION READ ONLY). Options: YES requests read consistency. NO means do not provide read consistency. Default: 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). 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 via the READONLY argument or setting). 1.7 The report is executed and the Between Page trigger fires for each page except the last one. (Note that data can be fetched at any time while the report is being formatted.) Note: COMMITs can occur during this time due to any of the followinguser exit with DDL, SRW.DO_SQL with DDL, or if ONFAILURE=COMMIT, and the report fails. 1.8 COMMIT is executed (if READONLY is specified) to end the transaction. 1.9 After Report trigger is fired. 1.10COMMIT/ROLLBACK/NOACTION is executed based on what was specified via the ONSUCCESS argument or setting. NO
Executables
1 41
Caution: In steps 1.4 through 1.8, avoid DDL statements that would modify the tables on which the report is based. Step 1.3 takes a snapshot of the tables and the snapshot must remain valid throughout the execution of the report. In steps 1.6 through 1.8, avoid DML statements that would modify the contents of the tables on which the report is based. Queries may be executed in any order, which makes DML statements unreliable (unless performed on tables not used by the report). Caution: If you specify READONLY, you should avoid DDL altogether. When you execute a DDL statement (e.g., via SRW.DO_SQL or a user exit), a COMMIT is automatically issued. If you are using READONLY, this will prematurely end the transaction begun by SET TRANSACTION READONLY. 2. This keyword is only useful for reports using multiple queries, because ORACLE automatically provides read consistency, without locking, for single query reports.
BUFFERS
Is the size of the virtual memory cache in kilobytes. Note: You should tune this setting to ensure that you have enough space to run your reports, but not so much that you are using too much of your systems resources. Options: A number from 1 through 9,999. For some operating systems, the upper limit may be lower. For more information, see the Developer/2000 Installation Guide for your operating system. 640K
Default: Rules: 1. PAGESIZE
If this setting is changed in the middle of your session, the change does 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 the printer outputs). Options: Any valid page dimensions of the form: page width x page height, where page width and page height are zero or more. The maximum width/height depends upon the unit of measurement. For inches, the maximum width/height is 512 inches. For centimeters, it is 1312 centimeters. For picas, it is 36,864 picas.
1 42
Note that the page must be large enough to contain the report. For example, if a frame in a report expands to a size larger than the page dimensions, the report will not run. Default: For bitmap, 8.5 x 11 inches. For character mode, 80 x 66 characters. If the report was designed for character mode and is being run or converted on bitmap, the following formula is used to determine page 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 bitmapped page size would be: (8.5 * 80)/80 x (11 * 20)/66 = 8.5 x 3.33.
Rules: Caution: On some printers the printable area of the physical page is restricted. For example, the sheet of paper a printer takes may be 8.5 x 11 inches, but the printer might only be able to print on an area of 8 x 10.5 inches. If you define a page width x page height in Oracle Reports that is bigger than the printable area your printer allows, clipping may occur in your report output. To avoid clipping, you can either increase the printable area for the printer (if your operating system allows it) or you can set the page width x page height to be the size of the printable area of the page. 1. 2. PROFILE If this keyword is used, its value overrides the page dimensions of the report definition. A PAGESIZE value entered on the Runtime Parameter Form will override any PAGESIZE value entered on the command line.
Is the name of a file in which you want to store performance statistics on report execution. If you specify a filename, Oracle Reports calculates statistics on the elapsed and CPU time spent running the report. PROFILE calculates the following statistics:
TOTAL ELAPSED TIME is the amount of time that passes between when you issue R25DES and when you leave the designer. TOTAL ELAPSED TIME is the sum of Oracle Reports Time and ORACLE Time. Oracle Reports Time is the amount of time spent in Oracle Reports.
Executables
1 43
ORACLE Time is the amount of time spent in the database and is composed of the following: UPI is the amount of time spent to do such things as connect 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 while in the designer. Note: For some operating systems, the Oracle Reports time includes the database time because the database is included in Oracle Reports process. For more information, see the Developer/2000 Installation Guide for your operating system.
Options: RUNDEBUG
Any valid filename in the current directory.
Is whether you want extra runtime checking for logical errors in reports. RUNDEBUG checks for things that are not errors but might result in undesirable output. RUNDEBUG checks for the following:
frames or repeating frames that overlap but do not enclose another object. This can lead to objects overwriting other objects in the output. layout objects with pagedependent references that do no have fixed sizing. Oracle Reports will make such objects fixed in size regardless of the Vertical and Horizontal Sizing properties. For more 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 error checking.
Options:
Default: ONSUCCESS
YES
Is whether you want a COMMIT or ROLLBACK performed when a report is finished executing. Options: COMMIT means perform a COMMIT when a report is done. ROLLBACK means perform a ROLLBACK when a report is done. NOACTION means do nothing when a report is done. Default: COMMIT, if a USERID is provided.
1 44
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 after the After Report trigger fires. Other COMMITs and ROLLBACKs can occur prior to this one. For more information, see READONLY on page 1 41.
ONFAILURE
Is whether you want a COMMIT or ROLLBACK performed if an error occurs and a report fails to complete. Options: COMMIT means perform a COMMIT if a report fails. ROLLBACK means perform a ROLLBACK if a report fails. NOACTION means do nothing if a report fails. Default: ROLLBACK, 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 ONFAILURE is performed after the report fails. Other COMMITs and ROLLBACKs can occur prior to this one. For more information, see READONLY on page 1 41.
ERRFILE
Is the name of a file in which you want Oracle Reports to store all error messages that are issued during the designer session. Options: Any valid filename.
LONGCHUNK
Is the size (in kilobytes) of the increments in which Oracle Reports retrieves a LONG column value. When retrieving a LONG value, you may want to retrieve it in increments rather than all at once because of memory size restrictions. LONGCHUNK applies only to ORACLE7. Options: A number from 1 through 9,999. For some operating systems, the upper limit may be lower. For more information, see the Developer/2000 Installation Guide for your operating system. 10K
Default:
Executables
1 45
ACCESS
Is the location from which modules should be opened. Oracle Reports will search in this location for the module you specify with MODULE. If ACCESS is not specified, Oracle Reports will use its file path search order to find the file. For more information about file path search order, see File Searching Method on page 18 9. Options: FILE DATABASE Default: FILE
ORIENTATION
Controls the direction in which the pages of the report will print. Options: DEFAULT means use the current printer setting for orientation. LANDSCAPE PORTRAIT Default: Rules: 1. If ORIENTATION=LANDSCAPE for a character mode report, you must ensure that your printer definition file contains a landscape clause. For more information, see Printer Definition File Syntax on page B 3. DEFAULT
BACKGROUND
Specifies whether the report should be run in the background. BACKGROUND=YES is not supported for R25DES. For more information, see BACKGROUND on page 1 31. Options: YES NO is not a valid option for R25DES. Default: NO
MODE
Specifies whether to run the report in character mode or bitmap. This enables you to run a charactermode report from bitmapped Oracle Reports or vice versa. For example, if you want to send a report to a Postscript printer from a terminal (e.g., a vt220), you could invoke charactermode R25RUN and run the report with MODE=BITMAP. Additional Information: On Windows, specifying MODE=CHARACTER means that the Oracle Reports ASCII driver will be used to produce editable ASCII output. Options: BITMAP
1 46
DEFAULT means to run the report in the mode of the current executable being used. CHARACTER Default: PRINTJOB DEFAULT
Specifies whether the Print Job dialog box should be displayed before running a report. Options: YES NO Default: 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 as R25DES), the Print Job dialog box will not appear, regardless of PRINTJOB. When DESTYPE=MAIL, the Print Job dialog box will not appear, regardless of PRINTJOB. YES
2. <PARAM>>
Is a parameter that is part of the reports definition. The value you specify for the parameter is used for that parameters value. Options: Default: Any valid value for that parameter. Taken from the Initial Value field of the Parameter property sheet for the parameter. For more information on the Parameter property sheet, see Parameter Properties on page 6 45.
Examples: 1. Following is an example of R25DES specifying a parameters value:

r25des scott/tiger myparam1=100 yourparam=Stratford theirparam=10DEC93
Rules: 1. You can override the default value on the Runtime Parameter Form. For more information, see Runtime Parameter Form on page 9 2. Values of arguments may be in single or double quotes. The effect of single or double quotes is operatingsystem specific. For more information, see the Developer/2000 Installation Guide for your operating system.
2.
Executables
1 47
3. TRACEFILE
The PARAM value is not parsed, or validated, because the parameters may refer to those that have not yet been defined.
Is the name of the file in which Oracle Reports logs trace information. Options: Rules: 1. 2. Trace information can only be generated when running a .rdf file. You cannot specify logging when running a .rep file. If you specify ERRFILE as well as TRACEFILE, all of the trace information will be placed in the most recently specified file. For example, suppose you specify the following:
r25des USERID=scott/tiger TRACEFILE=trace.log ERRFILE=err.log
Any valid filename.
In this case, all of the specified trace information would be placed in err.log because it is the last file specified in the R25DES command. TRACEMODE Indicates whether Oracle Reports should add the trace information to the file or overwrite the entire file. Options: TRACE_APPEND adds the new information to the end of the file. TRACE_REPLACE overwrites the file. Default: Rules: 1. TRACEOPTS Trace information can only be generated when running a .rdf file. You cannot specify logging when running a .rep file. TRACE_APPEND
Indicates the tracing information that you want to be logged in the trace file. Options: A list of options in parentheses means you want all of the enlcosed options to be used. For example, TRACE_OPTS=(TRACE_APP, TRACE_PRF) means you want TRACE_APP and TRACE_PRF applied. TRACE_ALL means log all possible trace information in the trace file. TRACE_APP means log trace information on all the report objects in the trace file.
1 48
TRACE_BRK means list breakpoints in the trace file. TRACE_ERR means list error messages and warnings in the trace file. TRACE_PLS means log trace information on all the PL/SQL objects in the trace file. TRACE_PRF means log performance statistics in the trace file. TRACE_SQL means log trace information on all the SQL in the trace file. TRACE_TMS means enter a timestamp for each entry in the trace file. Default: Rules: 1. AUTOCOMMIT Trace information can only be generated when running a .rdf file. You cannot specify logging when running a .rep file. TRACE_ALL
Specifies whether database changes (e.g., CREATE) should be automatically committed to the database. Note that some nonORACLE databases (e.g., SQL Server) require that AUTOCOMMIT=YES. Options: YES NO Default: NO
NONBLOCKSQL
On Windows, specifies whether to allow other programs to execute while Oracle Reports is fetching data from the database. This keyword is ignored on platforms other than Windows (e.g., Motif). Options: YES NO Default: YES
Executables
1 49
1 50
PART
II
Externals
CHAPTER
Defaulting
efaulting in Oracle Reports creates objects and defines certain D settings so that you dont have to. Without defaulting, you would have to manually create each object in your report and for each of the objects settings, enter a value. You should know the following about Oracler 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
Defaulting
21
Data Model Defaulting

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

groups 2 2 columns 2 2 parameters 2 3
The circumstances under which Oracle Reports creates these objects are described below. Note: Queries and links (parentchild relationships) are never created by default. You must always create those objects yourself. Groups Objects Created/Circumstances Oracle Reports will create one group for each query you create. Ownership The group will be owned by the query you created. In turn, the group will own all of the columns found in the querys SELECT list (e.g., ENAME, EMPNO, SAL). Ordering The order of the groups determines the default order in which the groups columns appear in a default layout. Specifically, a group above, or to the left of other groups will have its columns appear above 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 or to the left of the second group). Note: The previous sentence is true only when a reports default layout is first generated. Adding PL/SQL to the formatting objects, adding anchors, changing format settings, moving layout objects, etc. can cause a groups data to appear elsewhere in a report output. Settings Name: G_queryname Query: Q_queryname Filter... Type: None All other fields are blank. Columns Objects Created/Circumstances Oracle Reports will create one column for each item in a querys SELECT list. Ownership The default columns are assigned to the default group for the query.
22
Ordering Columns appear in the default group in the order in which the columns appear in the SELECT list. (For example, if the SELECT statement is SELECT ENAME, EMPNO, SAL FROM EMP, ENAME will appear in the default group above EMPNO, and EMPNO will appear above SAL.) Also, the order of the columns in the default group determines the order in which the columns appear in a default layout. (For example, using the SELECT statement above, ENAME will appear in a default layout above or to the left of EMPNO, and EMPNO will appear above or to the left of SAL in a default layout.) Note: The previous sentences are true only when a reports default layout is first generated. Adding PL/SQL to the formatting objects, adding anchors, changing format settings, moving layout objects, etc. can cause a column to appear elsewhere in a report output. If additional columns are added to the query, the additional default columns will be added to the end of the list of default columns. Settings Name: G_queryname Query: Q_queryname Filter... Type: None All other fields are blank. Parameters Objects Created/Circumstances Oracle Reports will create system parameters (e.g., DESTYPE) each time you create a new report. Also, Oracle Reports will create one parameter for each bind parameter reference you make in a query. It will not create a parameter in the following cases:

for a bind column reference in your query for a lexical reference, because the query cannot parse without an initial 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 P_1 Data Type character Width 40
Defaulting
23
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 a default layout. For more information, see How To in Chapter 8 of Building Reports Manual.
Object Defaulting
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 layout objects are described later in this chapter. A conceptual overview of layout object defaulting is below. It is important to realize, however, that the layout objects Oracle Reports generates are layoutstyle specific (e.g., different layout objects are created for a tabular report and a matrix report). For more information about 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 you understand the remainder of this layout defaulting section. Frames Objects Created/Circumstances Oracle Reports will create one frame to surround all objects owned by a group (it is named M_groupname_GRPFR), to surround column labels (it is named M_groupname_HDR), and to surround summaries (it is named M_groupname_FTR). Ownership A frame is owned by the object surrounding it (a frame or repeating frame), unless otherwise noted.
24
Repeating Frames
Objects Created/Circumstances Oracle Reports will create one repeating frame to surround all fields that are created for a groups columns (it is named R_groupname). The repeating frame prints (is fired) once for each record of the group. Ownership A repeating frame is owned by the object surrounding it (a frame or repeating frame), unless otherwise noted.
Fields
Objects Created/Circumstances Oracle Reports will create one field for each column selected in the Default Layout dialog box (it is named F_columnname). Ownership A field is owned by the object surrounding it, typically a repeating frame, unless the field is a summary (in which case it is owned by a frame).
Boilerplate
Objects Created/Circumstances Oracle Reports will create one boilerplate object for each label selected in the Default Layout dialog box (it is named B_columnname). Also, one boilerplate object is sometimes created for each report summary. For more information about the conditions under which summaries have boilerplate generated, see Global Layout Defaulting Rules on page 2 41. Ownership A boilerplate object is owned by the object surrounding it, unless otherwise noted.
Anchors
Objects Created/Circumstances (Recall that there are two types of anchors: explicit and implicit. See the glossary for an explanation of these terms.) Oracle Reports will create implicit anchors at runtime. Ownership An anchor is owned by the child object to which it is anchored.
Matrix Objects
Objects Created/Circumstances Oracle Reports will create one matrix object 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 two repeating frames: it isnt really owned by anything, nor does it own anything.
Buttons
Objects Created/Circumstances Oracle Reports will create a button object for you if you have selected a column that contains or points to a multimedia object (e.g., sound or video). Ownership A button object is owned by the object surrounding it, unless otherwise noted.
Defaulting
25
Object Defaulting For Each Layout Style
This section describes what objects are created for each layout style (i.e., tabular, mailing label, form letter, form, master/detail, and matrix). 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
Tabular Reports
Tabular Report Requirements
This section describes the layout requirements, object generation, and rules 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 the highestselected group must have the same initial Repeat direction. For example, if the highestselected group repeats Across, its children must have a Repeat direction of Across or Across/Down. Likewise, if the highestselected group repeats Down/Across, its children must have a Repeat direction of Down or Down/Across. If more than one tree has a selected group, each trees highestselected group may have a different repeat direction. A crossproduct group may not be selected.
Repeat Direction Example
Assume you have a report with the following group trees, and you selected the shaded groups.
26
If group 1 has a Repeat direction of Across, its children (groups 2, 3, and 5even though group 4 is not selected) must have either a Repeat direction of Across or Across/Down. Group 6 may have any Repeat direction, because it has no ancestors. If you have it Repeat Down, its children (groups 7 and 8) must have a Repeat direction of Down or Down/Across; if it repeats Across, its children must repeat Across or Across/Down. Finally, group 10 may also have any Repeat direction because it is the highestselected group in its tree. Tabular Report Defaulting The way that your tabular report defaults depends on the number of groups you select in the Default Layout dialog box, and on the relationship of those groups. Therefore, this section is divided into two sections:

singlegroup defaulting (i.e., when only one group is selected) multiplegroup defaulting (i.e., when multiple groups are selected) Note: This section describes defaulting for down reports, only. Across tabular reports are transposed Down reports. For more information on how to transpose a report, see Global Layout Defaulting Rules on page 2 41.
Singlegroup Defaulting
This section is divided into two parts:

defaulting without summaries defaulting with summaries
Tabular Defaulting without Summaries Assume you selected only one group, and that group owns two columns. Generated Objects: If you use the default Repeat direction, Down, your Layout editor will contain the following objects: B_columnname For the label of each selected column in the Default Layout dialog box. B_ implies it is a boilerplate object. For each column that you selected in the Default Layout dialog box. F_ implies it is a field. For each group that you selected in the Default Layout dialog box. R_ implies it is a repeating frame. For each group you selected in the Default Layout dialog box. M_ implies it is a frame; HDR implies it is for the header information (i.e., labels).
F_columnname R_groupname
M_groupname_ HDR
Defaulting
27
M_groupname_ GRPFR
For each group that you selected in the Default Layout dialog box. M_ implies it is a frame; GRPFR implies it is a group frame. M_groupname_GRPFR is used to keep all of that groups 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 the repeating frame that encloses them. A header frame that contains boilerplate labels for fields must be on a layer below the boilerplate. It must also be on a layer above the repeating frame that contains it.
Print Conditions: All objects have a Print Condition Type/Object of Default/Anchoring, except M_groupname_HDR, which is All/Enclosing. Recall that whenever a setting has Default as its default, it means that Oracle Reports will determine what the setting should be at runtime, based on the layout style the object is in, the objects settings, and the settings of the objects near it. Tabular Defaulting with Reportlevel Summaries Assume the same scenario as above, only this time there are also two reportlevel summaries. Generated Objects: The following objects are generated in addition to those created for the tabular report without summaries: B_columnname For the label of each selected column in the Default Layout dialog box, and if there is room, for summary labels. For more information, see Rules about Summaries on page 2 42. B_ implies it is a boilerplate object.
28
F_columnname M_groupname_ FTR
For each reportlevel summary that you selected in the Default Layout dialog box. For each group that owns a report summary that you 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 summary fields for that group from being overwritten by other 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 the repeating frame that encloses them. A footer frame that surrounds fields must be on a layer below the fields it contains. It must also be on a layer above the group frame that contains it.
Print Conditions: All objects have a Print Condition Type/Object of Default/Anchoring, except M_groupname_HDR, which is All/Enclosing. Multiplegroup Defaulting This section is divided into two parts:

defaulting for sibling groups defaulting for parent/child groups
Defaulting
29
Tabular Defaulting for Sibling Groups Tabular reports produced with two or more sibling groups are almost identical to tabular reports produced with master/detail models. If the siblings have the same parent (directly or indirectly), they appear sidebyside in the layout. If the siblings do not have the same parent, the sibling that is higher in the group hierarchy appears above the other siblings in the layout. The latter case is illustrated in the figure below.
Tabular Defaulting for Parent/Child Groups (with reportlevel summaries) Assume you only have one group tree, you selected only two groups, one of which is the parent of the other, and each group owns two columns. Assume also that there are four summaries (see the figure below): two parentlevel summaries, which sum the columns in the child group; and two reportlevel summaries, where one sums a column in the child group and one sums a column in the parent group. Generated Objects: If you use the default Repeat direction, Down, your Layout editor will contain the following objects: B_columnname For the label of each selected column in the Default Layout dialog box, and if there is room, for summary labels. (For details, see Rules about Summaries on page 2 42.) B_ implies it is a boilerplate object. For each column that you selected in the Default Layout dialog box. F_ implies it is a field. For each group that you selected in the Default Layout dialog box. R_ implies it is a repeating frame.
2 10
M_groupname_ HDR
For each group for which you have selected one or more labels in the Default Layout dialog box. M_ implies it is a frame; HDR implies it is for the header information (i.e., labels). For each group that you selected in the Default Layout dialog box. (M_ implies it is a frame; GRPFR implies it is a group frame. M_groupname_GRPFR is used to protect all of that groups objects from being overwritten by other objects in the report.)
M_groupname_ GRPFR
Appearance:
Layers: In general, if there is room for a frame and a repeating frame to appear on the same level (i.e., if they do not overlap), they will appear on the same level. In a tabular report with a parent/child relationship, the childs frames and repeating frames overlap the parents frames and repeating frames; therefore, the child frame and repeating frame objects 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 Conditions assigned to each object, where: AA DA LA AE 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.
Defaulting
2 11
Note: Whenever a setting has Default as its default, it means that Oracle Reports will determine what the setting should be at runtime, based on the layout style the object is in, the objects settings, and the settings of the objects near it.
Rules: Below are rules for tabular reports with master/detail and controlbreak data models: 1. 2. Header (HDR) and footer (FTR) frames have a Horizontal Sizing and Vertical Sizing of Fixed. The repeating frame of the innermost detail has a Horizontal Sizing and Vertical Sizing of Fixed, unless it contains a column with a datatype of LONG, in which case it has a Vertical Sizing of Expanding. All other frames and repeating frames have a Horizontal Sizing of Fixed, and Vertical Sizing of Expanding. In Across reports, no labels for summaries will appear by default. Note: For more information on rules on summaries and their labels, see Global Layout Defaulting Rules on page 2 41.
3. Tabular Rules 1.
Mailing Label Reports

Mailing Label Report Requirements
This section describes the layout requirements, object generation, and rules for the mailing label report layout style. Data Model Requirements You can use any type of data relationship. Default Layout Requirements In a group tree, all groups you select must be siblings (i.e., not parent groups and children groups). The report group is an exception; it is treated like a sibling group. See the figure below for an example of valid and invalid selected groups.
2 12
Mailing Label Report Defaulting
This section is divided into two sections:

singlegroup defaulting (i.e., when only one group is selected) multiplegroup defaulting (i.e., when multiple groups are selected) Note: This section describes defaulting for Down reports, only. For other Repeat directions, the layout is identical, except that the default repeating frame will have a corresponding Print direction.
Assume you only have one group tree, you selected only one group, and that group owns two columns. Generated Objects: If you use the default Repeat direction, Down, your Layout editor will contain the following objects: F_columnname R_groupname For each column that you selected in the Default Layout dialog box. F_ implies it is a field. For each group that you selected in the Default Layout dialog box. R_ implies it is a repeating frame.
Defaulting
2 13
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 that encloses them. Print Conditions: All objects have a Print Condition Type/Object of Default/Anchoring. Multiplegroup Defaulting Mailing label reports produced with two or more selected sibling groups are almost identical to those produced with only one selected group. The only difference is that the default layout for the first group appears above the second. See the figure below for an example.
Rules: Below are rules for mailing label reports with multiple groups selected: 1. Oracle Reports creates the default layout objects for each selected group in the following manner: 1) find the bottom leftmost selected group; 2) move up the tree one node and check for siblings, recursively. For example, assume that the shaded groups in the figure below are the groups you selected. In your default layout, group 5 would appear above all other groups, and group 4 would appear above group 2.
2 14
Mailing Label Rules
1.
In a group tree, all groups you select must be siblings (i.e., not parent groups and children groups). The report group is an exception. A field created for a column with a LONG datatype has a Horizontal and Vertical Sizing of Fixed. As a result, the data of that field will be truncated if the size of the data is greater that the size of the field.
2.
Form Reports
Form Report Requirements
This section describes the layout requirements, object generation, and rules 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 select must be siblings. The report group is an exception; it is treated like a sibling group. This section is divided into two sections:

Form Report Defaulting
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 that the default repeating frame will have a corresponding Print direction.
Assume you only have one group tree, you selected only one group, and that group owns two columns. Generated Objects: If you use the default Repeat direction, Down, your Layout editor will contain the following objects: B_columnname For the label of each selected column in the Default Layout dialog box. B_ implies it is a boilerplate object.
Defaulting
2 15
For each column that you selected in the Default Layout dialog box. F_ implies it is a field. For each group that you selected in the Default Layout dialog box. R_ implies it is a repeating frame.
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 that encloses them. Print Conditions: All objects have a Print Condition Type/Object of Default/Anchoring. Multiplegroup Defaulting Form reports produced with two or more selected sibling groups are almost identical to those produced with only one selected group. The only difference is that the default layout for the first group appears above the second. See the figure below for an example.
2 16
Form Rules
1.
To ensure that only one set of records is printed on each form, the Maximum Records per Page setting of each repeating frame is 1. Also, the Page Break Before setting for the repeating frame is selected (but is ignored for the first record). If a repeating frame owns a LONG field (i.e., a field with a Source of a column with a LONG datatype), the repeating frame will have a Horizontal Sizing of Fixed, and Vertical Sizing of Variable. Otherwise, it will have a Vertical Sizing of Fixed. If there is no room for both a field and its label to fit at the end of a line, they will both be moved to the next line.
2.
3.
Form Letter Reports

Form Letter Report Requirements
This section describes the layout requirements, object generation, and rules for the form letter report layout style. Data Model Requirements You can use any type of data relationship. Default Layout Requirements In a group tree, all groups you select must be siblings. The report group is an exception; it is treated like a sibling group. This section is divided into two sections:

Form Letter Report Defaulting
defaulting when only one group is selected defaulting when multiple groups are selected Note: This section describes defaulting for down reports, only. Across form letter reports are transposed down form letter reports. For other Repeat directions, the layout is identical, except that the default repeating frame will have a corresponding Print direction.
Assume you only have one group tree, you selected only one group, and that group owns two columns. Generated Objects: If you use the default Repeat direction, Down, your Layout editor will contain the following objects: B_groupname For each group that you selected in the Default Layout dialog box. B_ implies it is a boilerplate object. For each column that you selected in the Default Layout dialog box. F_ implies it is a field.
F_columnname
Defaulting
2 17
In form letters, fields are hidden. A hidden fields data does not appear in the place in which it is located in the editor; instead, its data appears where the hidden field is referenced in its related boilerplate object. (The related boilerplate object is the boilerplate object created for the group that owns the fields column). To reference a hidden field, type &fieldname in the fields related boilerplate object. R_groupname For each group that you selected in the Default Layout dialog box. R_ implies it is a repeating frame.
Note: &fieldnames seen in the editor are simply text of the boilerplate object. At runtime, the fields content will appear where 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 their enclosing repeating frame. In form letter reports, the boilerplate is placed on a layer above the hidden fields. And the hidden fields and the boilerplate are on layers above their enclosing repeating frame. Print Conditions: All objects have a Print Condition Type/Object of Default/Anchoring.
2 18
Multiplegroup Defaulting
Form letter reports produced with two or more selected sibling groups are almost identical to those produced with only one selected group. The only difference is that the default layout for the first group appears above the second. See the figure below for an example.
Form Letter Report Rules
1.
The repeating frame must enclose its boilerplate object. It has a Maximum Records per Page setting of 1, and its Page Break Before setting is selected (but is ignored for the first instance). The repeating frames width is the width of the logical page, minus the margin; its length is the length of the field references (&fieldname), plus a little more, so that it can surround the references. Hidden fields may only be referenced within a boilerplate object, and the reference must be in the form of &fieldname. A hidden field may be referenced in a boilerplate object that is not owned by that hidden fields repeating frame. A hidden field may, but is not restricted to have the same Print Condition as its related boilerplate object. All hidden fields have a Horizontal Sizing of Variable, and a Vertical Sizing of Fixed. Parameters do not become hidden fields. To reference a parameter, create a field that has a source of the parameter, then reference the field.
2.
3. 4. 5. 6. 7.
Defaulting
2 19
Master/Detail Reports
Master/Detail Report Requirements
This section describes the layout requirements, object generation, and rules 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 be selected. In a group tree, all children of the highestselected group must have the same initial Repeat direction. For more information on this requirement, see Tabular Report Requirements on page 2 6. This section is divided into two sections:

Master/Detail Report Defaulting
defaulting when only one group is selected defaulting when multiple groups are selected Note: This section describes defaulting for down reports, only. Across master/detail reports are transposed Down master/detail reports. For more information on how to transpose a report, see Global Layout Defaulting Rules on page 2 41.
Assume you selected only one group, and that group owns two columns. The defaulting for this type of report is identical to that of a simple tabular report. For more information, see Tabular Reports on page 2 6.
2 20
Multiplegroup Defaulting
Master/Detail report layouts are almost identical to Tabular report layouts. The only difference is that if there is a parent/child relationship (a link) between two selected groups, the parent group is formatted like a Form report, and the child group(s) are formatted like a Tabular report. For example, the parent group in a tabular report:
Deptno Deptno
looks like this in master/detail:
Deptno Deptno
This section is divided into four sections:

one group tree with multiple groups selected, all of which are siblings multiple group trees with multiple groups selected, all of which are siblings one group tree with multiple groups selected, some of which are parents of others multiple group trees with multiple groups selected, some of which 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 tabular report with two groups. For more information, see Tabular Reports on page 2 6.
Defaulting
2 21
Multiple Group Tree, All Siblings Assume you have two group trees, you selected two groups from eachall of which are siblingsand each group owns two columns. See the figure below for an example.
The defaulting for this type of report is identical to that of a tabular report with two groups. For more information, see Tabular Reports on page 2 6.
2 22
Single Group Tree, Parents and Children Assume you only have one group tree, you selected three groupsone of which is the parent of the other twoand each group owns two columns. See the figure below for an example.
Defaulting
2 23
Generated Objects: If you use the default Repeat direction, Down, your Layout editor will contain the following objects: B_columnname For the label of each selected column in the Default Layout dialog box, and if there is room, for summary labels. B_ implies it is a boilerplate object. For each column that you selected in the Default Layout dialog box. F_ implies it is a field. For each group that you selected in the Default Layout dialog box. R_ implies it is a repeating frame. For each group for which you have selected one or more labels in the Default Layout dialog box. M_ implies it is a frame; HDR implies it is for the header informationi.e., labels. For each group that you selected in the Default Layout dialog box. M_ implies it is a frame; GRPFR implies it is a group frame. M_groupname_GRPFR is used to protect all of that groups objects from being overwritten by other objects in the report.
M_groupname_ HDR
M_groupname_ GRPFR
Appearance:
2 24
Layers: In general, if there is room for a frame and a repeating frame to appear on the same level (i.e., if they do not overlap), they will appear on the same level. In a master/detail report, a child groups frames and repeating frames overlap its parents frames and repeating frames; therefore, the childs frames and repeating frames 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: All objects have a Print Condition Type/Object of Default/Anchoring. Multiple Group Tree, Parents and Children (with Summaries) Assume you only have one group tree, you selected three groupsone of which is the parent of the other twoand each group owns two columns. See the figure below for an example. Assume also that group 1 owns a summary that sums a field in group 2.
Generated Objects: The following objects are generated in addition to those created for the Single Group Tree, Parents and Children report: M_groupname_ FTR For each group that owns a report summary that you 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 summary fields for that group from being overwritten by other objects in the report.
Defaulting
2 25
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 parent is selected, or if the report group is selected, siblings (e.g., groups 1 and 2) appear one above the other. (The upperleft most sibling in the group tree will appear above its other siblings.) Layers: If there is room for a frame or a repeating frame to appear on the same level (i.e., if they do not overlap), they will be on the same level. In a master/detail report, a child groups frames and repeating frames overlap its parents frames and repeating frames; therefore, the childs frames and repeating frames 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: All objects have a Print Condition Type/Object of Default/Anchoring.
2 26
Matrix Reports
Matrix Report Requirements
This section describes the layout requirements, object generation, and rules for the matrix report layout style. Data Model Requirements You must have a matrix, nested matrix, or matrix break data model. The data model must have at least four groups, one of which must be a cross product group. For more information, see the Building Reports Manual. Note: For data models that require a break group, you should create the break group before creating the crossproduct group. If the crossproduct group already exists, delete it, create the break group(s), and then recreate the crossproduct group. Matrices and Summaries When creating summaries that will appear within the matrix, the summary must be owned by the cross product group and must have Product Order specified. Oracle Reports uses the Product Order to determine where to place the fields for the summaries in the layout. (Note that summaries owned by the crossproduct group cannot have a Reset At or Compute At of Page or rely on columns that do.) Default Layout Requirements You must select the cross product group, and at least two of the groups inside of it.
Matrix Report Defaulting
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
Matrix Defaulting without Summaries
Assume you only have one group tree, you selected the cross product group, two groups inside of it, and one group below it. Assume that each group contains one column. Generated Objects: Your Layout editor will contain the following objects: B_columnname For the label of each selected column in the Default Layout dialog box. (B_ implies it is a boilerplate object.) For each column that you selected in the Default Layout dialog box. (F_ implies it is a field.)
F_columnname
Defaulting
2 27
R_groupname
For each group that you selected in the Default Layout dialog box. (R_ implies it is a repeating frame.) For each group that you selected in the Default Layout dialog box. (M_ implies it is a frame; HDR implies it is a header frame. M_groupname_HDR is used to protect field labels from being overwritten by other objects in the report.) For each pair of repeating frames that intersect to form the matrix. By multiplying the number of across dimensions by the number of down dimensions, you can calculate the number of matrix objects created. In this case, one dimension going down multiplied by one dimension going across yields one matrix object.
M_groupname_ HDR
X_groupname
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 their enclosing repeating frame. In matrix reports, the matrix object must be on a layer above the repeating frames that it relates (i.e., the across/down dimension repeating frames). The across dimension repeating frame also must be on a layer above the down dimension repeating frame.
2 28
Matrix Defaulting with Summaries
Assume you only have one group tree, you selected the cross product group, the two groups inside of it (each of which has one column), the child group, and three summary columns. One summary column that sums salary by department, one that sums salary by job, and one that sums all salaries in the report. Generated Objects: The objects generated are the same as a matrix report without summaries, except for the additional fields and boilerplate for the summary columns. Appearance:
Layers: The layers are almost identical to those of a matrix report without summaries. The only difference is the fields and boilerplate that appear for the summary columns on a layer above the frames and repeating frames that contain them. Matrix Defaulting with Summary of Child Group Assume you only have one group tree, you selected the cross product group, two groups inside of it (each of which has one column), and the cross productlevel summary of the child group. The child group is not selected because the cross productlevel summary is the source of the field inside the matrix object. Generated Objects: The objects generated are almost identical to a matrix report without summaries. The difference is the absence of a repeating frame for the child group.
Defaulting
2 29
Appearance:
Layers: The layers are almost identical to those of a matrix report without summaries. The differences are that the repeating frame is not generated for the child group (because it is not selected). Nested Matrix Defaulting without Summaries Assume you only have one group tree, you selected the cross product group, three groups inside of it (one of which is the parent of one of the groups), and one group below it. Assume that each group contains one column. Generated Objects: Your Layout editor will contain the following objects: B_columnname For the label of each selected column in the Default Layout dialog box. (B_ implies it is a boilerplate object.) For each column that you selected in the Default Layout dialog box. (F_ implies it is a field.) For each group that you selected in the Default Layout dialog box. (R_ implies it is a repeating frame.)
M_groupname_HD For each group that you selected in the Default R Layout dialog box. (M_ implies it is a frame; HDR implies it is a header frame. M_groupname_HDR is used to protect field labels from being overwritten by other objects in the report.)
2 30
X_groupname
For each pair of repeating frames that intersect to form the matrix. By multiplying the number of across dimensions by the number of down dimensions, you can calculate the number of matrix objects created. In this case, two dimensions going down multiplied by one dimension 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 their enclosing repeating frame. In matrix reports, the matrix object must be on a layer above the repeating frames that it relates (i.e., the across/down dimension repeating frames). The innermost matrix object must be on a layer above the outermost matrix object. The child dimension repeating frame must be on a layer above the parent dimension repeating frame. Nested Matrix Defaulting with Summaries Assume you only have one group tree, you selected the cross product group, four groups inside of it, and one group below it. Assume that each group contains one column. Generated Objects: The objects generated are almost identical to the nested matrix report without summaries. The difference is that you have two dimensions going across the top of the matrix instead of one. Consequently, you have two across repeating frames instead of one. In addition, fields and boilerplate are generated for the summaries. The fields are placed in the layout according to the position and Product Order of their source columns in the data model. Below is a list of the summaries (their numbers correspond to the numbers in the diagram that follows):
Defaulting
2 31
Owned by crossproduct group. Product Order: all possible combinations of all four groups (G_State, G_City, G_Dept, G_Job). Owned by crossproduct group. Product Order: G_State, G_Job, G_Dept. Owned by crossproduct group. Product Order: G_Job, G_Dept. Owned by crossproduct group. Product Order: G_Dept, G_State, G_City. Owned by crossproduct group. Product Order: all possible combinations of G_State and G_Dept. Owned by crossproduct group. Product Order: G_Dept Owned by crossproduct group. Product Order: G_State, G_City Owned by crossproduct group. Product Order: G_State Owned by the report. Because this summary is not within the matrix (i.e., it is owned by the report), it has no Product Order.
2 3 4 5 6 7 8 9
Appearance:
2 32
Layers: The layers are identical to those of the nested matrix report without summaries. The only differences are the fields and boilerplate that appear for the summary columns, the additional across repeating frame, and the two additional matrix objects. Matrix Break Defaulting without Summaries Assume you only have one group tree, you selected the cross product group, a group that is its parent, two groups inside of it, and one group below it. Assume that each group contains one column. Generated Objects: Your Layout editor will contain the following objects: B_columnname For the label of each selected column in the Default Layout dialog box. (B_ implies it is a boilerplate object.) For each column that you selected in the Default Layout dialog box. (F_ implies it is a field.) For each group that you selected in the Default Layout dialog box. (R_ implies it is a repeating frame.) For each group that you selected in the Default Layout dialog box. (M_ implies it is a frame; HDR implies it is a header frame. M_groupname_HDR is used to protect field labels from being overwritten by other objects in the report.) For each pair of repeating frames that intersect to form the matrix. By multiplying the number of across dimensions by the number of down dimensions, you can calculate the number of matrix objects created. In this case, two dimensions going down multiplied by one dimension going across yields two matrix objects.
M_groupname_ HDR
X_groupname
Defaulting
2 33
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 their enclosing repeating frame. In matrix reports, the matrix object must be on a layer above the repeating frames that it relates (i.e., the across/down dimension repeating frames). The across dimension repeating frame also must be on a layer above the down dimension repeating frame. Matrix Break Defaulting with Summaries Assume you only have one group tree, you selected the cross product group, a group that is its parent, two groups inside of it, one group below it, and three summary columns. One summary column that sums salary by department, one that sums salary by job, and one that sums all salaries by year. Generated Objects: The objects generated are the same as a matrix break report without summaries, except for the additional fields and boilerplate for the summary columns.
2 34
Appearance:
Layers: The layers are identical to those of the matrix break report without summaries. The only differences are the fields and boilerplate that appear on Layer 0 for the summary columns. Matrix Restrictions 1. A crossproduct group cannot contain another crossproduct group (i.e., crossproduct groups cannot be nested within each other). A crossproduct group must have a child group. The crossproduct group contains the dimensions of a matrix and its child is needed to fill the dimensions with data. Without the child, the data model would make no sense. A crossproduct group cannot have a filter on it. A crossproduct group cannot contain a placeholder column. A crossproduct group must contain at least two dimension groups. A matrix requires at least two dimensions (one going across and one going down) and, as a result, the crossproduct must contain at least two groups.
2.
3. 4. 5.
Defaulting
2 35
6.
In multiquery data models, you need more than two queries because separate queries are required for the down and across dimensions. You need at least two queries because dimension groups from the same query must have repeating frames with the same Print Direction. Consequently, if you did not have two or more queries in the crossproduct group, your dimensions would either be all down or all across dimensions, which wouldnt make any sense. In addition to having separate queries for dimensions, the data for the matrix cells must also be selected by a separate query. For example, in the data model below, one query (Q_YrD) selects values for the down dimensions (year and department) and one query (Q_Job) selects values for the across dimension (job). Another query (Q_Sum) selects the data for the matrix cells. In this case, it would be invalid to have only one query for YEAR, DEPTNO, and JOB. In addition, it would be invalid to have SAL selected by Q_YrD or Q_Job.
7.
For multiquery data models with crossproduct groups, the following rules apply:
You cannot create links between crossproduct groups or their contents.
2 36
You cannot create links between the children of crossproduct groups and queries whose groups are contained in crossproduct groups. This would create a circular dependency. You cannot create links between the children of crossproduct groups and queries whose groups are the parents of crossproduct groups. This would create a circular dependency. You cannot create a direct link between a dimension group (a group inside the crossproduct group) and anything outside of the crossproduct group. All links that go outside of the crossproduct group emanate from the crossproduct group. You cannot create a link the crossproduct group to its parent or one of its dimension groups.
8.
If you have a multiquery data model, then all of the groups of a query must either be inside or outside of the crossproduct group. You cannot have some of a querys groups inside and some outside of the crossproduct group. (Note that in singlequery data models, a query can have some of its groups inside and some of its groups outside of the crossproduct group.) Matrix objects cannot be anchored to anything (i.e., they may not be the parent or child object for an anchor).
9.
10. When you create layout objects for a matrix report, you must be careful where you place them. You need to place objects such that it is clear where you want the object to appear. In the diagram below, objects B_1, B_2, B_3, B_4, and B_5 are placed ambiguously. Oracle Reports would be unable to determine whether the objects should appear beside, above, or below the nearest repeating frame. For example, it is impossible to tell whether B_3 should appear below R_D_2 or to the right of R_D_2. A layout like the one below would cause unpredictable results.
Defaulting
2 37
In the diagram below, objects B_1, B_2, B_3, B_4, and B_5 are placed correctly. It is clear to Oracle Reports where the objects should appear in relationship to the repeating frames.
Note: If the objects in the layout above had Expand or Variable sizing and grew such that their positioning became ambiguous, an error would be raised when you ran the report. For example, if object B_2 grew horizontally beyond the right edge of R_A_2, an error would be raised. Similarly, an object anchored to B_2 would also need to be able to fit within the boundary defined by R_A_2. 11. While you can have matrices with nested dimensions (i.e., a nested matrix report), you cannot have one matrix contained entirely inside another matrix. For example, the layout below is invalid and would cause and error when run:
2 38
12. Layout objects that you want to appear inside the matrix must be entirely within the border defined by the outermost repeating frames of the matrix. In the diagram below, object B_1 would cause an error when the report is run. Object B_2 would not cause an error.
13. The following areas in a matrix layout can only contain fixed sized objects:

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 a field) can have its Vertical Sizing be variable (i.e., Variable, Expand, or Contract). It cannot have its Horizontal Sizing be variable.
Defaulting
2 39
15. If you want a layout object to appear completely outside of the matrix, you should create a frame around the matrix and place the object outside of the frame. This ensures that the matrix will not overwrite the object. 16. You can put a border on a matrix object, its dimension repeating frames, or the fields and repeating frames inside of it just as you would any other object. The width, however, will always be the minimum width possible. You cannot widen the border due to the closeness of the objects in a matrix layout. 17. If a repeating frames source group is a dimension group (i.e., a group within a crossproduct group), then the repeating frame must appear inside the repeating frame(s) of its source groups ancestors (if any). For example, in the data model shown below, the repeating frame with a source group of G_Dept would have to be placed inside of the repeating frame with the source group of G_Year.
2 40
Global Layout Defaulting Rules

1. Unless otherwise noted, a group with a Repeat direction of Across defaults identically as a group with a Repeat direction of Down, except that the default format is transposed. To quickly determine the 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 counterclockwise 90 degrees. 2. In form letter reports, all default fields are hidden, and have a Horizontal Sizing of Variable and a Vertical Sizing of Fixed. In mailing label reports, all default fields have a Horizontal and Vertical Sizing of Fixed. And, in all other reports (tabular, form, master/detail, and matrix reports), those fields have a Horizontal and Vertical Sizing of Fixed. The only exception to this rule is found in the next rule. If you select one the following columns in the Default Layout dialog box:

3.
a CHAR column and you reduce its default Width in the Default Layout dialog box a LONG column
Oracle Reports will do the following for tabular, form, master/detail, and matrix reports: create a default field with a Horizontal Sizing of Fixed and a Vertical Sizing of Variable. As a result, all of the fields data will be displayed, instead of truncated, by wordwrapping any data to the next lines. Caution: For form letter and mailing label reports, Oracle Reports will create a default field with a Horizontal and Vertical Sizing of Fixed. As a result, the data of that field will be truncated if the size of the data is greater than the size of the field. 4. When you default a layout, and one or more selected fields have a Horizontal or Vertical Sizing of Variable, Oracle Reports will do the following for Down reports:
create a frame called M_groupname_EXP that has a width equal to the width of the repeating frame that owns the variablesized field, and a length of one field place the frame around that variablewidth field and any other fields that are found to the right or left of it
Defaulting
2 41
It does this to ensure that all fields to the right and left of the Variable field begin to print on the same line, even though the Variable field may span several lines. Note: For Across reports, transpose the rule. 5. All fields and boilerplate have a Print Condition Type/Object of Default/Anchoring, except for matrices. (That is, it will take on the Print Condition of the frame or repeating frame that owns it.) Summaries that are owned by the report, not by a group, are allowed in all report layout styles. They are all formatted in the following way:
Rules About Summaries
6.
If the layout style is form, form letter, or mailing label, the summary is a report column. A report column is formatted like any other database column for that report style. If the layout style is tabular, master/detail, or matrix, and the column on which the summary performs its function is not selected, the summary is a report column. (It is formatted as is stated in the bullet above.) Otherwise, the summary is a report summary. It is formatted leftjustified 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 matrix reports only. 7. A summary is defaulted like a database column if the column it summarizes is not selected. Otherwise, a summary is defaulted like summaries (i.e., appearing inside the M_groupname_FTR frames).
2 42
8.
Oracle Reports places one summary type perline, in the following order:

SUM AVERAGE MINIMUM MAXIMUM COUNT FIRST LAST % OF TOTAL STANDARD DEVIATION VARIANCE
9.
The summary label will appear to the farleft of the group footer frame (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 create implicit anchors at runtime. This algorithm is the same for the header, body, and trailer regions. The margin algorithm differs slightly.
Header/Body/Trailer Algorithm
1.
Determine which objects are not entirely enclosed by a repeating frame of frame (directly or indirectly), or explicitly anchored to an object that is enclosed by a frame or repeating frame (directly or indirectly). Well call these objects Type A objects. (Type A objects are typically group frames, repeating frames, other objects you create that are not owned by a frame or repeating frame, etc..) An object is considered to be enclosed by another object only if all of the following are true:

Both objects belong to the same region (Body, Margin, Header, or Trailer). The outermost of the two objects is a frame or repeating frame. The outermost of the two objects is behind the other object.
Defaulting
2 43
The innermost of the two objects lies entirely within the borders of the other object.
2. 3.
Determine all children objects of a frame or repeating frame (these are the nonType A objects). Well call these objects Type B objects. Follow this procedure for Type A and Type B objects independently: 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 Sizing of Variable or Expand, and a second object is located in its push path (i.e., in the area in which it can possibly grow). Also, a repeating frame with a Horizontal and/or Vertical Sizing of Fixed or Contract has a push path: its Repeat Direction. 3.3 Create pairs of objects found in step 3.2. Each pair must contain 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 anchorthose objects are ignored. 3.4 Go through this loop. For each pair, determine the distance in the push path between the pusher and pushee. Next, find the pair with the shortest distance. Finally, create an implicit anchor between those two objects using this algorithm: If the push path direction is Down, anchor the pushee objects top 0% to the pusher objects bottom 0%. If the push path direction is Across, anchor the pushee objects left 0% to the pushed objects right 0%. That pair is now treated like one object, and the loop continues until either all objects have one anchor, or nothing will push the remaining, unanchored objects. 3.5 For each remaining, unanchored object, create an implicit anchor from the topleft corner of the object to the topleft corner of the region (header, body, or trailer). 3.6 Move to the next layer, and follow the procedure starting at step 1.
2 44
Rules: 1. If an object is in the push path of two other objects and it is equidistant from the other two objects, the implicit anchoring of the object may vary between executions of the report. For example, the drawing below shows two cases where this could occur:
Defaulting
2 45
In the first case, M_Sums is in the push path of both B_Text1 and R_Ename. Because M_Sums is equidistant from B_Text1 and R_Ename, though, Oracle Reports normal criteria (shortest distance) for determining implicit anchors does not work in this case. Consequently, Oracle Reports will randomly create an implicit anchor between M_Sums and either B_Text1 or R_Ename at runtime. To avoid this behavior, you could create an explicit anchor between M_Sums and B_Text1 or R_Ename. In the second case, B_Text3 is in the push path of M_Emp. Since the bottom edges of M_Emp and R_Mgr are virtually in the same position, though, Oracle Reports cannot determine whether to implicitly anchor B_Text3 to M_Emp or R_Mgr. Consequently, Oracle Reports will randomly create an implicit anchor between B_Text3 and either M_Emp or R_Mgr at runtime. To avoid this behavior, you could create an explicit anchor from B_Text3 to one of the objects or remove the explicit anchor between R_Ename and B_Text2. Removing the explicit anchor would cause Oracle Reports to treat R_Mgr as a descendant of M_Emp and, therefore, the implicit anchor would always be created between B_Text3 and M_Emp. (Note that Case 2 is most likely to occur in character mode, where it is common to have the edges of objects overlap in the Layout editor.)
Margin Algorithm
Create implicit anchors for all Type B objects this region using the Header/Body/Trailer Algorithm. For each Type A object, however, create an implicit anchor from the topleft corner of the object to the topleft corner of the margin. No Type A object will be implicitly anchored to another Type A object. (This ensures that Type A objects will not be pushed off the page. However, they may be overwritten by another Type A object, if they are found on the same layer.)
2 46
Print Condition Algorithm

This section describes the algorithm that Oracle Reports uses to define an objects Print Condition at runtime. This algorithm is the same for the header, body, and trailer regions.
Header/Margin/Body/ Trailer Algorithm
1. 2.
If you specified a Print Condition for an object, Oracle Reports uses that condition. If you specified a Print Condition Type of *Default, then Oracle Reports sets it to either *First or *Last. If the object is a child of an implicit or explicit anchor and its parent has a Print Condition Type of All, All but First, or All but Last, Oracle Reports sets it to *First and Enclosing. If the object is a child of an implicit or explicit anchor and its parent has any other Print Condition Type, Oracle Reports sets it to *Last. Otherwise, for objects that are implicitly anchored to the region (header, body, or trailer), Oracle Reports sets it to *First.
Parameter Form Defaulting

Object Defaulting
When you create a default Runtime Parameter Form for your report, Oracle Reports will create the following parameter form objects for you:

default fields default boilerplate
The circumstances under which Oracle Reports creates these objects are described below. Fields Objects Created/Circumstances Oracle Reports will create one field for each parameter that is selected in the Default Parameter Form dialog box (it is named F_parametername). Ownership The field is not owned by other parameter form objects.
Defaulting
2 47
Ordering The fields will appear in the order in which the parameters appear in the Default Parameter Form dialog box. The dialog box orders the parameters in the following way: first, all default parameters appear in the following orderDESTYPE, DESNAME, DESFORMAT, COPIES, CURRENCY, THOUSANDS, DECIMALnext, all usercreated parameters appear in the order in which they appear in the Parameter property sheet. (Specifically, a usercreated parameter above, or to the left of other usercreated parameters will have its fields appear above others (if two parameters have the same x coordinate, the parameter above the second will appear in the Default Parameter Form dialog box above the second parameter). Settings Name: F_parametername Datatype: Is the datatype on the Parameter property sheet. Source: Is the source on the Parameter property sheet. Boilerplate Objects Created/Circumstances Oracle Reports will create one boilerplate object for each label selected in the Default Parameter Form dialog box (it is name B_parametername). Ownership The boilerplate is not owned by other parameter form objects. Settings Name: B_parametername Type: Is the datatype on the Parameter property sheet.
2 48
CHAPTER
Menus
he menu items for Oracle Reports are described in the online help system. Select Help>Contents for more information.
Menus
31
32
CHAPTER
Report Properties
eport properties are properties that you define for your report as a whole. When you select a report in the Object Navigator and doubleclick on its node or select Tools>Properties, its Report property 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 Properties
41
Report Tab of Report Property Sheet

The Report tab of the Report property sheet is shown below. It contains 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
42
Direction
Is the reading direction for the entire report. Required/Optional: Required. Options: Default means that the reading direction is determined by the NLS environment variables. Left to Right Right to Left
Logical Page Size
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 is one physical page for each logical page. For another example, look at Examples below. Note: Logical Page Size is not necessarily the number of physical pages that the report will require when printed. Required/Optional: Required. Options: Default: Examples: 1. In the following illustration, one logical page is made up of six physical pages. The logical page is three physical pages wide and two physical pages high. Consequently, the Logical Page Size is 3 x 2. If you wanted the logical page to be two physical pages wide and three physical pages high, you would specify a Logical Page Size of 2 x 3. Enter any dimensions of the form A x B, where A and B are whole numbers from 1 through 50. 1x1
Report Properties
43
Panels are the representations of the physical pages within a logical page. Notice in the following illustration that the physical pages continue to number sequentially from the first logical page to the second, while the panel numbers reset; e.g., the first panel of Logical Page 1 is Physical Page 4, while the first panel of Logical Page 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 physical page wide.
44
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 are determined by the positions of the objects on the pages.
Maximum Body Pages
Is the maximum number (wide and tall) of body pages you want to appear in your report. Required/Optional: Required. Options: Default: Enter any dimensions of the form A x B, where A and B are whole numbers from 1 through 999. 10
Maximum Header Pages
Is the maximum number of header pages you want to appear in your report. Required/Optional: Required. Options: Enter a whole number from 1 through 999.
Report Properties
45
Default:
10
Maximum Trailer Pages
Is the maximum number of trailer pages you want to appear in your report. Required/Optional: Required. Options: Default: Enter a whole number from 1 through 999. 10
Page Height
Is the height of one physical page (including the margin) in the Unit of Measurement (e.g., 11 inches). Required/Optional: Required. Options: Enter a valid height of zero or more. The maximum height depends upon the unit of measurement. For inches, the maximum height is 512 inches. For centimeters, it is 1,312 centimeters. For picas, it is 36,864 picas. Note that the page must be large enough to contain the report. For example, if a frame in a report expands to a size larger than the Page Height, the report will not run. Default: Rules: 1. If you change the Unit of Measurement after you have already specified the Page Height, the Page Height will automatically change to the approximate height in the new Unit of Measurement. If you change the width or height of the physical page, the size of the logical page will change accordingly, so that the dimensions of the margin are preserved wherever possible. 11 inches
2.
Caution: On some printers the printable area of the physical page is restricted. For example, the sheet of paper a printer takes may be 8.5 x 11 inches, but the printer might only be able to print on an area of 8 x 10.5 inches. If you define a Page Width x Page Height in Oracle Reports that is bigger than the printable area your printer allows, clipping may occur in your report output. To avoid clipping, you can either increase the printable area for the printer (if your operating system allows it) or you can set the Page Width x Page Height to be the size of the printable area of the page. 3. You can override the dimensions of a page by specifying different values for the PAGESIZE parameter on the command line.
46
4.
The default top and bottom margin is a half an inch each.
Page Width
Is the width of one physical page (including the margin) in the Unit of Measurement (e.g., 8.5 inches). Required/Optional: Required. Options: Enter a valid width of zero or more. The maximum width depends upon the unit of measurement. For inches, the maximum width is 512 inches. For centimeters, it is 1,312 centimeters. For picas, it is 36,864 picas. Note that the page must be large enough to contain the report. For example, if a frame in a report expands to a size larger than the Page Width, the report will not run. Default: Rules: Caution: On some printers the printable area of the physical page is restricted. For example, the sheet of paper a printer takes may be 8.5 x 11 inches, but the printer might only be able to print on an area of 8 x 10.5 inches. If you define a Page Width x Page Height in Oracle Reports that is bigger than the printable area your printer allows, clipping may occur in your report output. To avoid clipping, you can either increase the printable area for the printer (if your operating system allows it) or you can set the Page Width x Page Height to be the size of the printable area of the page. 1. If you change the Unit of Measurement after you have already specified the Page Width, the Page Width will automatically change to the approximate width in the new Unit of Measurement. If you change the width or height of the physical page, the size of the logical page will change accordingly, so that the dimensions of the margin are preserved wherever possible. You can override the dimensions of a page by specifying different values for the PAGESIZE parameter on the command line. The default right and left margin size is zero. 8.5 inches
2.
3. 4.
Panel Print Order
Is the order in which the physical pages comprising a logical page should be printed. It also determines the order in which panels are numbered within the logical page. The figure below illustrates logical pages, physical pages, and panels.
Report Properties
47
Required/Optional: Required. Options: Across/Down means the physical pages of the report body will print lefttoright then toptobottom. Down/Across means the physical pages of the report body will print toptobottom and then lefttoright. Default: Examples: 1. Suppose that you have a logical page size of 2 x 2 (i.e., the logical page is two physical pages wide and two physical pages tall). If Panel Print Order were Across/Down, the order in which the physical pages would print for each logical page would be as follows: Across/Down
48
If Panel Print Order were Down/Across, the order in which the physical pages would print for each logical page would be as follows:
Unit of Measurement
Is the standard of measure used to specify the dimensions of the report and the parameter form. Required/Optional: Required. Options: Centimeter Inch Point is a printers type size that makes up a pica. Each pica contains twelve points and is equivalent to onesixth of an inch. Default: Inch
Report Properties
49
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
Form Height
Is the height of one parameter form page in the Unit of Measurement. Required/Optional: Required. Options: Enter a valid height of zero or more. The maximum height depends upon the unit of measurement. For inches, the maximum height is 512 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 already specified Form Height, the Form Height will change automatically to the approximate height in the new Unit of Measurement.
Form Width
Is the width of one parameter form page in the Unit of Measurement. Required/Optional: Required.
4 10
Options:
Enter a valid width of zero or more. The maximum width depends upon the unit of measurement. For inches, the maximum width is 512 inches. For centimeters, it is 1,312 centimeters. For picas, it is 36,864 picas. 4 inches or 10 centimeters or 300 points
Default: Rules: 1.
If you change the Unit of Measurement after you have already specified the Form Width, the Form Width will change automatically to the approximate width in the new Unit of Measurement.
Number of Pages
Is the total number of pages you want in your Runtime Parameter form. Required/Optional: Required. Options: Default: Enter a number from 1 through 9,999. 1
Previewer Title
Is the text that appears at the top of the Previewer. To change the default title, type the desired text in the field provided. For more information, see Previewer on page 11 1. Options: Enter an alphanumeric string not to exceed 256 bytes. You can restore the default title by deleting whatever title text you entered yourself.
Character Mode Tab of Report Property Sheet

The Character Mode tab of the Report property sheet is shown below. It contains the following properties:

Convert BitMapped 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
Report Properties
4 11
Report Width x Height 4 14 Start in Zoom 4 15 Suppress Previewer Title 4 15 Use Character Units in Designer 4 15
Some charactermode settings (Use Character Units in Designer, Convert BitMapped Objects to Boxes, Convert Borders) apply to charactermode output. These settings take effect whenever you are viewing character mode output (e.g., previewing ASCII output in the Previewer) Other settings (e.g., Start in Zoom) apply to the charactermode environment and only take effect when running the report in a charactermode environment. Oracle Reports is designed to support the native lookandfeel of the environment on which it is running. Therefore, the GUI and charactermode versions of Oracle Reports differ in some respects. For example, charactermode Oracle Reports has a Host item in the File menu. This menu item enables the user to access the operating system from Oracle Reports. In GUI Oracle Reports, this feature is unnecessary because the operating system can be accessed in other ways.
Convert Bitmapped Objects to Boxes
Converts all bitmapped objects (i.e., Oracle Graphics displays and boilerplate objects except for text, lines, and rectangles) to boxes when the report is run in character mode. If this setting is unchecked, all bitmapped objects and any explicit anchors to them will be deleted when the report is run in character mode.
4 12
Default: Rules: 1.
Unchecked.
Lines that are not horizontal or vertical will always be converted to horizontal or vertical lines in character mode, regardless of this setting. Similarly, rotated rectangles will be converted to nonrotated rectangles in character mode, regardless of this setting.
Convert Borders
Turns on borders in character mode for any objects that have a line width greater than zero in bitmapped. If you do not check this setting, all borders are turned off in character mode. Specifying this and Use Character Units in Designer causes the Layout Editor to display charactermode borders for objects with line widths greater than zero. Default: Unchecked.
Disable Host
Disables the Host item in the File menu in both the Runtime Parameter Form and the Previewer. The Host item appears in the File menu of charactermode Oracle Reports. Default: Unchecked.
Disable Split
Disables the [Split Vertical] and [Split Horizontal] function keys. Default: Unchecked.
Disable Zoom
Disables the [Zoom/Unzoom] function key in the Previewer. Default: Rules: 1. If Disable Zoom and Start in Zoom are both checked, the Previewer will be started in zoom and you will be unable to toggle out of zoom. Unchecked.
Previewer Hint Line
Is the line of the Previewer that is displayed on the second to last line of your screen. To change the default hint line, select the check box next to Previewer Hint Line and type the desired text. You can restore the default hint line by deleting whatever hint text you entered yourself. For more information about the Previewer, see Previewer on page 11 1. Options: Default: Enter an alphanumeric string not to exceed 80 bytes. Unchecked and blank.
Report Properties
4 13
Rules: 1. If Previewer Hint Line is unchecked, Oracle Reports does not reserve a line for it. This enables you to see one more line of your report output per screen.
Previewer Status Line
Is the last line of the Previewer. To change the default status line, select the check box next to Previewer Status Line and type the desired text. You can restore the default status line by deleting whatever status line text you entered yourself. For more information about the Previewer, see Previewer on page 11 1. Options: Default: Rules: 1. If Previewer Status Line is unchecked, Oracle Reports does not reserve a line for it. This enables you to see one more line of your report output per screen. When you change the Previewer Status Line, the report name will not appear in the status line unless you enter it there yourself. For example, you could enter:
This report is for Human Resources personnel only (Report: deptinfo)
Enter an alphanumeric string not to exceed 80 bytes. Unchecked and blank.
2.
Report Width x Height
Is the page dimensions for your report in character units. The first number is the page height and the second number is the page width. Required/Optional: Required. Options: Default: Rules: 1. When displaying a character mode report in the bitmapped Previewer of the designer, Oracle Reports uses this setting to choose the font to display. The font may be slightly larger or smaller than the actual character cell size. As a result, when you run a report designed for character mode in the bitmapped Previewer, you may see some truncation. Enter any dimensions of the form A x B, where A and B are whole numbers from 1 through 9,999. 80 x 66 characters
4 14
Start in Zoom
Starts the Previewer as if you had pressed [Zoom], i.e., the border that normally appears around the Previewer is not visible and all you see is the report output. Default: Rules: 1. If Disable Zoom and Start in Zoom are both checked, the Previewer will be started in zoom and you will be unable to toggle out of zoom. Unchecked.
Suppress Previewer Title
Suppresses the display of the Previewer title. Default: Checked.
Use Character Units in Designer
Specifies that the Layout Editor and its grid use units of character cells. Using this and Convert Borders causes the Layout Editor to display charactermode 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 you can document the report. For example, you could describe the purpose of the report so that someone else would be able to quickly understand what it does. Required/Optional: Optional. Options: Default: Enter any text not to exceed 64K. Blank.
Report Properties
4 15
4 16
CHAPTER
Data Model Editor

he Data Model editor enables you to create and edit your reports data model. You should know the following about the Data Model editor:

definition and purpose 5 2 access 5 3 component descriptions 5 3 popup menu 5 7
Data Model Editor
51
Definition and Purpose

The Data Model editor is a work area in which you define the data to be used in your report. You create, define, and modify data model objects (queries, groups, columns, parameters, and links). For more information, see Data Model Properties on page 6 1. Oracle Reports uses the data model to determine what data to retrieve for the report. Note that the data retrieved from the database may or may not appear in the report output. The figure below displays an example data model in the Data Model editor.
52
Access
There are several ways to access the Data Model editor:

Select Tools>Data Model Editor. This menu option toggles between displaying and hiding the Data Model editor. From the Windows menu, select a window with the Data Model editor in it. From the Object Navigator, doubleclick on the Data Model node.
Components
The Data Model editor has the following components:

painting region toolbar tool palette status line
Painting Region
The painting region is the area in which you can create, modify, position, or delete objects while viewing their graphical representations on the screen. Objects have only their relative positions in the data model graphically represented in an editor. To see an objects settings, you must open its property sheet by doubleclicking on the object. The painting region consists of the following:

objects rulers grid
Objects
The data model objects that you can create in the painting region include queries, groups, columns (summary and formula), parameters, and links. For more information on each object, see Data Model Properties on page 6 1. You cannot cut, copy, paste, or duplicate data model objects (i.e., Cut, Copy, Paste, and Duplicate are disabled in the Edit menu).
Data Model Editor
53
Note: Group hierarchy in the data model is determined by parentchild relationships or position in the editor. If there is no parentchild relationship between two groups (e.g., they are siblings or unrelated groups), then the hierarchy is determined by reading from left to right then top to bottom in the Data Model editor. Column hierarchy is determined by reading from top to bottom inside each group. The groups and columns in the Default Layout dialog box are ordered according to the group and column hierarchy in the data model. The order of the groups and columns in the Default Layout dialog box, in turn, determines the order in which objects will appear in the default layout. Rulers 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 the following from Ruler Settings dialog box:

inches centimeters points character cells
Markers Markers move along both of the rulers to track your cursor location in the painting region. The rulers scroll along with the painting region. Likewise, when you magnify part of the painting region, the rulers are updated to reflect the magnification. Ruler Guides Ruler guides provide you with a point of reference for creating and modifying objects. To create a ruler guide, click on one of the rulers and drag into the painting region. Note: To show rulers and ruler guides, select the Rulers and Ruler Guides menu options in the View menu. To hide rulers and ruler guides, deselect these menu options. Grid Inside the painting region is a grid to help you position objects in the painting region. Grid Lines The grid is drawn in relationship to the rulers. From the Ruler Settings dialog box, you specify the interval at which grid lines appear per unit on the ruler. For example, if you have a Unit of inches and a Grid Spacing of 0.5, there will be one grid line per halfinch on the ruler.
54
Toolbar
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 the outline view to select them, then click on the desired tool. The action represented by that tool will be performed on the selected object(s).
Tool Palette
The Tool palette contains the following tools:

Selecting 5 6 Magnify 5 6 Query 5 6 Data Link 5 6
Summary Column 5 6 Formula Column 5 6 Placeholder Column 5 6 Cross Product 5 6
The sections that follow provide information on how to use the Tool palette and brief descriptions of the items in the Tool palette. Activating Tools Only one tool is available for use, or active, at a time. The Selecting tool is the default active tool. There are two ways to activate a different tool:
Position the cursor over the desired tool and click once. This activates the tool for a single operation, such as creating a single query. You can tell that the tool is activated for a single operation because its border is highlighted. After you perform the operation with the tool, the default tool (the Selecting tool) once again becomes active. Position the cursor over the desired tool icon and doubleclick. This locks the tool for multiple operations, such as creating multiple queries consecutively. You can tell that a tool is locked because the entire icon is highlighted. The tool remains the active tool until you click or doubleclick on another tool.
Data Model Editor
55
Constrained Modes
In the Data Model editor, the column tools offer a constrained mode which produces only squares when drawing those objects. Note that the constrained mode only works if you make your column or parameter 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 an operation. By clicking and dragging on a point on an object with the Select tool, you can resize the object. When you select an object(s) in the Data Model editor, it is also selected in the Object Navigator. The Magnify tool magnifies an area around the cursor by a factor of two (i.e., the area becomes twice as big). This tool is useful when you want to focus on one part of a large data model. The Query tool creates a new query in the data model. Once the query is created, you can further define it from its property sheet. The Data Link tool draws a link between a parent group and a child query. Once the link is created, you can further define it from its property sheet. Creating a link is a drag and drop operation. Clicking and dragging from one column to another creates a link between those two columns. Clicking and dragging from one query to another creates all possible links between columns selected by the queries based on database constraints. Clicking and dragging between two groups creates a grouptogroup link (i.e., a link with no columns). The Summary Colum tool creates a new summary column in the data model. Once the column is created, you can further define it from its property sheet. The Formula Colum tool creates a new formula column in the data model. Once the column is created, you can further define it from its property sheet. The Placeholder Column tool creates a new placeholder in the data model. Once the placeholder is created, you can further define it from its property sheet. The cross product tool creates a cross productgroup around two or more other groups. A cross product is a mathematical cross product. Cross products are most often used to build a matrix. Once the crossproduct group is created, you can further define it from its property sheet.
Selecting Tool
Magnify Tool
Query Tool
Data Link Tool
Summary Column Tool
Formula Column Tool
Placeholder Column Tool
Cross Product Tool
56
Status Line
In the Data Model editor, the status line displays the following information:

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 and action being performed. The following table shows what is displayed in the status line under different circumstances: Tool Every tool Magnify Select Action moving mouse clicking mouse dragging rectangle moving object resizing object Status Information x,y coordinates of cursor zoom level x,y coordinates of starting point change in x,y change in x,y
PopUp Menu
The popup menu appears when you click your right mouse button in the Data Model editor.

Cut Copy Paste Clear
Attention: If your platform does not support a right mouse button, then you can use the right mouse button equivalent (e.g., on Mac, the command button plus a mouse click is equivalent to a right mouse click) to access the popup menu.
The popup menu in the Data Model editor contains the following items: Is always disabled. Is always disabled. Is always disabled. Is the same as Edit>Clear.
Properties Is the same as Tools>Properties. This item only appears if the cursor is over an object.
Data Model Editor
57
Program Unit Editor Help
Is the same as Tools>Program Unit Editor. This item only 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 the popup menu, only a subset of these items appears.
58
CHAPTER
Data Model Properties

ata model properties define the objects that make up a data model D for a report. Each object has a property sheet associated with it that defines 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
61
Query Properties
A query contains a SQL SELECT statement that retrieves data from the database for your report. When you doubleclick on a query in the Data Model editor or its icon in the Object Navigator, the Query property sheet is displayed. The Query property sheet is also displayed if you select a query and then select Properties from the Tools 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. It contains the following properties.

External Query 6 3 List 6 4 Maximum Rows 6 4 Name 6 5 SELECT Statement 6 5 Tables/Columns
62
External Query
Is the name of an external query (stored in the database or a file) whose SELECT statement should be used as the querys SELECT statement. Required/Optional: Optional. Options: Enter a valid external query name not to exceed 1K. The external query you reference cannot exceed 32K in length. If it does, it will be truncated and a warning raised. If the query is stored in a file, you can prefix a path to the query name. If a path is not prefixed to the filename, Oracle Reports uses its file path search order to find the file. For more information about file path search order, see FileSearching Method on page 18 9. Note: To ensure the portability of your reports, you can take advantage of the Oracle Reportsspecific environment variable called REPORTS25_PATH. You can use this variable to specify the default directory or directories where you want Oracle Reports to search for external files you use in your reports (e.g., external queries, boilerplate, and PL/SQL). This prevents the need to hardcode directory paths in your report. For more information on setting this variable, see Oracle Reports Environment Variables on page 18 10. If the query is stored in the database, you can prefix DB: to it to indicate that it is stored in the database. For example:
DB:myquery
If you prefix DB: to the query name, Oracle Reports will go directly to the database to find the query. If you are not connected to the database, Oracle Reports will not be able to find the query and will issue a message to that effect. Default: Rules: 1. The SELECT statement of the external query you reference from this field is validated when you accept the Query property sheet. Blank.
63
2.
If you update the external query, you must ensure that the update does not invalidate the report definition. For example, if the report has a column for DEPTNO and you delete DEPTNO from the SELECT list of the external query, the report cannot run. When you specify an external query name, the SQL SELECT statement of the external query appears in the SELECT Statement field as readonly. To modify it, you must open the external query.
3.
List
Is a button that brings up the Display dialog box. After you accept this dialog box, the External Query from File or External Query from Database dialog box appears. From these dialog boxes, you can select an 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 that you specify in this field. When you are designing a report, you often must run it many times to see how it looks. If your report retrieves a lot of data, this can be very time consuming. This property can improve performance by reducing the amount of data retrieved and formatted. To restrict the rows retrieved by some, but not all, of a querys groups, use Filter in the Group property sheet. For more information, see Filter on page 6 15. Required/Optional: Optional. Options: A whole number from 1 through 32K. Blank means that all the rows selected by the query should be retrieved. Default: Rules: 1. Rows that were not retrieved because they were beyond the maximum will not be used in any Oracle Reportsspecified calculations. For example, if you set Maximum Rows to 5 on a child query, then a summary of the child contained in the parent group 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 the report output, use a Format Trigger to restrict what appears in the output. For more information, see Format Trigger on page 13 28. Blank
Maximum Rows
64
Name
Is the name that Oracle Reports uses to identify the current query. Required/Optional: Required. Options: Enter a valid name not to exceed 30 bytes. For more information on naming conventions, see Naming Conventions on page D 1. Q_n, where n is a number that is unique among query names of the report.
Default:
SELECT Statement
Is a SQL SELECT statement that retrieves data from the database for your report. In building your SQL SELECT statement, you can do the following:

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. Required/Optional: Required. Options: Enter a valid SELECT statement not to exceed 64K. The upper limit may vary between operating systems. Refer to your Installation and Users Guide. All features of the SELECT statement are supported, except the INTO and FOR UPDATE clauses.
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. */
65
2.
Following is an example of a SELECT statement that uses bind and lexical references:
SELECT CUSTID, SUM(TOTAL) TOTAL FROM &FROMGROUP HAVING SUM(TOTAL) > :MINTOTAL
where:
&FROMGROUP
Is ORD GROUP BY CUSTID (or some other value that you enter at runtime). Note that, in this case, you must define a parameter named FROMGROUP with an Initial Value specified. If the value of &FROMGROUP is null when the SELECT statement is parsed, you will get an error because the statement has no table name after FROM. Is a column from another query that is used to select customers with a minimum total of orders.
:MINTOTAL
For more information on bind and lexical references, see SQL Topics on page E 1. 3. Following is an example of a SELECT statement that uses a lexical reference to a parameter:
SELECT ENAME, EMPNO FROM EMP WHERE ENAME LIKE UPPER (&NAME)
where:
&NAME
Refers to a parameter with a default value of JO%. Note that you can also specify a value for 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. For details, see the ORACLE7 Server SQL Language Reference Manual. Oracle Reports checks the syntax when you leave SELECT Statement and when the report is generated or executed. No semicolon, slash, or any other character should be used to end the SELECT statement.
2.
66
3.
You must have the appropriate privileges on the tables and views referenced in the SELECT statement in order for the SELECT statement to be validated. A query that is the child in a link with a SQL Clause of START WITH should contain a CONNECT BY clause in its SELECT Statement (without a START WITH clause, since that is in the Link property sheet). Similarly, a query that is the child in a link with a SQL Clause of HAVING should contain a GROUP BY clause in its SELECT Statement (without a HAVING clause, since that is in the Link property sheet). If SELECT expressions are added to, renamed in, or deleted from a query, Oracle Reports automatically creates or deletes the corresponding columns. If the layout has been defined (i.e., the Layout editor contains objects), Oracle Reports will not update the Layout editor based upon changes to the SELECT statement. You must update the effected layout objects in the editor manually or create a new default layout for the report. The reason Oracle Reports does not update the layout for you automatically is that you could inadvertently lose manual modifications to your layout. If you make any changes in the database to the datatype or name of columns that are selected by your query, you must manually make whatever changes are necessary to the Oracle Reports columns and fields that use the changed column as a Source.
4.
5.
6.
Caution: If the width of a column in the database is increased after you have created your report, you need to update both the data model and the layout to reflect the change. Otherwise, truncation may occur. Database columns are automatically updated when the query is reparsed (e.g., enter a space in SELECT Statement and select OK). Summaries, formulas, and placeholders whose source columns have increased in width must have their own widths updated manually. Similarly, fields in the layout must be resized or have their sizing settings changed to accommodate the increased size of their source columns. 7. The order of the columns in the SELECT statement determines the initial column order. Subsequent changes to the order of columns in the SELECT statement will not change the order of the columns. If you add new columns to the SELECT statement, they will be added at the end of the lowest child group belonging to the query. The order of the columns is used to order the associated fields in the default layout.
Tables/Columns
Is the same as Tools>Tables/Columns.
67
Comment Tab of Query Property Sheet

The Comment tab of the Query property sheet contains a field in which you can document the query. For example, you could describe the purpose of the query so that someone else would be able to quickly understand what it does. Note: You can also insert comments directly into your SELECT statement using Oracles standard SQL comment delimiters (e.g., /* comment */). For more information, see the ORACLE7 Server SQL Language Reference Manual. Required/Optional: Optional. Options: Default: Enter any text not to exceed 64K. Blank.
Link Properties
Links relate the results of multiple queries. When you doubleclick on a link in the Data Model editor, the Link property sheet, shown below, is displayed. The Link property sheet contains the following properties:

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 Model Editor on page 5 1.
68
A link (or parentchild relationship) causes the child query to be executed once for each instance of its parent group. From the Link property sheet settings, Oracle Reports constructs a clause that will be added to the child querys SELECT statement at runtime. The column names in Parent Column and Child Column are the columns that relate the parent group to the child query. These fields are readonly, their values are derived from what you have drawn in the Data Model editor. The value in Condition tells Oracle Reports how to relate these two columns (e.g., DEPT.DEPTNO = EMP.DEPTNO). SQL Clause is the type of clause you want to be used in creating the link (e.g., WHERE). The diagram below illustrates a link.
69
Examples: 1. Suppose that you are creating a master/detail report with the following two queries:
Q_1: SELECT DISTINCT ENAME, EMPNO FROM EMP WHERE JOB = SALESMAN SELECT REPID, AMOUNT FROM SALES ORDER BY REPID
Q_2:
To join these two queries, you create a link such that the Link property sheet settings are as follows: SQL Clause
WHERE
Parent Column
EMPNO
Condition
=
Child Column
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 a break group for ENAME and EMPNO. For more information about 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 something like the figure below.
Ename ALLEN Empno 7499 Repid 7499 7499 7499 7499 7499 7499 7499 7499 7499 7499 7499 7654 7654 7654 7654 7844 7844 Amount 3000 810 847 24 1500 340 240 400 180 280 250 16569 2301 3306 5600 350 485
MARTIN
7654
TURNER
7844
6 10
7844 7844 7844
293 50 1703
2.
Suppose that you wanted to create a report that listed employees by their position in the management hierarchy. Following are the queries you might use:
Q_1: Q_2: SELECT EMPNO FROM EMP WHERE JOB = MANAGER 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 Link property sheet settings are as follows: SQL Clause
START WITH
Parent Column
EMPNO
Condition
=
Child Column
EMPNO1
Using a tabular default layout, your output would look something like the figure below.
Empno 7566 Ename JONES SCOTT ADAMS FORD SMITH BLAKE ALLEN WARD MARTIN TURNER JAMES CLARK MILLER Job Empno1 MANAGER 7566 ANALYST 7788 CLERK 7876 ANALYST 7902 CLERK 7369 MANAGER 7698 SALESMAN 7499 SALESMAN 7521 SALESMAN 7654 SALESMAN 7844 CLERK 7900 MANAGER 7782 CLERK 7934 Mgr 7839 7566 7788 7566 7902 7839 7698 7698 7698 7698 7698 7839 7782 Level 1 2 3 2 3 1 2 2 2 2 2 1 2
7698
7782
Rules: 1. If you are creating a link with columns specified, then you must have both a parent and a child column and the columns must have compatible datatypes. For example, if the parent column is a character datatype (e.g., VARCHAR) then the child column also must be a character datatype (e.g., CHAR). For more information about rules regarding links in data models with crossproduct groups, see Matrix Restrictions on page 2 35.
2.
6 11
Child Column
Is a column in the child query that relates to a column in the parent group (i.e., parent column). The Child Column must be a database column, it cannot be a summary or formula. It also cannot depend upon a lexical reference (look at Rules below). For more information on 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 should be determined by a lexical reference. To achieve this functionality, you need to create a link with no columns specified and then enter the SQL clause (e.g., WHERE) for the link directly in the query. For example, your parent and child queries might be written as follows:
Parent Query: Child Query: SELECT DEPTNO FROM EMP 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 example assumes that you have created a link between the queries in the Data Model editor with no columns specified.
Child Query
Is the name of the query defined as the child when you created the link in the Data Model editor. This field is readonly. For more information on creating and accessing links, see Data Model Editor on page 5 1. Rules: 1. A Child Query can have only one Parent Group. Multiple parents for the same child are not allowed.
Condition
Is a SQL operator that defines the relationship between Parent Column and Child Column. For details, see the ORACLE7 Server SQL Language Reference Manual. Required/Optional: Required, if a Parent Column is specified. Options: = < <= <> > >= (equal to) (less than) (less than or equal to) (not equal to) (greater than) (greater than or equal to)
6 12
Like means that the condition is true when the value in one column matches the pattern in the other column. The pattern can contain % and _ as wildcard characters. Not Like means that the condition is true when the value in one column does not match the pattern in the other column. The pattern can contain % and _ as wildcard characters. Default: = (equal sign)
Parent Column
Is a column in the parent group that relates to a column in the child query (i.e., child column). Parent Column can be a database, summary, or formula column in the parent group. If Parent Column is a summary or formula column, it cannot depend, directly or indirectly, on a column owned by the child query. This field is readonly. For more information on creating and accessing links, see Data Model Editor on page 5 1. Is the name of the group defined as the parent when you created the link in the Data Model editor. This field is readonly. For more information 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 without specifying any columns by which to link. This establishes a relationship between the two objects; however, all of the detail records will appear for each master record in the parent group. A Parent Group cannot have the Child Query as one of its ancestors. In other words, your links cannot create a circular dependency (i.e., a situation where the child query depends on the parent group and the parent group depends on the child query).
Parent Group
2.
SQL Clause
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. Options: HAVING START WITH WHERE Default: WHERE
6 13
Rules: 1. If you use a SQL Clause of START WITH, then the SELECT Statement of the Child Query should contain a CONNECT BY clause (without a START WITH clause, since that is contained in this property). Similarly, if you use a SQL Clause of HAVING, then the SELECT Statement of the Child Query should contain a GROUP BY clause (without a HAVING clause, since that is contained in this property).
Group Properties
Groups are created to organize the columns in your report. When you doubleclick on a group in the Data Model editor or its icon in the Object Navigator, the Group property sheet is displayed. The property sheet is divided into the following tabs:

6 14
Rules: 1. 2. Any group that is not the lowest group owned by a query must contain at least one column with Break Order specified. For rules regarding crossproduct groups, see Matrix Restrictions on page 2 35.
General Tab of Group Property Sheet

The General tab of the Group property sheet is shown below. It contains the following properties.

Edit 13 23 Filter 6 15 Name 6 16
Edit
Is a button that displays the Program Unit editor in which you can enter your PL/SQL group filter. For more information about group filters, see Group Filters on page 13 23. Is a set of radio buttons that specifies the type of filter Oracle Reports should use on the records being fetched for the group. To restrict the rows retrieved by the entire query, use Maximum Rows in the Query property sheet. For more information, see Maximum Rows on page 6 4. Required/Optional: Optional.
Filter
6 15
Options:
Condition means that a PL/SQL function for determining which records to include in the group will be defined (or referenced). Select Edit to access the group filter. First means that the first n records retrieved should be included in the group. n is a number specified in the field next to First. Last means that the last n records retrieved should be included in the group. n is a number specified in the field next to Last. No Filter means that you are not using a filter for the group.
Default: Examples: 1.
No Filter
Suppose that you have a group named EMP that contains two columns (ENAME and SAL). The parent group of EMP is DEPT, which contains one column (DEPTNO). You specify a Filter of First 3 for DEPT and a Filter of First 5 for EMP. This will return the first three department numbers retrieved by Oracle Reports with the first five names and salaries retrieved for each department.
Rules: 1. 2. 3. If Filter is First or Last, you must specify a positive whole number in the associated field. The number cannot exceed 64K in size. A crossproduct group cannot have a filter on it. Records excluded from the group by filter are not used in computations. If you want to use data in calculations but not have it appear in the report output, use a Format Trigger to restrict what appears in the output. For more information, see Format Trigger on page 13 28.
Name
Is the name Oracle Reports uses to identify the current group. Required/Optional: Required. Options: Enter any valid group name not to exceed 30 bytes. For more information on naming conventions, see Naming Conventions on page D 1.
6 16
Default:
G_queryname, where queryname is the name of the query and a number that is unique among groups. If the query has a default name (e.g., Q_1), the default group name is of the form: G_n, where n is a number that is unique among group names for the report. If the group is not associated with a query (i.e., a cross product group), the default group name is also G_n.
Comment Tab of Group Property Sheet

The Comment tab of the Group property sheet contains a field in which you can document the group. Required/Optional: Optional. Options: Default: Enter any text not to exceed 64K. Blank.
Common Column Properties

A column contains data for your report. When you doubleclick on a column in the Data Model editor or its icon Object Navigator, a property sheet is displayed. Columns have a number of properties in common. These common properties appear on the following tabs:

General Tab of Column Property Sheets

The General tab of the column property sheets is shown below. It contains the following properties:

Break Order 6 18 Datatype 6 20 Format 6 21
6 17
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 these properties in their General tab.
Break Order
Is the order in which to display the columns values. This property consists of a check box and a list of values. The check box indicates that the column is a break column and the list of values indicates the ordering to use for the columns values. This property applies only to columns that identify distinct values of usercreated groups (i.e., break groups). The order of column values in a default group is determined by the ORDER BY clause of the query. For column values in usercreated groups, however, you must use Break Order to specify how to order the break columns values. Required/Optional: Optional. Options: Ascending Descending Default: Ascending
6 18
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_DEPT contains the DEPTNO column and G_JOB contains the JOB column. If you select the check box and specify a Break Order of Descending for the DEPTNO column and Ascending for the JOB column, your output would appear similar to that below (assuming you use a tabular layout):
Deptno 30 Job CLERK MANAGER SALESMAN Ename JAMES BLAKE WARD MARTIN TURNER ALLEN SCOTT FORD SMITH ADAMS JONES MILLER CLARK KING Sal 950.00 2850.00 1250.00 1250.00 1500.00 1600.00 3000.00 3000.00 800.00 1100.00 2975.00 1300.00 2450.00 5000.00
20
ANALYST CLERK MANAGER CLERK MANAGER PRESIDENT
10
2.
Suppose that you created a break report with DEPTNO and ENAME. In the query, you have ORDER BY DEPTNO. You have also selected the check box and specified a Break Order of Descending for the DEPTNO column. The output would appear similar to that below:
Deptno 30 Ename JAMES WARD MARTIN TURNER ALLEN BLAKE SMITH ADAMS JONES SCOTT FORD MILLER
20
10
6 19
CLARK KING
Notice that the Break Order property takes precedence over the ORDER BY clause (i.e., the department numbers are in descending order). Rules: 1. Break Order has no effect on columns that belong to the lowest group of a particular query. Break Order only effects columns in groups that are above the lowest child group of a query. Every group above the lowest child group of a query must have at least one column with Break Order set. Break Order cannot be specified for columns of Datatype Long or Long Raw. Break Order only affects the ordering of the column on which you are breaking. It does not affect the ordering of the columns within the break group. For example, suppose that you break on DEPTNO and for each department you list ENAME. If the Break Order is Ascending, then department numbers are printed in ascending order, but the names within each department print in the order specified by the query. (You would need to use an ORDER BY clause in your SELECT statement to change their ordering.) A column with a Function of % of Total cannot be a break column and cannot have Break Order set.
2. 3. 4.
5.
Datatype
Is the columns datatype. Required/Optional: Required. Options: Character Date Long Long Raw Number Raw REFmeans that the column is to always retrieve its data from the database. The data will not be cached locally. This is useful for reports with large numbers of images, where caching locally would take up too much space.
6 20
Varchar Varchar2 Note: Trusted Oracle datatypes (MLSLABEL and ROWLABEL) are supported by Oracle Reports. When running on an operating system with Trusted Oracle, Oracle Reports treats these columns as Trusted Oracle datatypes. This means that the columns can be properly sorted. When running on an operating system without Trusted Oracle (e.g., Windows), Oracle Reports treats these columns as character datatypes. Default: For database columns, the default Datatype is derived from the database. For summary columns, the default Datatype is Number, if the Function is Count; otherwise, the default is derived from Source. For formula and placeholder columns, the default 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 to Character, Date, and Number. A column of Datatype Long, Long Raw, or Raw is treated as text unless you specify otherwise in the Format field. For more information, see Format on page 6 21. If a column has an alias and you change your query, causing the datatype of the column to change, the change in datatype will be automatically reflected in Datatype when you accept the query.
2.
3.
Format
Is the format of the object being retrieved by the column from the database. This property tells Oracle Reports whether the object is graphic, image, or text, and the format in which it is stored. This list is similar to the one that appears next to Read from File when it is checked. Options: 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 Oracle format Sound Video
6 21
OLE2 is a linked object to be embedded in your report All the other image formats are provided in case you want to open the report in Oracle Reports Version 2.0. If you are planning to open/run the report in Version 2.0, select the specific image format of the column. If not, you can choose from the above choices. For more information on the available formats, see Oracle Reports File Storage on page 18 2. Rules: 1. 2. Format may only be specified if the column has a Datatype of Long, Long Raw, or Raw. Sound and Video sources can only be accessed from usercreated buttons. For more information on usercreated buttons, see Button Properties on page 8 81.
Name
Is the name that Oracle Reports uses to identify the current column. Required/Optional: Required. Options: Enter any valid name not to exceed 30 bytes. For more information on naming conventions, see Naming Conventions on page D 1. For a database column, the name as referenced in the SELECT list of the SELECT statement. For a summary column, CS_n, where n is a number that is unique among summary names for the report. For a formula column, CF_n, where n is a number that is unique among formula names for the report. For a placeholder column, CP_n, where n is a number that is unique among placeholder names for the report.
Default:
Rules: 1. 2. Name is only editable for summary, formula, and placeholder columns. Oracle Reports uses the column name, alias, or text of the expression from the query as the default name for a database column.
6 22
Read from File
Indicates that the column contains the names of files. When you check Read from File, you then must specify the format of the files in the list of 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 are pointed to by a column in a table. If you check Read from File, the contents of the files will be imported and used as the values of the column. If you do not check Read from File, the column will get its values from the database. As a result, if a column contains filenames and you do not specify Read from File, the filenames will be printed instead of the file contents. You can use Read from File with database, summary, formula, or placeholder columns (assuming that the columns values are filenames). You can also include files in your report as boilerplate. For more information, see Link File on page 8 60. Required/Optional: Optional. Examples: 1. Suppose that for each of your employees you have a .bmp file that contains a picture of the employee. In your employee table, you have a column named PICTURE that contains the name of the .bmp file with the employees picture. To generate a report that displays the employees pictures, you select the PICTURE column in your query. On the Column property sheet for the PICTURE column, you check Read from File and specify Image as the format. Oracle Reports will then display the files pointed to by the PICTURE column wherever you have referenced the PICTURE column in your layout. Note: If you do not specify Read from File, the filenames will be printed instead of the pictures. 2. Suppose that you want to create an employee listing with some text from a file next each employees information. If the employees salary is greater than $2000 you want text from a file called salary1.txt to appear next to the employee. If the employees salary is less than $2000 you want the text from a file called salary2.txt to appear next to the employee.
6 23
You create a formula column with a Datatype of Character and Read from File set (with a format of Text). In the Formula field for the column, 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. 2. 3. The size of each file may be at most 4 gigabytes. (On some operating systems the file may be at most 64K.) Read from File may only be set if the Datatype of the column is charactercompatible (i.e., Character, V ARCHAR, or V ARCHAR2). You can prefix paths to the filenames in the column. If a path is not prefixed to the filename, Oracle Reports uses its file path search order to find the file. For more information about file path search order, see FileSearching Method on page 18 9. Note: To ensure the portability of your reports, you can take advantage of the Oracle Reportsspecific environment variable called REPORTS25_PATH. You can use this variable to specify the default directory or directories where you want Oracle Reports to search for external files you use in your reports (e.g., external queries, boilerplate, and PL/SQL). This prevents the need to hardcode directory paths in your report. For more information on setting this variable, see Oracle Reports Environment Variables on page 18 10. 4. If you set Read from File on a summary or formula column, the summary or formula is calculated before the file is read. Similarly, for placeholder columns with Read from File set, the columns value is calculated first.
Value If Null
Is a value to be substituted for any null values of the column. For example, if you enter X in this field, then an X will be displayed for null values fetched for the column. If left blank, no substitution will be done for null values. Required/Optional: Optional. Options: Enter any valid value that conforms to the columns Datatype. Value if Null cannot exceed 1K in length. Blank.
Default:
6 24
Rules: 1. For columns with a character datatype (e.g., VARCHAR), if the width of the string you enter for Value if Null exceeds the Width of the column, the string is truncated. If a column is referenced via a lexical reference in a query, that columns Value if Null is used to validate the query. The value entered for Value If Null must be the same datatype as the column. For example, if the columns Datatype is Number, you cannot specify XX in Value If Null, you must specify a number. If you enter a date value in Value If Null, it is validated against Oracle Reports internal mask for dates (i.e., DDMONYY). (Number and character values are not validated.) Entering a string for Value if Null on a break column causes Oracle Reports to prefetch all of the rows in the break columns group. This could degrade performance when you run the report. To avoid prefetching, use the NVL function in your query rather than entering a string for Value if Null.
2. 3.
4.
5.
Width
Is the maximum number of characters that the values of the column can occupy. This Width refers to the width that Oracle Reports uses internally for the column. It effects such things as the calculation of summaries and formulas. The size used to display the columns data, however, is determined by the size of the associated field in the Layout editor and its Vertical and Horizontal Sizing properties. Required/Optional: Required. Options: Enter any number from 1 through 64K. Enter two numbers in the form a,b where a indicates the number of digits to the left of the decimal point and b indicates the number of digits to the right of the decimal point. (This form can only be used for defining the width of numbers.) Default: For database columns, the default Width is derived from the database. For summary and formula columns, the default for Width is 10, 0. If a column has a Type of Summary, Oracle Reports updates the Width based upon what you enter as the columns Source and Function.
6 25
Rules: 1. If the columns Type is Database and the Datatype is Character, Date, Number, or Raw, Width is uneditable. However, this does not mean you cannot control the width of the columns values in the report output. You can change the width of the values in the output by modifying the fields width in the Default Layout dialog box or the Field property sheet. If the columns Type is Database or Placeholder and the Datatype is Long or Long Raw, you can enter a value in Width. Note that if you do not specify a width for a Long or Long Raw column, Oracle Reports allocates the maximum width for the column. You can also enter a Width for a column of Type Formula. Caution: If the value of a column of Type Database and Datatype Long or Long Raw exceeds the Width of the column, the value is truncated. 3. 4. If the value of a column of Type Placeholder or Formula exceeds the Width of the column, an exception is raised. If a column has an alias and you change your query, causing the width of the column to change, the change in width will be automatically reflected in Width when you accept the query.
2.
6 26
Comment Tab
The Comment tab is a text field in which you can document the column. Required/Optional: Optional. Options: Default: Enter any text not to exceed 64K. Blank.
Database Column Properties

A database column represents a column that is selected by the query. When you doubleclick on a database column in the Data Model editor or the Object Navigator, the Database Column property sheet is displayed. The Database Column property sheet is also displayed if you select a Database column and then select Properties from the Tools menu. The property sheet is divided into the following tabs:

Rules: 1. Only Oracle Reports can create database columns (it creates one for each item in the SELECT lists of your queries). To create a database column, you must add to the SELECT list of your query and Oracle Reports will then create the database column for you. Database columns can only be deleted by removing the associated item from the SELECT list.
2.
Summary Column Properties

A summary column performs a computation on another columns data. When you doubleclick on a summary column in the Data Model editor or the Object Navigator, the Summary Column property sheet is displayed. The Summary Column property sheet is also displayed if you select a summary column and then select Properties from the Tools menu.
6 27
The property sheet is divided into the following tabs:

General Tab of Summary Column Property Sheet

The General tab of the Summary Column property sheet is shown below. It contains the following properties:

Break Order 6 18 Compute At 6 29 Datatype 6 20 Function 6 32 Name 6 22 Product Order 6 33 Read from File 6 23 Reset At 6 39 Source 6 40 Value if Null 6 24 Width 6 25
6 28
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., SMITHs salary/total department salaries). Compute At defines the total for a percentage calculation. Using this field, Oracle Reports determines 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 valid compute groups. Required/Optional: Required, for summary columns with a Function of % of Total. Options: Page is used to calculate the source column as a percentage of the total values on a page. Report is used to calculate the source column as a percentage of the total values in the report. Select any valid group name(s). Default: Examples: 1. Suppose that you have a report that looks like the one below:
Deptno 10 Dname ACCOUNTING Ename Sal %Dept MILLER 1300.00 14.86% CLARK 2450.00 28.00% KING 5000.00 57.14% Deptno 20 Dname RESEARCH Ename Sal %Dept SMITH 800.00 7.36% ADAMS 1100.00 10.11% JONES 2975.00 27.36% SCOTT 3000.00 27.59% FORD 3000.00 27.59% %Total 6.62% 12.48% 25.48%
The parent group of the summary columns group
%Total 4.08% 5.61% 15.16% 15.29% 15.29%
The parent group, G_DEPT, contains the DEPTNO and DNAME columns. The child group, G_EMP, contains the ENAME and SAL columns.
6 29
To get a summary that calculates each employees salary as a percentage of total department salaries (Pct_Dept), you create a summary column in G_EMP with the following settings: Function % of Total Reset At G_EMP Compute At G_DEPT
In this case, Reset At indicates that the summary should be reset to null for each employee. This is because you want a separate percentage for each individual employee. Compute At indicates that the total of salaries for the department is the whole (100%) across which to compute the percentages. It should also be noted that this summary is placed in the G_EMP group because you want the percentage to appear for each employee. To get a summary that calculates each employees salary as a percentage of total salaries for the entire report (Pct_Total), you create a summary column in G_EMP with the following settings: Function % of Total Reset At G_EMP Compute At Report
In this case, Compute At indicates that the total of salaries for the entire report is the whole (100%) across which to compute the percentages. As with the Pct_Dept summary above, Reset At indicates that the summary should be reset to null for each employee and the summary is placed in the G_EMP group because you want the percentage to appear for each employee. 2. Suppose that you have a matrix report that looks something like the one below and you want to add some percentage summaries to it.
Dept Analyst 10 20 6000 30 Total 6000 Clerk 1300 1900 950 4150 Manager 2450 2975 2850 8275 Total 3750 10875 3800 18425
Group G_JOB contains the column JOB, G_DEPT contains DEPTNO, G_SAL contains SUMSAL, and G_CROSS is the crossproduct group. (G_CROSS contains all of the summaries for the matrix.)
6 30
To get a summary that calculates each job categorys total salaries per department as a percentage of total salaries for that job in all departments, you would enter the following settings for a summary column in G_CROSS: Function % of Total Reset At G_DEPT Compute At G_JOB Product Order G_JOB, G_DEPT
In this case, Reset At indicates that the summary should be reset to null for each department. This is because you want a separate percentage for each individual department. Compute At indicates that the total of salaries for the job category is the whole (100%) across which to compute the percentages. It should also be noted that this summary is placed in G_CROSS because all summaries that apply to the matrix itself must belong to the crossproduct group. Note: Because this is a matrix report, you need to use Product Order for the summary. For further information about Product Order, see Product Order on page 6 33. (One of the examples uses the same output as this example and more fully explains the use of Product Order.) This would calculate the percentages as follows:
Dept 10 20 30 Total Analyst Pct_Job 6000 100.00% 6000 (100%) Clerk Pct_Job 1300 31.33% 1900 45.78% 950 22.89% 4150 (100%) Manager Pct_Job Total 2450 29.61% 3750 2975 35.95% 10875 2850 34.44% 3800 8275 18425 (100%)
Rules: 1. 2. Compute At is only editable when the column is a summary and the Function is % of Total. The Compute At group of a summary column may be any group above the summary columns group, including Report and Page, if the summary columns group is not Report. Summary columns that are owned by a crossproduct group cannot have a Compute At of Page. If a summary has a Compute At of Page, then the sizing of the field or boilerplate object that displays it must be fixed. For more information, see Vertical Sizing on page 8 20.
3. 4.
6 31
Function
Is the computation to be performed on the values of the column specified in Source. To create running summaries, you place the column in the appropriate group and use Function in conjunction with Reset At. Required/Optional: Required, if column is a summary column. Options: Average calculates the average of the columns values within the reset group. Count counts the number of records within the reset group. First prints the columns first value fetched for the reset group. Last prints the columns last value fetched for the reset group. Maximum calculates the columns highest value within the reset group. Minimum calculates the columns lowest value within the reset group. % of Total calculates the columns percent of the total within the reset group. Std. Deviation calculates the columns positive square root of the variance for the reset group. Sum calculates the total of the columns values within the reset group. Variance sums the squares of each column values distance from the mean value of the reset group and divides the total by the number of values minus 1. Default: Rules: 1. 2. 3. 4. Function is only editable when the Type of the column is Summary. Sum, Average, % of Total, Std. Deviation, and Variance can only be applied to fields with a Datatype of Number. Oracle Reports sets the Datatype for the summary based on the Datatype of the column being summarized. If the column being summarized is changed, the datatype of the summary changes to match. Blank.
6 32
5. 6.
A reportlevel summary cannot have a Function of % of Total. Such a column would make no sense because it would always be 100%. A column with a Function of % of Total cannot be a break column and cannot have Break Order set.
Product Order
Is the order in which groups are evaluated in the cross product for a summary. Product Order also defines the frequency of a summary, formula, or placeholder in a cross product group. That is, the summary, formula, or placeholder has one value for each combination of values of the groups in its Product Order. Product Order is used only for columns owned by crossproduct groups. Because a cross product relates multiple groups, the groups in the cross product could be evaluated in any one of many different orders. Therefore, when creating a summary for a cross product, you must use Product Order to specify for Oracle Reports which group should be evaluated first, which second, and so on. You must also use Product Order to specify the frequency of a summary, formula, or placeholder within the cross product. Required/Optional: Required, if the column is a summary or formula column belonging to a cross product group. Options: Select a valid group combination.
6 33
Examples: 1.
Job Year 80 Dept 10 20 30 ANALYST
Suppose that you have a matrix report like the one below.
CLERK MANAGER PRESIDENT SALESMAN
800
800 800
81
10 20 30
3000 950
2450 2975 2850
5000 5600
7450 5975 9400 22825 1300 3000 4300
82
10 20 30
1300 3000
83
10 20 30
1100
1100 1100
6000
4150
8275
5000
5600
Group G_JOB contains the column JOB, G_DEPT contains DEPTNO, G_YEAR contains YEAR, G_SAL contains SUMSAL, and G_CROSS is the cross product group. (G_CROSS contains all of the summaries for the matrix.) To get the summary of salaries by job, you create a summary column in G_CROSS with the following settings: Function % of Total Reset At G_JOB Product Order G_JOB
6 34
In this case, you want the summary to calculate a sum for each record of G_JOB (i.e., each job category) so Product Order is G_JOB. (This summary appears along the bottom of the matrix.) For more information about Reset At, see Reset At on page 6 39. To get the summary of salaries by year, you create a summary column in G_CROSS with the following settings: Function Sum Reset At G_YEAR Product Order G_YEAR
In this case, you want the summary to calculate a sum for each record of G_YEAR (i.e., each year) so Product Order is G_YEAR. (This summary appears along the right edge of the matrix directly underneath 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 following settings: Function Sum Reset At G_DEPT Product Order G_YEAR, G_DEPT
In this case, you want the summary to calculate a sum for each department in each year (G_DEPT and G_YEAR). For this summary, G_YEAR has the lowest frequency (i.e., it changes only once for each three records of G_DEPT) and G_DEPT has the highest frequency (i.e., it changes three times for each record of G_YEAR). As a result, G_YEAR (lowest frequency) appears first and G_DEPT (highest frequency) appears second in Product Order. 2. Suppose that you have a matrix report that looks something like the one below and you want to add some percentage summaries to it.
Dept Analyst 10 20 6000 30 Total 6000 Clerk 1300 1900 950 4150 Manager 2450 2975 2850 8275 Total 3750 10875 3800 18425
Group G_JOB contains the column JOB, G_DEPT contains DEPTNO, G_SAL contains SUMSAL, and G_CROSS is the cross product group.
6 35
To get a summary column that calculates each job categorys total salaries per department as a percentage of total salaries for that job in all departments, you would enter the following settings for a summary column in G_CROSS: Function % of Total Reset At G_DEPT Compute At G_JOB Product Order G_JOB, G_DEPT
In this case, you want the summary to go down the matrix and then across. Since the summary goes down the matrix first, G_JOB has the lowest frequency (it changes only once per three departments) and is the first group in Product Order. Since the summary goes across the matrix after going down, G_DEPT has the highest frequency (it changes three times per one job) and is the second group in the Product Order. For more information about Reset At and Compute At, see Reset At on page 6 39. For more information, see Compute At on page 6 29. (Compute At contains an example based on the same output as this example and more fully explains Compute At.) This would calculate the percentages as follows:
Dept 10 20 30 Total Analyst Pct_Job 6000 100.00% 6000 100% Clerk Pct_Job 1300 31.33% 1900 45.78% 950 22.89% 4150 100% Manager Pct_Job Total 2450 29.61% 3750 2975 35.95% 10875 2850 34.44% 3800 8275 18425 100%
To get a summary that calculates each departments total salaries per job category as a percentage of total salaries for that department, you would enter the following settings for a summary column in G_CROSS: Function % of Total Reset At G_JOB Compute At G_DEPT Product Order G_DEPT, G_JOB
In this case, you want the summary to go across the matrix and then down. Since the summary goes across the matrix first, G_DEPT has the lowest frequency (it changes only once per three jobs) and is the first group in Product Order. Since the summary goes down the matrix only after going across, G_JOB has the highest frequency (it changes three times per one department) and is the second group in the Product Order.
6 36
This would calculate the percentages as follows:

Dept 10 20 30 Total 6000 Analyst Pct_Job Clerk Pct_Job 1300 34.67% 1900 950 4150 17.47% 25.00% Manager Pct_Job Total 2450 65.33% 3750 100% 2975 27.36% 10875 100% 2850 75.00% 3800 100% 8275 18425
6000
55.17%
To get a summary that calculates each departments total salaries per job category as a percentage of total salaries in the report, you would enter the following settings for a summary column in G_CROSS: Function % of Total Reset At G_JOB Compute At Report Product Order G_DEPT, G_JOB
In this case, the summary could go across the matrix and then down, or down the matrix and then across because you are computing this summary for the entire report (e.g., Compute At is Report). Product Order could be either G_DEPT, G_JOB (across, down) or G_JOB, G_DEPT (down, across). Note, however, that Reset At must be the group that has the highest frequency: G_DEPT if Product Order is G_JOB, G_DEPT; G_JOB if Product Order is G_DEPT, G_JOB. This would calculate the percentages as follows:
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 like the one below and you want to add a formula to it.
Dept Analyst 10 20 6000 30 Clerk 1300 1900 950 Manager 2450 2975 2850 President 5000 Salesman
5600
6 37
Group G_JOB contains the column JOB, G_DEPT contains DEPTNO, G_SAL contains SUMSAL, and G_CROSS is the cross product group. To add a formula that calculates the sum of aftertax salaries for each department, you first create a summary column (DEPTSUM) in G_CROSS with the following settings: Function % of Total Reset At G_DEPT Product Order G_DEPT
Next, you create a formula (AFTERTAX) in G_CROSS with the following settings: Formula
:deptsum * .9
Product Order G_DEPT
Because the formula is in G_CROSS, you must give it a Product Order. In this case, the frequency of the formula is the same as the summary column, DEPTSUM. This would calculate the formula as follows:
Dept Analyst 10 20 6000 30 Clerk Manager President 1300 2450 5000 1900 2975 950 2850 Salesman Comp 7875 9788 5600 8460
Rules: 1. 2. This field is only available if the summary, formula, or placeholder columns group is a cross product. A summary which is not a running summary (i.e., its Reset At is not Report) must have a Product Order that is a subset of its source columns Product Order. The source column of the summary must be at least as frequent as the summary, which means that the summarys Product Order should be some subset of the source columns Product Order. A running summary (i.e., its Reset At is Report) must have a Product Order that is a prefix of the source columns Product Order. For example, if the source columns Product Order were A,B,C, then the summary columns Product Order would have to be either A (by itself) or A,B. The summarys Product Order could not be B,A.
6 38
Reset At
Is the group at which the summary column value resets to zero (if Function is Count), null (if Function is not Count), or Value If Null (if the column has one). Reset At has a list of values containing valid reset groups. Reset At determines if the summary is a running summary or a periodic (e.g., grouplevel) summary. Required/Optional: Required, for columns of Type Summary. Options: Page is used for pagelevel summaries. The summary is reset between pages. Report is used for summaries that apply to the entire report, such as grand totals. The summary is reset after the report (i.e., it is never reset). Select any valid group name. The summary is reset after each record of the group. Examples: 1. Suppose that you want to create a master/detail report like the one below:
DEPT NAME 10 SMITH JONES KING 20 SAL 1000 1000 1000 RESETSUM 1000 2000 3000 RUNSUM 1000 2000 3000 4500 5500
JOHNSON 1500 1500 WARD 1000 2500
The parent group, G_DEPT, contains the DEPTNO column. The child group, G_EMP, contains ENAME and SAL. To get the sum of salaries for each department (RESETSUM), you create a summary column in G_EMP with the following settings Function Sum Reset At G_DEPT
In this case, Reset At indicates that the summary should be set to null after each department. To get the running sum of salaries (RUNSUM), you create a summary column in G_EMP with the following settings: Function Sum Reset At Report
In this case, Reset At indicates that the summary should not be reset to null but should accumulate throughout the report.
6 39
For more information about how to use Reset At in percent of total calculations, see Compute At on page 6 29. Rules: 1. 2. 3. 4. Reset At is only editable when the Type of the column is Summary. The reset group of a summary column may be its group or any group above its group, including Report and Page. Summary columns that are owned by a crossproduct group cannot have a Reset At of Page. If a summary has a Reset At of Page, then the sizing of the field or boilerplate object that displays it must be fixed. For more information, see Vertical Sizing on page 8 20. If a column has a Reset At of Page, then any fields that use it as a source must be contained in repeating frames that use the columns group as their source.
5.
Source
Is the name of the column whose values will be summarized. Source is a list of values containing those columns that are valid for the specified Function. Required/Optional: Required, if the column is a summary column. Options: Default: Rules: 1. The source of a summary column may be any column within or below the summary columns group (with a valid Datatype for the function). If you change the Source of a summary column, the Datatype of the summary column changes to reflect the Datatype of the new source column, unless the column has Read from File specified. Any column can be the Source of multiple summary columns. If you specify a source for a summary column and later delete the source column from your report, your summary column no longer has access to data to summarize. Select any valid column name. Blank.
2.
3. 4.
6 40
Formula Column Properties

A formula column performs a userdefined computation on another column(s) data. When you doubleclick on a formula column in the Data Model editor or its icon in the Object Navigator, the Formula Column property sheet is displayed. The property sheet is divided into the following tabs:

Rules: 1. You can set placeholder or formula columns to any of the following Datatypes: 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:

Break Order 6 18 Datatype 6 20 Formula 13 25 Name 6 22 Product Order 6 33 Read from File 6 23 Value if Null 6 24 Width 6 25
6 41
Formula
Is a button that displays the Program Unit editor in which you can enter 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.
Product Order
Placeholder Column Properties

A placeholder is a column for which you set the datatype and value in PL/SQL that you define. You can set the value of a placeholder column in the following places:

the Before Report Trigger, if the placeholder is a reportlevel column a reportlevel formula column, if the placeholder is a reportlevel column a formula in the placeholders group or a group below it (the value is set once for each record of the group)
When you doubleclick on a placeholder column in the Data Model editor or its icon in the Object Navigator, the Placeholder Column property sheet is displayed.
6 42
The property sheet is divided into the following tabs:

Examples: 1. Suppose that you wanted to create a master/detail report that would list the highest paid employee(s) for each department. The output 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 PRESIDENT 5000.00 MILLER CLERK 1300.00 Dname RESEARCH Loc DALLAS Ename SMITH JONES SCOTT ADAMS FORD Job CLERK MANAGER ANALYST CLERK ANALYST Sal 800.00 2975.00 3000.00 1100.00 3000.00
KING
Highest Paid Employee(s):
SCOTT and FORD
To get the names of the highest paid employee(s), you create a column named HIGHEST_PAID_EMP of Type Placeholder and Datatype Character. The value of HIGHEST_PAID_EMP is set by a column named SET_HIGHEST_PAID_EMP of Type Formula and Datatype Character. R_COUNT is a column of Type Summary with a Function of Count. SET_HIGHEST_PAID_EMP contains the following 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 employees name */ if (:sal = :max_dept_sal) then if (:highest_paid_emp <> ) then
6 43
:highest_paid_emp := :highest_paid_emp|| and ||:ename; else :highest_paid_emp := :ename; end if; end if; return (:highest_paid_emp); end;
Rules: 1. 2. You can set placeholder or formula columns to any of the following Datatypes: Character, Number, and Date. You can only assign the value of a placeholder column from one group. 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 shown below. It contains the following common column properties:

Break Order 6 18 Datatype 6 20 Formula 13 25 Name 6 22 Product Order 6 33 Read from File 6 23 Value if Null 6 24 Width 6 25
6 44
Edit
Is a button that displays the Program Unit editor in which you can enter 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 parameters icon in the Object Navigator, the Parameter property sheet is displayed. The parameter properties are described alphabetically after the figure. The property sheet is divided into the following tabs:

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 one called System Parameters. User parameters are parameters that you create for the report. System parameters are parameters that Oracle Reports creates for every report. Both user and system parameters can be assigned values at runtime (e.g, from the Runtime Parameter Form or the command line). Note, though, that while you can delete or rename a user parameter you cannot delete or rename a system parameter.
6 45
Additional Information: You can prevent system parameters from appearing on the Runtime Parameter Form. Deselect the parameter in the Default Parameter Form dialog box or delete its related field in the Parameter Form editor. Alternatively, if you do not create your own parameter form, only DESTYPE, DESNAME, and any usercreated parameters will appear in the Runtime Parameter Form. The system parameters are described in the following table: Name BACKGROUND COPIES CURRENCY DECIMAL DESFORMAT Function Is whether the report should run in the foreground or the background. Is the number of report copies that should be made when the report is printed. Is the symbol for the currency indicator (e.g., $). Is the symbol for the decimal indicator (e.g., .). Is the definition of the output devices format (e.g., landscape mode for a printer). Note: This parameter is not used in a bitmapped environment. It is only used when running the report in a charactermode environment. Is the name of the output device (e.g., the file name, printers name, mail userid). Is the type of device to which to send the report output (screen, file, mail, printer, or screen using PostScript format). Is whether the report should run in character mode or bitmap. Is the print direction for the report (landscape, portrait, default). Is whether the Print Job dialog box should appear before the report is run. Is the symbol for the thousands indicator (e.g., ,).
DESNAME DESTYPE
MODE ORIENTATION PRINTJOB THOUSANDS
6 46
General Tab of Parameter Property Sheet

The General tab of the Parameter property sheet is shown below. It contains the following properties:

Datatype 6 47 Edit 13 27 Initial Value 6 48 Input Mask 6 48 Name 6 49 Width 6 49
Datatype
Is the parameters datatype. Required/Optional: Required. Options: Character Date Number Default: Rules: 1. 2. Any values supplied for a parameter must conform to the parameters Datatype, even at runtime. Datatype cannot be edited for packaged parameters (e.g., DESTYPE). Character
6 47
3.
Parameters with a Datatype of Character are not padded, unless you explicitly pad them in a SQL statement.
Edit
Is a button that displays the Program Unit editor in which you can enter 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 is overridden on the command line or the Runtime Parameter Form. If Initial Value is left blank, the parameter has no default value. Required/Optional: Optional. Options: Default: Rules: 1. Initial Value is validated according to the Datatype and Width of the parameter. In addition, Initial Value is validated against format masks:

Initial Value
Enter any value appropriate for the Datatype. Initial Value cannot exceed 1K in length. For DESTYPE, Screen. For DESFORMAT, dflt. For COPIES, 1. For all other parameters, blank.
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., DDMONYY) is used. (Number and character values are not validated unless you specify an Input Mask.)
2.
If no value is specified and the parameter is referenced in SQL or PL/SQL, a null is used to parse the SQL or PL/SQL. If a null causes the SQL or PL/SQL construct to parse incorrectly, an error will be raised.
Input Mask
Is the format mask to be used by Oracle Reports to validate the value supplied for the parameter on the command line or the Runtime Parameter Form. It is also used to validate the Initial Value of the parameter. For more information, see Format Mask on page 8 42. Required/Optional: Optional. Options: Enter any valid format mask not to exceed 128 bytes. Select a value from the list.
6 48
Default:
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 DDMONYY), and when the Datatype is Number, the input format is 9999.
Rules: 1. The values displayed initially in the Input Mask list are determined by the datatype of the parameter (e.g., for a parameter of Datatype Number, only number masks are shown in the list). If you enter a mask not in the list for Input Mask and accept the Parameter property sheet, the new format mask will appear in the list of values. However, these format masks are only valid during the current Oracle Reports session. If you quit Oracle Reports and then invoke it again, the list for the Input Mask field does not contain the format masks you created in the previous Oracle Reports session (unless you open the report(s) that used these masks). To include masks in the list that will be saved between sessions, use Format Masks in the Preferences dialog box (Tools>Options). 2. You cannot enter a format mask for parameters of Datatype Character.
Name
Is the name that Oracle Reports uses to identify the current parameter. Required/Optional: Required. Options: Enter any valid parameter name not to exceed 30 bytes. For more information on naming conventions, see Naming Conventions on page D 1. P_n, where n is a number that is unique among column names for the report. If you create a parameter by making a bind reference in your query, though, the name that you used in the query is the default.
Default:
Rules: 1. You cannot rename system parameters.
Width
Is the maximum number of characters of the parameter value when entered on the command line and the Runtime Parameter Form. Required/Optional: Required. Options: Enter a number from 1 through 64K.
6 49
Default: Rules: 1. 2.
40 characters
Oracle Reports truncates any parameter value supplied at runtime that is longer than Width. 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 shown below. 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 only available for usercreated parameters. System parameters only have the General and Comment tabs.
6 50
Add
Is a button that adds the value in the Value field to the list of static values. Required/Optional: Required, if you want to add to the static values.
Remove Restrict List to Predetermined Values
Is a button that removes the selected value(s) from the list of static values. Is a checkbox that indicates whether a value for the parameter must be in the list of values. For example, if you check Restrict List to Predetermined Values and the Initial Value does not match a value in the list of values, an error will be generated when you accept the Parameter property sheet. Similarly, if you set a value for the parameter on the command line or in a command script and it does not match a value in the list of values, an error will be generated when the report is run. If you check Restrict List to Predetermined Values, a list of values will appear in the runtime parameter form. If you do not check it, a combo box will appear (i.e., you can enter values as well as select from the list). Default: Checked.
Is a radio button that indicates whether you want to use a SELECT SELECT Statement/Static Values statement or a static list to populate the list of values for the parameter. Required/Optional: Required. Options: SELECT Statement indicates that you want to enter a SELECT statement to populate the list of values for the parameter. If you select this option, then you must enter a SELECT statement in the area underneath the SELECT Statement radio button. Static List indicates that you want to manually enter values to populate the list of values for the parameter. If you select this option, you must create a list of values manually. To do this, you enter a value in the Value field and then choose the Add button. Repeat this process for each value you want in the list. To remove value(s), select them in the list and then choose the Remove button.
6 51
Hide First Column
Is a checkbox that indicates whether the first column in your SELECT list should be displayed in the parameters list of values. This setting is useful for hiding values that the user doesnt know about or are confidential. Look at Examples below. Default: 1. Checked.
You want to create a report that lists the employees in a department that the user specifies at runtime. The tables you will be using have DEPTNO as the primary/foreign key. The people using the report do not know departments by number, they only know them by name. The report query would be as follows:
SELECT * FROM EMP WHERE DEPTNO = :MYDEPT
In the Data/Selection tab of the Parameter property sheet, you choose SELECT Statement and enter the following SQL statement to populate the list of values:
SELECT DEPTNO, DNAME FROM DEPT
You then check Hide First Column. This means that DEPTNO will not appear in the list of values when you run the report. Only DNAME will appear. When the user selects a DNAME value from the list, the corresponding DEPTNO value will be used for the parameter MYDEPT.
Value
Is a value that will be added to the static list of values for the parameter when you choose the Add button. Required/Optional: Required, if you want to add a value to the static list. Options: Enter a valid value for the parameter and then choose the Add button to add it to the static list of values.
Comment Tab of Parameter Property Sheet

The Comment tab of the Parameter property sheet contains a field in which you can document the parameter. Required/Optional: Optional. Options: Default: Enter any text not to exceed 64K. Blank.
6 52
CHAPTER
Layout Editor
he Layout editor enables you to create and edit your reports layout. You should know the following about the Layout editor:

definition and purpose 7 2 access 7 3 components 7 3 popup menu 7 18 navigation 7 20 margins 7 21
Layout Editor
71

The Layout editor is a work area in which you define the format of your report output. To do this, you define and modify layout objects (frames, repeating frames, fields, boilerplate, anchors, and Oracle Graphics objects) For more information, see Layout Properties on page 8 1. When you run a report, Oracle Reports uses the Layout editor as a template for the report output. This template will grow or shrink based on the data fetched for and the PL/SQL logic assigned to the layout objects. The figure below displays an example report layout in the Layout editor.
72
Access
There are several ways that you can access the Layout editor:
Select Tools>Default Layout. After Oracle Reports builds the objects for you, you are placed in the Layout editor to see the results of the defaulting. Select Tools>Layout Editor. From the Windows menu, select a window with the Layout editor in it. From the Object Navigator, doubleclick on the Layout nodes icon.
Components
The Layout editor has the following components:

painting region 7 3 toolbar 7 7 tool palette 7 7 status line 7 17
Painting Region
The painting region is the area in which you can create, modify, position, or delete objects while viewing their graphical representations on the screen. Objects have their sizes, relative positions, patterns, colors, and fonts graphically represented in the editor. To see an objects settings, you must open its property sheet by doubleclicking on the object. The painting region consists of the following:

objects 7 3 regions 7 4 rulers 7 6 grid 7 6
Objects
The layout objects that you can create in the painting region include frames, repeating frames, fields, boilerplate, anchors, buttons, OLE2 objects, and Oracle Graphics objects. For more information, see Layout Properties on page 8 1.
Layout Editor
73
Graphic representations (or icons) in the editor indicate the type of object being represented and, in some cases, its settings. The figure below illustrates the meaning of these icons in the editor.
Report Layout Regions
There are three report regions in the Layout editor:

header body/margin trailer
The report regions are illustrated in the following figure and described below the figure.
74
Header
The report header pages appear once at the beginning of each report on a set of separate pages. They can contain text, graphics, data, and computations. The body/margin pages appear between the header and trailer pages, and are the bulk of the report. Each physical page in this section consists of a body and a margin. The body contains the majority of the reports 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, page numbers, page totals, and grand totals. The default margin size is one half inch each for the top and bottom margins and zero for the left and right margins. For more information about the margin, see Margins on page 7 21.
Body/Margin
Layout Editor
75
Trailer
The report trailer pages appear once at the end of each report on a set of separate pages. They can contain text, graphics, data, and computations.
Rulers
Rulers are located around the left and top edges of the painting region. Rulers are initially shown in the Layout editor. To hide rulers, deselect the Rulers menu option in the View menu. Units You can set the unit of measurement of the ruler to any of the following from Ruler Settings dialog box:

inches centimeters points character cells
When you change the reports Unit of Measurement in Global Properties, the ruler units are updated to reflect the Unit of Measurement. When you select Use Character Units in the Character Mode Settings dialog box, the ruler units are changed to character cells. Markers Markers move along both of the rulers to track your cursor location in the painting region. The rulers scroll along with the painting region. Likewise, when you magnify part of the painting region, the rulers are updated to reflect the magnification. Ruler Guides Ruler guides provide you with a point of reference for creating and modifying objects. To create a ruler guide, click on one of the rulers and drag into the painting region. Note: To hide rulers and ruler guides, deselect the Rulers and Ruler Guides menu options in the View menu. To show rulers and ruler guides, select these menu options. Grid Inside the painting region is a grid to help you position objects in the painting region. Grid Lines The grid is drawn in relationship to the rulers. From the Ruler Settings dialog box, you specify the interval at which grid lines appear per unit on the ruler. For example, if you have a Unit of inches and a Grid Spacing of 0.5, there will be one grid line per halfinch on the ruler.
76
Toolbar
The Toolbar contains the following tools in the Layout editor:

Open Save Run Print Cut Copy Paste Default Layout
Body Margin Header Trailer Confine Flex Help
Tool Palette
The Tool palette contains the following tools in the Layout editor:

Selecting 7 9 Frame Select 7 10 Rotate 7 10 Reshape 7 11 Magnify 7 11 Line 7 11
Frame 7 13 Repeating Frame 7 13 Field 7 14 Link File 7 14 Oracle Graphics 7 14 Button 7 14 OLE2 7 15 Additional Default Layout 7 15 Border/Fill/Font display 7 15 Fill Color 7 15 Line Color 7 16 Text Color 7 17
Rounded Rectangle 7 12 Anchor 7 14 Rectangle 7 12 Ellipse 7 12 Arc 7 12 Polygon 7 12 Polyline 7 13 Freehand 7 13 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.
Layout Editor
77
Activating Tools
Only one tool is available for use, or active, at a time. The Selecting tool is the default active tool. There are two ways to activate a different tool:
Position the cursor over the desired tool icon and click once. This activates the tool for a single operation, such as creating a rectangle. You can tell that the tool is activated for a single operation because its border is highlighted. After you perform the operation with the tool, the default tool (the Selecting tool) once again becomes active. Position the cursor over the desired tool icon and doubleclick. This locks the tool for multiple operations, such as creating multiple frames consecutively. You can tell that a tool is locked because the entire icon is highlighted. The tool remains the active tool until you click or doubleclick on another tool. Note: If you are typing/editing text in the editor, you must exit text mode (i.e., click outside of the boilerplate text object) before activating another tool.
Constrained Mode
Some tools offer a constrained mode of operation which makes it easier to draw certain shapes or move objects in a straight line. For example, the constrained mode of operation for the rectangle tool produces only squares. Similarly, the constrained mode of operation for the ellipse tool produces only circles. When moving an object, the constrained mode forces the object to be moved in a straight line (either diagonally, horizontally, or vertically). To perform a constrained operation, hold down the constrain key (usually the shift key, check your platformspecific documentation) while drawing. Constraints are imposed only during the initial creation of objects and will not be retained by the object after creation. For example, when a constrained rectangle operation is used and a square results, that square can later be resized into a rectangle. However, if the constraint key is also used during the resizing operation, the object will retain the constraint characteristics.
78
Confine Mode and Flex Mode
When moving or resizing an object, you often want to ensure that the object maintains the same relationship to its parent object. For example, if you resize a field such that it no longer fits in its parent repeating frame, you will get a frequency error when you run the report. To ensure that objects maintain the correct relationship to their parent objects, Oracle Reports Layout editor provides the following modes:
Confine mode prevents you from performing an operation that would cause the layout not to work. For example, in confine mode, Oracle Reports will not allow you to move a field outside of its parent repeating frame. Confine mode is on by default in the Layout editor. To turn confine mode on or off, use the Confine tool in the toolbar or the Layout tab of the Layout Options dialog box (View>Settings>Layout). Flex mode moves or resizes the object, its enclosing objects, and objects in their push path simultaneously to maintain the same overall relationships in the layout. For example, if you try to move a field outside of its parent repeating frame in flex mode, its repeating frame will grow as necessary to contain it and any objects around the repeating frame will also grow or be pushed as necessary. You can only move or resize objects in one direction at a time (vertically or horizontally, not diagonally). To use flex mode, select the Flex tool in the toolbar or Flex in the Layout Options dialog box, or hold down the Control key while moving 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.
Selecting Tool
The Selecting tool enables you to select an object or a group by clicking on it. To select an object, you click on it with the Selecting tool. If you click on an object that has been grouped together via Group in the Arrange menu, the entire group of objects is selected. To select only one object in a group at a time you must click on the border of the object. By shiftclicking, you can select multiple objects or groups. When you select an object, its control points become visible. When you select an object(s) in the Layout editor, it is also selected in the Object Navigator. Once you have selected one or more objects, you can perform operations on them (e.g., set colors, copy, align). When the Selecting tool is active, you can move objects by clicking on them and dragging them. You can resize objects by dragging their control points.
Layout Editor
79
Scoping Rules Oracle Reports enforces certain scoping rules for selecting objects. These rules are enforced while any object is selected, regardless of whether you use the Selecting or Single Select tool to select other objects. The rules are: 1. The two selecting tools allow you to select only objects that belong to the same group as the currently selected object(s). To select an object in another group (or one not in any group), do one of the following:
First deselect all objects by clicking on an unoccupied part of the Layout editor, then select the other object as you normally would. Choose one of the items in the Arrange>Group Operations submenu.
2.
Frame Select Tool
You can select multiple objects only if they belong to the same grouped set of objects in the Layout editor (i.e., they are siblings).
The Frame Select tool enables you to select a frame or repeating frame and all of the objects within it. Note: Explicit anchors can affect which objects are selected by the Frame Select tool. Any object that is indirectly or directly anchored to an object within the frame or repeating frame will be selected. Any object that is anchored to the frame or repeating frame or an object outside of the frame or repeating frame will not be selected.
Rotate Tool
The Rotate tool enables you to rotate the currently selected objects or groups. You can only rotate boilerplate text and graphics. To rotate the objects or groups, you click and drag a handle of one of the selected objects. The selected objects or groups will rotate in the direction you drag. Note: You cannot rotate a field directly, but you can reference a field (e.g., &ename) in a boilerplate text object, which can be rotated. Rules: 1. You can only rotate boilerplate text that you typed or imported in the editor. You cannot rotate boilerplate text created with the Link File tool. Rotated text is not supported on all operating systems. For example, rotated text will not appear rotated in character mode.
2.
7 10
3.
For rotated text, the Horizontal Sizing setting refers to the direction in which you read the text. For example, if you rotate your text 90 degrees and give it a Fixed Horizontal Sizing, it actually means that the text will occupy a fixed vertical space. If you set Horizontal and Vertical Sizing to Variable or Expand and the rotation angle of the text is not a multiple of 90 degrees, the objects width will actually be treated as contracting (for Variable) or fixed (for Expand).
4.
Reshape Tool
The Reshape tool enables you to change the shape of the selected objects. To reshape objects, you click and drag on their handles. Note that the handles you see when reshaping differ from those you seen when selecting an object. The Reshape tool is only useful for certain objects:
For arcs, the Reshape tool enables you to change the sweep angle to something other than 90 degrees (the default when creating an arc). For polygons, the Reshape tool enables you to move any vertex to a new position. For rectangular objects (e.g., frames, fields, and Oracle Graphics objects), the Reshape tool enables you to move any vertex to a new position. Note that this is only useful if the rectangle has been rotated such that the select handles no longer coincide with the reshape handles. For anchors, the Reshape tool enables you to move any vertex to a new position, including moving the endpoints to new positions on the same or different objects.
Magnify Tool
The Magnify tool magnifies an area around the point on which you click by a factor of two (i.e., the objects become twice as big as they were). By pressing the constraint key while using the Magnify tool, you magnify by a factor of onehalf (i.e., the objects become half as big as they were). This tool is useful when you want to focus on one part of a large layout. The Line tool enables you to draw a line boilerplate object. To draw a line, 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 this chapter).
Line Tool
Layout Editor
7 11
Rounded Rectangle Tool
The Rounded Rectangle tool enables you to draw a rounded, rectangular boilerplate object. Rounded rectangles are drawn by the same method as rectangles. For more information, see Rectangle Tool on page 7 12}. To create squares with rounded corners, use constrained mode. For more information, see Constrained Mode on page 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 the opposite vertex. To draw perfect squares, use constrained mode (look at Constrained Mode earlier in this chapter). Note: The way an object is drawn depends upon the Object Creation setting in the General Drawing Options dialog box. (To get to this dialog box, select Drawing Options from the Format menu and General from the submenu.) If Object Creation is set to Draw from Center, you click where you want the center of the rectangle and drag to a vertex.
Rectangle Tool
Ellipse Tool
The Ellipse tool enables you to draw an elliptic boilerplate object. Ellipses are drawn by the same method as rectangles. For more information, see Rectangle Tool on page 7 12. To create perfect circles, use constrained mode. For more information, see Constrained Mode on page 7 8. The Arc tool enables you to draw an arc boilerplate object. Arcs are drawn by the same method as rectangles. For more information, see Rectangle Tool on page 7 12. To create circular arcs, use constrained mode. For more information, see Constrained Mode on page 7 8. The Polygon tool enables you to draw a polygon boilerplate object. Polygons are drawn by clicking on each vertex of the polygon and doubleclicking on the last vertex. When pressing the constraint key during specification of a polygon vertex, that segment of the polygon will be constrained to the nearest 45 degree increment. Constraining one vertex does not affect subsequent vertices. Each vertex must be individually constrained. For more information on constrained mode, see Constrained Mode on page 7 8. Note: While you are defining a polygon, the only things you can do are define a vertex and move the editor scrollbar.
Arc Tool
Polygon Tool
7 12
Polyline Tool
The Polyline tool enables you to create a polyline boilerplate object. A polyline is similar to a polygon except that its last vertex need not be joined to the first vertex (i.e., the object need not be closed). Polylines are 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 draw with 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 two ways:

Freehand Tool
Text Tool
Click where you want the text to start and begin typing. Text will word wrap only when you type a return to start a new line. Click and drag to create a bounding box for the text. Text entered in the box will word wrap to fit within the horizontal boundaries 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 and start typing/editing. When you are typing or editing text, you are in text mode. To get out of text mode, click outside of the boilerplate text object. While in text mode, you can perform actions on text (such as changing fonts, cutting, copying, or pasting) by selecting menu items. For more information, see Edit Boilerplate Text in Chapter 8 of Building Reports Manual. Note: If you change the font or size of the boilerplate text, the bounding box automatically grows or shrinks with the text.
Frame Tool
The Frame tool enables you to create a frame. Frames are drawn and modified in the same way as rectangles. For more information, see Rectangle Tool on page 7 12. To create perfect squares, use constrained mode. For more information, see Constrained Mode on page 7 8. The Repeating Frame tool enables you to create a repeating frame. Repeating frames are drawn and modified in the same way as rectangles. For more information, see Rectangle Tool on page 7 12. To create perfect squares, use constrained mode. For more information, see Constrained Mode on page 7 8.
Repeating Frame Tool
Layout Editor
7 13
Field Tool
The Field tool enables you to create a field. Fields are drawn and modified in the same way as rectangles. For more information, see Rectangle Tool on page 7 12. To create perfect squares, use constrained mode. For more information, see Constrained Mode on page 7 8. The Link File tool enables you to create a boilerplate object that is read in from a file. The boilerplate may be text, drawings, or images and is represented as a rectangle in the editor. The boilerplate object is drawn and modified with the Link File tool in the same way as rectangles. For more information, see Rectangle Tool on page 7 12. To create perfect squares, use constrained mode. For more information, see Constrained Mode on page 7 8. The Oracle Graphics tool enables you to create an Oracle Graphics object. An Oracle Graphics object is associated with an Oracle Graphics display. The object is executed by Oracle Graphics and incorporated in the report at runtime. The Oracle Graphics object is drawn and modified in the same way as rectangles. For more information, see Rectangle Tool on page 7 12. To create perfect squares, use constrained mode. For more information, see Constrained Mode on page 7 8. The Button tool enables you to draw a button object. Userdefined buttons are drawn using the same method as is used for rectangles. For more information, see Rectangle Tool on page 7 12. To create perfect squares, use constrained mode. For more information, see Constrained Mode on page 7 8. Note: Userdefined buttons will appear in the Previewer with the same characteristics as native buttons on your platform. The Anchor tool enables you to anchor two objects together. To draw an anchor, click on an edge of the child object, click at other positions in the editor (optionally), and doubleclick on an edge of the parent object. When pressing the constraint key during specification of an anchor, the placing of the anchor on the child object is constrained to the nearest 25 percent increment. For more information, see Constrained Mode on page 7 8.
Link File Tool
Oracle Graphics Tool
Button Tool
Anchor Tool
7 14
Additional Default Layout Tool
The Additional Default Layout tool enables you to define a default layout for a portion of your layout. This enables you to create a layout without overwriting the entire Layout editor. To define the area in which you want the default layout, you use the same method as you would for drawing rectangles. For more information, see Rectangle Tool 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 dialog box, the default layout is generated within the area you have defined.
OLE2 Object Tool
The OLE2 Object tool enables you to place an OLE2 object in your layout. OLE2 objects are drawn by the same method as rectangles. For more information, see Rectangle Tool on page 7 12. To create perfect squares, use constrained mode. For more information, see Constrained Mode on page 7 8. After you have drawn the OLE2 object, the standard Insert Object OLE2 dialog box will be displayed. From this dialog box, you define the type, source, and whether the object is linked or imbedded. Note that all of these items must be defined to create an OLE2 object. If you cancel out of the dialog box, the object is not created.
Line/Fill/Text Display
The Line/Fill/Text display shows current selections for line, fill, and text. To change the current selections, use the Fill, Line, Text Color tools. The Fill Color tool displays all of the available colors, No Fill, and Patterns. Choosing any of the colors or No Fill sets the Fill color for the selected objects and all subsequently created objects. Selecting Patterns displays a pattern palette. Choosing any pattern sets the Fill pattern for the selected objects and all subsequently created objects. At the bottom of the Pattern palette are foreground and background color palettes. Choosing foreground and background colors sets the colors for the patterns. To change the available colors, you can import a different color palette or change the colors using Color Palette in the Format menu. Rules: 1. On Windows, button colors will not display when the report is run.
Fill Color Tool
Layout Editor
7 15
Line Color Tool
The Line Color tool displays all of the available colors, No Line, and Patterns. Choosing any of the colors or No Line sets the Line color for the selected objects and all subsequently created objects. Selecting Patterns displays a pattern palette. Choosing any pattern sets the Line pattern for the selected objects and all subsequently created objects. At the bottom of the Pattern palette are foreground and background color palettes. Click on these to display the available colors. Choosing foreground and background colors sets the colors for the patterns. To change the available colors, you can import a different color palette or change the colors using Color Palette in the Format menu. Line Width You set the line width of an object by selecting Format>Line. Half of the width of the line extends outside of the object and the other half extends inside of the object. The figure below illustrates this.
Rules: 1. The borders of sibling objects (e.g., two fields inside the same repeating frame) can overlap one another. Note, however, that this means one of the objects will be at least partially overwritten by the other. A field or its border cannot overlap its parent repeating frame. If the field and its border do not fit entirely inside the repeating frames borders, you will get a frequency error when you run the report. 2. If you create a repeating frame with a border, the border applies to each instance of the repeating frame. If Vertical Spacing is zero for the repeating frame, there will be no space between the borders of the instances. If Vertical Spacing is greater than zero, the space will be added between the borders of the instances.
7 16
3.
Anchors are attached to the edges of objects, not their borders. Therefore, at runtime if an objects border is displayed, then any objects anchored to it will be displayed relative to the objects edge, not its border. If you set a border using PL/SQL, the PL/SQL will override the border created using Format>Line. On Windows, button colors will not display when the report is run.
4. 5.
Text Color Tool
The Text Color tool displays all of the available colors. Choosing any of the colors sets the Text color for the selected objects and all subsequently created objects. To change the available colors, you can import a different color palette or change the colors using Color Palette in the Format menu. Rules: 1. On Windows, button colors will not display when the report is run.
Status Line
In the Layout editor, the status line displays the following information:

absolute mouse position (in pixels, inches, or centimeters) mouse drag distance (in pixels, inches, or centimeters) rotation angles zoom levels anchor percentages
The behavior of the status line varies based on the tool being used and action being performed. The following table shows what is displayed by the status line under different circumstances: Tool Every tool Arc, Ellipse, Rectangle, g Rounded R t l Rectangle Freehand Line Action move mouse create object Status Information x,y coordinates of cursor x,y coordinates of starting point, width, gp dh i ht and height x,y coordinates of cursor x,y coordinates of starting point, line length, g , and rotation angle l (h (horizontal) i l)
create object create line
Layout Editor
7 17
Tool Magnify Polygon, Polyline
Action click mouse create object
Status Information zoom level x,y coordinates of cursor and rotation angle l (h (horizontal) i t l) x,y ,y coordinates of starting point change in x,y rotation angle g (h l) (horizontal) x,y ,y coordinates of starting point change in x,y change in x,y p g along g child percentage and d parent edges d percentage along child and parent edges
Rotate, , Group p Rotate
drag g rectangle g move object rotate object j
Select, , Group p Select
drag g rectangle g move object resize object
Anchor
j move object resize object
PopUp Menu
The popup menu appears when you click your right mouse button in the Layout editor.

Confine Mode Flex Mode Cut
The popup menu in the Layout editor for nonOLE2 objects contains the following items: Turns confine mode on or off. For more information, see Confine Mode and Flex Mode on page 7 9. This item only 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 item only appears if the cursor is over a blank area of the editor. Is the same as Edit>Cut.
7 18
Copy Paste Clear
Is the same as Edit>Copy. Is the same as Edit>Paste. Is the same as Edit>Clear.
Properties Is the same as Tools>Properties. This item only appears if the cursor is over an object. Program Unit Editor Help Is the same as Tools>Program Unit Editor. This item only appears if the cursor is over an object. Is the same as Help>Contents.
If your cursor is in a blank area of the editor or on an object that cannot have PL/SQL, only a subset of these items appears. OLE2 PopUp Menu In addition to the standard popup menu items, the following appear when you click your right mouse button while the cursor is over an OLE2 object in the Layout editor: Object Links Show Object Types Is the same as Edit>Object. Is the same as Edit>Links. Toggles between showing and not showing special outlines around OLE2 objects to indicate whether they are linked. Linked objects will have a dashed outline and imbedded objects a solid line.
Layout Editor
7 19
Navigation
This section describes how to navigate between regions within the Layout editor. Note: For more information about how to manipulate objects, see How To in Chapter 8 of Building Reports Manual. Navigating between Regions When you first enter the Layout editor of a new report, you are placed in the Body/Margin region. You can create, modify, and delete objects in 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 owned by the margin), do the following: 1. 2. 3. Select View>Settings>Layout. The Layout Options dialog box is displayed. In the dialog box, choose Margin under Display Layout Using. Accept the dialog box or select the Apply button. You are placed in the margin when you accept the dialog box or select the Apply button.
Likewise, you can move to the header or trailer pages by selecting Header or Trailer in the Layout Settings dialog box.
Defining Pages
You specify the size of each layout page and the number of physical pages per logical page using Global Properties (doubleclick on the reports nodes icon in the Object Navigator). For more information on defining layout pages, see Report Properties on page 4 1.
7 20
Margins
In the Layout editor, the Margin region lies underneath the Body region. The boundary of the Body region of your report is shown as a dark 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 will be overlaid by the Body in the output. As a result, if the objects in the margin overlap objects in the Body, the Margin objects will be overwritten by the Body objects.
Layout Editor
7 21
For example, suppose you have objects in the Body and Margin regions as shown below:
B_Margin_Text is located in the Margin region and R_Sal and F_Sal are located in the Body region. Because B_Margin_Text overlaps R_Sal and F_Sal, it will be partially overwritten by R_Sal and F_Sal. This happens because 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 in Chapter 8 of Building Reports Manual.
7 22
CHAPTER
Layout Properties
ayout properties define the objects that make up the layout for a report. Each of the following objects has a property sheet associated with it that defines its properties:

common layout object 8 2 repeating frame 8 28 frame 8 28 field 8 41 boilerplate 8 59 anchor 8 62 matrix 8 70 Oracle Graphics 8 73 userdefined button 8 81 OLE2 object 8 85
Layout Properties
81
Common Layout Object Properties

Frames, repeating frames, fields, boilerplate, Oracle Graphics display objects, button objects, and OLE2 objects have a number of properties that 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 do not conflict with each other. Because of the power of the layout properties, it is possible to specify properties such that they conflict with other properties. You should avoid the following combinations of layout properties on the same object. If you try to use these combinations on the same 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 an object that is located after its anchoring object) or Page Break After set (for an object that is located before its anchoring object)
2.
Similarly, combinations of properties on different objects can cause unpredictable results or an infinite report. For example, suppose you have two boilerplate objects anchored together inside of a frame. The parent object has a Print Condition Type of All and an Object of Enclosing. The child object has a Print Condition Type of First, a Print Condition Object of Anchoring, and Page Break Before set. The figure below illustrates this layout:
82
When you run the report, the child object does not appear in the output. Because it has Page Break Before set, the child can never satisfy its Print Condition (Type First, Object Anchoring). Note, however, that the object underneath the child object (B_Plate3) does appear.
General Layout Tab

The General Layout tab is shown below. It contains the following properties:

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
Note that some layout objects only have a subset of these properties in their property sheets.
Layout Properties
83
Format Trigger
Is a button that displays the Program Unit editor in which you can enter the PL/SQL function or anonymous function body for a Format Trigger. For more information about Format Triggers, see Format Triggers on page 13 28. Is how the horizontal size of the object will change at runtime to accommodate the objects or data within it. Horizontal Sizing is identical to Vertical Sizing, except that it refers to the width rather than the height of the object. For more information on sizing options and rules, see Vertical Sizing on page 8 20. The figure below illustrates how the Horizontal Sizing setting is displayed in the Layout editor.
Horizontal Sizing
84
Examples: 1. Suppose that you have a field with the following characteristics: Characteristic width Horizontal Sizing height Vertical Sizing Value 1 inch Contract 1 inch Fixed
The following diagram shows what the field might look like when formatted:
Note that when the data is less than one inch wide the size of the field decreases to the minimum size necessary to hold the data. It is also important to note here that if the data was more than one inch long, it would be truncated because the field cannot expand vertically or horizontally. 2. Suppose that you have a frame named M_1 with the following characteristics: Characteristic Horizontal Sizing height Vertical Sizing Value Variable 7 inches Fixed
Assume further that the Page Width you defined in the report property sheet is eight inches. M_1 contains a repeating frame with one field, F_Ename. The first value of F_Ename is four inches wide, the next value is 3 inches, the next is four inches, and the last is four inches. The following diagram shows how the frame might be formatted:
Layout Properties
85
Note that the first two instances of field F_Ename print on the first logical page, but, the second two instances, because there is not enough room on the first logical page, print on the second logical page. It is also important to note that if the Horizontal Sizing was Contract or Fixed, instead of Variable, the frame would not print unless it could fit entirely on one logical page.
Keep with Anchoring Object
Indicates whether to keep an object and the object to which it is anchored on the same logical page. Checking Keep with Anchoring Object means that if the object, its anchoring object, or both cannot fit on the logical page, they will be moved to the next logical page. If you set Keep with Anchoring Object for a repeating frame, it means the first instance of the repeating frame must be able to fit on the same page as its anchoring object. Otherwise, the Keep With Anchoring Object condition is not satisfied. If you set Keep With Anchoring Object for any layout object other than a repeating frame, it means the object must be able to format entirely on the same page as its anchoring object. The anchor between the two objects may be explicit or implicit. Consequently, Keep With Anchoring Object may have an effect even if you have not explicitly created an anchor between two objects. For more information about implicit anchoring, see Implicit Anchoring Algorithm on page 2 43. Required/Optional: Optional. Default: Unchecked.
86
Examples: 1. Suppose that you have created three boilerplate objects similar to the following:
B_2 and B_3 each has Keep With Anchoring Object specified. On the logical page where Oracle Reports first tries to print these objects, 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 its anchoring object is B_2, B_2 and B_3 would be moved to the next logical page. Since B_2 also has Keep With Anchoring Object specified and its anchoring object is B_1, B_1 would also be moved to the next logical page. Rules: 1. Keep With Anchoring Object applies only to the first logical page on which the object is triggered to be formatted. Keep With Anchoring Object is ignored on subsequent pages. If moving the object and its anchoring object to the next logical page would leave the current logical page blank or only containing repeated objects (e.g., a page heading), Keep With Anchoring Object will not be applied. This prevents unnecessary blank pages in your report. If the anchoring object is a repeating frame and the current object is outside of the repeating frame, then anchoring object refers to the repeating frame as a whole (all the instances of the repeating frame).
2.
3.
Layout Properties
87
4.
If two objects are anchored to their enclosing frame and the frame has Vertical and/or Horizontal Sizing of Contract or Variable, then all three objects must be able to complete formatting on the same page to satisfy the Keep With Anchoring Object condition. If the two objects are enclosed by a repeating frame instead of a frame, then this rule applies to each instance of the repeating frame. The figure below illustrates this rule.
In the figure, B_1, B_2, and M_1 would all have to be able to complete formatting on the same page in order to satisfy the Keep With Anchoring Object condition.
Name
Is the name that Oracle Reports uses to identify the current layout object. Required/Optional: Required. Options: Enter any valid name not to exceed 30 bytes. For more information about naming conventions, see Naming Conventions on page D 1. For frames, M_n, where n is a number that is unique among frame names for the report. For repeating frames, R_n, where n is a number that is unique among repeating frame names for the report. For fields,F_n, where n is a number that is unique among field names for the report. For boilerplate, B_n, where n is a number that is unique among boilerplate names for the report.
Default:
88
For matrix objects, X_n, where n is a number that is unique among matrix names for the report. For Oracle Graphics objects, D_n, where n is a number that is unique among Oracle Graphics object names for the report. For button objects, U_n, where n is a number that is unique among field names for the report. For OLE2 objects, B_n, where n is a number that is unique among boilerplate object names for the report.
Page Break After
Indicates that you want all children of the object to be moved to the next 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 Break Before set. Note that this does not necessarily mean that all the objects below the object with Page Break After will move to the next page. Look at Rules below. Required/Optional: Optional. Default: Rules: 1. Page Break After delays only the formatting of an objects child objects. The formatting of sibling objects is not delayed because there is no hierarchy (i.e., parentchild relationship) by which Oracle Reports can determine the order of formatting for siblings. As a result, an object must be anchored (implicitly or explicitly) to another object as the parent for Page Break After to have an effect. For example, in the following diagram Page Break After is set on for frame M_Dept. Both M_Dept and M_Emp have Fixed Vertical and Horizontal Sizing. Page Break After does nothing in this case because M_Dept and M_Emp are siblings inside of the parent frame M_Parent. Unchecked.
Layout Properties
89
In the following diagram, everything is the same as the previous case except that M_Dept is explicitly anchored to M_Emp as the parent. Page Break After delays the formatting of M_Emp in this case because M_Dept is the parent of M_Emp.
2.
For repeating frames, Page Break After sets a logical page break after the repeating frame as a whole. To have a page break after each instance of the repeating frame you should also set Maximum Records per Page to 1 on the Repeating Frame property sheet. Objects below an object with Page Break After set may not move to the next page. If an object is not a child of the object with Page Break After set, then that object, if it can fit, may print on the same page as the object with Page Break After set. The figure below provides an example of this concept:
3.
8 10
Notice how B_Graph, which appears below R_Sal in the layout, actually ends up printing on page 1 with R_Sal. This happens because B_Graph is not a child of R_Sal. If you explicitly anchored B_Graph as a child to R_Sal, then B_Graph would have appeared on page 2 instead of page 1. 4. If an object has no external objects anchored to it (implicitly or explicitly), then Page Break After has no effect.
Page Break Before
Indicates that you want the object to be formatted on the page after the page on which it is initially triggered to print. Note that this does not necessarily mean that all the objects below the object with Page Break Before will move to the next page. Look at Rules below. Required/Optional: Optional. Default: Rules: 1. For repeating frames, Page Break Before sets a logical page break before the repeating frame as a whole. To have a page break before each instance of the repeating frame, you should also set Maximum Records per Page to 1 on the Repeating Frame property sheet. Objects below an object with Page Break Before set may not move to the next page. If an object is set to print on a page but is moved to the next page because of Page Break Before, other objects may be placed in the space where the object was originally set to print, if there is sufficient room. The figure below provides an example of this concept: Unchecked.
2.
Layout Properties
8 11
Notice how B_Graph, which appears below R_Sal in the layout, actually ends up printing on page 1 instead of page 2.
Page Protect
Indicates whether to try to keep the entire object and its contents on the same logical page. Checking Page Protect means that if the contents of the object cannot fit on the current logical page, the object and all of its contents will be moved to the next logical page. Note: Using Page Protect may cause objects below the page protected object(s) to appear above the page protected object(s). Look at Rules below. Required/Optional: Optional. Default: Examples: 1. Suppose that you have created a frame named M_1 with a number of fields that display various columns and summaries. For ease of reading, you want to keep all of the fields in M_1 on the same logical page so that readers can see the columns and their summaries together. Specify Page Protect for M_1. If M_1 and all its fields cannot fit on the first logical page that Oracle Reports attempts to print them, Oracle Reports will try to print M_1 and all its objects on the next logical page. The figures below illustrate what would happen to the frame with and without Page Protect checked. Unchecked.
8 12
2.
Assume the conditions stated in the above example. Suppose further, though, that M_1 and all its fields cannot fit on the second logical page on which Oracle Reports tries to print it. Oracle Reports will print as much of M_1 as it can on the logical page and print the rest of it on the following logical page. Suppose that you have a masterdetail report. If at all possible, you would like to have all of the details and the master appearing on the same page. To do this, you select Page Protect for the master repeating frame (the outermost repeating frame). If the details and the master cannot fit on the first page on which they are triggered to print, they will be triggered to print on the next page instead.
3.
Layout Properties
8 13
Rules: 1. Page Protect applies only to the first logical page on which the object is triggered to be formatted. Page Protect is ignored on subsequent pages. For repeating frames, Page Protect refers to each instance of the repeating frame. Each instance of the repeating frame and its enclosed objects will be kept together by Page Protect. The only exception is that page protection is not applied to the first instance on a page other than the first page of the repeating frame. For example, in the diagram below, page protection is applied to instances 1, 2, and 4, but not to instance 3. Instance 3 is the first instance to format on the second page of the repeating frame. Notice that, in this case, if page protection had been applied to instance 3, it would have started on page 3 instead of page 2. This would have left page 2 almost completely blank.
2.
3.
Page Protect is not supported for repeating frames that are part of a matrix. When repeating frames are related via matrix object, setting Page Protect will not effect them. If moving the object and its contents to the next logical page would leave the current logical page blank or only containing repeated objects (e.g., a page heading), Page Protect will not be applied. This prevents unnecessary blank pages in your report.
4.
8 14
5.
If Page Protect causes an object to be moved to the next logical page when formatting, an object alongside the page protected object may or may not be moved as well. If the object alongside the page protected object is not anchored (implicitly or explicitly) to the page protected object, and that object can fit in the space where the page protected object could not fit, the object will print on that logical page. Otherwise, the object will be moved along with the page protected object to the next logical page.
Print Condition Object Is the object on which to base the Print Condition Type of the current
object. For example, if you specify a Print Condition Type of All and a Print Condition Object of Anchoring Object, the current object will be triggered to print on every logical page on which its anchoring object (parent object) appears. Required/Optional: Required. Options: Anchoring Object is the parent object to which the current object is implicitly or explicitly anchored. Enclosing Object is the object that encloses the current object. Default: Examples: Look at Examples under Print Condition Type. Rules: Look at Rules under Print Condition Type. Anchoring Object
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 which the object should be triggered to print with regard to the Print Condition 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 logical page does not mean it will print on that logical page. Other settings (e.g., Page Break Before) or the amount of space available on the page may cause Oracle Reports to print an object on a page other than the one on which it was initially triggered to print.
Layout Properties
8 15
In applying these options, Oracle Reports considers the first page of an object to be the first logical page on which some part of the object is printed. Likewise, the last page is considered to be the last logical page on which some part of the object is printed. For example, if you specify a Print Condition Type setting of First and a Print Condition Object setting of Enclosing Object, the object will be triggered to print on the first logical page on which its enclosing object appears. Required/Optional: Required. Options: All means the object and all of its contents will be printed on all logical pages of the Print Condition Object. The object will be repeated on any overflow pages of the Print Condition Object and will be truncated at the logical page boundary, if necessary. All but First means the object and all of its contents will be printed on all logical pages of the Print Condition Object except the first logical page. The object will be formatted only on overflow pages of the Print Condition Object and will be truncated at the logical page boundary, if necessary. All but Last means the object and all of its contents will be printed on all logical pages of the Print Condition Object except the last logical page. The object will be repeated on any overflow pages of the Print Condition Object except the last one and will be truncated at the logical page boundary, if necessary. *Default means that Oracle Reports will use object positioning to set the Print Condition Type to either *First or *Last for you. (The asterisk indicates that Oracle Reports specified the setting for you.) For more information on how Oracle Reports does this, see Print Condition Algorithm on page 2 47. First means that the object and all of its contents will only be printed on the first logical page of the Print Condition Object. The object will be formatted and will overflow to subsequent pages, if necessary.
8 16
Last means that the object and all of its contents will only be printed on the last logical page of the Print Condition Object. The object will be formatted after the Print Condition Object and will overflow to subsequent pages, if necessary. Default: Examples: 1. Suppose that you have created a summary column named Col_Sum that sums the values of a column in a group named Group_1. Col_Sum is the source of a field (F_1) that is enclosed in a repeating frame (R_1), which contains the values from Group_1. If you specify a Print Condition Type setting of All and a Print Condition Object setting of Enclosing Object for F_1, it prints in every instance of R_1 on every logical page. The diagram below illustrates a layout and the resulting output. Varies according to object.
2.
Because it is outside of repeating frame C, boilerplate object Ds Print Condition Object refers to the repeating frame as a whole. Because they are inside the repeating frame, boilerplate objects A and Bs Print Condition Object refer to each instance of repeating frame C.
Layout Properties
8 17
Object D appears on all logical pages on which repeating frame C appears. Object A, however, only prints when an instance of repeating frame C overflows. The Print Condition Type of All But First in this case means to trigger the object to print on every logical page of each instance of the repeating frame, except for the very first page on which an instance prints. Since repeating frame C only contains two objects (boilerplate objects A and B), it only overflows to a second page when boilerplate object B overflows. Looking at the Print Condition Type of objects A and B (All But First and First), you would think that these two objects could never appear on the same page. In this scenario, however, they can only appear on the same page. Rules: Caution: If its contents cannot fit within the logical page on which it starts to print, an object with a Print Condition Type of All, All But First, or All But Last cannot overflow onto subsequent pages. In this case, the contents of the object will be truncated and the object will print with the same, truncated contents on every logical page it is triggered to print. 1. If its contents cannot fit within the logical page on which it starts to print, an object with a Print Condition Type of First or Last can overflow onto subsequent pages. As a result, even though it is triggered to print only on the first or last page, it may overflow beyond the first or last page. Note: As a result of overflow, a Print Condition Type of First and a Print Condition Type of All But First are not necessarily mutually exclusive. For example, if one layout object has a Print Condition Type of First and another has All But First and they both have the same Print Condition Object, you might think that the two objects could never appear on the same page. If the layout object with First overflows onto the second page, though, the two objects could appear on the same page. 2. An object that is implicitly or explicitly anchored to its enclosing frame or repeating frame cannot have a Print Condition Type of Last or All But Last. An object that is anchored to another object within its frame or repeating frame cannot have a Print Condition Type of Last or All But Last with a Print Condition Object of Enclosing Object. The figure below illustrates this rule.
8 18
3.
If the Print Condition Object of a layout object is a repeating frame that encloses the layout object, then it refers to each instance of the repeating frame to which the object is anchored. If the Print Condition Object of a layout object is a repeating frame and the layout object is outside of the repeating frame, then it refers to the repeating frame as a whole. For example, a Print Condition Type of First means the first logical page on which the repeating frame is triggered to print. Whether the Print Condition Object refers to a repeating frame as a whole or the instances of a repeating frame, the Print Condition Type always refers to logical pages. For example, suppose the Print Condition Object of a layout object is a repeating frame and the layout object is outside of the repeating frame. In this case, the Print Condition Object would refer to the instances of the repeating frame. A Print Condition Type of First, however, does not mean the first instance of the repeating frame. It means the first logical page on which each instance of the repeating frame is triggered to print. Objects in the margin region are restarted on every physical page. As a result not all Print Condition Types make sense for margin objects. Because objects are restarted on every page, it is as if you are 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 object never goes beyond first.
4.
5.
6.
Layout Properties
8 19
Vertical Sizing
Is how the vertical size of the object may change at runtime to accommodate the objects or data within it:
For frames and repeating frames, sizing defines whether the size of the frame or repeating frame should vary with the objects inside of it. For objects containing text, sizing defines whether the field or boilerplate should vary with the size of the text. Fixed size text will wrap within the defined size of the object and may be truncated if there is not enough room. Look at Rules. Number or date data will appear as asterisks if the data cannot fit within the defined size. For images, drawings, and Oracle Graphics displays, Oracle Reports uses proportional scaling. The sizing options for images, drawings, and Oracle Graphics displays determine the scaling factor.
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 displayed in the Layout editor.
Required/Optional: Required. Options: Contract means the vertical size of the object decreases, if the formatted objects or data within it are short enough, but it cannot increase to a height greater than that shown in the editor. Note:Truncation of data may occur; look at Examples. (You can think of this option as meaning only contract, do not expand.)
8 20
Expand means the vertical size of the object increases, if the formatted objects or data within it are tall enough, but it cannot decrease to a height less than that shown in the editor. (You can think of this option as meaning only expand, do not contract.) Fixed means the height of the object is the same on each logical page, regardless of the size of the objects or data within it. Note: Truncation of data may occur; look at Examples. The height of the object is defined to be its height in the editor. Variable means the object may expand or contract vertically to accommodate the objects or data within it (with no extra space), which means the height shown in the editor has no effect on the objects height at runtime. Default: Examples: 1. Suppose that you have a field with the following characteristics: Characteristic width Horizontal Sizing height Vertical Sizing Value 1 inch Fixed 2 inches Expand Varies according to the object.
The following diagram shows what the field might look like when formatted. Note that the field always takes up at least two inches vertically and is always one inch wide. If the data takes more than one inch horizontally and two inches vertically, the field grows vertically to accommodate the data.
Layout Properties
8 21
2.
Suppose that you have a frame named M_2 with the following characteristics: Characteristic width Horizontal Sizing Vertical Sizing Value 5 inches Fixed Variable
Assume further that the Page Height for the report is twelve inches. Because of the size of the objects within it, M_2 requires eight 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 the Vertical Sizing is Variable, the first five inches of M_2 are printed on the first logical page and the last two inches are printed on the second 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 you included in your report. You gave the Oracle Graphics object in your report a Vertical and Horizontal Sizing of Fixed. Oracle Reports scales the display to fit within the dimensions you defined for the object.
8 22
Rules: Caution: If the contents of an object exceed its defined height, its Vertical and Horizontal Sizing determine whether the contents overflow onto the next page or are truncated. The table below shows the combinations of objects and sizing choices that cause overflow and truncation. (Expand and Variable in the table apply if either the Vertical or Horizontal Sizing is Expand or Variable.) Images, drawings, and Oracle Graphics displays cannot overflow. Look at the rules below for details about images, drawings, and Oracle Graphics displays. Object repeating frame instances and frames (contents <= defined height) repeating frame instances and frames (contents > defined height) Fixed/ Contract no overflow Expand no overflow Variable no overflow
no overflow
overflow, if unable to fit on the page no overflow
overflow, if unable to fit on the page no overflow
fields and boilerplate no overflow (contents <= defined height) fields and boilerplate truncate* (contents > defined height)
overflow, if unable to fit on the page
overflow, if unable to fit on the page
* To avoid truncation, make the field or boilerplates Vertical Sizing Variable and surround it with a frame that has Fixed Vertical Sizing. Note also, that when truncation of text occurs, it occurs after the field or boilerplate text has been wrapped. Additional Information: If you want your data truncated, you should use the SQL SUBSTR function in your query. For example, if you want only the first four characters of a column, then use SUBSTR in your SELECT statement to retrieve only those characters from the database. 1. When formatting an object, if Vertical Sizing is Fixed Oracle Reports will only format it on a logical page if the page has enough space to contain the entire object. If Vertical Sizing is Expand, Oracle Reports will only format the object on a logical page if the page has enough space to contain the defined height of the object (i.e., its minimum size). If formatting is not complete, the object overflows to the next page.
2.
Layout Properties
8 23
3.
If Vertical Sizing is Variable or Contract, Oracle Reports will format as much of the object as possible on the first logical page and, if necessary, complete the object on the following logical page(s). If a number cannot fit in its field, then asterisks will appear in the field instead of the value. To get the value to appear, you either need to resize the object or change its Horizontal Sizing to Expand or Variable. The following sizing rules apply to layout objects (e.g., fields or boilerplate) that contain an image/drawing or an Oracle Graphics display:
4.
5.
If the sizing of the layout object is variable (i.e., both Vertical and Horizontal Sizing are Variable), then the contents will appear the same 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 and Horizontal Sizing are Fixed), then proportional scaling is performed on the contents. In some cases, this may lead to empty space or gaps between the contents and the border of the layout object. For example, if an object is Fixed both horizontally and vertically and the image is too large for the object, then the image will only fill the object in one direction. In the other direction, the image will be shorter than the object. To avoid these gaps, you can either 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 Oracle Graphics display is Fixed in only one direction, Oracle Reports will always attempt to have the contents fill up the Fixed dimension. If the sizing of the layout object is Contract in one direction and Fixed in the other, the contents may be clipped. To avoid clipping of the contents, you can either change the sizing (e.g., make it Variable both horizontally and vertically) or you can manually resize the object. If the sizing of the layout object is variable (i.e., Vertical or Horizontal Sizing is Variable) and the layout object cannot fit in its enclosing object (e.g., a frame or the logical page), the report will infinitely loop (because the object can never format).
8 24
6.
If a value to be displayed in the report output relies on the formatting of the report, then the field or boilerplate object that displays the value must have a Vertical and Horizontal Sizing of Fixed. (This is sometimes referred to as pagedependent referencing.) If the sizing is not fixed, Oracle Reports will change it to be fixed at runtime. A typical case of pagedependent referencing is a field that has a Source of &Total Logical Pages. The total number of logical pages cannot be determined until the entire report has been formatted. But Oracle Reports must format the field before the end of the report and cannot wait until the report is completely formatted to determine how big to make the field. Consequently, the fields sizing must be fixed, so that Oracle Reports knows how much space to reserve for it before its source value is determined. Following are cases of pagedependent referencing, where a field or boilerplate objects sizing must be fixed because its source value depends on the formatting of the report:
If a summary column has a Reset At or Compute At of Page, then the field or boilerplate object that displays its value must have fixed sizing. If a formula or summary column relies on a summary column that has a Reset At or Compute At of Page, then the field or boilerplate 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 the field (either the field itself or a boilerplate object) must have fixed sizing. If a field has a page number as its Source and, in the Page Numbering dialog box, Reset At is a repeating frame, then any layout object that displays its value must have fixed sizing.
Note: If a field containing a pagedependent reference has Hidden set, 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.
Layout Properties
8 25
Printer Codes Tab

Printer codes are references to printer escape sequences that define special printing instructions (e.g., special font sizes or highlighting) for the object. The Printer Codes tab is shown below. It contains the following properties:

After 8 27 Before 8 27
Caution: Printer codes are only used when running your report in charactermode. They are not used when running it in bitmap. Note: In most cases, you should be able to accomplish any special formatting by writing PL/SQL for the layout objects. Examples: 1. Suppose that in your printer definition file you created two printer codes named &123 and &456. &123 causes the printer to print special font. &456 causes the printer to print the normal font. Assume that you want all fields in a repeating frame (R_1) to be printed using the special font. You could either use the printer code for each individual field or use it for the entire repeating frame. The latter case is easier to create and maintain. You select the Printer Codes button from the R_1 repeating frame property sheet and enter &123 in the Before field and &456 in the After field. When R_1 is printed, the printer code will be executed before and after each line of R_1 is printed. The diagram below shows the points at which each printer code is invoked:
8 26
After
Is a reference to the printer escape sequence to be executed after each line of the object. The printer escape sequence is inserted after the object is triggered to print but before it has actually printed. Entries in this field may be of the form &number, where number is a number assigned to a packaged Oracle Reports printer code or a printer code you created. Options: Enter a valid printer code reference not to exceed 256 bytes in length.
Before
Is a reference to the printer escape sequence to be executed before each line of the object. The printer escape sequence is inserted after the object is triggered to print but before it has actually printed. Entries in this field may be of the form &number, where number is a number assigned to a packaged Oracle Reports printer code or a printer code you created. Options: Enter a valid printer code reference not to exceed 256 bytes in length.
Comment Tab
The Comment tab contains a text field in which you can document the layout object. Required/Optional: Optional. Options: Default: Enter any text not to exceed 64K. Blank.
Layout Properties
8 27
Frame Properties
When you doubleclick on a frame in the Layout editor or its icon in the Object Navigator, its Frame property sheet is displayed. The Frame property sheet is divided into the following tabs:

General Layout 8 3 Printer Codes 8 26 Comments 8 27
Repeating Frame Properties

When you doubleclick on a repeating frame in the Layout editor or its icon in the Object Navigator, its Repeating Frame property sheet is displayed. The Repeating Frame property sheet is divided into the following tabs:

Object 8 29 General Layout 8 3 Printer Codes 8 26 Comments 8 27
Rules: 1. A repeating frame can be placed anywhere in the Layout editor unless its source group is a dimension of a matrix. For more information about matrix reports, see Matrix Reports on page 2 27. A repeating frame must be behind the objects (e.g, fields and boilerplate) that it contains.
2.
8 28
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
Column Mode
Controls how Oracle Reports fetches and formats data for instances of repeating frames. The figures below illustrate how Column Mode affects the formatting of repeating frame instances.
Layout Properties
8 29
With Column Mode, the next instance of a repeating frame can begin formatting before the previous instance is completed. In the figure above, Instance 3 begins formatting on page 1 even though Instance 2 does not finish until page 2. In addition, when an instance overflows onto another page, the overflow is aligned across pages. In the figure above, Instance 2 appears in the same relative position on page 2 that it appeared in on page 1.
8 30
Without Column Mode, the next instance cannot begin formatting before the previous instance is completed. In the figure above, Instance 3 begins formatting on page 2 because Instance 2 does not finish until page 2. Also, if an instance overflows, the overflow is not aligned across pages. In the figure above, Instance 2 formats in the middle of page 1 and its overflow formats on the left side of page 2. Column Mode is used mainly for master repeating frames or repeating frames that contain fields that may expand vertically or horizontally (i.e., sizing is Variable or Expand). Required/Optional: Optional. Default: Examples: 1. The figure below shows a sample layout in which you might use Column Mode. (Assume that X has Horizontal Sizing of Fixed.) Unchecked.
The first figure below shows instances 1 through 3 if repeating frame X has Column Mode checked. The positioning is the same on logical pages 1 and 2, even though instance 2 completed on logical page 1. 2. The second figure below shows the positioning of instances 1 through 5 if repeating frame X does not have Column Mode checked. Instances 1 and 2 complete on logical Page 1. As a result, the position of instance 3, which did not complete on logical Page 1, is not the same on logical Page 2 as it was on logical Page 1.
Layout Properties
8 31
Rules: 1. You can only specify Column Mode for repeating frames that have either:

Print Direction of Across and Horizontal Sizing of Fixed Print Direction Down and Vertical Sizing of Fixed
8 32
Repeating frames with a Print Direction of Across/Down or Down/Across cannot have Column Mode specified.
Horizontal Spacing
Is the amount of space (in the reports unit of measurement) that you want horizontally between instances of the repeating frame. The figure below illustrates Horizontal Spacing.
Required/Optional: Required. Options: Enter a number of zero or more. The maximum amount depends upon the unit of measurement. For inches, the maximum is 512 inches. For centimeters, it is 1,312 centimeters. For picas, it is 36,864 picas. 0
When the Print Direction is Down, this setting has no effect. When the Print Direction is Down/Across, this setting affects space between instances that appear one next to the other.
Maximum Records per Is the maximum number of instances of the repeating frame that will be formatted on a logical page. Page
Required/Optional: Optional. Options: Enter any positive, whole number from 1 through 32K. Blank means that as many instances of the repeating frame as possible can be formatted on a logical page. Default: Blank.
Layout Properties
8 33
Examples: 1. Suppose that you have a repeating frame with many instances. To improve the appearance of your report, you prefer to have at most three instances of the repeating frame on a given logical page. To ensure that you never have more than three instances per logical page, you set Maximum Records Per Page to 3. Suppose that you want each instance of a repeating frame to be on a logical page by itself. First, set Maximum Records Per Page to 1 for the repeating frame so that only one instance appears on each logical page. Then, check Page Break Before and Page Break After, to make sure that the first instance of the repeating frame starts on a new logical page.
2.
Minimum Widow Records
Is the minimum number of instances that should appear on the logical page where the repeating frame starts to print. If the number of instances specified for this property cannot fit on the logical page where the repeating frame is initially triggered to print, then the repeating frame will start formatting on the next page. If this property is 1, there is no minimum and the repeating frame will start formatting on any logical page that can fit one instance. Minimum Widow Records is similar to Minimum Widow Lines for fields and boilerplate. For more information about Minimum Widow Lines, see Minimum Widow Lines on page 8 51. Required/Optional: Required. Options: Enter any positive, whole number from 1 through 32K. Blank means that there is no minimum. Default: Examples: 1. To improve the appearance of your report, you want to make sure that you do not have the first instance of the repeating frame printed at the bottom of a logical page, by itself. To make sure that there are at least two instances on the logical page, you set Minimum Widow Records to 2. Blank
8 34
2.
Suppose that you want all instances of a repeating frame to appear on one logical page. To do this, you set Minimum Widow Records to a very large number. If not all instances can fit on the first logical page where the repeating frame is triggered to print, none will be formatted on that page. Instead, they are all formatted on the next logical page. Notice, though, that on the next and all subsequent pages, Minimum Widow Records is ignored. Since you are starting with a fresh page, if all instances cannot fit on that logical page, they will not all fit on any one logical page anyway.
Rules: 1. Minimum Widow Records applies only to the first logical page on which the object is triggered to be printed. Minimum Widow Records is ignored on subsequent pages. If Minimum Widow Records is greater than the total number of instances of the repeating frame, then all instances must be able to fit on the first logical page where the repeating frame is triggered to format. If all instances cannot fit on the first logical page where the repeating frame is triggered to format, the repeating frame will start formatting on the next page.
2.
Print Direction
Is the direction in which successive instances of the repeating frame appear. Required/Optional: Required. Options: Across means that each instance of the repeating frame subsequent to the first instance is printed to the right of the previous instance across the logical page. Across/Down means that each instance of the repeating frame subsequent to the first instance is printed to the right of the previous instance until an entire instance cannot fit between the previous instance and the right margin of the logical page. At that time, Oracle Reports prints the instance below the leftmost instance on the logical page, provided there is enough vertical space left on the logical page for the instance to print completely. Down means that each instance of the repeating frame subsequent to the first instance is printed below the previous instance down the logical page.
Layout Properties
8 35
Down/Across means that each instance of the repeating frame subsequent to the first instance is printed below the previous instance until an entire instance cannot fit inside the bottom margin of the logical page. At that time, Oracle Reports prints the instance to the right of the topmost instance on the logical page, provided there is enough horizontal space left on the logical page for the instance to print completely. Default: Examples: 1. Suppose that you have a repeating frame like the one shown below. Since the Print Direction is Across/Down, instances of the repeating frame print from left to right and then top to bottom. Down
8 36
If, however, there was an object (e.g., a graphic) on a page that prevented two instances of the repeating frame going across the page, the repeating frame instances would only print down the page. Where there is room to print more than one instance across the page, the repeating frame instances begin printing across and then down.
Layout Properties
8 37
8 38
Rules: 1. If a nested repeating frame has a Print Direction of Across and its enclosing repeating frame has a Print Direction of Down, the across repeating frame can cause overflow when it is too wide for the current page. The next instance of the outer, down repeating frame will not print until the previous instances of the across repeating frame completes. The figure below illustrates this rule graphically.
Notice that there are too many instances of B in A3 to fit on the first logical page. As a result, A3 overflows onto the second logical page and A4 can begin only after A3 completes. Note: If you wanted A3 on page 1 to be aligned with the overflow of A3 on page 2, you could use Column Mode. For more information, see Column Mode on page 8 29. 2. Matrix dimension repeating frames whose source groups are in the same family hierarchy (i.e., are descendants or ancestors of each other) within a crossproduct group must have the same Print Direction. Parentchild relationships within a crossproduct group are used to create nesting in the matrix. As a result, the repeating frames associated with such groups must print in the same direction on the page.
Source
Is the group that owns the data for the repeating frame. Source is a list of values containing valid source groups. Required/Optional: Required. Options: Select any valid group name.
Layout Properties
8 39
Rules: 1. Source cannot be a crossproduct group.
Vertical Spacing
Is the amount of space (in the reports unit of measurement) you want vertically between instances of the repeating frame. The figure below illustrates Vertical Spacing.
Required/Optional: Required. Options: Enter a number of zero or more. The maximum amount depends upon the unit of measurement. For inches, the maximum is 512 inches. For centimeters, it is 1,312 centimeters. For picas, it is 36,864 picas. 0
When the Print Direction is Across, this setting has no effect. When the Print Direction is Across/Down, this setting determines the space between instances that appear one below the other.
8 40
Field Properties
When you doubleclick on a field in the Layout editor or its icon in the Object Navigator, its Field property sheet is displayed. The Field property sheet is divided into the following tabs:

Rules: 1. The maximum size of text in a field is 64K of text per paragraph and 64K paragraphs. This limit may vary according to your operating system. The contents of fields are wrapped on word boundaries, i.e., on spaces, hyphens, and tabs. Other punctuation marks are considered to be the last character of the word they follow. New line characters in the fields contents force new lines. There is no limit to the number of lines that can be created. In the Layout editor, a field must be placed inside of a repeating frame whose source group is the group (or a descendant of the group) that contains the fields source column. If a fields source is a summary owned by a crossproduct group, then the field must be placed inside of the set of repeating frames whose sources are the groups in the summary columns Product Order. For more information on Product Order, see Product Order on page 6 33. A field must be in front of the repeating frame that contains it. If a number cannot fit in its field, then asterisks will appear in the field instead of the value. To get the value to appear, you either need to resize the object or change its sizing to Expand or Variable.
2.
3.
4. 5.
Object Tab of Field Property Sheet

The Object tab of the Field property sheet is shown below. It contains the following properties:

Datatype 8 42 Format Mask 8 42
Layout Properties
8 41
Hidden 8 49 Page Numbering 8 52 Source 8 56
Datatype
Is a readonly field that displays the datatype of the fields Source. For more information, see Column Properties on page 6 17. For more information, see Parameter Properties on page 6 45. Rules: 1. A field of Datatype Long, Long Raw, or Raw is treated as text unless you specify otherwise in the Format field of the Column property sheet. For more information, see Format on page 6 21.
Format Mask
Defines how you want to display Date and Number values in the field. You can enter custom masks for numbers and dates using the syntax described in the tables below or you can select from the predefined list of values. Character values have no format mask. You cannot enter a format mask for fields with Character values. The values displayed initially in the list are determined by the datatype of the field (e.g., for a field of Datatype Number, only number masks are shown in the list). If you enter a mask not in the list for Format Mask and accept the Field property sheet, the new format mask will appear in the list of values.
8 42
However, these format masks are only valid during the current Oracle Reports session. If you quit Oracle Reports and then invoke it again, the list of values for the Format Mask field does not contain the format masks you created in the previous Oracle Reports session (unless you open the report(s) that used these masks). To include masks in the list that will be saved between sessions, use Format Masks in the Tools Options dialog box (Tools>Tools Options). Required/Optional: Optional. Options: Enter any valid number or date format mask not to exceed 1K. Look at the tables below for the syntax of format masks. Select a value from the list. Default: Blank. This implies that the Oracle Reports should determine how to format the values based on the Datatype of the fields source. When the Datatype of the fields source is Date, the format mask is the default for your language (e.g., in the United States, the default is DDMONYY). When the Datatype of the source is Number, the values are formatted according to the width of the source. The table below shows some examples. Note: This default behavior is the same as SQL*ReportWriter Version 1.1. Value 9.99999 9.99999 9.99999 9.99999 9.99999 9.99999 9.99999 400 4.563 4.563 4.563 Width of Source 4 3 2 1 4 3 2 2 5 4 3 Output Displayed 10.0 10. 10 * 10. 10 ** ** 4.563 4.56 4.6
Layout Properties
8 43
Value 0.001 0.001 0.001 0.001 0.001 0.01 0.01 0.01 0.01 Date Format Masks
Width of Source 5 4 3 2 1 4 3 2 1
Output Displayed .001 .001 .00 .0 . .01 .0 .
The following table illustrates the format masks for dates: Format Mask
SCC or CC YYYY or SYYYY YYY, YY, or Y Y,YYY SYEAR or YEAR BC, AD, or B.C., A.D. Q MM MONTH or MON WW ; W DDD, DD, or D DAY DY J AM, PM, or A.M., P.M.
Explanation Century, abbreviated; S prefixes BC with () Year; S prefixes BC date with a () Last 3, 2, or 1 digit(s) of year Year with comma Year, spelled out; S prefixes BC date with () Century indicator Quarter of year (JanMar=Quarter 1) Month in digits (Jan = 01) Name of month, or 3letter abbreviation Week in year; week in Julian days Day in year, month, or week Day of week (MONDAY) Name of day, 3letter abbreviation Julian day; the number of days since January 1,4712 BC Meridian indicator
8 44
Format Mask
HH or HH12; HH24 MI SS; SSSSS
Explanation Hour of day (112); Hour of day (023) Minute Second in minute; seconds in day Toggles fill mode which replaces multiple spaces before or between dates, numbers, or words with a single space
fm
The following suffixes may be added to the format masks: Suffix

TH SP SPTH or THSP
Explanation Suffixed number (DDth for 4th) Spelled out number (DDSP for FOUR) Spelled and suffixed number (DDSPTH for FOURTH)
Number Format Masks
The following table describes the tokens you can use in creating a number format mask. To create a number format mask, you build a string using these tokens. Format Token 0 N Explanation Prints one digit. Prints one digit, unless it is a leading zero to the left of the decimal point or a trailing zero to the right of the decimal point. Prints one digit, unless it is a leading zero to the left of the decimal point, in which case an asterisk (*) is printed. Trailing zeros to the right of the decimal point are printed. Prints one digit, unless it is a leading zero to the left of the decimal point, in which case a space is printed. Trailing zeros to the right of the decimal point are printed. Prints a leading plus (+) for positive values and a leading minus () for negative values. This token must lead the mask. Prints a leading minus () for negative values and nothing for positive values. This token must lead the other tokens.
Layout Properties
8 45
Format Token MI
Explanation Prints a minus () after negative values and a space after positive values. This token must trail the other tokens. Prints a minus () for negative values and a plus (+) for positive values (wherever the S appears in the mask). This token must lead or trail the other tokens. Prints angle brackets (<>) around negative values and spaces around positive values. This token must trail the other tokens. Prints parentheses around negative values and spaces around positive values. The parentheses must surround the other tokens. Prints a DB after positive values. This token must trail the other tokens. Prints a CR after negative values. This token must trail the other tokens. Causes no sign symbol to be printed for negative or positive values. Causes the number to be multiplied by 10N, * and S tokens where N is the number of 0 0, 9 9, *, that appear to the right of the V. Causes the number to be printed in scientific notation. All digit tokens refer to digits of the mantissa. There must be exactly one digit to the left 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 minus (), if the ordinate is negative, and two digits representing the ordinate (e.g., E99). Prints the string between the double quotes. To have doublequotes q inside the string, g type yp d bl doublequotes t back b k to t back b k (). () Prints a period (.) to separate the integral and fractional parts of a number. Prints the local decimal character to separate the integral and fractional parts of a number. Prints a comma (,) as the group/thousands separator. Prints the local group/thousands separator.
PR
()
DB CR Y V
EEEE
string string
. (period) D , (comma) G
8 46
Format Token $ L C % B K <>
Explanation Prints $. Prints the local currency symbol. Prints the ISO currency symbol. Prints %. Prints a blank space. (Do not include quotes in mask.) Prints a blank space for all zero values, regardless of other tokens. Prints a blank space. Delineates the beginning and ending of the decimalaligned region (i.e., that part of the number that you want aligned with the decimal point in the format mask). Angle brackets indicate that the number should always occupy the same amount of space. If necessary, values are padded with blanks to the left or right of the decimal point. Oracle Reports will align the decimal point based on the number of characters to the right of the decimal point. If a proportional font is used, it does not actually align the decimal point. Prints values in uppercase or lowercase Roman numerals, respectively. You cannot enter any other tokens with this token.
RN rn Examples:
The following tables illustrates some sample format masks: Sample Date Format MM/DD/YY DD MON YYYY Mon. DD, YYYY Day Month DD fmHH:MI AM Dy Mon ddth fmHH24:MI:SS Day the ddthsp of Month Sample Date Display 03/04/85 04 MAR 1985 Mar. 4, 1985 Monday March 4 11:35 AM Mon Mar 4th 23:35:22 Monday the fourth of March
Layout Properties
8 47
Sample Number Format

0000
Value
7934 7934
Number Displayed*
7934 7934 07934 7639 535 **** 7902 *7902 +100 99 1600 (800) 1600 <800> 1600 800 34300 7.37E+03 SRW7782 $800 $1600 %10 3 000 + + $ $ $ $ $ $ 1950.00 900.00 1200.00 500.00 1200.00 DB 500.00 1200.00 500.00 CR
00000 NNNN
7934 7639 535
NNN **** ***** +NNNN
7639 7902 7902 100 99
(NNNN)
1600 800
NNNNPR
1600 800
NNNNMI
1600 800
NNNVNN N.NNEEEE SRW0000 $NNNN.NN
343 7369 7782 800 1600
%NNN NN NNN.NN +KKNNNNN.00
10 3000 1950 900
$<NNNNN.00>
1200 500
$<NNNNN.00> DB
1200 500
$<NNNNN.00> CR
1200 500
* Note that the quotation marks will not appear in your output. They are used here to make it clear where there are leading or trailing spaces.
8 48
Rules: 1. If For number format masks, if the actual value is longer than the specified format mask, the value will appear as a string of asterisks in the report output, regardless of the fields width. For example, if a fixed fields width is 8, the value is 1234567, and the format mask is <NNNNNN>, your output will be *******. Similarly, if the number format mask causes the value to be larger than the field width, asterisks will appear in place of the value. For example, if a fixed fields width is 6, the value is 1234, and the format mask is 99999999, your output will be ******. This occurs because the format token 9 prints a blank for leading zeros to the left of the decimal. As a result, the value is too long to be displayed in a field of width 6. 2. If you do not specify a sign token in the format mask, positive values are preceded by a space and negative values are preceded by a minus (). This behavior is different from the default behavior in SQL*ReportWriter Version 1.1. Specifying the Y format mask token causes the Version 1.1 default behavior. 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 the source columni.e., format masks for numbers are displayed when the source column is a number, and format masks for dates are displayed when the source column is a date. Format masks that print spaces for zeros (e.g., 9) increase the number of bytes per page taken up by your output.
3.
4.
Hidden
Indicates that the field should not be formatted. Hidden is used for fields that you only want to reference in boilerplate text. This property is most often used for form letter reports, where fields are referenced in boilerplate text. To reference a hidden field, type &fieldname within the boilerplate text object. Look at Examples below. For more information about boilerplate, see Boilerplate Properties on page 8 59. Required/Optional: Optional. Default: Unchecked.
Layout Properties
8 49
Examples: 1. Suppose that you are building a form letter report and you want to insert the name, address, and phone number of the addressee in the letter. You create a field called NAME1 for the name of the addressee, ADDRESS for the address, and PHONE for the phone number. These fields are only to appear within boilerplate text, so you check Hidden. Within the boilerplate text where you want these 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 4153631234
Rules: 1. The following properties and attributes of a hidden field are applied 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
8 50
2.
A hidden field reference can appear anywhere in boilerplate text. If you want to place the field reference next to other text with no spaces in between, enclose the field name in angle brackets (e.g., &<fieldname>Kg). Otherwise, Oracle Reports will assume that all of the text between the ampersand and the next space is part of the field name. Note, however, that you can put references right next to each other with no spaces in between and without angle brackets (e.g., &field1&field2&field3).
Minimum Widow Lines
Is the minimum number of lines of the field that should appear on the logical page where the field starts to print. If the number of lines specified for this property cannot fit on the logical page, then the field starts to format on the next page. If this property is 1, there is no minimum and the field will start printing on any logical page that can fit one line of the field. Note: This property applies only to the initial lines of text in the field. It does not provide widow protection for individual paragraphs within the field. Required/Optional: Optional. Options: Enter any whole, positive number from 1 through 32K. Blank means the same as entering 1. Default: Examples: 1. With Minimum Widow Lines set to 1, you might get a situation like the one shown in the first figure below, where the first line of the field is printed at the bottom of a logical page and the rest is printed on the next logical page. With Minimum Widow Lines set to 2 (or more), you can avoid having one line of a field at the bottom of the logical page by itself, as shown in the second figure. Blank.
Layout Properties
8 51
Page Numbering
Is a button that displays the Page Numbering dialog box, shown below. Page numbering is how page numbers are calculated for fields that have a Source of &Physical Page Number, &Total Number of Physical Pages, &Logical Page Number, or &Total Number of Logical Pages. Note: The settings for each page are based on the logical or physical page as specified by the fields source. The figure below illustrates the differences between logical page, physical page, and panel numbering. Note that each region may contain multiple logical pages. Furthermore, within each logical page you may have multiple panels. In the Header and Trailer region, however, the logical page can only be one panel wide. In the Body region, the logical page can be more than one panel wide. Note: In the figure below, physical pages are numbered consecutively starting with the Header pages. This assumes that you selected Header, Body, and Trailer under Include.
8 52
Include
Indicates which report sections are used to compute the report page numbers. You can check Header, Body, Trailer, or some combination of choices. The default is Header, Body, and Trailer all checked, implying that all pages of the report should be included in computing page numbers.
Layout Properties
8 53
Start At
Is a number from 1 through 32K that should be used for the first page on which the field is formatted. The default is 1, implying that numbering should begin with 1. Is a number from 1 through 32K by which to increment for each page. The default is 1, implying that the page number should be incremented by 1 for each new page. Is when to reset the page number to the initial value specified in Start At. Reset At has a list of values (&Report and all enclosing repeating frames). The default is &Report, implying that the page number only be reset once at the beginning of the report. When a repeating frame is specified, the page number will be reset for each instance of the repeating frame.
Increment By
Reset At
Examples: 1. Suppose that you want to number the physical pages of the Body region of your report. You create a field named F_PAGE and give it a Source of &Physical Page Number. You then select Page Numbering from the Field property sheet and fill out the Page Numbering dialog box as follows:

Check Body and uncheck Header and Trailer because you only want 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 to number 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 each page of your report. Furthermore, you want the page number to be of the form Page n of total pages. 2.1 Create a field called F_PAGE and give it a Source of &Physical Page Number. You then select Page Numbering from the Field property sheet and fill out the Page Numbering dialog box. 2.2 Check Body and uncheck Header and Trailer because you only want to number the Body region pages. 2.3 Enter 1 in the Start At setting.
8 54
2.4 Enter 1 in the Increment By setting. 2.5 Enter &Report in the Reset At setting because you dont want the page numbers to reset to zero until the report is done. Now you need to create a field called F_TOTPGE and give it a Source of &Total Number of Physical Pages. 2.6 Select Page Numbering from the Field property sheet and fill out the Page Numbering dialog box. 2.7 Check Body and uncheck Header and Trailer because you only want 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 dont want the page numbers to reset to zero until the report is done. You could hide these fields (i.e., select Hidden in the Field property sheet) and reference them within boilerplate text:
Page &F_PAGE of &F_TOTPGE
Alternatively, position F_PAGE and F_TOTPGE beside each other. Insert boilerplate to the left of F_PAGE that contains the text Page. Insert boilerplate between F_PAGE and F_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 that each instance spans. Assume also that you want the page number to be of the form Page n of total pages. Follow the same steps as in Example 2 above, with the following exceptions:

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 following text:
Page &F_PAGE of &F_TOTPGE
Alternatively, position F_PAGE and F_TOTPGE beside each other, inside R_1, using the Layout editor. Insert boilerplate to the left of F_PAGE that contains the text Page. Insert boilerplate between F_PAGE and F_TOTPGE that contains the text of.
Layout Properties
8 55
Set the Print Condition of F_PAGE and F_TOTPGE such that they will print on all logical pages of R_1, i.e., Print Condition Type of All and Print Condition Object of Enclosing Object.
Rules: 1. If the Reset At value is a repeating frame, do not have the field appear 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 repeating frame 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 is reset. This ensures that the field will only appear when the repeating frame appears. Create a Format Trigger for the field such that it will only be displayed on pages where its value makes sense (i.e., pages on which one instance of the repeating frame appears).
Similarly, if the field is not inside the repeating frame it resets at and multiple instances appear on the same page, Oracle Reports cannot determine the value of the field and the results are again unpredictable. To avoid this situation, you can do any one of the following:

Place the field inside the repeating frame at which its value is reset. Set Maximum Records Per Page to one for the repeating frame at which the the fields value is reset.
Source
Is the place where the field gets its values (usually a column or a parameter). Note: If the Source is a page number value (e.g., &Logical Page Number), you can select Page Numbering to control how the page numbering is done. For more information, see Page Numbering on page 8 52. Required/Optional: Required. Options: &Current Date is the operating system date when the report runs, after the Runtime Parameter Form is finished. &Logical Page Number is the current page number based upon numbering the output by logical pages.
8 56
&Panel Number is the current panel number within the logical page. &Physical Page Number is the current page number based upon numbering the output by physical pages. &Total Logical Pages is the total number of pages based upon numbering the output by logical pages. &Total Panels is the total number of panels within a logical page. &Total Physical Pages is the total number of pages based upon numbering the output by physical pages. Select any valid column or parameter name. Examples: 1. Assume that you have a report with a data model like the one in the figure below. Assume further that G_Dept is the Source for repeating frame R_Dept and G_Emp is the Source for repeating frame R_Emp.
In this example, DEPTNO and DNAME could be the Source for fields in either R_Dept or R_Emp. ENAME and SAL could only be the Source for fields in R_Emp. Rules: 1. If a field is enclosed in a repeating frame, the column used as its Source must be in the source group or an ancestor of the source group of the fields enclosing repeating frame. The figure below shows a group tree. If the source group of the repeating frame were 6, then the field source could be 1, 3, or 6.
Layout Properties
8 57
If the field has no enclosing repeating frame, the column must be a reportlevel 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 a source must be contained in repeating frames that use the columns group as their source. In addition, any boilerplate objects that reference the field must also be contained in repeating frames that use the columns group as their source. If you specify a source for a field and later delete that source from your report (i.e., create a summary column, specify it as the source for a field, and later delete that summary column), your field no longer has access to data to display, and *UNDEFINED* appears in
the Source field.
3.
4.
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 the field (either the field itself or a boilerplate object) must have fixed sizing. For more information, see Vertical Sizing on page 8 20. A field cannot have a Source of Sound or Video.
5.
8 58
Boilerplate Properties
When you doubleclick on a boilerplate object (e.g., text or an image) in the Layout editor or its icon in the Object Navigator, its Boilerplate property sheet is displayed. The Boilerplate property sheet is divided into the following tabs:

Object Tab of Boilerplate Property Sheet

The Object tab of the Boilerplate property sheet is shown below. It contains the following properties:

Format 8 60 Link File 8 60 Minimum Widow Lines 8 62 Note: The Object tab only appears for certain types of boilerplate (e.g., link file boilerplate).
Layout Properties
8 59
Rules: 1. The maximum size of boilerplate text is 64K of text per paragraph and 64K paragraphs. This limit may vary according to your operating system. Boilerplate must be in front of the repeating frame that contains it.
2.
Caution: When you resize boilerplate text, ensure the text fits in the object. If font descends (the space left for the lower parts of letters like g and q) do not fit, the text line will appear in the editor, but, when the report is run, the line may not appear in the output, depending upon the Horizontal/Vertical Sizing settings.
Format
Is the format of the file displayed in Link File. Required/Optional: Required, if Link File is specified. Options: 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 Oracle format. All the other image formats are provided in case you want to open the report in Oracle Reports Version 2.0. If you are planning to open/run the report in Version 2.0, select the specific image format of the boilerplate. If not, you can choose from the above choices. For more information on the available formats, see Oracle Reports File Storage on page 18 2.
Link File
Is the name of a file to which the boilerplate is linked. Link File is useful for including the contents of files that are likely to change. The boilerplate is automatically updated to reflect the latest contents of the file when you do any of the following:

accept the property sheet paste the object import the object (if its in Oracle Format) open the report run the report
8 60
The contents of a file linked to a boilerplate object will appear in the Layout editor, but cannot be edited within the Layout editor. You can also include files in your report using Read from File. For more information, see Read From File on page 6 23. If you specify Link File, you must also specify Format. Required/Optional: Optional. Options: Enter a valid filename not to exceed 1K in length. You can prefix a path to the filename. If a path is not prefixed to the filename, Oracle Reports uses its file path search order to find the file. For more information about file path search order, see FileSearching Method on page 18 9. To ensure the portability of your reports, you can take advantage of the Oracle Reportsspecific environment variable called REPORTS25_PATH. You can use this variable to specify the default directory or directories where you want Oracle Reports to search for external files you use in your reports (e.g., external queries, boilerplate, and PL/SQL). This prevents the need to hardcode directory paths in your report. For more information on setting this variable, see Oracle Reports Environment Variables on page 18 10. Default: Rules: 1. 2. The maximum size of the file you specify depends upon your operating system. The link file name may be operatingsystem dependent. If you move the report to another operating system, you may need to update the name in Link File. This field appears only for objects created with the Link File tool. For more information, see Link File Tool on page 7 14. 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 treated as an anonymous graphical object (i.e., the properties of the object will be ignored). If you want the objects properties to be used, then you should import it instead of using Link File. Blank.
3. 4.
Layout Properties
8 61
Minimum Widow Lines
Is the minimum number of lines of the boilerplate text that should appear on the logical page where the text starts to print. If the number of lines specified for this property cannot fit on the logical page, then all lines of the boilerplate are moved to the next page. If this property is 1, there is no minimum and the boilerplate will start printing on any logical page that can fit one line of the boilerplate. This property is similar to Minimum Widow Lines for fields. For more information about Minimum Widow Lines for fields, see Minimum Widow Lines on page 8 51. Note: This property applies only to the initial lines of text in the boilerplate object. It does not provide widow protection for individual paragraphs within the boilerplate. Required/Optional: Optional. Options: Any whole, positive number from 1 through 32K. Blank means that the boilerplate should only be printed if all of its lines can fit on the logical page. Default: Rules: 1. Minimum Widow Lines can only be used on text boilerplate. Blank.
Anchor Properties
When you doubleclick on an anchor in the Layout editor or its icon in the Object Navigator, the Anchor property sheet, shown below, is displayed. The Anchor property sheet contains these fields:

Collapse Horizontally/Vertically 8 69 Edge (parent and child) 8 69 Object 8 69 Parent 8 69
8 62
Anchors are used to determine the vertical and horizontal positioning of a child object relative to its parent. The end of the anchor with a symbol on it is attached to the parent object. Since the size of some layout objects may change when the report runs (and data is actually fetched), you need anchors to define where you want objects to appear relative to one another. An anchor defines the relative position of an object to the object to which it is anchored. Positioning is based on the size of the objects after the data has been fetched rather than on their size in the editor. (Note that in positioning the anchor on the objects edges, you can shiftclick 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 repeating frame that has its Horizontal Sizing set to Variable. You also want the field to be a fixed distance from the top edge of the repeating frame. Since you dont know how large or small the formatted repeating frame will be, you need to use anchors to center the field. To center the field horizontally within the repeating frame do the following:
Layout Properties
8 63
1.1 Place the field inside the repeating frame such that the x coordinate of the center of the top of the field is the same as the x coordinate of the center of the top of the repeating frame. See the figure below. 1.2 Draw an anchor from the center of the top of the field to the center 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 repeating frame that has its Vertical Sizing set to Variable. You also want the field to be a fixed distance from the top edge of the repeating frame. Since you dont know how large or small the formatted repeating frame will be, you need to use anchors to center the field. To center the field vertically within the repeating frame, draw an anchor from the center of the left edge of the field to the center of the left edge of the repeating frame. The field will now be centered vertically within the repeating frame. See the figure below.
8 64
3.
Suppose that you have anchored Field B to Field A and you check Vertically under Collapse. The figure below illustrates the anchor between the two fields.
Assume that on the first logical page of the report, Field A prints and takes up so much room that Field B cannot fit on the logical page. Therefore, Field B prints on the second logical page, where Field A does not appear. Because Vertically is checked, the anchor collapses in the y direction. Field B maintains its relative positioning to Field A in the x direction even though Field A does not actually appear on the logical page.
Layout Properties
8 65
4.
Assume the same conditions as in the previous example, but in this case you want Field B to move both vertically and horizontally into the 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 Field A. 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 up so much room that Field B cannot fit on the logical page. Therefore, Field B prints on the second logical page, where Field A does not appear. The anchor collapses and Field B moves into the position that Field A would have appeared in had it appeared on the logical page as painted.
8 66
The diagram below illustrates this:
When Fields A and B do print on the same logical page, the anchor does not collapse and the fields maintain their relative position to one another. Rules: 1. 2. An object may be anchored to only one other object. Matrix objects, anchors, and the margin cannot be anchored to anything (i.e., they may not be the parent or child object for an anchor). A repeating frame that is the vertical or horizontal repeating frame for a matrix cannot be anchored to another object, but other objects may be anchored to it (i.e., it can be the parent but not the child object for an anchor). Nothing can be anchored to a hidden object (an object with Hidden checked). Moving an anchor also causes the two objects it anchors together to move.
3.
4. 5.
Layout Properties
8 67
6.
Objects cannot be anchored together in such a way that they have a circular dependency. For example:
Assume that object A and object B are anchored together and object A is the parent. Object B cannot be the parent for another anchor between object A and object B. In addition, object B cannot be the parent for an anchor to object C, if object C is the parent for an anchor to object A.
Assume that frame A contains field B and field B is above frame A 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 C cannot be the parent for an anchor to field B. Because it is inside of frame A, field B cannot be anchored to field C, if field C is the parent.
8 68
7.
To copy an anchor, you must select the anchor and the two objects it anchors together. If you select the anchor by itself, nothing will be copied to the paste buffer. If you select the anchor and one of the objects, only the object is placed in the clipboard. An anchor cannot be resized. 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 child objects). Oracle Reports prevents you from moving the anchor to a layer below its parent and child objects.
8. 9.
10. You cannot use Align, Align Objects, or Size Objects from the Arrange menu on anchors.
% (Child)
Is the percentage down or across (from top to bottom or left to right) the child objects Edge where the anchor is located. This setting is the position of the anchor on the Edge when the object is populated. Options: An integer from 0 through 100.
% (Parent)
Is the percentage down or across (from top to bottom or left to right) the parent objects Edge where the anchor is located. This setting is the position of the anchor on the Edge when the object is populated. Options: An integer from 0 through 100.
Edge (Child)
Is the edge of the child object (Top, Bottom, Left, Right) on which the anchor is located. Options: Bottom Left Right Top
Edge (Parent)
Is the edge of the parent object (Top, Bottom, Left, Right) on which the anchor is located. The options for this setting are the same as those listed above for Edge (Child). Indicates whether the anchor should have zero length if the parent object does not print for some reason (e.g., because of its Print Condition or Format Trigger). If the parent object does not print, the child object moves horizontally into the space vacated by the parent. Is the name of the child object. This field is readonly. Is the name of the parent object. This field is readonly.
Horizontally
Object Parent
Layout Properties
8 69
Vertically
Indicates whether the anchor should have zero height if the parent object does not print for some reason (e.g., because of its Print Condition or Format Trigger). If the parent object does not print, the child object moves vertically into the space vacated by the parent.
Matrix Properties
When you doubleclick on the matrix area in the center of overlapping repeating frames or a matrix objects node in the Object Navigator, the Matrix property sheet is displayed. A report may have multiple matrices within it, provided that the data model contains the necessary groups. The Matrix property sheet is divided into the following tabs:

General Tab of Matrix Property Sheet

The General tab of the Matrix property sheet is shown below. It contains the following properties:

Cross Product Group 8 72 Horizontal Frame 8 72 Name 8 8 Vertical Frame 8 73
8 70
Examples: 1. Suppose that you have a group named Group1 that contains a column called C_DEPTNO, which gets its values from the database column DEPTNO. A group called Group2, contains column C_JOB, which gets its values from the database column JOB, and column C_DEPTNO1, which is used for linking to Group1s query. A group called Group3 contains a column called SUMSAL, which is a summary of the database column SAL.
Analyst Dept 10 20 30 $6000 Job Clerk $1300 $1900 $ 950 Manager $2450 $2975 $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 contains Group1 (the department numbers). The Cross Product Group is Group4 (the group that is the parent of Group1 and Group2).
If you need to build a more complex matrix, you can do so by adding more columns to Group1 and Group2. For example, instead of having Group1 just contain department numbers, it could also contain the locations (LOC) of the departments. The matrix might then look something like the one below.
Loc New York Dallas Chicago Dept 10 20 30 Analyst $6000 Job Clerk $1300 $1900 $ 950 Manager $2450 $2975 $2850
Rules: 1. 2. The down repeating frames must be below the across repeating frames in a matrix. A matrix object must always be on top of the repeating frames that form it (i.e., it must be one or more layers above its horizontal and vertical repeating frames). Oracle Reports prevents you from moving the matrix below its horizontal and vertical repeating frames. Moving a matrix also causes its two repeating frames to move.
3.
Layout Properties
8 71
4.
A matrix object cannot be anchored to another object and other objects cannot be anchored to it (i.e., a matrix object cannot be the parent or child object for an anchor). To copy a matrix, you must select the matrix and its two repeating frames. If you select the matrix by itself, nothing will be copied to the paste buffer. If you select the matrix and one of the repeating frames, only the repeating frame is placed in the paste buffer. A matrix object can only be resized by resizing its associated repeating frames. You cannot use Align, Align Objects, or Size Objects from the Arrange menu on matrix objects. The source groups of the repeating frames that make up the dimensions of a matrix must be from the same crossproduct group. Repeating frames whose source groups are in the same family hierarchy (i.e., are descendants or ancestors of each other) must have the same Print Direction. Parentchild relationships within a crossproduct group are used to create nesting in the matrix. As a result, the repeating frames associated with such groups must print in the same direction on the page.
5.
6. 7. 8.
9.
10. You can put a border on a matrix object just as you would any other object, but the width will always be the minimum width possible. You cannot widen the border due to the closeness of the objects in a matrix layout.
Cross Product Group
Is the group that contains the source groups of the Horizontal and Vertical Frames. The cross product group correlates values between one or more groups to produce the data in the matrix. For more information about cross product groups, see Data Model Properties on page 6 1. Required/Optional: Required. Options: Default: Enter a valid cross product group name. Blank.
Horizontal Frame
Is the repeating frame whose values produce the row headings and summaries, and help compute the cross product for the matrix. See the diagram above for a graphic representation of Horizontal Frame. Required/Optional: Required. Options: Enter any valid repeating frame name.
8 72
Default: Rules: 1.
Blank.
The source groups of the repeating frames specified in Horizontal and Vertical Frame must be within the same crossproduct group.
Vertical Frame
Is the repeating frame whose values produce the column headings and summaries, and help compute the cross product for the matrix. See the diagram above for a graphic representation of Vertical Frame. Required/Optional: Required. Options: Default: Rules: 1. The source groups of the repeating frames specified in Horizontal and Vertical Frame must be within the same crossproduct group. Enter any valid repeating frame name. Blank.
Oracle Graphics Properties

When you doubleclick on an Oracle Graphics object in the Layout editor or its icon in the Object Navigator, its Oracle Graphics property sheet is displayed. The Oracle Graphics property sheet is divided into the following tabs:

O.G. Display 8 75 O.G. Query 8 78 General Layout 8 3 Printer Codes 8 26 Comments 8 27
Layout Properties
8 73
Examples: 1. Suppose that you have a master/detail report with the following data model:
In Oracle Graphics, you have created an Oracle Graphics display (empsal.ogd) that shows a bar chart of salaries for each employee and you would like to include it in your report. Using the Oracle Graphics tool in the Layout editor, you first draw an Oracle Graphics object inside the repeating frame for the master repeating frame (R_Dept). This means that the bar chart will appear once for each department. You then go to the property sheet for the Oracle Graphics object and enter empsal.ogd for Display Name. Display Name can optionally contain a path, but, in this case, no path was specified because we want Oracle Reports to use the path specified for the REPORTS25_PATH environment variable. For more information on the file searching method, see FileSearching Method on page 18 9. You then fill out the property sheet as follows: Source G_Emp Display Query Q_OG_Emp Report /Display Column ENAME/OG_NAME SAL/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_Emp contains the following SELECT statement:
SELECT ENAME OG_NAME, SAL OG_SALARY FROM EMP
8 74
Because you specified Q_OG_Emp for Display Query, this query will retrieve the values of ENAME and SAL from Oracle Reports instead of the database. Report Column and Display Column map the reports columns to the displays columns. You select ENAME and SAL from the list under Report Column. You must enter the names of the display columns 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 placed anywhere in the Layout editor unless its source group is a dimension of a matrix. If an Oracle Graphics displays source group is a dimension group (i.e., a group within a crossproduct group), then it must appear inside the repeating frame(s) of its source groups ancestors (if any). For more information on matrix reports, see Matrix Reports on page 2 27. An Oracle Graphics display that passes parameters must be placed inside of a repeating frame whose source group is the group (or a descendant of the group) that contains the columns or parameters it is passing. If a column being passed is a summary owned by a crossproduct group, then the Oracle Graphics display must be placed inside of the set of repeating frames whose sources are the groups in the summary columns Product Order. For more information on Product Order, see Product Order on page 6 33.
2.
O.G. Display Tab of Oracle Graphics Property Sheet

The O.G. Display tab of the Oracle Graphics property sheet is shown below. It contains the following properties:

Display Name 8 76 Display Parameter 8 77 List 8 77 Report Column 8 77
Layout Properties
8 75
Display Name
Is the name of the file in which the Oracle Graphics display is located. Required/Optional: Required. Options: Enter any valid filename (not to exceed 512 bytes in length) of an Oracle Graphics display (the .ogd extension is optional). You can optionally prefix a path to the filename. If a path is not prefixed to the filename, Oracle Reports uses its file path search order to find the file. For more information about file path search order, see FileSearching Method on page 18 9. Note: To ensure the portability of your reports, you can take advantage of the Oracle Reportsspecific environment variable called REPORTS25_PATH. You can use this variable to specify the default directory or directories where you want Oracle Reports to search for external files you use in your reports (e.g., external queries, boilerplate, and PL/SQL). This prevents the need to hardcode directory paths in your report. For more information on setting this variable, see Oracle Reports Environment Variables on page 18 10.
8 76
Display Parameter
Is a parameter in the Oracle Graphics display that corresponds to the column or parameter specified in Report Column. Note that one report column or parameter can correspond to multiple display parameters, but for each display parameter there can only be one report column or parameter. Required/Optional: Optional. Options: Enter the name (not to exceed 1K in length) of a valid parameter in your Oracle Graphics display. Enter a list of valid parameter names in your Oracle Graphics display, separating each one with a comma (e.g. parm1,parm2,parm3). Default: Oracle Reports parameter name.
List
Is a button that brings up the Display dialog box. After you accept this dialog box, the Oracle Graphics Display from File dialog box appears. From this dialog box, you can select an Oracle Graphics display for the Display Name field. Is a list of the columns and parameters in your report that could be used to supply the value of a parameter in an Oracle Graphics display. Selecting a column or parameter means that there is a corresponding parameter in the display and that the display parameter will get its value from the selected report column or parameter. If the parameter in the display has a different name than the column or parameter in the report, you must specify its name in the corresponding Display Column field. Required/Optional: Optional. Options: Rules: 1. A pagelevel summary column (i.e., a summary with a Reset At or Compute At of Page) cannot be passed to an Oracle Graphics display. Similarly, any summary or formula column that depends upon a pagelevel summary cannot be passed to a display. Select valid columns or parameters in your report.
Report Column (for Display Parameter)
Layout Properties
8 77
O.G. Query Tab of Oracle Graphics Property Sheet

The O.G. Query tab of the Oracle Graphics property sheet is shown below. It contains the following properties:

Display Column 8 78 Display Query 8 79 Report Column 8 79 Source 8 80
Display Column
Is a column or list of columns in the Oracle Graphics display that corresponds to the column or parameter specified in Report Column. Note that one report column or parameter can correspond to multiple display columns, but for each display column there can only be one report column or parameter. Required/Optional: Optional. Options: Enter the name (not to exceed 1K in length) of a valid column in your Oracle Graphics display. Enter a list of valid column names in your Oracle Graphics display, separating each one with a comma (e.g. col1,col2,col3). Default: Oracle Reports column name.
8 78
Display Query
Is the name of the query in the Oracle Graphics display that should get its records from Oracle Reports. If you specify a query name, that query will retrieve its records through Oracle Reports instead of the database. This enables your display to reflect any filtering or summarizing that your report performs on the data. Display Query ensures that the data used in the display is the same as the data in the report. If you specify a query name here, you must also specify which report columns or parameters should have their values used by the displays query. For more information on report columns, see Report Column (for Display Column) on page 8 79. For more information on display columns, see Display Column on page 8 78. Required/Optional: Optional. Options: Enter any valid query name (not to exceed 512 bytes in length) of the Oracle Graphics display specified in Display Name.
Report Column (for Display Column)
Is a list of the columns and parameters in your report that could be used by the query specified in Display Query. Selecting a column or parameter means that there is a corresponding column(s) in the Oracle Graphics display and that the display column(s) will get its value from the selected report column or parameter. If the column(s) in the display has a different name than the column or parameter in the report, you must specify its name in the corresponding Display Column field. Note: The list of columns and parameters is restricted by the group that you specify in Source. Only columns in the source group or above it in the group hierarchy are available for selection. Required/Optional: Required, if you entered Display Query. Options: Rules: 1. Any columns that you pass to the Oracle Graphics display via Report Column (for display column) must be in the Source group or its ancestor. A pagelevel summary column (i.e., a summary with a Reset At or Compute At of Page) cannot be passed to an Oracle Graphics display. Similarly, any summary or formula column that depends upon a pagelevel summary cannot be passed to an Oracle Graphics display. Select valid columns or parameters in your report.
2.
Layout Properties
8 79
Source
Is the group in the report that is summarized by the Oracle Graphics display Source is a list of values containing valid source groups. Required/Optional: Required, if value entered for Display Query. Options: Rules: 1. 2. You cannot specify a crossproduct group for Source. Any columns that you pass to the Oracle Graphics display via Report Column (for display column) must be in the Source group or its ancestor. If you select a Source but not a Display Query, the Source is deselected when you accept the property sheet. Select any valid group name.
3.
UserDefined Button Properties

When you doubleclick on a button object in the Layout editor or the Object Navigator, its Button property sheet is displayed. The Button property sheet is divided into the following tabs:

Rules: 1. 2. Buttons do not appear in printed output. They also do not appear when reports containing them are run in character mode. Buttons appear in the Previewer with the characteristics of native buttons on your platform. Therefore, changes made in the Layout editor that affect the appearance of the button (e.g., changing borders to dashed lines) may not appear in your output. Changing the border to a dashed line appears in the Layout editor but not the Previewer. The ability to assign different colors and patterns to userdefined buttons is platformspecific. For more information, refer to your Installation and Users Guide. You cannot rotate a button.
3.
4.
8 80
5.
A button is always be displayed on the uppermost layer of objects in the Previewer. However, it may not truly be on the top layer of your layout; for example, if it is covered by a repeating frame in the Layout editor, it will appear above the objects within the repeating frame in the Previewer, but will not repeat with the repeating frame.
Object Tab of Button Property Sheet

The Object tab of the Button property sheet is shown below. It contains the following properties:

Action 8 81 Label 8 83 Text String 8 83
Action
Is a set of radio buttons specifying the origin of the action that is performed when you press the userdefined button in the Previewer. The Action radio buttons govern whether the buttons source is a database column, a file, or a PL/SQL program unit. Required/Optional: Required.
Layout Properties
8 81
Options:
Multimedia Column indicates that the action to be performed when the button is pressed is contained in a database column. If you select Multimedia Column, you need to select a source column from the list to the right of the radio button. Selecting a source column automatically sets the proper multimedia type (i.e., sound, video, or image) under Type. Multimedia File indicates that the action to be performed when the button is pressed is contained in a file in your operating system. Enter the name of the file, including full path information, in the text field to the right of Multimedia File, or select List to use the file selection dialog box to choose the file. Then select Sound, Video, or Image from the Type list of values to the right of the text field. Execute PL/SQL indicates that the action to be performed when the media button is pressed is governed by a PL/SQL program unit associated with the button. To create or reference the PL/SQL, select Edit next to the Execute PL/SQL radio button. The PL/SQL Program Unit editor appears.
Multimedia File
If you select Multimedia Column, the name of the column must be selected under Source. If you select Multimedia File, you must indicate the filename in the text field provided. If you do not give a path for a file, Oracle Reports uses its file path search order 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 Oracle Reportsspecific environment variable called REPORTS25_PATH. You can use this variable to specify the default directory or directories where you want Oracle Reports to search for external files you use in your reports (e.g., external queries, boilerplate, and PL/SQL). This prevents the need to hardcode directory paths in your report. For more information about setting this variable, see Oracle Reports Environment Variables on page 18 10.
8 82
3.
If you specify a source for the action of a button and later delete that source from your report (i.e., select a image column, specify it as the source of the action for a button, and later delete that column or change its format to a nonmultimedia format), your button no longer has access to data to display, and Source becomes undefined. If the buttons property sheet is open at the time the Source becomes undefined, you must choose another source before you can accept the property sheet. If the property sheet is closed at the time the Source becomes undefined, you will not be alerted to the loss of the buttons source until you run the report and try to activate the button. An error will result.
4.
If you specify Execute PL/SQL and your PL/SQL uses SRW.RUN_REPORT, the Runtime Parameter Form will not appear by default when the button is selected. If you want the Runtime Parameter Form to appear, you must specify PARAMFORM=YES in the call to SRW.RUN_REPORT. Raising SRW.PROGRAM_ABORT in a buttons action trigger kills any Previewer window that was raised by the button.
5.
Label
Is the identifier appearing on the media button in the Previewer. Required/Optional: Optional. Options: Text indicates that you want to use a text string as the button label. Use the Text String field to the right of Label to enter the text string you want to use as a label. Icon indicates that you want to use an icon as the button label. Use the text field to the right of Label to the name of the icon you want to use as a label. Oracle Reports will use the path defined by the TK21_ICON environment variable. Default: Rules: 1. An icon used as a label should be in the standard icon format of your platform, with an extension of .ico. Icons are not portable. Text (text field is blank).
Text String
Is the text label that will appear on the button if you selected Text for the Label. Required/Optional: Optional.
Layout Properties
8 83
Options:
Any text string up to 2K in length; however, practical length is governed by the size of the button. Any text string used as a label is centerjustified both horizontally and vertically on the button. Empty.
Default: Rules: 1.
You can change the font, size, weight, and style of the label text using some of the choices on the Format menu. However, certain menu choices do not affect button text, such as Spacing and Justification. The text does not wrap to a second line, it is clipped on both the left and the right if it does not fit.
2.
OLE2 Object Properties

When you doubleclick on an OLE2 object in the Layout editor or its icon in the Object Navigator, its OLE2 property sheet is displayed. The OLE2 property sheet is divided into the following tabs:

General Layout 8 3 Printer Codes 8 26 Comments 8 27 Additional Information: If you click the right mouse button while the cursor is on an OLE2 object, a popup menu appears with actions appropriate to the object.
8 84
CHAPTER
Parameter Form Editor

he Parameter Form editor enables you to create and edit what appears in the Runtime Parameter Form, which typically appears before the report is executed. You should know the following about the Parameter Form editor:

what is the Runtime Parameter Form 9 2 definition and purpose 9 4 access 9 5 components 9 5 popmenu 9 7 navigation 9 8
91
Runtime Parameter Form

The sections that follow describe the following about the Runtime Parameter Form:

definition and purpose 9 2 access 9 2 components 9 2
Definition and Purpose The Runtime Parameter Form appears when a report is run. It enables
you to change the value of parameters in your report at runtime. For example, the user can specify the printer name, Oracle Mail userid, number of copies to be made, and bind and lexical values for parameters at runtime.
Access
The Runtime Parameter Form is accessed whenever you run a report, unless you have suppressed it. Note: To suppress the Runtime Parameter Form, you can include the keyword PARAMFORM=NO when you invoke R25DES or R25RUN, or you can check Hide Parameter Form in the Tools Options dialog box. For more information, see R25RUN on page 1 17 For more information, see R25DES on page 1 35.
Components
The Runtime Parameter Form has the following components:

title hint line parameter input area
92
Title
Title is the name given to the Runtime Parameter Form by you or Oracle Reports. What appears in the title is determined by what is in the Parameter Form editor, described later in this chapter. Hint Line is hint text for the Runtime Parameter Form created by you or Oracle Reports. What appears in the hint line is determined by what is in the Parameter Form editor, described later in this chapter. In general, the hint line provides information about what the user should do in the Runtime Parameter Form. The parameter input area is the part of the Runtime Parameter Form where you may enter values for parameters. What appears in the parameter input area is determined by what is in the Parameter Form editor, described later in this chapter. In general, the parameter input area contains the names of the parameters, their default value (if any), and a space for you to enter a value. The Destination Type parameter does not contain a default value, but if you clickandhold on the value field, a list of values appears from which you can choose. When you are done with the Runtime Parameter Form, accept it to run your report.
Hint Line
Parameter Input Area
93

The Parameter Form editor is the work area in which you define the format of the reports Runtime Parameter Form. To do this, you define and modify parameter form objects (fields and boilerplate). For more information, see Parameter Form Properties on page 10 1. When you run a report, Oracle Reports uses the Parameter Form editor as a template for the Runtime Parameter Form. Fields and boilerplate appear in the Runtime Parameter Form exactly as they appear in the Parameter Form editor. Note: If you do not define a Runtime Parameter Form in the Parameter Form editor, Oracle Reports displays a default Parameter Form for you at runtime. The figure below displays an example parameter form layout in the Parameter Form editor.
94
Access
There are several ways you can access the Parameter Form editor:
Select Tools>Default Parameter Form. After Oracle Reports builds the objects for you, you are placed in the Parameter Form editor to see the results of the defaulting. Select the Tools>Parameter Form Editor. From the Windows menu, select a window with the Parameter Form editor in it. From the Object Navigator, doubleclick on the Parameter Form nodes icon.
Components
The Parameter Form editor has the following components:

painting region toolbar tool palette status line
Painting Region
The painting region is the area in which you can create, modify, position, or delete objects while viewing their graphical representations on the screen. Objects have only their sizes and relative positions graphically represented in an editor. To see an objects settings, you must open its property sheet by doubleclicking on the object. The Parameter Form objects that you can create in the painting region are: fields and boilerplate. For more information, see Parameter Form Properties on page 10 1. Caution: You can cut, copy, paste, and duplicate objects in the Parameter Form editor, but note that only the graphical representations of the objects are copied. The property sheet settings are not copied with the objects.
Objects
Parameter Form Pages
The Parameter Form editor has no separate regions (such as header and trailer), and is comprised of physical pages. For more information, see Parameter Form Pages on page 9 8.
95
Rulers
Around the left and top edges of the painting region are rulers. These rulers function exactly as their counterparts in the Layout editor. For more information, see Painting Region on page 7 3. Inside the painting region is a grid to help you position objects in the painting region. The grid functions exactly as its counterpart in the Layout editor. For more information, see Painting Region on page 7 3. The Toolbar contains the following tools in the Parameter Form editor:

Grid
Toolbar
Open Save Run Print Clear Default Layout Help
Tool Palette
The Tool palette contains the following tools in the Parameter Form editor:

Selecting 7 9 Magnify 7 11 Rotate 7 10 Reshape 7 11 Rectangle 7 12 Line 7 11 Ellipse 7 12 Arc 7 12 Polygon 7 12
Polyline 7 13 Rounded Rectangle 7 12 Freehand 7 13 Text 7 13 Field 7 14 Border/Fill/Font display 7 15 Fill Color 7 15 Line Color 7 16 Text Color 7 17
These tools function exactly as their counterparts in the Layout editor.
96
Status Line
In the Parameter Form editor, the status line displays the following information:

absolute mouse position (in pixels, inches, or centimeters) mouse drag distance (in pixels, inches, or centimeters) 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.
PopUp Menu
The popup menu appears when you click your right mouse button in the Parameter Form editor.

Undo Cut Copy Paste Clear
The popup menu in the Parameter Form editor for nonOLE2 objects contains 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 Edit>Clear.
Properties Is the same as Tools>Properties. This item only appears if the cursor is over an object. Program Unit Editor Help Is the same as Tools>Program Unit Editor. This item only 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 or on an object that cannot have PL/SQL, only a subset of these items appears.
97
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 the Tool palette, see How To in Chapter 8 of Building Reports Manual.
Parameter Form Pages
A parameter form layout is composed of one or more physical pages. A physical page of the parameter form is a window of information that can contain boilerplate text and graphics, and fields. When you first enter the Parameter Form editor, you are placed on the first physical page. You can navigate to other pages of your parameter form by scrolling down. Pages are separated by dark lines in the editor, as shown below.
98
Defining Pages
You specify the size of each parameter form page and the number of pages using the Report property sheet (doubleclick on the reports node in the Object Navigator). The Parameter Form editor will display as many pages vertically as you have specified, separating each page by a horizontal line. For more information on specifying Parameter Form default settings, see Report Properties on page 4 1. Rules: 1. Objects that span pages will only appear on the first page of the Runtime Parameter form and will be truncated.
99
9 10
CHAPTER
10
Parameter Form Properties

arameter form properties define the objects that make up the parameter form layout. Each of the following objects has a property sheet associated with it that defines its properties:

field 10 2 boilerplate 10 4
10 1
Parameter Form Field Properties

When you doubleclick on a parameter form field in the Parameter Form editor or its icon in the Object Navigator, its Parameter Form Field property sheet is displayed. The Parameter Form Field property sheet is divided into the following tabs:

General Tab of Parameter Form Field Property Sheet

The General tab of the Parameter Form Field property sheet is shown below. It contains the following properties:

Datatype 10 2 Name 10 2 Source 10 3
Datatype
Is a readonly field that displays the datatype of the parameter form fields Source. Default: The datatype of the Source parameter.
Name
Is the name that Oracle Reports uses to identify the current field.
10 2
Required/Optional: Required. Options: Enter any valid parameter form field name. For more information about naming conventions, see Parameter Form Object Naming Conventions on page D 3. PF_n, where n is a number that is unique among parameter form field names for the report.
Default:
Source
Is the parameter from which the parameter form field gets its value. A list of values is provided and it contains all parameters in the report. Required/Optional: Required. Options: Default: Rules: 1. 2. The Source of a parameter form field must be a data model parameter. You cannot specify more than one parameter form field with the same Source. Enter any valid parameter name. Blank.
Comment Tab of Parameter Form Field Property Sheet

The Comment tab contains a field in which you can document the parameter form object. Required/Optional: Optional. Options: Default: Enter any text not to exceed 64K. Blank.
10 3
Parameter Form Boilerplate Properties

When you doubleclick on a parameter form boilerplate object in the Parameter Form editor or its icon in the Object Navigator, its Parameter Form Boilerplate property sheet is displayed. The Parameter Form Boilerplate property sheet is divided into the following tabs:

General Tab of Parameter Form Boilerplate Property Sheet

The General tab of the Parameter Form Boilerplate property sheet is shown below. It contains the following properties:

Name 10 4 Type 10 5
Name
Is the name that Oracle Reports uses to identify the current boilerplate. Required/Optional: Required. Options: Enter any valid boilerplate name. For more information about naming conventions, see Parameter Form Object Naming Conventions on page D 3.
10 4
Default:
PB_n, where n is a number that is unique among parameter form boilerplate names for the report.
Type
Is the kind of boilerplate the object is. This field is readonly.
Comment Tab of Parameter Form Boilerplate Property Sheet

The Comment tab contains a field in which you can document the parameter form object. Required/Optional: Optional. Options: Default: Enter any text not to exceed 64K. Blank.
10 5
10 6
CHAPTER
11
Previewer
he Oracle Reports Previewer enables you to view your report output in a window. You should know the following about the Oracle Reports Previewer:

definition and purpose 11 2 access 11 3 components 11 3 navigation 11 5 modification 11 6 character mode previewing 11 7 accessing multimedia objects 11 8 printing 11 11
Previewer
11 1

The Previewer is a window in which you view a reports output. When you run a report, you can send its output to several places, one of which is the Previewer (shown in the figure below). If you have the output sent to the Previewer, it appears automatically when you run a report.
DrillDown Oracle Reports enables you to have userdefined buttons with PL/SQL actions attached to them. By using the packaged procedure SRW.RUN_REPORT, you could define an action for a button that calls another report. This second (or detail) report appears in its own, modal Previewer. There is no limit to the number of levels you can drill down in this way. Multimedia Oracle Reports enables you to have userdefined buttons which play multimedia objects (e.g., video or sound) from the Previewer. When you define the button, you associate a multimedia object with it and when that button is selected in the Previewer the multimedia object is played. OLE2 Oracle Reports enables you to open OLE2 objects in your report from the Previewer. Doubleclicking on an object in the Oracle Reports Previewer will open the server application with the currently selected object. (Note if the object is linked, its source object is displayed.)
11 2
Access
To display and access the Previewer, you must first run a report. You can 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 the Previewer, the value of DESTYPE is probably being set someplace other than the Runtime Parameter Form.
From the Windows menu, select a window with the Previewer in it.
Components
The Previewer has the following components:

main menu 11 3 title 11 4 viewing region 11 4
Main Menu
If you run the report from within the designer (by selecting Run... from the File menu), the main menu appearing at the top of the Previewer contains the same activated menu items as in the designer menu. However, if the report was run using R25RUN, a subset of the designers main menu and its submenu choices is available:

The File menu contains Connect, Disconnect, Run, Print, Page Setup, 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 Oracle Reports. Note: When you select a button in the Previewer that runs another report, an additional, modal Previewer window is opened and some of the above menu items are disabled.
Previewer
11 3
Title
By default, the Previewer title is <report name>: Previewer. For more information on modifying the Previewer title, see Modification on page 11 6. The viewing region is the area in which you can browse through each page of your report output. When the Previewer first appears, the top of 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:

Viewing Region
report sections 11 4 physical and logical pages 11 4
Report Sections
A report section is one of three parts of your report: Header, Body/Margin, and Trailer. The Header can be any number of physical pages long, but only one physical page wide. The Body/Margin can be any length or any width. The Trailer can be any number of physical pages long, but only one physical page wide (like the Header). For more information on report sections, see Layout Editor on page 7 1.
Physical and Logical Pages
A physical page (or panel) is the size of a page that will be output by your printer. A logical page is the size of one page of your actual report (it can be any number of physical pages wide or long). The Previewer displays the logical pages of your report output, one at a time. The figure below illustrates an example of physical and logical pages.
11 4
Navigation
To navigate within the Previewer, do the following:

Select the First, Last, Next, and Previous buttons to move to the first, last, next, and previous page of output, respectively. Select the home, end, page down, and page up keys to move to the first, last, next, and previous page of output, respectively. Type a page number in the field beside the Page button. Select Page: to go to that page. If the number is greater than the number of pages, the last page will be displayed. Use the scroll bars and arrows to move the windows contents to the direction specified. Select the Print button to print the report output. For more information, see Printing from the Previewer on page 11 11. Note: If you split your Previewer, you must click in the desired section before navigating in it. Additional Information: If your report contains userdefined buttons, you can select them to execute their action. Buttons may play multimedia objects or execute a PL/SQL action.
Previewer
11 5
Modification
You can modify the following components within the Previewer:

title 11 6 viewing region 11 6
Title
To modify the Previewer title, do the following: 1. 2. 3. Doubleclick on the report nodes icon in the Object Navigator to display the Report property sheet. Go to the Parameter Form tab and enter new text in the Title field. Accept the Report property sheet.
Viewing Region
You can perform the following modifications on the Previewers viewing region:

split 11 6 magnify 11 7 open a new instance 11 7
Splitting the Viewing Region
To split the viewing region, do the following: 1. Clickandhold on the box that appears to the left of the horizontal scroll bar (to split horizontally) or above the vertical scroll bar (to split vertically). Drag the box to the point at which you wish to split the screen. For example, to split the screen so that the resulting sections are about equal in size, you would drag the box to the approximate vertical or horizontal center of the Previewer. When you release the mouse button, the viewing region splits into two 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.
11 6
Magnifying the Viewing Region
To magnify the viewing region select the Magnify icon in the lower left corner of the Previewer. The large Magnify icon increases the size of the Previewer contents and the small Magnify icon decreases the size of the contents. To open a new Previewer window with the same contents as the current one, select New from the current Previewer window.
Opening Another Window
Character Mode Previewing

If you intend to run a report from the charactermode runtime, you can enter settings to change the appearance of the charactermode Previewer by doing the following: 1. 2. 3. Doubleclick on the report nodes icon in the Object Navigator to display the reports property sheet. Go to the Character Mode tab and change the settings as desired. Accept the Report property sheet.
Previewer
11 7
Rules: 1. When displaying a character mode report in the bitmapped Previewer, Oracle Reports uses the report width and height defined in the Character Mode tab of the Report property sheet to choose the font size to display. The measured size of the font becomes the cell size. This ensures that the text of the report is shown completely (without clipping or overwriting), but it means that the Previewer page size may not be exactly 8.5 by 11.
Accessing Multimedia Objects

Userdefined buttons in your report can play multimedia objects or execute PL/SQL. Userdefined buttons can access the following types of multimedia objects:

sound 11 8 video 11 10 images 11 10
Accessing Sound
If the source associated with the userdefined button at design time is a sound, when the button is pressed the Sound dialog box is displayed to play the sound. Rules: 1. 2. If you close the Previewer while the Sound Dialog is open, the Sound Dialog also closes. Button actions are mutually exclusive. This means that only one button action can be in effect at a time.
Sound Dialog Box Options
The Sound dialog box is shown below and its options are described alphabetically following the figure.
Forward
Fast forwards to the end of the sound.
11 8
Options
Is a button that displays the Audio Control Panel. You use the Panel to set Sound Dialog options. The figure below shows the Audio Control Panel; its settings are described alphabetically following the figure.
Playback Setting Under Playback Setting are the following two options for controlling the play of a sound file: Volume Is the relative loudness of the sound when played. Click on the list and choose a number from zero to nine, with zero being softest and nine being loudest. Is whether the sound is output over your machines own speakers or headphones. Click on the list and choose your preference.
Device
Record Setting Under Record Setting are options governing the recording of a sound. Since you cannot record from the Previewer, these options are all disabled. Play Record Rewind Slidebar Stop Plays the sound beginning from wherever the slider is currently positioned. 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 move the slider to any position and play from that point. Stops the sound at any point.
Previewer
11 9
Accessing Video
If the source associated with the userdefined button at design time is video, when the button is pressed the Video Player dialog box is displayed to play the video. Rules: 1. 2. 3. If you close the Previewer while the Video Player dialog box is open, the Video Player also closes. Button actions are mutually exclusive. This means that only one button action can be in effect at a time. Video may not be available on all platforms. For more information, see the Developer/2000 Installation Guide for your operating system.
Video Player Dialog Box Options
The Video Player dialog box is shown below and its options are described alphabetically following the figure.
Play/Stop Slidebar Sound/Mute
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 move the slider to any position and play from that point. Plays the videos sound or mutes it at any point. If the source associated with the userdefined button at design time is an image, when the button is pressed an Image Viewer window, shown below, is displayed, containing the image. Additional Information: The Image Viewer window displays images with better fidelity than if they were simply imbedded in the report output. Rules: 1. If you close the Previewer while the Image Viewer is open, the Image Viewer also closes.
Accessing Images
11 10
2. Image Viewer Options
Button actions are mutually exclusive. This means that only one button action can be in effect at a time.
The Image Viewer is shown in the figure below and its tools are described alphabetically following the figure.
Magnify Tool
Magnifies an area around the point on which you click by a factor of two; i.e., the image becomes twice as big as it was. By pressing the constraint key (e.g., the shift key) while using the Magnify tool, you magnify by a factor of onehalf; i.e., the image become half as big as it was. This tool is useful when you want to focus on one part of a large image. Moves the image within the Image Viewer. Panning is similar to scrolling; however, you can move the image in two dimensions at once. To pan the image, select the Panning tool and drag the image.
Panning Tool
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 of this dialog box varies between operating systems. For more information, see the Developer/2000 Installation Guide for your operating system. After you accept the Print Job dialog box, the output is sent to the printer (specified in File>Choose Printer), file, or mail id. If you ran the report with a DESTYPE of Screen, a warning appears before the Print Job dialog box that you should run the report with a DESTYPE of Preview before printing. Preview creates PostScript output, which is typically more desirable for printing. Note: The Previewer output is displayed in terms of logical pages and will also be printed in terms of logical pages.
Previewer
11 11
11 12
CHAPTER
12
Object Navigator
he Object Navigator provides a simple and powerful way get around in Oracle Reports. You should know the following about the Object Navigator:

definition and purpose 12 2 access 12 2 component descriptions 12 3 popup menu 12 4 nodes 12 5 hierarchical views 12 10 navigation 12 15
Object Navigator
12 1

The Object Navigator provides a hierarchical display of all major objects 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 objects property sheet, edit an objects PL/SQL, drag and drop PL/SQL program units, and search for an object by name. For more information about the PL/SQL you can create in Oracle Reports, 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.
12 2
Components
The Object Navigator has the following components:

module list 12 3 Find field 12 3 Toolbar 12 3 object tree 12 3
Module List
At the top of the Object Navigator is a list of all of the currently open modules in the Object Navigator, and the most recently selected node and its ancestors. By selecting a name from the list, you can immediately select its node in the Object Navigator. At the top of the Object Navigator is a field called Find in which you can enter a target string for the node search. Next to the Find field are two tools for directing the search backward or forward: Finds the next node whose name matches the search string in Find. It will 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.
Find Field
Search Forward Search Backward
Toolbar
The Toolbar contains the following in the Object Navigator:

Open Save Run Print Create
Delete Expand Collapse Expand All Collapse All
Object Tree
The Object Tree is the area that displays a listing of objects in the current session of the designer. This listing consists of nodes, each representing an object or type of object. For more information, see Nodes on page 12 5.
Object Navigator
12 3
PopUp Menu
The popup menu appears when you click your right mouse button in the Object Navigator.
The popup menu in the Object Navigator contains the following items for most objects: Properties Editor Is the same as Tools>Properties. Displays the editor (Data Model, Layout, Parameter Form) that is associated with the currently selected object(s). If you have multiple objects selected, the editors associated with all the objects will be displayed. For example, if you select a field and then a column, the Data Model and Layout editors would be displayed when you select Editor. Is the same as Tools>Program Unit Editor. Is the same as Help>Contents.
Program Unit Editor Help
The popup menu in the Object Navigator contains the following items for breakpoints: Enable Disable Enables the selected breakpoint. Disables the selected breakpoint.
The popup menu in the Object Navigator contains the following items for program units or builtin program units: Paste Name Paste Arguments Pastes the name of the selected program unit into the last active Program Unit Editor. Pastes the arguments of the selected program unit into the last active Program Unit Editor.
Additional Information: Paste Name and Paste Arguments only work when the Program Unit Editor is already open.
12 4
Nodes
Each object or object type in your current designer sessionfrom each open report, to the objects in each reportis represented in the Object Navigator by a node. (A node is any selectable line in the Object Navigator.) This section discusses the following aspects of nodes:

node format 12 5 node types 12 7 hierarchical views of nodes 12 10
Node Format
Each node in the Object Navigator consists of some or all of the following:

a plus or a minus indicating the nodes expansion status 12 5 an icon representing the objects 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 and Object Navigator options (Navigator>Navigator Options). Plus/Minus Indicates the expansion status of the node:
A plus indicates that the node has other nodes underneath it, but they are not currently displayed. A node with a plus can be expanded to display its hidden child nodes. If the plus is greyed out, it means that the node could contain other nodes but currently doesnt. A minus indicates that the node has other nodes underneath it and they are currently displayed. A node with a minus can be collapsed to hide all its currently displayed child nodes.
Children of the current node can be displayed by doing any of the following:

Click on the plus to expand or shiftclick to expand all. Select Expand from the Toolbar. Select Navigator>Expand or Navigator>Expand All.
Object Navigator
12 5
The tree can be contracted in a similar fashion by doing any of the following:

Click on the minus to collapse or shiftclick 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. PL/SQL Icon Indicates that the object can have PL/SQL associated with it and whether 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 Unit Editor with the objects program unit in it, doubleclick on the PL/SQL icon. The figure below shows two nodes in the Object Tree. Both are for columns. Notice the difference between the PL/SQL icons in the nodes. The first node has a PL/SQL program unit associated with it. The second one could have a program unit associated with it but does not currently.
Object Type or Editor Icon Indicates the type of object or editor represented by the node; e.g., a node representing a query will display a query icon and the Data Model heading node will display a Data Model editor icon. To select the node, click on the object or editor icon. If the node represents a selectable object and its editor is open (e.g., the Layout editor), clicking also selects the object in its editor. To display an objects property sheet, doubleclick on its object icon. To display an editor, doubleclick on its editor icon. If you do not want the object icons to display, ensure that the Show Object Icons checkbox in the Object Navigator Options dialog box is unchecked. Note that if you hide the icons, you will need to use the Tools menu to access property sheets (Tools>Properties) and editors.
12 6
Object Name or Heading
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 is already select, a single click on the name places it in edit mode, and you can edit the name of the object (you cannot edit headings). Clicking outside the object deactivates edit mode and updates the edited name in all appropriate places (e.g., the layout and the objects property sheet). Similarly, if you change the objects name elsewhere, it will automatically be updated in the Object Navigator. Note: If the name in the Object Navigator is in edit mode but edited elsewhere, the name will not get updated in the Object Navigator. Instead, the name in the Object Navigator takes precedence and the objects final name will be that which is in the Object Navigator at the time edit mode is deactivated. Doubleclicking on the following heading nodes creates a new node, if the heading currently has no nodes underneath it:

Attached Libraries External Queries Libraries Program Units Reports Stored Program Units Triggers
Node Types
A node can represent one of the following:

heading 12 7 object 12 10
Heading Nodes
Heading nodes denote types of report objects or properties; e.g., Reports, Frames, Boilerplate, etc. These headings precede the nodes representng actual report objects and are used in navigation. The following is a listing of the heading nodes in the Object Navigator in the order in which they appear. Any actions specific to the node are explained. Heading Node Anchor Information Attached Libraries Description Lists all anchors (implicit and explicit) for an explicitly anchored object. Lists libraries attached to the report.
Object Navigator
12 7
Heading Node Body
Description Lists all the objects in the reports body pages. This node only appears when View Layout by Structure is selected in the Object Navigator Settings dialog box. Lists the available builtin packages. Lists all the button objects in the report. y the reLists all the columns selected by ports queries. Lists all the data links in the report. Lists database users and the stored program units, libraries, tables, and views owned by these users. Lists all data model objects in the report. Can be used to access the Data Model editor. Lists the debug actions in the current report. Lists the repeating frames that are related by the parent matrix object. Lists all the external boilerplate objects in the report. Lists external queries open in the current session. Lists objects whose frequency is the same as that of the repeating frame. Lists all the fields in the report Lists all the formula columns in the report. Lists all the frames in the report. Lists all the boilerplate graphic objects in the report. Lists all the groups in the report. Lists all the objects in the reports header pages. This node only appears when View Layout by Structure is selected in the Object Navigator Settings dialog box.
Builtin Packages Buttons Database Columns Data Links Database Objects
Data Model
Debug Actions Dimension Repeating Frames External Boilerplate External Queries Frequency <repeating frame name> Fields Formula Columns Frames Graphics Boilerplate Groups Header
12 8
Heading Node Image Boilerplate Layout Libraries Margin
Description Lists all the static image boilerplate objects in the report. Lists all layout objects in the report. Can be used to access the layout editor. Lists external libraries open in the current session. Lists all the objects in the reports margin. This node only appears when View Layout by Structure is selected in the Object Navigator Settings dialog box. Lists all the matrix objects in the report. Lists all the OLE2 objects in the report. Lists all the Oracle Graphics documents in the report. Lists all parameter form objects in the report. Can also be used to access the Parameter Form editor. Lists all the placeholder columns in the report. Lists all program units in the report. Lists the other program units that reference the program unit. Lists the other program units that are referenced by the program unit. Lists all the repeating frames in the report Lists reports open in the current session. Can be fully expanded to show all objects in the reports. Lists all the report triggers in the report. Shows the program units specification. Shows all objects in the Reports stack for current debug session. Lists all the summary columns in the report. Lists system parameters in the report. Lists all the text objects in the report.
Matrices OLE2 Objects Oracle Graphics Documents Parameter Form
Placeholder Columns Program Units Referenced By References Repeating Frames Reports
Report Triggers Specification Stack Summary Columns System Parameters Text Boilerplate
Object Navigator
12 9
Heading Node Trailer
Description Lists all the objects in the reports trailer pages. This node only appears when View Layout by Structure is selected in the Object Navigator Settings dialog box. Lists the usercreated parameters in the report.
User Parameters Object Nodes
Object nodes represent specific objects found in open reports during the current designer session; e.g., F_1, M_GRPFR_Dept, B_Rectangle, etc. When you select and object node in the Object Navigator, the object is also select in the appropriate editor (e.g., the Layout editor), if the editor is already open. The Object Navigator enables you to examine the hierarchy of report objects. You can examine the:

Hierarchical Views
data hierarchy 12 11 layout hierarchy 12 13
Below is a data model and layout for a sample report. Refer back to this sample during the following discussions.
12 10
Data Hierarchy
You can display groups and columns in the Object Navigator in either one of the following ways:

by structure 12 11 by type 12 12
View by Structure You can display groups and/or columns in a hierarchical tree structure. Child groups appear underneath their parent groups. Columns appear underneath the groups that own them. The tree is fully expandable and contractable, enabling you to examine relationships at any level. Siblings are displayed alphabetically. To view groups by structure, select View by Structure in the Groups tab of the Object Navigator Settings dialog box. To view columns by structure, select Show Columns in Groups in the Groups tab. The example below shows a data model object tree while View by Structure and Show Columns in Groups are selected.
Object Navigator
12 11
View by Type You can display groups and/or columns by type of object. Hierarchy is not indicated. To view groups by type, deselect View by Structure in the Groups tab of 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 View by Structure and Show Columns in Groups are deselected.
12 12
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 tree structure. Objects are shown underneath the objects that own them. The tree is fully expandable and contractable, enabling you to examine relationships at any level. Siblings are displayed alphabetically. To view layout by structure, select View by Structure in the Layout tab of the Object Navigator Settings dialog box. The example below shows a layout while View Layout by Structure is selected.
Object Navigator
12 13
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 of the Object Navigator Settings dialog box. The example below shows the same layout while View Layout by Structure is deselected.
12 14
Navigation
The Oracle Reports Object Navigator includes features that enable you to navigate among Object Navigator nodes, editors, and report objects:

navigation within the Object Navigator 12 15 navigation to other report objects 12 17
Navigation Within the Object Navigator
To aid in navigation within the Object Navigator, Oracle Reports provides the following features:

expanding and contracting nodes 12 15 searching in the Object Navigator 12 16
Expanding and Collapsing Nodes
Oracle provides several methods for expanding and collapsing nodes in the Object Navigator, enabling you to view as much or as little of the object tree as you wish.
Object Navigator
12 15
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 the following:

Shiftclick 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 the following:

Shiftclick 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 retain their expanded or collapsed state, independent of the action taken on their parent node. For example, suppose a node and all its subnodes are currently expanded. The node is collapsed, then subsequently expanded again. All its subnodes display in their original expanded state. To collapse a node without retaining its previous state, you must collapse all (e.g., shiftclick on the minus).
Searching in the Object Navigator
To search for a specific node in the Object Navigator, type the object name in the Find field. Select one of the icons to the right of the Find field to direct the search up or down in the Object Navigator. The first node name to match the target string is highlighted in the Object Navigator. All parent nodes of the target are expanded as necessary. Rules: 1. The Object Navigator search facility is caseinsensitive.
12 16
Navigation to Other Report Objects
To aid in navigation among report objects, Oracle Reports provides the following features:

quick access to editors 12 17 quick access to property sheets and associated PL/SQL 12 17
Accessing Editors
If you want to access an editor that is not open, iconized, or simply hidden behind other windows, doubleclick on the icon of the appropriate 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 can also use the Windows menu, but editors that are not open will not appear as menu choices.
Accessing Property Sheets To access the property sheet of a report object, go to the node and Associated PL/SQL representing that object in the Object Navigator and doubleclick on its objecttype icon. (For more information on the different parts of a node, see Nodes on page 12 5.) The property sheet for that object is displayed. To access the PL/SQL associated with a report object, go to the node representing that object in the Object Navigator and doubleclick on its PL/SQL icon. This will display the Program Unit Editor with the appropriate PL/SQL code already loaded and ready to edit. You can also select the node and then select Tools>Program Unit Editor.
Object Navigator
12 17
12 18
PART
III
Integration
CHAPTER
13
PL/SQL Interface
L/SQL provides conditional control and database transaction processing. The following describe PL/SQL in Oracle Reports:

overview 13 2 description of value constructs (functions and exceptions) 13 4 description of nonvalue 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 the PL/SQL Users Guide and Reference.
PL/SQL Interface
13 1
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
Definition and Purpose PL/SQL is a language for application development and database
transaction processing. It combines extensive procedural capabilitiessuch as conditional control and loopingwith the nonprocedural capabilities of SQL. You use PL/SQL to add its capabilities to an object, for example:

database manipulation capabilities (DML), such as ORACLE INSERTs, UPDATEs, and DELETEs procedural capabilities, such as perform arithmetic, string, and Boolean operations; specify branching with IF...THEN and GOTO statements; specify exception handlers for error processing)
To do so, you write a PL/SQL construct and assign it to an object. Note: PL/SQL does not support database definition capabilities (DDL). You can add DDL capabilities to Oracle Reports objects using the SRW.DO_SQL packaged procedure. For more information on this packaged procedure, see SRW.DO_SQL on page 13 43.
Types and Usage of PL/SQL Constructs
There are two basic types of PL/SQL constructs (code structures) that you can write: those that return (i.e., set) a value, and those that dont. The PL/SQL terms for these two types of constructs are:

value constructs, for PL/SQL code that returns a value nonvalue constructs, for code that does not return a value
In general, you write a value construct when the Oracle Reports object requires that you return a value; you write nonvalue constructs when the object requires that you do not. Objects Requiring Value Constructs
Report Triggers enable you to check the status of an object or change the logic of the report. Report Triggers can only return TRUE, i.e., continue the report execution, or FALSE, i.e., stop the execution.
13 2
Group Filters enable you to reduce the number of rows that are used in your report. Group Filters can only return TRUE, i.e., fetch the data specified in the filter, or FALSE, i.e., do not fetch the data specified. Formula Columns enable you to perform customized computations. They can return a number, date, character, or boolean. The value that is returned will become the value of the formula. Formula columns can also be used to set the value of placeholder columns. Placeholder Columns normally contain no PL/SQL, but, if their values are set in a user exit, their formulas must contain SRW.REFERENCE. Validation Triggers enable you to check the value entered on the Runtime Parameter Form. Validation Triggers can only return TRUE, i.e., continue processing, or FALSE, i.e., invalidate parameter. Frame, Repeating Frame, Field, and Boilerplate Format Triggers enable you to conditionally suppress or modify the appearance of data printed by these layout objects. They can either return TRUE, i.e., print the object with the specified attributes (if any), or FALSE, i.e., do not print the object.
Objects Requiring Nonvalue Constructs (None.) Objects Accepting Both Value and NonValue Constructs
External PL/SQL Libraries (packages, functions, or procedures) enable you to type code once that will be used by more than one module (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 that you can reference from the reports objects) enable you to type code once that will be used by more than one report object, thereby reducing redundant code. They can return any valid PL/SQL return type.
PL/SQL Interface
13 3
Value Constructs
A value construct is a PL/SQL construct (code structure) that returns a value. You can use value constructs in report triggers; group filters; column formulas; and frame, repeating frame, field, and boilerplate format triggers. In Oracle Reports, you express a value construct using a 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;
Advantages
Functions have a name and, therefore, can be referenced from other constructs. This allows constructs to be shared and reduces redundant code. Functions support exception handling, local variable declarations, and arbitrary control structure.
Syntax
FUNCTION function_name [argument_list] RETURN [type] IS [local_variable_declaration] BEGIN statements [EXCEPTION exception_handlers] RETURN(result); END;
where:
function_ name argument_ list
Is the unique name of the function. This name must adhere to ORACLE naming conventions. Is ({var_name [mode] type [:= value]}[, ...]) where:
var_name
Is the unique name of a local variable. Is {IN|OUT|IN OUT}.
mode
13 4
type
Is{BOOLEAN|CHAR|NUMBER|DATE| PLS_INTEGER}. Is a PL/SQL expression.
value
(Functions entered directly in Formula, Validation Trigger, Filter Condition, Formula, or a report trigger cannot take arguments.)
local_ variable_ declaration statements exception_ handlers result
Is {var_name type [:= value]}[,...]
Are the executable PL/SQL statements. For more information, see the PL/SQL Users Guide and Reference. Is the expression indicating the value of the function.
Examples: 1. Suppose you want to create a function that calculates the product of two numbers (e.g., to calculate an employees bonus pay). To do so, 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 BONUS column:
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 above example is to simply write the function completely in the BONUS columns formula:
FUNCTION MY_FORMULA RETURN NUMBER IS BEGIN RETURN(:PERCENT * :SAL); END;
PL/SQL Interface
13 5
3.
Assume that you created a parameter for your report called MY_PARAM, and before the report is run, you want to set the parameter to 100. To do so, you create the following in the Before Form trigger:
FUNCTION FOO RETURN BOOLEAN IS BEGIN :my_param := 100; RETURN (TRUE); END;
Note: Note that report triggers must always return a boolean value.
Nonvalue Constructs
A nonvalue construct is a PL/SQL construct (valid code syntax) that does not return a value. Nonvalue constructs are executed solely to perform a specified sequence of actions or side effects. For example, the side effect of an after report trigger might be to mail the report output to an interested party. A nonvalue construct may be expressed in PL/SQL as one of the following:

a procedure definition 13 6 a package 13 8
Procedures
You specify a nonvalue construct by entering a complete procedure definition. 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;
13 6
Advantages
Procedures have names and, therefore, can be referenced from other constructs. This allows constructs to be shared and reduces redundant code. Procedures support local variable declarations, and arbitrary control structure.
Syntax
PROCEDURE procedure_name [argument_list] IS [local_variable_declaration] BEGIN statements [EXCEPTION exception_handlers] END;
where:
procedure_ name
Is the unique name of the procedure. This name must adhere to ORACLE naming conventions. For more information, see the ORACLE7 Server SQL Language Reference Manual. Is ({var_name [mode] type [:= value]}[, ...]) where:
var_name
argument_ list
Is the unique name of a local variable. Is {IN|OUT|IN OUT}. Is {BOOLEAN|CHAR|NUMBER|DATE| PLS_INTEGER}. Is a PL/SQL expression.
mode type
value local_ variable_ declaration statements exception_ handlers
Is {var_name type [:= value]}[,...]
Are the executable PL/SQL statements. For more information, see the PL/SQL Users Guide and Reference.
PL/SQL Interface
13 7
Examples: 1. Assume you want to log PL/SQLdetected errors into a table called EXCEPTION_TABLE. To do so, you create the following reportlevel program unit:
PROCEDURE ERROR_LOG (MESSAGE VARCHAR2) IS BEGIN insert into ERROR_TABLE values (MESSAGE); END;
Packages
A package is a database object that groups logically related PL/SQL types, objects, and functions or procedures. Packages usually have two parts, a specification and a body, although sometimes the body is unnecessary. The specification is the interface to your module; it declares the types, variables, constants, exceptions, cursors, and functions or procedures that are available for use. The body fully defines cursors, functions, or procedures, and so implements the specification. Advantages

Modularity: packages enable you to encapsulate logically related types, objects, functions, and procedures in a named module. Added Functionality: global (package) variables and cursors persist for the duration of a session. So, they can be shared by all constructs. And, they enable you to maintain data across transactions without having to store it in the database. Note: Globals will perform faster than Oracle Reports parameters that you treat like globals. Globals are more useful than placeholder columns because they are not restricted: a formula column that sets a placeholder must be in the same group as the placeholder column. Globals can be used to set any value.
Better Performance: When you call a packaged function or procedure for the first time, the whole package is loaded into memory. Therefore, subsequent calls to related functions or procedures in the package require no disk I/O. In addition, packages stop cascading dependencies, and thus avoid unnecessary recompiling. For example, if you change the definition of a function, you must recompile all constructs that call the function. However, if you change the definition of a packaged function, you do not need to recompile the calling constructs because they do not depend on the package body.
13 8
Package Spec Syntax
PACKAGE name IS
specification (visible part)
public type and object declarations function or procedure specifications END [name];
Package Body Syntax
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 your module. The body holds implementation details and private declarations, which are hidden from your module. Think of the specification as the operational interface, and of the body as a black box. You can debug, enhance, or replace a package body without 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 will increment a global named NUMGLOB if the salary is greater than 2500, or decrement NUMGLOB if the salary is equal to or less than 2500. To do so, you must first create a library and write a package spec:
PACKAGE GLOBAL IS NUMGLOB NUMBER; PROCEDURE INCREMENT; PROCEDURE DECREMENT; END GLOBAL;
2.
Next, you would write a package body corresponding to the package 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;
PL/SQL Interface
13 9
END DECREMENT; BEGIN NUMGLOB := 0; END GLOBAL;
initializes numglob
3. 4.
Save the library. Now suppose that you want to create a report that will print the salary field if the value of NUMGLOB is a multiple of 10 (e.g., 10, 20, etc.). (This scenario is for exemplary purposes onlyto demonstrate how to reference objects in a package.) To do so, you would 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 by including 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 IS BEGIN 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 other ways; it is just an example of how to use a package.
13 10
PL/SQL Exceptions
To trap, or isolate, success and failure in your PL/SQL constructs, you use exceptions. There are two types of exceptions:

usercreated (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 on page 13 14.
UserCreated Exceptions
You can declare, raise, and handle your own exceptions. For more information on how to do so, see the PL/SQL Users 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;
Packaged Exceptions
A packaged exception is a PL/SQL exception that is shipped with Oracle Reports. To execute a packaged exception, all you need to do is to write an exception handler for the exceptionit will be declared and raised automatically. For more information on how to write an exception handler, see the PL/SQL Users 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 Interface
13 11
PL/SQL Exceptions
The following exceptions are shipped with PL/SQL Version 1 and are supported by Oracle Reports:

DUP_VAL_ON_INDEX PROGRAM_ERROR INVALID_CURSOR INVALID_NUMBER LOGIN_DENIED NO_DATA_FOUND NOT_LOGGED_IN OTHERS STORAGE_ERROR TIMEOUT_ON_RESOURCE TOO_MANY_ROWS VALUE_ERROR ZERO_DIVIDE
For more information on these exceptions, refer your PL/SQL Users Guide and Reference. Note: Notice that the PL/SQL exceptions do not have the SRW. prefix. If you were to add the SRW. prefix, Oracle Reports would search the SRW package for it, not find it, and then raise an error. Thus, to use the PROGRAM_ERROR exception, you would type WHEN PROGRAM_ERROR, not WHEN SRW.PROGRAM_ERROR. Oracle Reports Exceptions The following Oracle Reports exceptions are shipped with Oracle Reports (notice that they have the SRW. prefix). For more information on these exceptions, see Descriptions of Packaged Functions, Procedures, and Exceptions on page 13 41.
Packaged Exception SRW.CONTEXT_FAILURE SRW.DO_SQL_FAILURE SRW.INTEGER_ERROR SRW.MAXROW_INERR SRW.MAXROW_UNSET
What Raises It Oracle Reports, when an Oracle Reports packaged function or procedure is called from an invalid place. Oracle Reports, when the SRW.DO_SQL packaged procedure fails. Oracle Reports, when SRW.MESSAGE or SRW.SET_MAXROW is called with a noninteger. Oracle Reports, when it detects an internal error while executing the SRW.SET_MAXROW packaged procedure. Oracle Reports, when the SRW.SET_MAXROW packaged procedure is called after the querys records have already been fetched. Oracle Reports, when one of its packaged functions or procedures is called with a missing argument.
SRW.NULL_ARGUMENTS
13 12
Packaged Exception SRW.PROGRAM_ABORT SRW.RUN_REPORT_FAILURE SRW.RUN_REPORT_BATCHNO SRW.TRUNCATED_VALUE SRW.UNKNOWN_QUERY SRW.UNKNOWN_USER_EXIT SRW.USER_EXIT_FAILURE
What Raises It Nothing. (To handle this exception, you must first raise it.) Oracle Reports, when the SRW.RUN_REPORT packaged procedure fails. Oracle Reports, when the SRW.RUN_REPORT procedure is called with a command line string containing BATCH=NO. Oracle Reports, when a parameter or column is set with a value that is larger than the objects size. Oracle Reports, when the SRW.SET_MAXROW packaged procedure is called with an unknown query. Oracle Reports, when the user exit specified for the SRW.USER_EXIT packaged procedure cannot be located. Oracle Reports, when the SRWERB buffer is nonempty. For more information, see Raising Errors from the User Exit on page 14 9.)
Examples: The following example demonstrates how to use both Oracle Reports and PL/SQL packaged exceptions. (The bold code segments make up the exception handlers.) Notice that the example tests for a packaged procedure failure in the exception handler of the current construct. This practice is required. If you raise an exception but do not handle it, Oracle Reports will handle it for you.
PL/SQL Interface
13 13
1.
Assume you call a user exit from the SAL column. To ensure that the 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;
Exception Rules
1.
If you do not handle an exception, Oracle Reports will handle it for you: at the time at which the exception is raised, Oracle Reports will raise an error and halt report execution. 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 objecteven another formulacannot test for its failure.
2.
13 14
PL/SQL in Oracle Reports

You can use PL/SQL in a number of ways within Oracle Reports:

external libraries 13 16 attached libraries 13 16 report triggers 13 17
formulas 13 25 validation triggers 13 27 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 you can use PL/SQL and the type of PL/SQL that is valid there. Object/Module external PL/SQL library Valid PL/SQL Program Units packages, procedures, and functions packages, procedures, and functions functions packages, procedures, and functions functions functions functions functions functions functions functions procedures and functions Location of PL/SQL in the Object Navigator Libraries node
attached library
Attached Libraries node (you cannot edit the PL/SQL here) Report Triggers node Program Units node
report triggers report program units
group column parameter frame repeating frame field boilerplate button
PL/SQL icon of group PL/SQL icon of column PL/SQL icon of parameter PL/SQL icon of frame PL/SQL icon of repeating frame PL/SQL icon of field PL/SQL icon of boilerplate PL/SQL icon of button object
PL/SQL Interface
13 15
External PL/SQL Libraries
External PL/SQL libraries are sets of PL/SQL procedures, functions, and packages that are independent of a report definition. By attaching an external library to a report (or another module, e.g., a form), you can reference its contents any number of times. This eliminates the need to reenter the same PL/SQL for each application. For more information on attaching external PL/SQL libraries to your report, see Attached Libraries on page 13 16. Access: You can access external PL/SQL libraries via the Object Navigator (File>New>External PL/SQL Library or File>Open). Function is used to return a single value. Package Body is used to define a program unit that is part of a package. Package Spec is used to define which program units make up the package that you want to include in your library. Packages are used to provide modularity, added functionality, and better performance. For more information, see Packages on page 13 8. For example, you can create a global variable in a package spec. Procedure is used to perform an action without returning a value.
Options:
Attached Libraries
Attached libraries is a list of external PL/SQL libraries that you want to associate with a report or another external library. When an external library is attached, you can reference its packages, functions, and procedures from within your report. For more information about external PL/SQL libraries, see External PL/SQL Libraries on page 13 16. Access: You can attach or detach libraries via the Object Navigator. For more information, see Reference External PL/SQL Libraries In a Report in Chapter 8 of Building Reports Manual. If a path is not prefixed to the filename, Oracle Reports uses its file path search order to find the file. For more information about file path search order, see File Searching Method on page 18 9. Libraries stored in the database have DB: prefixed to them.
13 16
Rules: 1. If Oracle Reports cannot find a library that you specify in the Attached Libraries list, a warning will be raised when you accept the dialog box, save the report, or open the report. If you try to run the report or compile the PL/SQL in it, an error will be raised. The Attached Libraries list is saved. The next time you open the report or library the list will have the same contents it did when you last saved the report. If an external library references another library, you must attach both libraries to the report even if the first library already has the second one attached.
2.
3.
Report Triggers
Report triggers enable you to execute PL/SQL functions at specific times during the execution and formatting of your report. Using the conditional processing capabilities of PL/SQL for these triggers, you can do things such as customizing the formatting of your report, performing initialization tasks, and accessing the database. To create or modify a report trigger, you select Triggers from the Tools menu. Which Trigger to Use As a general rule, any processing that will effect the data retrieved by the report should be performed in the Before Form or After Form triggers. (These are the two report triggers that fire before anything is parsed or fetched.) Any processing that will not effect the data retrieved by the report can be performed in the other triggers. For more information on the order of events when executing a report, look at Rules below. Oracle Reports has five global report triggers. You cannot create new global report triggers. The trigger names indicate at what point the trigger fires: Before Report After Report Fires before the report is executed but after queries are parsed and data is fetched. Fires after you exit the Previewer, or after report output is sent to a specified destination, such as a file, a printer, or an Oracle*Mail userid. This trigger can be used to clean up any initial processing that was done, such as deleting tables. Note, however, that this trigger always fires, whether or not your report completed successfully.
PL/SQL Interface
13 17
Between Pages
Fires before each page of the report is formatted, except the very first page. This trigger can be used for customized page formatting. Note: In the Previewer, this trigger only fires the first time that you go to a page. If you subsequently return to the page, the trigger does not fire again.
Before Form
Fires before the Runtime Parameter Form is displayed. From this trigger, you can access and change the values of parameters, PL/SQL global variables, and reportlevel columns. Note: If the Runtime Parameter Form is suppressed, this trigger still fires. Consequently, you can use this trigger for validation of command line parameters.
After Form
Fires after the Runtime Parameter Form is displayed. From this trigger, you can access parameters and check their values. This trigger can also be used to change parameter values or, if an error occurs, return to the Runtime Parameter Form. Columns from the data model are not accessible from this trigger. Note: If the Runtime Parameter Form is suppressed, the After Form trigger still fires. Consequently, you can use this trigger for validation of command line parameters or other data.
Access:
You can access report triggers via the Object Navigator or the Program Unit editor. For more information about creating and deleting PL/SQL for report triggers, see Working with Report Triggers in Chapter 8 of Building Reports Manual. PL/SQL functions are used to return a single value. The function or anonymous function must return a boolean value (TRUE or FALSE). Oracle Reports packaged functions, procedures, and exceptions can be referenced in any PL/SQL construct you enter here. For more information, see The Oracle Reports Package: SRW on page 13 41.
Options:
13 18
Report triggers must explicitly return TRUE or FALSE. The following table describes what happens if a report trigger returns FALSE: Report Trigger Before Report p After Report What Happens If Trigger Returns False Displays p y an error message g and then returns to the place l from which h h you ran the h report. Does not affect formatting because the report is done. You can raise a message, though, to indicate that the report did not run correctly. For example, you could put the system time in a variable in the Before Report trigger and then compare it against the system time in the After Report trigger. If the report took longer than a certain time to run, you could raise an error. Displays an error message when you try to go to the page for which the trigger returned FALSE. The p pages to the p page g subsequent q g that returned f d Note: N t If the h trigger igg FALSE are not formatted. returns the l last happens t FALSE on th t page, nothing thi h because the report is done formatting. formatting The Between Page trigger does not fire before the first page. If the trigger returns FALSE on the first page, the first page is displayed, but, if you try to go to the second page, an error message is displayed. p y an error message g and then returns to the Displays place l from which h h you ran the h report. Returns to the Runtime Parameter Form. If the Form is suppressed, then returns to place from which you ran the report.
Between Page
Before Form After Form
Rules: 1. The list below shows the order of events when a report is executed. 1.1 Before Form trigger is fired. 1.2 Runtime Parameter Form appears (if not suppressed). 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 via the READONLY argument or setting).
PL/SQL Interface
13 19
1.7 The report is executed and the Between Page trigger fires for each page except the last one. (Note that data can be fetched at any time while the report is being formatted.) Note: COMMITs can occur during this time due to any of the followinguser exit with DDL, SRW.DO_SQL with DDL, or if ONFAILURE=COMMIT, and the report fails. 1.8 COMMIT is executed (if READONLY is specified) to end the transaction. 1.9 After Report trigger is fired. 1.10COMMIT/ROLLBACK/NOACTION is executed based on what was specified via the ONSUCCESS argument or setting. Caution: In steps 1.4 through 1.8, avoid DDL statements that would modify the tables on which the report is based. Step 1.3 takes a snapshot of the tables and the snapshot must remain valid throughout the execution of the report. In steps 1.6 through 1.8, avoid DML statements that would modify the contents of the tables on which the report is based. Queries may be executed in any order, which makes DML statements unreliable (unless performed on tables not used by the report). Caution: If you specify READONLY, you should avoid DDL altogether. When you execute a DDL statement (e.g., via SRW.DO_SQL or a user exit), a COMMIT is automatically issued. If you are using READONLY, this will prematurely end the transaction begun by SET TRANSACTION READONLY. 2. If you are sending your report output to the Previewer, you should note that some or all of the report triggers may be fired before you see the report output. For example, suppose that you use SRW.MESSAGE to issue a message in the Between Page trigger when a condition is met. If there are forward references in the report (e.g., a total number of pages displayed before the last page), Oracle Reports may have to format ahead to compute the forward references. Hence, even though you have not yet seen a page, it may already have been formatted and the trigger fired.
13 20
3.
In report triggers, you can read the values of Oracle Reports columns and parameters of the correct frequency (look at the rule below). For example, you can use the value of a parameter called COUNT1 in a condition (e.g., IF :COUNT1 = 10). In the Before and After Form, and Before and After Report triggers, you can also set the values of reportlevel placeholder columns or parameters (e.g., give them a value in an assignment statement, :COUNT1 = 15). In the Between Page trigger, you cannot set the values of any data model objects. Note also that the use of PL/SQL global variables to indirectly set the values of columns or parameters is not recommended. If you do this, you may get unpredictable results. In report triggers, you can only reference reportlevel columns or parameters. In addition, you cannot reference any pagedependent columns (i.e., Reset At of Page) or columns that rely on pagedependent columns. If you run a report from Oracle Reports Runtime (i.e., not the command line or SRW.RUN_REPORT), you should commit database changes you make in the Before Form, After Form, and Validation triggers before the report runs. When running in this way, these triggers will share the parent process database connection. When the report is actually executed, however, it will establish its own database connection. A lexical reference cannot be used to create additional bind variables after the After Form trigger fires. For example, suppose you have a query like the following (note that the WHERE clause is replaced by a lexical reference):
SELECT ENAME, SAL FROM EMP &where_clause
4.
5.
6.
If the value of the WHERE_CLAUSE parameter contains a reference to a bind variable, you must specify the value in the After Form trigger or earlier. You would get an error if you supplied the following 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 report would run.
PL/SQL Interface
13 21
Report Program Units
Report program units are packages, functions, or procedures that you can reference from any PL/SQL within the current report. Note: Report program units cannot be referenced from other modules. If you want to create a package, function, or procedure that can be referenced from multiple modules, create an external PL/SQL library. For more information about external PL/SQL libraries, see External PL/SQL Libraries on page 13 16. Access: You can access report program units via the Object Navigator or the Program Unit editor. For more information about how to create and delete reportlevel 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. For more information, see Packages on page 13 8. For example, you can create a global variable in a package spec. PL/SQL functions are used to return a single value. PL/SQL procedures are used to perform an action without returning a value. Oracle Reports packaged functions, procedures, and exceptions can be referenced in any PL/SQL construct you enter here. For more information, see The Oracle Reports Package: SRW on page 13 41. Examples: Suppose that you have a report with the following groups and columns: Groups
RGN
Options:
Columns
REGION RGNSUMSAL COSTOFLIVING
Summary
SUM(DEPTSUMSAL)
DEPT
DNAME DEPTNO DEPTSUMSAL SUM(EMP.SAL)
JOB
JOB HEADCOUNT COUNT(EMP.EMPNO)
13 22
Groups
EMP
Columns
ENAME EMPNO SAL COMM
Summary
Given these groups and columns, you might create multiple formulas that apply the cost of living factor (COSTOFLIVING) to salaries. To avoid duplication of effort, you could create the following PL/SQL function 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/SQL function in formulas:
CompSal(:RGNSUMSAL)
or
CompSal(:SAL) + COMM
Rules: 1. If you delete a PL/SQL package, function, or procedure, you must also delete all references to it in your report. Otherwise, you will get an error when you compile, generate, or run the report. PL/SQL package, function, and procedure names must be unique within the report and may not duplicate the names of any columns, groups, queries, or printable objects, such as repeating frames, frames, fields, and boilerplate.
2.
Group Filters
Group filters are PL/SQL functions that determine which records to include in a group, if Filter is Condition. A PL/SQL function is required for any group with a Filter of Condition. Access: You can access PL/SQL for group filters via the Object Navigator, the Program Unit editor, or the Group property sheet (i.e., the Edit button). For more information about how to create and delete reportlevel PL/SQL, see Working with PL/SQL in Chapter 8 of Building Reports Manual.
PL/SQL Interface
13 23
Options:
PL/SQL functions or anonymous function bodies are used to return a single value. The function or anonymous function, must return a boolean value (TRUE or FALSE). TRUE means that the record will be included and FALSE means it will not be included. Oracle Reports packaged functions, procedures, and exceptions can be referenced in any PL/SQL construct you enter here. For more information, see The Oracle Reports Package: SRW on page 13 41.
Examples: 1. Suppose that you want to display data for salespeople whose commissions 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. 2. 3. Group filters cannot be added to groups if Filter is First, Last, or No Filter. Group filters cannot be added to crossproduct groups. In a group filters, you can read the values of Oracle Reports columns and parameters of the correct frequency (look at the rule below), but you cannot directly set their values. For example, you can use the value of a parameter called COUNT1 in a condition (e.g., IF :COUNT1 = 10), but you cannot directly set its value in an assignment statement (e.g., :COUNT1 = 10). Note also that the use of PL/SQL global variables to indirectly set the values of columns or parameters is not supported. If you do this, you may get unpredictable results. You also cannot reference any pagedependent columns (i.e., Reset At of Page) or columns that rely on pagedependent columns in a group filter.
13 24
4.
The function that you enter for a group filter can only depend upon the following columns:

a database column owned by the groups query or a query above it in the data model hierarchy computed columns (formulas or summaries) that depend on unrelated queries (i.e., computed columns that do not depend upon columns in the group, the groups ancestors, or the groups descendants)
Formulas
Formulas are PL/SQL functions that populate columns of Type Formula. A PL/SQL function is required for any column of Type Formula. Access: You can access the PL/SQL for formulas via the Object Navigator, the Program Unit editor, or the Column 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 a Formula that returns a value of datatype NUMBER. A column of Datatype Date can only have a Formula that returns a value of datatype DATE. A column of Datatype Character can only have a Formula that returns a value of datatype CHARACTER, VARCHAR, or VARCHAR2. Oracle Reports packaged functions, procedures, and exceptions can be referenced in the PL/SQL function you enter here for the formula. For more information, 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;
Options:
This formula adds the salary and commission paid to each employee.
PL/SQL Interface
13 25
2.
If you are creating a formula in which a value may be null, it is usually best to use a function rather than an expression. In a function, you can perform your calculations conditionally. Below is a function that you might enter in Formula which checks a value prior 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 (look at the rule below). For example, you can use the value of a column called COMP in a condition (e.g., IF :COMP = 10) and you can directly set its value in an assignment statement (e.g., :COMP := 15). A formula can only make reference to columns that are in the same or a higher group in the group hierarchy. For example, a formula for a reportlevel column can only reference other reportlevel columns. Formulas are calculated such that any column referenced in the formula will be calculated first. To do so, Oracle Reports builds a dependency list, to guarantee proper ordering of calculations. Note that circular dependencies, in which a column references another column which in turn references the first column, either directly or indirectly, are not allowed. A user exit may only change the value of a column that has a Type of Placeholder.
2.
3.
4.
13 26
5.
When using SRW.DO_SQL, we recommend that you do not read database values that are updated or inserted in the same report. There is no guarantee of the exact time Oracle Reports will fetch records from the database for formatting the output. Oracle Reports does internal data lookahead to optimize performance. Thus, a particular record might already have been accessed before an update is issued to the same record. Oracle Reports builds internal dependency lists which guarantee that events, such as invocation of user exits, calculation of summaries, etc., happen in the correct order. However, Oracle Reports cannot guarantee these events will be synchronized with its internal data access or with the formatting of data.
Validation Triggers
Validation Triggers are PL/SQL functions that are executed when parameter values are specified on the command line and when you accept the Runtime Parameter Form. (Notice that this means each Validation Trigger may fire twice when you execute the report.) Validation Triggers are also used to validate the Initial Value of the parameter in the Parameter property sheet. Access: You can access the PL/SQL for validation triggers via the Object Navigator, the Program Unit editor, or the Parameter property sheet (i.e., the Edit button). PL/SQL functions are used to return a single value. The function or anonymous function, must return a boolean value (TRUE or FALSE). TRUE means that the parameter is valid, and FALSE means it is not valid and an error is raised. When the Validation Trigger returns FALSE, the user is returned to parameter value in the Runtime Parameter Form where they can either change it or cancel the Runtime Parameter Form. Oracle Reports packaged functions, procedures, and exceptions can be referenced in any PL/SQL construct you enter here. For more information, see The Oracle Reports Package: SRW on page 13 41. Rules: 1. The PL/SQL in a Validation Trigger can be a maximum of 32K characters. The upward limit may vary between operating systems.
Options:
PL/SQL Interface
13 27
2.
In a Validation Trigger, you can read and assign values to Oracle Reports parameters. You cannot read or assign values to columns. For example, you can use the value of a parameter called COUNT1 in a condition (e.g., IF :COUNT1 = 10) and you can directly set its value in an assignment statement (e.g., :COUNT1 = 15). Note also that the use of PL/SQL global variables to indirectly set the values of columns is not supported. If you do this, you may get unpredictable results.
3.
For reports that are spawned processes of other reports (e.g., run with BACKGROUND=YES), you should commit database changes you make in the Before Form, After Form, and Validation triggers before the report runs. Spawned processes use their parent process database connection for the Before Form, After Form, and Validation triggers. When the spawned process runs the report, though, it establishes its own database connection. Any database changes not committed by the time the child report runs will therefore be lost. For more information about when new processes are spawned, see BACKGROUND on page 1 31.
Format Triggers
Format Triggers are PL/SQL functions executed before the object is formatted. The trigger can be used to dynamically change the formatting attributes of the object. Access: You can access the PL/SQL for Format Triggers via the Object Navigator, the PL/SQL Program Unit editor, or the layout object property sheet (i.e., the Format Trigger button). PL/SQL functions are used to return a single value. The function must return a boolean value (TRUE or FALSE). TRUE means that the object will be formatted and FALSE means it will not be formatted. Oracle Reports packaged functions, procedures, and exceptions can be referenced in any PL/SQL construct you enter here. For more information, see The Oracle Reports Package: SRW on page 13 1. Examples: 1. Suppose that you are building a banking report and would like it to indicate if a customer is overdrawn. To do so, you give the repeating frame around the customer information a Format Trigger that causes it to have a border only if a customers account balance is less than 0 (or the required minimum balance).
Options:
13 28
The Format Trigger might look something like the following:

function my_formtrig return BOOLEAN is begin 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 no detail records are retrieved for a master record, you do not want the boilerplate labels to appear. To do this, you first create a summary column called MYCOUNT with a Function of Count in the source group of the master repeating frame. In the Format Trigger for the group frame that surrounds the detail repeating frame and its labels, you enter the following:
function my_formtrig return BOOLEAN is begin 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 to see salaries above $2500. In the report summary of all salaries, however, you want all salaries to be included. To do this, you create a data model for the report without restricting the records retrieved. Then, you enter the following Format Trigger for the repeating frame:
function my_formtrig return BOOLEAN is begin if :sal > 2500 then return (true); else return (false); end if; end;
The report output will only show salaries greater than $2500, but the summary that calculates the sum of all salaries will include all the salaries retrieved from the database.
PL/SQL Interface
13 29
4.
Suppose that you want to create a commaseparated list for the names of employees. First, you create a field inside a repeating frame with a Print Direction of Across. Next to the field, you create a boilerplate text object that contains a comma followed by a space. To ensure that the comma does not appear after the last name in the list, enter the following Format Trigger for the boilerplate object:
function my_formtrig return BOOLEAN is begin if :ename <> :lastname then return (true); else return (false); end if; end;
LASTNAME is a summary column with a Source of ENAME, a Function of Last, and Reset At of Report. Rules: Caution: The PL/SQL in a Format Trigger is executed each time that Oracle Reports attempts to format the layout object. As a result, format triggers should only contain PL/SQL program units that set formatting attributes (e.g., color and highlighting). You should not perform other actions, such as inserting data in a table, because you cannot predict when or how many times the trigger will fire. For example, if you have Page Protect checked for an object, the object might not be formatted on the logical page where the trigger is fired. In addition, the trigger may be executed more than once. 1. 2. Comments inserted directly into the PL/SQL code must use the PL/SQL comment delimiters. In a Format Trigger, you can read the values of Oracle Reports columns and parameters of the correct frequency (look at the rule below), but you cannot directly set their values. For example, you can use the value of a parameter called COUNT1 in a condition (e.g., IF :COUNT1 = 10), but you cannot directly set its value in an assignment statement (e.g., :COUNT1 = 10). (This restriction also applies to user exits called from the Format Trigger.) Note also that the use of PL/SQL global variables to indirectly set the values of columns or parameters is not supported. If you do this, you may get unpredictable results.
13 30
3.
You cannot reference columns or variables in the Format Trigger of an object that have a different frequency than the object. For example, if you create a master/detail report, the parent groups repeating frame cannot have a Format Trigger that relies on a value in the child group. For each parent, there may be multiple children. Therefore, at the parent record level, Oracle Reports cannot determine which of the child records to use. You also cannot reference any pagedependent columns (i.e., Reset At of Page) or columns that rely on pagedependent columns in a Format Trigger. The reason for this is that it would result in a circular dependency. That is, the value of a pagedependent column cannot be computed until the report is formatted, but the report cannot be formatted until the Format Trigger is executed.
4.
If a Format Trigger returns false and the object does not format, this can cause other objects not to print. For example, if a repeating frame does not format, any objects (fields, boilerplate, frames, or other repeating frames) it encloses would not format either. For repeating frames, the Format Trigger is executed for each instance of the repeating frame. To create a Format Trigger that acts upon all instances of a repeating frame at once, create a frame around the repeating frame and enter a Format Trigger for the frame. If the Format Trigger returns FALSE for every instance of a repeating frame on a logical page, the repeating frame will occupy no space on the logical page and anchors to other objects will collapse (if specified). The PL/SQL in a Format Trigger must return consistent results for the same object. For example, say you have a frame whose Format Trigger returns FALSE when a certain condition is met. If the frame spans two pages, the Format Trigger actually fires twice (once for each page on which the frame formats). The condition in your PL/SQL must return the same result both times the Format Trigger 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 on the second page does not). If the Format Trigger on a repeating frame in a matrix report returns FALSE, an entire row or column of the matrix will not format. For example, if an instance of the across dimension repeating frame does not format, the entire column will not format in the matrix. If you want to conditionally change the cell of a matrix, you should put a frame around the field inside the matrix and use the Format Trigger for the frame.
5.
6.
7.
8.
PL/SQL Interface
13 31
Action Triggers
Action Triggers are PL/SQL procedures executed when a button is selected in the Previewer. The trigger can be used to dynamically call another report (drill down) or execute any other PL/SQL. Access: You can access the PL/SQL for Action Triggers via the Object Navigator, the PL/SQL Program Unit editor, or the button object property sheet. PL/SQL procedures are used to perform an action without returning a value. Oracle Reports packaged functions, procedures, and exceptions can be referenced in any PL/SQL construct you enter here. For more information, see The Oracle Reports Package: SRW on page 13 41.
Options:
Oracle Reports References in PL/SQL

In a PL/SQL construct, you can refer to Oracle Reports objects in two ways:

as a bind variable reference 13 32 as a literal reference 13 33
Bind References
You use a bind variable reference to refer to the value of an Oracle Reports object. All bind variable references are prefixed with a colon. Examples: 1. 2. To make the value of the EMPNO column equal to 100, type:
:EMPNO := 100;
To add column COL1 to a user exit dependency list, type:

SRW.REFERENCE(:COL1);
Note: Only SRW.REFERENCE and SRW.MESSAGE require bind references when referencing an object name.
13 32
Literal References
You use a literal reference to refer to the name of an Oracle Reports object. All literal references must be enclosed in single quotes. Examples: 1. To put the F_EMPNO field name into a PL/SQL variable named FIELDNAME, type:
FIELDNAME := F_EMPNO;
2.
To modify the number of records being fetched for the Q_EMP query, type:
SRW.SET_MAXROW(Q_EMP, 0);
Caution: If you change the name, datatype, or width of an Oracle Reports object, you must ensure that any references to it within your PL/SQL program units are still valid. For example, if the datatype of a column changes, you need to make sure that any calculations that use the column are still correct.
PL/SQL Restrictions within Oracle Reports

1. Oracle Reports supports PL/SQL Version 1.1 on the client side and PL/SQL Version 2.0 on the server side. You can move a program unit from the client to the server side without restriction. If you move a program unit from the server to the client, though, you must ensure that it makes no Version 2.0 specific calls. Oracle Reports PL/SQL Version 1.0 engine supports the following Version 2.0 features:

subprograms packages the RECORD composite datatype
Program units that use only these Version 2.0 features can be moved from the server to the client side without restriction. Program units that use other PL/SQL Version 2.0 features cannot be moved from the server to the client side. 2. 3. You can only use Oracle Reports packaged functions, procedures, or exceptions when running PL/SQL within Oracle Reports. When you call an Oracle Reports packaged function, procedure, or exception, you must precede it with:
SRW. the period is required
PL/SQL Interface
13 33
For example:
SRW.USER_EXIT(my_exit);
4. 5.
When you call usercreated packages, you must precede them with the package name and a period (e.g., MYPACK.MYPROCEDURE;). 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 contains a procedure or function with arguments not of the supported datatypes (VARCHAR2, NUMBER, DATE, BOOLEAN). The stored procedures arguments are not declared with a type of TABLE.COLUMN%TYPE. Your System Global Area (SGA) has not become fragmented to the point where there are no contiguous 32K chunks available. To help avoid this, you can use the KEEP procedure of the DBMS_SHARED_POOL package (available with Version 7.0.15 of ORACLE7) to pin the DIUTIL package in memory.
6.
When you reference a stored program unit from a report, Oracle Reports includes a stub in the .rdf and .rep files for the report. The stubs decrease startup time when running the report from the Oracle Reports Runtime. If you update the stored program units, you should open the report in the Oracle Reports Designer and recompile it to refresh the stubs. Alternatively, you could use Oracle Reports Convert to force a recompilation. Convert the report using a Destination and Source Type of RDF File. If you open a Version 2.5 report that has stubs in an earlier version of Oracle Reports, the stubs will appear as local program units. To pick up changes from the stored program units in this case, you would need to delete the local program units and then recompile the report.
7.
You can only reference Oracle Reports objects in PL/SQL program units when running PL/SQL within Oracle Reports. Within ORACLE, if you execute or compile PL/SQL that contains references to Oracle Reports objects, you will receive errors. PL/SQL program units entered directly in Formula, Validation Trigger, Filter Condition, Formula, or a report trigger cannot take arguments.
8.
13 34
Oracle Procedure Builder

Most objects in Oracle Reports can have PL/SQL associated with them. Oracle Reports uses Oracle Procedure Builder features and functionality to allow you to debug the PL/SQL program units used in your 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 you cannot entirely delete PL/SQL unless it is local PL/SQL (i.e., under program units in the Object Navigator). For example, you could not delete the contents of a formula for a column during report execution. You cannot modify the bind references of a program unit.
2. The Interpreter
The Interpreter is the central debugging workspace of Oracle Procedure Builder. It is a paned window that enables you to define, display, and debug your PL/SQL program units. Depending on the context in which Oracle Procedure Builder is invoked, the Interpreter can be presented in two ways:

modal modeless
The modal Interpreter is presented automatically by Oracle Reports while executing an application (e.g., during execution Oracle Reports encounters a breakpoint you have set in a program unit). When the modal Interpreter is displayed, execution of both the application and its PL/SQL is suspended until you close the modal Interpreter window. The modeless Interpreter is presented when you manually invoke Oracle Procedure Builder by choosing Tools>Interpreter. The Program Unit Editor The Program Unit editor in Oracle Reports operates the same way as described in the Oracle Procedure Builder Users Guide and Reference. For more information on the Program Unit editor, see the Oracle Procedure Builder Users Guide and Reference. Note, however, that the following popup lists have Oracle Reportsspecific contents:

Type Name Object
PL/SQL Interface
13 35
Type: This list indicates what level of program units should be displayed in the other lists, Name and Object. Options: All indicates that you want all the PL/SQL program units (local and objectlevel) displayed under Name. Local indicates that you only want reportlevel PL/SQL progam units (that are not associated with any one object) displayed under Name. Object Level indicates that you only want PL/SQL program units associated with an object (e.g., the PL/SQL in a Format Trigger for a field) to be displayed. If you select Object Level, you can also select from the Object list described above. Name This list indicates what program unit is currently displayed in the Program Unit editor. If you are in objectlevel PL/SQL, this list will typically contain only one name. The only exception is for button objects. Options: A valid name for a PL/SQL program unit in the report. Button Action indicates that you are editing the program unit for a button objects action. This option applies only to button objects. Format Trigger indicates that you are editing the program unit for a button objects Format Trigger. This option applies only to button objects. Object: If you select Object Level for Type, this list indicates what kind of objects should be displayed in the list of objects to its right. Options: All indicates that you want the names of all the objects in the report to be included in the list to the right. Type of object (e.g., repeating frames or fields) indicates that you want only the names of that type of object to appear in the list to the right.
13 36
PL/SQL Compilation
After you write one or more PL/SQL program units for a report, or a library, you must first compile the PL/SQL before you can run it. The compiler detects syntax errors, semantic errors, and references to nonexistent 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 Compiler Error Syntax on page 13 38. Note: You can disable the PL/SQL compiler while you are designing a report. To do so, edit your preferences (i.e., check Disable Trigger Compilation in the Preferences dialog box).
Compiling Single Program Units
To compile a specific construct, display the construct by opening the property sheet or Program Unit editor, then select the Compile button. If no errors are detected, Oracle Reports displays a dialog box that states Compile Complete. If errors are detected, Oracle Reports displays the Program Unit editor: the constructs text appears in the Source field, and its errors are displayed in the Message field, with the first error highlighted. For more information on the Program Unit editor, see the Oracle Procedure Builder Users Guide and Reference. Rules: 1. A program unit must be compiled before any reference to it is compiled. For example, if FORMULA1 references FORMULA2, you must compile FORMULA2 before compiling FORMULA1.
Batchcompiling Program Units
Below are the ways you can compile all of a reports PL/SQL program units simultaneously:

while designing a report, select File>Compile (this compiles the uncompiled PL/SQL) while designing a report, select File>Compile All (this compiles all of the PL/SQL)
PL/SQL Interface
13 37
If no errors are detected, Oracle Reports displays a dialog box that states Compile Complete. If errors are detected, Oracle Reports displays the Program Unit editor: the Message field occupies the entire editor, and it contains all construct errors, with the first error highlighted. For more information on how to navigate in the Program Unit editor, see The Program Unit Editor on page 13 35.
Compiler Error Syntax As Oracle Reports compiles each construct, it displays compilation
error 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:
object_name object_type owner_name owner_type error_num line_num
Is the unambiguous name of the PL/SQL construct that Oracle Reports is compiling. Is construct, or construct spec. Is the unambiguous name of the Oracle Reports object to which the PL/SQL construct is attached. Is the type of Oracle Reports object to which the PL/SQL was assigned. Is the documented error number. Is the line number of the PL/SQL construct where the error occurred. This is the line number within the PL/SQL field. Is the column number of the PL/SQL structure where the error occurred. This is the column number within the PL/SQL field. Is a complete description of the error.
col_num
error_text
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 the ORACLE7 Server Messages and Codes Manual.
13 38
Oracle Procedure Builder Packages

In addition to the Oracle Reports built-in PL/SQL functions, and procedures, Oracle Procedure Builder provides the following built-in PL/SQL packages that contain many PL/SQL constructs you can reference while debugging your program units: DDE DEBUG LIST Provides Dynamic Data Exchange support within Developer/2000. Provides procedures, functions, and exceptions for debugging PL/SQL program units. Provides procedures, functions, and exceptions you can use to create and maintain lists of character strings (VARCHAR2). This provides a means of creating arrays in PL/SQL Version 1. Provides a PL/SQL API for creating, manipulating and accessing attributes of OLE2 Automation Objects. Provides a public interface for calling out to foreign(C) functions from PL/SQL. Enables you to extract high-level information about your current language environment. Provides procedures, functions, and exceptions you can use for tuning your PL/SQL program units (i.e. examining how much time a specific piece of code takes to run). Provides constructs that allow you to read and write information from and to files. Allows you to interact with Oracle environment variables. Allows you to access and manipulate the error stack created by other built-in packages such as DEBUG. Provides you with a means of extracting string resources from a resource file with the goal of making PL/SQL code more portable by isolating all textual data in the resource file.
OLE2
ORA_FFI ORA_NLS ORA_PROF
TEXT_IO TOOL_ENV TOOL_ERR
TOOL_RES
For more information on the Program Unit editor, see the Oracle Procedure Builder Users Guide and Reference.
PL/SQL Interface
13 39
The Developer/2000 PL/SQL Package: CDE_MM

The Developer/2000 package contains the CDE_MM.GET_REF procedure that you can call from a SELECT statement in ORACLE7, Version 7.1.
CDE_MM.GET_REF
CDE_MM.GET_REF specifies that you always want Oracle Reports to go to the database to get a columns value (i.e., the columns values will not be cached on the client side). Type: Procedure
Syntax: Parameters:
CDE_MM.GET_REF (table_name, col_name, tablename.rowid);
table_name col_name tablename. rowid
Is the name of the table that contains the column you want to retrieve from the database. Is the name of a LONG, LONG RAW, or RAW column that you want to retrieve from the database. Is the ROWID of the column that you want to retrieve from the database.
Description:
This procedure can be called in your SELECT statement to indicate that the specified columns values should always be retrieved from the database. The values of the specified column will not be cached on the client. This behavior is useful if you are running a report with many images or sounds that would require more space to cache than the client has available. Warning: Always referencing the database for the columns values will slow performance. As a result, this procedure should only be used when the report has so many images or sounds that it would be impractical to cache them on the client. Rules: 1. Lexical references can be used for the column name you pass to CDE_MM.GET_REF. Note, however, that the datatype of the column cannot change dynamically at runtime. If the column definition in the report is expecting one datatype and it receives a value of a different datatype, an error will occur.
13 40
The Oracle Reports PL/SQL Package: SRW

To save you time, Oracle Reports is shipped with a packagei.e., a collection of PL/SQL constructsthat contains many functions, procedures, and exceptions you can reference in any of your libraries or reports. The name of Oracle Reports package is SRW. As a result, any time you reference a construct in the SRW package, you must prefix it with SRW, for example, SRW.DO_SQL. The Oracle Reports Package contains the following:

SRW.BREAK SRW.CONTEXT_ FAILURE SRW.DO_SQL SRW.DO_SQL_FAILURE SRW.GETERR_RUN SRW.GET_PAGE_NUM SRW.INTEGER_ERROR SRW.MAXROW_INERR SRW.MAXROW_UNSET SRW.MESSAGE SRW.NULL_ARGUMENTS SRW.PROGRAM_ABORT SRW.REFERENCE SRW.RUN_REPORT SRW.SET_ATTR
SRW.RUN_REPORT_BATCHNO SRW.SET_FIELD_CHAR SRW.SET_FIELD_DATE SRW.SET_FIELD_NUM SRW.SET_MAXROW SRW.TRACE_ADD_OPTION SRW.TRACE_END SRW.TRACE_REM_OPTION SRW.TRACE_START SRW.TRUNCATED_VALUE SRW.UNKNOWN_QUERY SRW.UNKNOWN_USER_EXIT SRW.USER_EXIT SRW.USER_EXIT20 SRW.USER_EXIT_FAILURE
SRW.RUN_REPORT_FAILURE Note: You cannot reference constructs in the SRW package from another product, e.g., from SQL*Plus.
Constructs found in a package are commonly referred to as packaged; i.e., packaged functions, packaged procedures, and packaged exceptions.
SRW.BREAK
SRW.BREAK stops report execution. You can now use Oracle Procedure Builder to perform debugging in Oracle Reports. Type: Procedure Syntax:
SRW.BREAK;
PL/SQL Interface
13 41
Description:
This procedure temporarily stops report execution at the place at which SRW.BREAK was encountered, and displays (readonly) the current values of all columns and parameters. Report execution resumes when the readonly screen is accepted. Rules: 1. This procedure is not meaningful in a Before Form or After Form trigger, because data for the report is not fetched until the Before Report trigger (which fires after the After Form trigger). All column and parameter values are displayed in the readonly screen. No PL/SQL variables, nor any other object values are displayed.
2.
SRW.CONTEXT_ FAILURE
SRW.CONTEXT_FAILURE stops report execution when a program unit is run from the wrong context. Type: Exception
Syntax: Description:
SRW.CONTEXT_FAILURE;
This exception stops the report execution and raises the following error message:
REP1426: Running <construct_name> from incorrect context.
What Raises It: Oracle Reports, when an Oracle Reports packaged function or procedure is called in the wrong context (see the chart below). In this chart, NO means that the function or procedure cannot be called in that context; YES means it can. NAME srw.break srw.do_sql srw.geterr_run srw.message srw.reference srw.run_report srw.set_attr srw.set_field_char srw.set_field_date PARAM FORM NO YES YES YES YES YES NO NO NO DATA MODEL YES YES YES NO YES YES YES NO NO NO FORMAT TRIG YES YES YES YES YES YES YES YES YES YES REPORT TRIG NO YES YES NO YES YES YES NO NO NO
srw.get_page_num NO
13 42
NAME srw.set_field_num srw.set_maxrow srw.user_exit
PARAM FORM NO NO YES Examples:
DATA MODEL NO YES YES
FORMAT TRIG YES YES YES
REPORT TRIG NO YES YES
Suppose you want your own error message raised, instead of the default error message (above). You could handle this exception in the following way:
EXCEPTION when SRW.CONTEXT_FAILURE then srw.message(4000, Contact the Application Development group regarding SRW.CONTEXT_FAILURE.); raise srw.program_abort;
SRW.DO_SQL
SRW.DO_SQL executes a specified SQL statement. Type: Procedure
Syntax: Parameters: Description:
SRW.DO_SQL (sql_statement CHAR);
sql_statement
Is any valid SQL statement. Remember to precede any Oracle Reports object names with a colon (:).
This procedure executes the specified SQL statement from within Oracle Reports. The SQL statement can be DDL (statements that define data), or DML (statements that manipulate data). DML statements are usually faster when they are in PL/SQL, instead of in SRW.DO_SQL. Because you cannot perform DDL statements in PL/SQL, the SRW.DO_SQL packaged procedure is especially useful for performing them within Oracle Reports, instead of via a user exit. For more information on DDL or DML statements, see the ORACLE7 Server SQL Language Reference Manual. 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). 1.3 After Form trigger is fired. 1.4 Report is compiled. 1.5 Before Report trigger is fired and queries are parsed.
PL/SQL Interface
13 43
1.6 SET TRANSACTION READONLY is executed (if specified via the READONLY argument or setting). 1.7 The report is executed and the Between Page trigger fires for each page except the last one. (Note that data can be fetched at any time while the report is being formatted.) Note: COMMITs can occur during this time due to any of the followinguser exit with DDL, SRW.DO_SQL with DDL, or if ONFAILURE=COMMIT, and the report fails. 1.8 COMMIT is executed (if READONLY is specified) to end the transaction. 1.9 After Report trigger is fired. 1.10COMMIT/ROLLBACK/NOACTION is executed based on what was specified via the ONSUCCESS argument or setting. Caution: In steps 1.4 through 1.8, avoid DDL statements that would modify the tables on which the report is based. Step 1.3 takes a snapshot of the tables and the snapshot must remain valid throughout the execution of the report. In steps 1.6 through 1.8, avoid DML statements that would modify the contents of the tables on which the report is based. Queries may be executed in any order, which makes DML statements unreliable (unless performed on tables not used by the report). Caution: If you specify READONLY, you should avoid DDL altogether. When you execute a DDL statement (e.g., via SRW.DO_SQL or a user exit), a COMMIT is automatically issued. If you are using READONLY, this will prematurely end the transaction begun by SET TRANSACTION READONLY. For more information on READONLY, see READONLY on page 1 41. 2. A bind variables value can be at most 64,000 bytes. (When the value exceeds that limit, it will be truncated to the leftmost 64,000 bytes.) If you use a parameter as the destination of a character column for an INTO clause, you should ensure that the parameter is wide enough to contain the selected values. For example, suppose that you have the following SRW.DO_SQL statement:
srw.do_sql(SELECT ENAME INTO ||:my_ename|| FROM EMP);
3.
13 44
In this case, the destination parameter (my_ename) needs a width that is equal to the maximum width of the ENAME column. The reason for this is that the selected value contains trailing spaces up to the assumed size of the value. If the parameter is not large enough, you will get a truncation exception. If you are not sure about the maximum width of the SELECT list item, then you should use 2000 as the width for the parameter. Examples: The following examples illustrate the use of SRW.DO_SQL. 1. Suppose you want your report to create a table named CHECK just before the Runtime Parameter Form is displayed. Because CREATE TABLE is a SQL DDL statement (and PL/SQL cannot perform DDL statements), you need to use SRW.DO_SQL. Therefore, your PL/SQL could look like this in the Before Form trigger:
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 way for your report output, the table must exist before you create your query in the data model. Otherwise, Oracle Reports would not be able to parse your query. 2. Suppose you want to create a table of contents by getting the first character of a columns value, and page number on which its field fires 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);
PL/SQL Interface
13 45
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
SRW.DO_SQL_FAILURE stops report execution when a failure occurs in SRW.DO_SQL. Type: Exception
SRW.DO_SQL_FAILURE;
REP1425: Error running DO_SQL package REPmsg ORAmsg
where:
REPmsg ORAmsg
Is an Oracle Reports message. Is an optional ORACLE message, providing more information on the Oracle Reports message.
What Raises It: Oracle Reports, when the SRW.DO_SQL packaged procedure fails (e.g., if the user does not have DDL privileges, yet tries to create a table with SRW.DO_SQL). See Also: Examples: SRW.DO_SQL Suppose you want your own error message raised, instead of the default error message (above). You could handle this exception in the following way:
EXCEPTION when SRW.DO_SQL_FAILURE then
13 46
srw.message(1000, Error occurred while creating table CHECKS.);
SRW.GETERR_RUN
SRW.GETERR_RUN returns an error message if a failure occurs in SRW.RUN_REPORT. Type: Function
Syntax: Returns: Description: Examples:
SRW.GETERR_RUN;
An error message. This function returns an error message if Oracle Reports detects an error while running the SRW.RUN_REPORT procedure. Suppose you are sending parts of a report to users via Oracle*Mail. For more information, see SRW.RUN_REPORT on page 13 54. Also, suppose that if SRW.RUN_REPORT fails, you want to display a message 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_ NUM
Syntax: Parameters: Returns: Description:
SRW.GET_PAGE returns the current page number. Type: Function

SRW.GET_PAGE_NUM (page_num);
page_num
Is the variable in which you want to place the current page number.
The current page number. This function returns the current page number. This is useful when you want to use the page number in the fields Format Trigger.
PL/SQL Interface
13 47
Rules: 1. Examples: SRW.GET_PAGE_NUM is only meaningful in a Format Trigger. It has no effect when entered in other places.
Suppose you want to perform a computation based upon a page number. In the fields Format Trigger, you could use SRW.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
SRW.INTEGER_ERROR stops report execution when an invalid integer argument is passed. Type: Exception
SRW.INTEGER_ERROR;
This exception stops the report execution and raises the following error message.
REP1417: Invalid integer argument passed to <SRW.MESSAGE or SRW.SET_MAXROW>.
What Raises It: Oracle Reports, when SRW.MESSAGE or SRW.SET_MAXROW is called with a noninteger as a result of an internal error. (If an internal error is not present, PL/SQL will catch the type mismatch via the PL/SQL exception VALUE_ERROR.) Examples: Suppose you want your own error message raised, instead of the default error message (above). You could handle this exception in the following way:
EXCEPTION when SRW.INTEGER_ERROR then srw.message(4000, Contact the Application Development group regarding SRW.INTEGER_ERROR.); raise srw.program_abort;
SRW.MAXROW_ INERR
SRW.MAXROW_INERR stops report execution when a failure occurs in SRW.SET_MAXROW. Type: Exception
13 48
SRW.MAXROW_INERR;
This exception stops the report execution and raises the following error message.
REP1424: Internal error while executing SRW.SET_MAXROW.
If it is raised, you should contact Oracles customer support. What Raises It: Oracle Reports, when it detects an internal error while executing the SRW.SET_MAXROW packaged procedure. Rules: 1. When you handle SRW.MAXROW_INERR, you should always raise SRW.PROGRAM_ABORT to end the reports execution (because the report has an internal problem).
See Also: Examples:
SRW.SET_MAXROW Suppose you want your own error message raised, instead of the default error message (above). You could handle this exception in the following way:
EXCEPTION when SRW.MAXROW_INERR then srw.message(1000, Contact Oracles customer support: SRW.MAXROW_INERR); raise srw.program_abort;
SRW.MAXROW_ UNSET
SRW.MAXROW_UNSET stops report execution when a failure occurs setting the maximum rows for a query. Type: Exception
SRW.MAXROW_UNSET;
This exception temporarily stops the report execution and raises the error message below. After the message is raised and you accept it, the report execution will continue.
REP1423: Cannot set maximum rows of the query after it started executing.
What Raises It: Oracle Reports, when the SRW.SET_MAXROW packaged procedure is called after the querys records have already been fetched. See Also: SRW.SET_MAXROW
PL/SQL Interface
13 49
Examples:
EXCEPTION when SRW.MAXROW_UNSET then srw.message(1000, Data was fetched before SRW.SET_MAXROW was called.);
SRW.MESSAGE
SRW.MESSAGE displays a specified message and message number. Type: Procedure
Syntax: Parameters:
SRW.MESSAGE (msg_number NUMBER, msg_text CHAR);
msg_number msg_text
Is a number from 09999, to be displayed on the message line. Is at most 190 minus the msg_number alphanumeric characters to be displayed on the message line.
Description:
This procedure displays a message with the message number and text that you specify. The message is displayed in the format below. After the message is raised and you accept it, the report execution will continue.
MSGmgs_number:
msg_text.
Rules: 1. You cannot trap nor change Oracle Reports error messages. For a list of existing error numbers and messages, refer to the Reports Messages and Codes Manual. SRW.MESSAGE does not terminate the report execution; if you want to terminate a report after raising a message, use SRW.PROGRAM_ABORT. Any extra spaces in the message string will be displayed in the message; extra spaces are not removed by Oracle Reports.
2.
3.
13 50
Examples:
Suppose you have a user exit named MYEXIT to which you want to pass the values of the SAL column. Suppose, also, that you want to raise your own error if the user exit is not found (e.g., because it is not linked, compiled, etc.). To do these things, you could write the following 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.); raise srw.program_abort; RETURN (TRUE); END;
This trigger will raise your message as follows:

MSG1000: User exit MYEXIT failed. Call Karen Smith x3455.
SRW.NULL_ ARGUMENTS
SRW.NULL_ARGUMENTS stops report execution when a required argument is missing. Type: Exception
SRW.NULL_ARGUMENTS;
REP1418: 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 or procedures is called with a missing argument. This exception is useful when 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 string is passed from a PL/SQL library).
PL/SQL Interface
13 51
The following could raise this exception:

SRW.DO_SQL SRW.MESSAGE SRW.RUN_REPORT SRW.SET_MAXROW SRW.USER_EXIT
Examples:
EXCEPTION when SRW.NULL_ARGUMENTS then srw.message(4000, Contact Application Development regarding SRW.NULL_ARGUMENTS.); raise srw.program_abort;
SRW.PROGRAM_ ABORT
SRW.PROGRAM_ABORT stops report execution when you raise it. Type: Exception
SRW.PROGRAM_ABORT;
REP1419: PL/SQL program aborted.
13 52
What Raises It: You must raise the exception from within your PL/SQL. Examples: Suppose you want to put a border around the salary if it is greater than 0. Suppose, also, that if the report fetches a salary less than 0, you want to raise a customized error message (i.e., FOUND A NEGATIVE SALARY. . .), then terminate the report execution. To do so, you could write 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.); raise srw.program_abort; end if; RETURN (TRUE): END;
SRW.REFERENCE
SRW.REFERENCE adds the specified object to the dependency list of a program unit. Type: Procedure
SRW.REFERENCE (:object CHAR|DATE|NUMBER);
object
Is the Oracle Reports parameter or column whose value needs to be ascertained before the construct fires.
This procedure causes Oracle Reports to add the referenced object to the PL/SQL constructs dependency list. This causes Oracle Reports to determine the objects value just before firing the PL/SQL construct. This useful when you want to ensure that a column value passed to a user exit is the most recently computed or fetched value. Rules: 1. 2. The colon is required before the object name. SRW.REFERENCE is unnecessary when the object is already referenced in the current PL/SQL construct (e.g., in the example below, srw.reference(:temp) is unnecessary, because :temp is already referenced in the IF clause of the construct).
PL/SQL Interface
13 53
Examples:
Suppose you want to pass the temperature and pressure values to a user exit called SUPERHEAT. Suppose, also, that if the temperature is too low, you want to raise a customized error message. To do so, you could 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?); raise srw.program_abort; end if; RETURN(TRUE); END;
SRW.RUN_REPORT
SRW.RUN_REPORT executes the specified R25RUN command. Type: Procedure
SRW.RUN_REPORT (command_line CHAR);
command_line
Is a valid R25RUN command.
This procedure invokes R25RUN with the string that you specify. This procedure is useful for the following:

running drilldown reports (i.e., calling a report from a buttons Action Trigger) sending parts of a report to different recipients (e.g., to send a report via Oracle*Mail to each manager with just his or her groups data) sending parts of a report to different printers (e.g., to send each managers 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 Runtime Parameter Form to be passed in the R25RUN string, you must call SRW.RUN_REPORT after the Before Form trigger.
13 54
2.
The string that is specified for or passed to this procedure must follow the syntax and casesensitivity rules for your operating system. No userid should be specified for the SRW.RUN_REPORT procedure. The userid is inherited by the calling report. If the parent report that invokes SRW.RUN_REPORT is run in batch, then DESTYPE can only be File, Printer, Sysout, or Mail. Otherwise, DESTYPE can be File, Printer, or Mail. If SRW.RUN_REPORT is used in the PL/SQL for a button, the Runtime Parameter Form will not appear by default when the button is selected. If you want the Runtime Parameter Form to appear, you must specify PARAMFORM=YES in the call to SRW.RUN_REPORT. If you do not specify a path, Oracle Reports will use its file path search order to find the report. For more information about file path search order, see File Searching Method on page 18 9.
3. 4.
5.
6.
Examples:
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 a second report named MAIL_IT MAIL_IT, which queries employee names for the manager that MGR_RUN passes it, and sends the report output to the manager 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;
PL/SQL Interface
13 55
This PL/SQL invokes MAIL_IT, specifies that MAIL_ITs output should be sent to the manager via Oracle Mail, and passes the manager number, so that the MAIL_IT report can query only the managers employees. Note: EMPNOs values must be converted to characters (TO_CHAR in the PL/SQL above), because SRW.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 run together. The reports are named SALARY, COMMISS, and TAXES. To run these reports with one R25RUN command, you create a driver report named PAYROLL. The description of PAYROLL could 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 other three reports will all be run. (Note that, in this case, the query and the layout for Payroll could be anything. They are only used here in order to make it possible to run PAYROLL.)
13 56
SRW.RUN_REPORT_ BATCHNO
SRW.RUN_REPORT_BATCHNO stops report execution when BATCH=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 via SRW.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;
REP1429: SRW.RUN_REPORT cannot be invoked with batch=no.
What Raises It: Oracle Reports, when the SRW.RUN_REPORT procedure is called with a command line string containing BATCH=NO and that is not a valid choice. See Also: Examples: SRW.RUN_REPORT Suppose you want your own error message raised, instead of the default error message (above). You could handle this exception in the following way:
EXCEPTION when SRW.RUN_REPORT_BATCHNO then srw.message(4000, Contact Application Dev. Services regarding SRW.RUN_REPORT_BATCHNO.); raise srw.program_abort;
SRW.RUN_REPORT_ FAILURE
SRW.RUN_REPORT_FAILURE stops report execution when a failure occurs in SRW.RUN_REPORT. Type: Exception
SRW.RUN_REPORT_FAILURE;
If the SRW.RUN_REPORT packaged procedure fails, this exception stops the report execution and raises the following error message:
REP1428: Error while running SRW.RUN_REPORT.
What Raises It: Oracle Reports, when the SRW.RUN_REPORT packaged procedure fails. See Also: SRW.RUN_REPORT
PL/SQL Interface
13 57
Examples:
Suppose you want your own error message raised, instead of the default error message (above). The PL/SQL below will raise a customized error message when SRW.RUN_REPORT_FAILURE is raised.
EXCEPTION WHEN srw.run_report_failure then srw.message(30, Error mailing reports.); raise srw.program_abort;
SRW.SET_ATTR
SRW.SET_ATTR applies attibute settings such as font size or color to layout objects. Type: Procedure
Syntax: Parameters:
SRW.SET_ATTR (object_id NUMBER, attr SRW.GENERIC_ATTR);
object_id attr
Is always 0. (The object must always set its own attributes.) Is srw.attr (i.e., the attributes to change and their values).
Description:
This procedure applies formatting attributes to the current frame, repeating frame, field, or boilerplate object. You specify which formatting attributes should be applied to an object by defining a mask. A mask is a collection of attributes; each attribute has one or more values. You create a mask much like you would create a mask for a masquerade party: first you specify the attributes of the mask (e.g., eyes), then you set the value of each attribute (e.g., brown). To define and then apply a mask in PL/SQL, you do the following: 1. 2. Specify the masks attributes you wish to set (e.g., the border).
SRW.ATTR.MASK := SRW.BORDERWIDTH_ATTR; attribute
Specify a value for each attribute that you specified (e.g., width of 1 character).
SRW.ATTR.BORDERWIDTH := 1; value for attribute
3.
Apply the mask to the object by calling the SRW.SET_ATTR procedure.

srw.set_attr(0, srw.attr);
Below is an example of specifying two attributes (and their values) for the mask:
SRW.ATTR.MASK := SRW.BORDERWIDTH_ATTR + SRW.FILLPATT_ATTR; attribute attribute
13 58
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 a mask, you must use the plus sign (+) to add them. In the example above, the plus sign was needed because two attributes were assigned to the mask. Attributes and Their Values: Below are the attributes and their values that you can apply to a mask:
Attribute SRW.AFTCODE_ATTR (after printer code)
Character Mode Values Integer=the printer code in the printer definition file for that integer. Must be a string. N/Aattribute N/A attribute is ignored.
Bitmap Values N/Aattribute is ignored.
SRW.BBCOLOR_ATTR (background border color)
For valid color names, select Format> >Color Palette, then click on the color you y want. Must be a string. i N/Aattribute is ignored.
SRW.BEFCODE_ATTR (before printer code)
Integer=the printer code in the in the printer definition file for that integer. Must be a string. N/Aattribute is ignored.
SRW.BFCOLOR_ATTR (background fill color)
For valid color names, select Format>Color Palette, then click on the color you want. Must be a string. 0=no border; any other integer= picas border of that many picas. For valid fill p pattern names, , look at Appendix d G G. Must b be a string. The name of any font installed on the system on which the report will run. Must be a string. g For valid color names, select Format> >Color Palette, then click on the color you want. Must be a string.
SRW.BORDERWIDTH ATTR WIDTH_ATTR (border width) SRW.BORDPATT_ATTR _ (b d pattern) ) (border SRW.FACE_ATTR (type face) Can only be used for fields with a Type yp of CHAR DATE, CHAR, DATE or NUMBER. NUMBER SRW.FBCOLOR_ATTR (foreground border color)
0=no border; any other integer= border of 1 character. N/Aattribute / is ignored. g N/Aattribute N/A attribute is ignored.
N/Aattribute is ignored.
PL/SQL Interface
13 59
Attribute SRW.FFCOLOR_ATTR (foreground fill color)
Character Mode Values N/Aattribute is ignored.
Bitmap Values For valid color names, select Format> >Color Palette, then click on the color you want. Must be a string. See Pattern and Color Palette Any format mask. Must be a string.
SRW.FILLPATT_ATTR (fill pattern) SRW.FORMATMASK_ATTR (format mask) Can only be used for fields with a Type of CHAR, DATE, or NUMBER. SRW.GCOLOR_ATTR (global text color) Can only be used for fields with a Type of CHAR, DATE, or NUMBER.
N/Aattribute is ignored. Any format mask. Must be a string.
For valid color names, select Format>Color Palette, then click on the color you want. Must be a string. srw.single_spacing srw.onehlf_spacing srw.double_spacing srw.custom_spacing (You must specify the desired vertical spacing in VGS units. See Example 5 below.) srw.left_hjus j srw.center_hjust t hj t srw right hjust srw.right_hjust srw.flush_hjustignored srw.flush_hjust ignored in bitmap srw.plain_style srw.italic_style srw.oblique_style srw.underline_style srw.outline_style srw.shadow_style srw.inverted_style _ y srw.overstrike_style _ y srw.blink_style bl k l The size of the named font that is installed on the system on which the report will run.
SRW.GSPACING_ATTR N/Aattribute is ignored. (global text leading) Can only be used for fields with a Type of CHAR, DATE, or NUMBER, or for boilerplate with a Type of CHAR. J SRW.HJUST_ATTR (horizontal (h i t l justification) j tifi ti ) Can C only be used for fields with a Type of CHAR, DATE, or NUMBER. SRW.STYLE_ATTR (style) Can only be used for fields with a Type of CHAR, DATE, or NUMBER. srw.left_hjust j srw.center_hjust t hj t srw right hjust srw.right_hjust srw.flush_hjust N/Aattribute is ignored.
SRW.SZ_ATTR (size) Can only be used for fields with a Type of CHAR, DATE, or NUMBER.
13 60
Attribute SRW.TEXT_ATTR (text) Can only be used for fields with a Type of CHAR, DATE, or NUMBER.
Character Mode Values srw.plain_texta srw.reverse_texta srw.bold_texta srw.reversebold_texta srw.underline_texta srw.underlinereverse_texta srw.underlinebold_texta srw.reverseboldunderline_texta N/Aattribute is ignored.
Bitmap Values N/Aattribute is ignored; use SRW.WEIGHT_ATTR and SRW.SZ_ATTR instead. (See Example 4 below.)
SRW.WEIGHT_ATTR (weight) Can only be used for fields with a Type of CHAR, DATE, or NUMBER.
srw.ultralight_weight srw.extralight_weight srw.light_weight srw.demilight_weight srw.medium_weight srw.demibold_weight srw.bold_weight o _ g srw.extrabold_weight
Rules: 1. If you specify an attribute (e.g., SRW.FILLPATT_ATTR), you must specify a value for it. If you do not specify a value for a specified attribute, you will get unpredictable results for that attribute. If you specify a value that is not provided by the Oracle Reports package, it must be a string (i.e., enclosed by single quotes). For example, a value for SRW.ATTR.FORMATMASK must be enclosed by single quotes, because you may specify any value. A value for SRW.ATTR.HJUST must not be enclosed by single quotes, because you must specify one of the values that Oracle Reports provides.
2.
Examples:
The following examples illustrate the use of SRW.SET_ATTR. 1. Heres an example of using all of the formatting attributes valid for charactermode reports. Notice that there are two values applied to the horizontal justification attribute (HJUST). Note: For the printer codes &1 and &2 to be meaningful, the printer definition file for this report must define what the printer 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 + + + + +
PL/SQL Interface
13 61
SRW.ATTR.BEFCODE SRW.ATTR.AFTCODE SRW.ATTR.TEXT SRW.ATTR.FILLPATT SRW.ATTR.BORDERWIDTH SRW.ATTR.FORMATMASK SRW.ATTR.HJUST
:= := := := := := :=
SRW.FORMATMASK_ATTR SRW.HJUST_ATTR; &1; &2; SRW.BOLD_TEXTA; TRANSPARENT; 1; DDMONYY; 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 format mask 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 following attributes: 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 in character mode, only the border width (of 1) and fill pattern (of solid) will be set; all other settings will be ignored. When you run the report with this PL/SQL construct in bitmap, all of the attributes will be set. (Be aware that the border background color is not setable 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; + + + + + +
13 62
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 text attributes: text to bold, font to TIMES, size to 18 points, style to underline, weight to bold, text color to blue, and the justification to center. Note: When you run the report with this PL/SQL construct in character mode, only the text will be set to bold (SRW.TEXT_ ATTR); all other attributes will be ignored. When you run the report with this PL/SQL construct in bitmap, all of the attributesexcept SRW.TEXT_ATTRwill 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 spacing between lines to a custom size of 200 VGS units. (One inch is equivalent 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);
PL/SQL Interface
13 63
SRW.SET_FIELD_ CHAR
Syntax: Parameters:
SRW.SET_FIELD_CHAR sets the value of a character field. Type: Procedure

SRW.SET_FIELD_CHAR (object_id, text CHAR);
object_id text
Is always 0. (The object must always set its own attributes.) Is the character string you want the field to display.
Description:
This procedure sets the value of a Character field. This is useful when you want to conditionally change a fields 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 in other places.
Examples:
Suppose you want to conditionally change the value of a Character field, based on each employees salary. In the Format Trigger for the field, 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
Syntax: Parameters:
SRW.SET_FIELD_DATE sets the value of a date field. Type: Procedure

SRW.SET_FIELD_DATE (object_id, date DATE);
object_id date
Is always 0. (The object must always set its own attributes.) Is the date you want the field to display.
Description:
This procedure sets the value of a Date field. This is useful when you want to conditionally change a fields Date value.
13 64
Rules: 1. SRW.SET_FIELD_DATE is only meaningful in the Format Trigger of a field of Datatype Date. It has no affect when entered in other places.
Examples:
Suppose you want to conditionally change the date of the reunion invitation, based on each students graduation year. In the Format Trigger for the field, you could type the following:
FUNCTION CHGFIELD RETURN BOOLEAN IS BEGIN if :graduation >= 1975 then srw.set_field_date (0, 02JUL95); else end if; RETURN (TRUE); END;
SRW.SET_FIELD_ NUM
Syntax: Parameters:
SRW.SET_FIELD_NUM sets the value of a number field. Type: Procedure

SRW.SET_FIELD_NUM (object_id, number NUM);
object_id number
Is always 0. (The object must always set its own attributes.) Is the number you want the field to display.
Description:
This procedure sets the value of a Number field. This is useful when you want to conditionally change a fields Number value. Rules: 1. SRW.SET_FIELD_NUM is only meaningful in the Format Trigger of a field of Datatype Number. It has no affect when entered in other places.
Examples:
Suppose you want to conditionally change the number of a field, based on each employees salary. In the Format Trigger for the field, you could type the following:
FUNCTION CHGFIELD RETURN BOOLEAN IS TMP NUMBER; BEGIN if :sal >= 2000 then tmp := :sal * 1.08; srw.set_field_num (0, tmp);
PL/SQL Interface
13 65
else srw.set_field_num (0, 2500); end if; RETURN (TRUE); END;
SRW.SET_MAXROW
SRW.SET_MAXROW sets the maximum number of rows to be retrieved by the specified query. Type: Procedure
Syntax: Parameters:
SRW.SET_MAXROW (query_name CHAR, maxnum PLS_INTEGER);
query_name maxnum
Is the query whose fetched records will be limited. Is maximum number of records you want the query to fetch.
Description:
This procedure sets the maximum number of records to be fetched for the 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 data that is fetched for your report, enabling you to improve the reports performance. 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 called after the Before Report trigger (i.e., after the queries have been executed), the SRW.MAXROW_UNSET packaged exception is raised. Because this procedure causes only the specified number of records to be fetched, the unfetched records of the query are not used in computations, etc. If you specify that 0 records should be fetched, the query will still be parsed.
2.
3. Examples:
Suppose your report has two queries, Q_Stocks and Q_Bonds. Suppose also, that you have a usercreated parameter, named WHICHDATA, that enables users to specify which data they want the report to display: either stocks or bonds. In the Before Report trigger, you could use the SRW.SET_MAXROW procedure to ensure that only one querys data is fetched:
13 66
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
Syntax: Parameters:
SRW.TRACE_ADD_OPTION applies the trace options mask. Type: Procedure

SRW.TRACE_ADD_OPTION (SRW.TRACEOPTS); SRW.TRACE OPTS
Applies the trace options mask previously defined by SRW.TRACEOPTS.MASK. Note that SRWTRACE_APPEND and SRWTRACE_REPLACE are not trace options and are not available for use with SRW.TRACE_ADD_OPTION.
Description:
SRW.TRACE_ADD_OPTION enables you to specify a new trace option after you have begun logging trace information with SRW.TRACE_START. Description: Below is an example of specifying three tracing options for the mask and 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);
See Also:
SRW.TRACE_START SRW.TRACE_END stops the logging of trace information. Type: Procedure
SRW.TRACE_END
Syntax: Description: See Also:
SRW.TRACE_END ();
SRW.TRACE_END ends the logging of trace information to a file during report execution. To start the logging, use SRW.TRACE_START. SRW.TRACE_START
PL/SQL Interface
13 67
SRW.TRACE_ REM_OPTION
Syntax: Parameters:
SRW.TRACE_REM_OPTION removes trace options. Type: Procedure

SRW.TRACE_REM_OPTION (SRW.TRACEOPTS); SRW.TRACE OPTS
Removes the trace options in the mask previously defined by SRW.TRACEOPTS.MASK. Note that SRWTRACE_APPEND and SRWTRACE_REPLACE are not trace options and are not available for use with SRW.TRACE_REM_OPTION.
Below is an example of specifying three tracing options for the mask and then invoking the mask in a call to SRW.TRACE_REM_OPTION:
SRW.TRACEOPTS.MASK := SRW.TRACE_ERR + SRW.TRACE_BRK + SRW.TRACE_PRF; SRW.TRACE_REM_OPTION(SRW.TRACEOPTS);
See Also:
SRW.TRACE_START SRW.TRACE_START begins the logging of trace information. Type: Procedure
SRW.TRACE_START
Syntax: Parameters:
SRW.TRACE_START (filename,{SRW.TRACE_REPLACE| SRW.TRACE_APPEND}, SRW.TRACEOPTS);
filename
SRW.TRACE_ APPEND SRW.TRACE_ REPLACE SRW.TRACE OPTS
Is the name of the file in which Oracle Reports stores logging information. Adds the new information to the end of the file. Overwrites the file. Applies the trace options mask previously defined by SRW.TRACEOPTS.MASK.
Description:
SRW.TRACE_START enables you to start logging tracing information to a file during report execution. To stop the logging, use SRW.TRACE_END. You can also specify what information you want included in the log file. This information can be useful in debugging a report or finding performance bottlenecks. You specify which tracing options should be applied by defining a mask. To define and then apply a mask for tracing options in PL/SQL, you do the following:
13 68
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 you call 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 mask and then invoking the mask in a call to SRW.TRACE_START:
SRW.TRACEOPTS.MASK := SRW.TRACE_ERR + 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 example above, the plus sign was needed because three options were assigned to the mask. Options and Their Meaning: Below are the options that you can apply to a trace mask and their meaning: Mask Option
SRW.TRACE_ALL_ SRW.TRACE_APP_ SRW.TRACE_BRK_ SRW.TRACE_ERR SRW.TRACE_PLS_ SRW.TRACE_PRF SRW.TRACE_SQL_
Description Includes all possible trace information in the log file. Includes trace information on all the report objects in the log file. Lists breakpoints in the log file. Includes error messages and warnings in the log file. Includes trace information on all the PL/SQL objects in the log file. Includes performance statistics in the log file. Includes trace information on all the SQL in the log file.
Rules: 1. 2. Logging information can only be generated when running a .rdf file. You cannot specify logging when running a .rep file. Only one log session is allowed at one time. SRW.TRACE_START automatically ends any other log sessions.
PL/SQL Interface
13 69
See Also:
SRW.TRACE_END SRW.TRUNCATED_VALUE stops report execution when a value is truncated. Type: Exception
SRW.TRUNCATED_ VALUE
SRW.TRUNCATED_VALUE;
This exception will stop the report execution and raise one of two error messages. If the error resulted from a PL/SQL assignment, this message will be displayed:
REP1435: Value of column <parameter/column name> was truncated.
If the error resulted from a user exit IAF PUT, this message will be displayed:
REP1416: User exit <name> IAF PUT: value of column <parameter/column name> was truncated.
If the SRW.TRUNCATED_VALUE exception is handled, the value will be truncated and remain assigned to the parameter or column. What Raises It: Oracle Reports, when a user exit or PL/SQL construct attempts to assign a value to a parameter or column which is larger than the objects maximum width. Examples: Suppose you want your own error message raised, instead of the default error message (above). You could handle this exception in the following way:
EXCEPTION when SRW.TRUNCATED_VALUE then srw.message(2000, Contact Dan Brown: SRW.TRUNCATED_VALUE.);
SRW.UNKNOWN_ QUERY
SRW.UNKNOWN_QUERY stops report execution when a query name is not found by SRW.SET_MAXROW. Type: Exception
SRW.UNKNOWN_QUERY;
This exception will stop the report execution and raise the following error message:
REP1427: Nonexistent query name referenced in SRW.SET_MAXROW.
13 70
What Raises It: Oracle Reports, when the SRW.SET_MAXROW packaged procedure is called with an unknown query. See Also: Examples: SRW.SET_MAXROW Suppose you want your own error message raised, instead of the default error message (above). You could handle this exception in the following way:
EXCEPTION when SRW.UNKNOWN_QUERY then srw.message(4000, Contact Per Jensen: SRW.UNKNOWN_QUERY.); raise srw.program_abort;
SRW.UNKNOWN_ USER_EXIT
SRW.UNKNOWN_USER_EXIT stops report execution when a user exit name 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), this exception stops the report execution and raises the following error message:
REP1415: Unknown user exit.
What Raises It: Oracle Reports, when the user exit specified for the SRW.USER_EXIT or SRW.USER_EXIT20 packaged procedure cannot be located (e.g., because the user exit was not linked). See Also: Examples: SRW.USER_EXIT, SRW.USER_EXIT20 Suppose you want your own error message raised, instead of the default error message (above). The following PL/SQL will raise a customized error message for SRW.UNKNOWN_USER_EXIT.
EXCEPTION WHEN srw.unknown_user_exit then srw.message(200, PASS USER EXIT WAS UNKNOWN. CHECK IF ITS LINKED.);
SRW.USER_EXIT
SRW.USER_EXIT calls the specified user exit with two arguments. Type: Procedure
Syntax:
SRW.USER_EXIT (user_exit_string CHAR);
PL/SQL Interface
13 71
Parameters:
user_exit_ string
Is the name of the user exit you want to call and any columns or parameters that you want to pass to the user exit program.
Description:
This procedure calls the user exit named in user_exit_string. It is useful when you want to pass control to a 3GL program during a reports execution. 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 exit program, SRW.REFERENCE must be called before this procedure. For more information, see SRW.REFERENCE on page 13 53.
See Also: Examples:
SRW.USER_EXIT20 Suppose you have a user exit named STORE to which you want to pass salary values from Oracle Reports. To do so, you could write the following 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 ITS LINKED.); WHEN SRW.USER_EXIT_FAILURE THEN SRW.MESSAGE(200, STORE USER EXIT FAILED. CHECK ITS CODE.); RETURN(TRUE); END;
13 72
SRW.USER_EXIT20
SRW.USER_EXIT20 calls the specified user exit with five arguments. Type: Procedure
Syntax: Parameters:
SRW.USER_EXIT20 (user_exit_string CHAR);
user_exit_ string
Is the name of the user exit you want to call and any columns or parameters that you want to pass to the user exit program.
Description:
This procedure is the same as SRW.USER_EXIT, except that it calls the user exit with five arguments instead of just two. This enables you to share 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 and will always pass a value of .) a pointer to the length of the error string (This argument is not used by Oracle Reports and will always pass a value of 0.) an in query argument (This argument is not used by Oracle Reports and will always pass a value of 0.)
See Also:
SRW.USER_EXIT SRW.USER_EXIT_FAILURE stops report execution when a user exit fails. Type: Exception
SRW.USER_EXIT_ FAILURE
SRW.USER_EXIT_FAILURE;
This exception is raised when the user exit you called has failed. When called, it stops the report execution and raises the following error message:
REP1416: User exit <exit_name> failed.
PL/SQL Interface
13 73
What Raises It: Oracle Reports, when the SRWERB buffer is nonempty. (For details, see Raising Errors from the User Exit on page 14 9.) See Also: Examples: SRW.USER_EXIT, SRW.USER_EXIT20 Suppose you want your own error message raised, instead of the default error message (above). The following PL/SQL will raise a customized error message for SRW.USER_EXIT_FAILURE.
EXCEPTION when SRW.USER_EXIT_FAILURE then SRW.MESSAGE(200, PASS user exit failed. Check its code.);
13 74
CHAPTER
14
User Exit Interface

ser exits enable you to call your 3GL programs from Oracle Reports. 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, use the appropriate Developer/2000 Installation Guide to guide your actual work. Before you attempt to implement a user exit, you should have a thorough knowledge of operating system concepts. Previous exposure to the ORACLE Precompilers is also very useful.
User Exit Interface
14 1
Note: The section on writing a user exit describes how to write an ORACLE Precompiler user exitthe type of user exit you will use most often. That section does not cover all details on how to actually write and implement a user exit. Those details vary with the operating system on which you are working and the language in which you choose to write the user exit.

A user exit is a program that you write and then link into the Oracle Reports executable files. You build user exits when you want to pass control from Oracle Reports to a program you have written, which performs 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 such tasks with PL/SQL within Oracle Reports. Note: Not all types of user exits can perform all of the described tasks. You can accomplish most of these tasks only with 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 nonORACLE user exits
You can also write a user exit that combines both the ORACLE Precompiler interface and the OCI.
14 2
ORACLE Precompiler User Exits
An ORACLE Precompiler user exit incorporates the ORACLE Precompiler 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 SQL commands) and Oracle Reports variables, parameters, and columns.
Because of these features, you will write most of your user exits as ORACLE Precompiler user exits. For more information on the ORACLE Precompiler interface, refer to your Programmers Guide to the ORACLE Precompilers. Note: Not all operating systems support all of the listed languages. For more information, see the Developer/2000 Installation Guide for your operating system.
OCI (ORACLE Call Interface) User Exits
An OCI user exit incorporates the ORACLE Call Interface. This interface allows you to write a subroutine that contains calls to ORACLE. A user exit that incorporates only the OCI (and not the ORACLE Precompiler interface) cannot access Oracle Reports variables, parameters, and columns. For more information on the OCI, refer to your Programmers Guide to the ORACLE Call Interface.
NonORACLE User Exits
A nonORACLE user exit does not incorporate either the ORACLE Precompiler interface or the OCI. For example, a nonORACLE user exit might be written entirely in C. By definition, a nonORACLE user exit 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 user exit: 1. 2. 3. Create your report without user exits. Decide which user exits are needed. Write the user exit using one of the host programming languages.
User Exit Interface
14 3
4. 5.
Implement the user exit by modifying the sample source file. Create the Oracle Reports object and the user exit call (followed by arguments that you wish to pass). Note: Some details of implementing user exits are specific to each operating system. For more information on the exact steps you need to follow, see the Developer/2000 Installation Guide for your operating system.
Writing a User Exit

To write a user exit, you will need to know the following information about user exits:

supported functions (includes how Oracle Reports gets and passes arguments) 14 5 syntax of a passed user exit call (i.e., what the call looks like when the user exit program receives it) 14 8 error checking and raising 14 9 Note: This section applies specifically to ORACLE Precompiler user exits, because it is the type of user exit that you will use most often (it can access Oracle Reports variables, parameters, and columns, and ORACLE data), and it is the type that Oracle Corporation 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). For more information on how to write user exit calls, see Calling a User Exit on page 14 10.
Rules: 1. You cannot perform host language screen I/O from an ORACLE Precompiler user exit. This restriction exists because the runtime routines that a host language uses to perform screen I/O conflict with the routines that Oracle Reports uses to perform its I/O.
14 4
Supported Functions
When you write a user exit using one of the ORACLE Precompiler host languages, the user exit can perform procedural operations via host language statements, and perform additional functions via the following types of statements: Statement Types EXEC SQL EXEC IAF GET EXEC IAF PUT EXEC ORACLE Use Performs SQL commands. Passes values from Oracle Reports to a user exit. Passes values from a user exit to Oracle Reports. Executes ORACLE Precompiler options.
EXEC SQL Statements
An EXEC SQL statement is a SQL command, prefixed with EXEC SQL. EXEC SQL statements enable you to perform any SQL command in an ORACLE Precompiler user exit. It is your means of selecting or manipulating data in the database from a user exit.
EXEC SQL sql_statement;
Syntax
where:
sql_statement
Is any valid ORACLE SQL statement, except for the restricted commands noted in this section.
You do not need to perform an explicit CONNECT in an ORACLE Precompiler user exit, because Oracle Reports establishes the connection automatically. However, ORACLE does support concurrent connects. For more information, refer to your Programmers Guide to the ORACLE Precompilers. Rules: 1. The ONSUCCESS and ONFAILURE keywords for R25DES and R25RUN determine whether Oracle Reports performs a COMMIT, a ROLLBACK, or nothing after a report runs or fails. If you wish to COMMIT at any other time, you can do so in your user exit or in PL/SQL (after your user exit call, add SRW.DO_SQL(commit); ).
Caution: Avoid using DDL when you specify READONLY. When you execute a DDL statement (e.g., via SRW.DO_SQL or a user exit), a COMMIT is automatically issued. If you are using READONLY, this will prematurely end the transaction begun by SET TRANSACTION READONLY. For more information, see READONLY on page 1 41.
User Exit Interface
14 5
EXEC IAF GET
An EXEC IAF GET statement passes a value from Oracle Reports to an ORACLE Precompiler user exit. Specifically, it places the value of an Oracle Reports parameter or column into a host language variable. Once Oracle Reports passes a value to a user exit, the user exit can use the value for calculation, manipulation, or update. Syntax
EXEC IAF GET report_variable_1[, report_variable_2, ...] INTO :host_variable_1[, :host_variable_2, ...];
where:
report_ variable_n
Contains the name of the Oracle Reports parameter or column from which you are reading a value. which you are reading a value.
host_variable_n Is the name of the host language variable into
Notes 1. Report_variable_n can be a reference to any of the following items:
an unambiguous Oracle Reports parameter or column name (To get the current date, create a parameter with a Source of &DATE, then GET the parameters value. To get the current logical page number, call the SRW.GET_PAGE_NUM packaged function, then pass the value to the user exit via your user exit call.) a host language variable (prefixed with a colon) whose value is any of the above bulleted items
For possible restrictions on host language variables, refer to your Programmers Guide to the ORACLE Precompilers. Rules: 1. If an Oracle Reports objects data is longer than 64,000 bytes, the value returned from an EXEC IAF GET is truncated to the leftmost 64,000 bytes.
EXEC IAF PUT
An EXEC IAF PUT statement passes a value from an ORACLE Precompiler user exit to Oracle Reports. Specifically, it places the value of a constant or the value of a host language variable into an Oracle Reports parameter or column.
14 6
Syntax
EXEC IAF PUT report_variable[, ...] VALUES ({:host_variable | constant}[, ...]);
where:
report_variable Is the name of the Oracle Reports parameter or
column into which you are reading a value, or a host variable (prefixed with a colon) whose value is the name of an Oracle Reports parameter or column).
host_variable constant
Is the name of the host language variable from which 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 into an Oracle Reports object (the data will be truncated to the leftmost 64,000 bytes). You must represent host variables and constants in standard SQL format:

2.
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 Summit Sporting Goods 413.60 19910414083000 :holder1 EXEC ORACLE Statements Result Is how the constant string value, Summit Sporting Goods, is passed. Is how the constant numeric value, 413.60, is passed. Is how the date value, April 14, 1991, 8:30 A.M., is passed. Is how the value of the host variable, holder1, is passed.
An EXEC ORACLE statement is a statement that is not standard SQL and is used to execute ORACLE Precompiler options. For more information, refer to your Programmers Guide to the ORACLE Precompilers.
User Exit Interface
14 7
Rules: 1. The ONSUCCESS and ONFAILURE keywords for R25DES and R25RUN determine whether Oracle Reports performs a COMMIT, a ROLLBACK, or nothing after a report runs or fails. If you wish to COMMIT at any other time, you can do so with your user exit.
Caution: Avoid using DDL when you specify READONLY. When you execute a DDL statement (e.g., via SRW.DO_SQL or a user exit), a COMMIT is automatically issued. If you are using READONLY, this will prematurely end the transaction begun by SET TRANSACTION READONLY. For more information, see READONLY on page 1 41. Note: You can perform host language file I/O from a user exit.
Syntax of a Passed User Exit Call
Your user exit program will receive the user exit call as one string that contains 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. 2. It is the responsibility of the user exitnot Oracle Reportsto parse the user exit call string. If more than one space exits between arguments that are passed with the user exit name, Oracle Reports will delete the extra spaces before it passes the strings to the user exit.
14 8
For example, the following call:

quota 10 20 Q4

quota 10 20 Q4
Raising Errors from the In your user exit program, you can define an error message and raise it in Oracle Reports message region by copying the error string in the User Exit
SRWERB error buffer. Note: Within Oracle Reports, you can define and raise an error message via PL/SQL. For more information, see Calling a User Exit on page 14 10. Using the SRWERB Error Buffer You can define an error message in the user exit by writing the error string into a named 256 byte buffer, SRWERB. Oracle Reports initializes the SRWERB buffer when the report is executed. If, on returning from a user exit, Oracle Reports finds the buffer nonempty (i.e., the first character in the buffer is not null), then Oracle Reports will raise an error, using what it finds in the buffer as the error message.
Implementing User Exits

You implement user exits by modifying the sample source file.
Modifying the Sample Source File
To implement user exits, you can simply add entries to the sample source file, ue_xtb.c, for each user exit. The location of this file varies by operating system. For more information about its location, see the Developer/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 */
User Exit Interface
14 9
The first item in the entry is the name (inside double quotes) you will use in Oracle Reports to reference the user exit. The second item is the actual name of the user exit routine. The last item (XITCC) indicates that the user exit is called using C. For other languages, you would use the following for this last item:
XITCOB XITFOR XITPLI XITPAS XITAda /* /* /* /* /* COBOL */ FORTRAN */ PL/I */ PASCAL */ ADA */
After modifying the source file, compile it and your user exit program. For more information, see the Developer/2000 Installation Guide for your operating system. Next, link the resulting IAPXTB object file with the R25DES 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
Writing a User Exit Call You can call the user exit from any place in which you can enter
PL/SQL within Oracle Reports. Use the following syntax: Syntax
[SRW.REFERENCE(:object_name_1);] [SRW.REFERENCE(:object2_name_2); ...]; SRW.USER_EXIT(user_exit_name [argument_list]);
where:
object_name_n
Is the name of an Oracle Reports parameter or column whose value will be passed to the user exit in the user exit string. This causes Oracle Reports to build a dependency list: it will ensure that each referenced object will contain the most recently computed or fetched value before it is passed to the user exit. Note: You must reference each parameter or column separately. For details, see SRW.REFERENCE on page 13 53. For more information, see SRW.REFERENCE on page 13 53.
14 10
user_exit_name
Is the name of the user exit to which you are passing control. The user exit name may be any length. (On some operating systems, the name may be at most 6 characters. Check with your system administrator.) Can contain the names of parameters and columns, constants, character strings, or any combination thereof, that you wish to pass to the user exit. The argument list may be any length.
argument_list
Note: The above syntax will need to be embedded in a PL/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 be of the same format as user exit calls in Oracle Forms, you can use SRW.USER_EXIT20 instead of SRW.USER_EXIT. Examples: 1. Assume you have written a user exit (named INTEGRAL) that computes the area under a curve, based on two points on the curve. Also assume that you have two Oracle Reports columns (named POINT1 and POINT2) whose values contain the x and y coordinates of the two points. To pass copies of the column values to the user exit, you must reference the column names using SRW.REFERENCE. SRW.REFERENCE ensures that the values are computed 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 the SRW.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 Oracle Reports 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 Interface
14 11
Finally, assume that you want the user exit program to return (EXEC IAF PUT) the computed area into an Oracle Reports column named AREA. To do this, you write a PL/SQL function and for its RETURN 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 that another user exit will not PUT a value into the AREA column after INTEGRAL does (i.e., all other user exit EXEC IAF PUTs into this column will occur before the INTEGER user exit fires). Because column formulas must return a value, you must write a function instead of a procedure. For more information, see PL/SQL in Oracle Reports on page 13 15. Rules: 1. User exit names must follow the rules of your operating system and host language. Be aware that these rules might include case sensitivity rules. Maximum length of the user_exit_name is 10 characters (on some operating systems the limit is 6 characters). Maximum length of the argument_list is 230 characters. Spaces are counted. Note: These limits may be operatingsystem dependent. See your system administrator for exact limits. Arguments must be separated by spaces only. If more than one space exists between arguments in the argument_list, Oracle Reports will delete the extra spaces before it passes the string to the user exit. For example, the following call:
quota 10 20 Q4
2.
3.

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.
14 12
5.
If the argument_list contains the name of an Oracle Reports object (whose value you intend to pass to the user exit), you should reference the object name using the PL/SQL procedure, SRW.REFERENCE. SRW.REFERENCE will ensure that the object contains the most recently computed or fetched value before it is passed to the user exit. Note: There is no guarantee, however, that a user exit for a layout object will be calculated on the page on which the layout object is printed.
6.
If the user exit call is part of a PL/SQL value construct putting values into other objects, the value construct should RETURN the Oracle Reports object that owns the PL/SQL code. For example, if you write a PL/SQL function in the Formula field of the EMP column, the function should RETURN the EMP column: RETURN(:EMP);. (This ensures that another user exit will not PUT a value into the object after the user exit returns its value into the object.)
Checking for and Defining User Exit Errors in PL/SQL
In your PL/SQL code, you can check for errors, and define and raise an error 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 exit program. For more information, see Raising Errors from the User Exit on page 14 9.
Checking for Errors Using SRW.USER_ EXIT_FAILURE
In PL/SQL, you can determine whether a user exit failed by using the PL/SQL packaged exception, SRW.USER_EXIT_FAILURE. This exception has a value of TRUE if the SRWERB buffer is nonempty; 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.
User Exit Interface
14 13
Examples: Assume you have a user exit called MYEXIT, and you want to 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 portion of the PL/SQL code. Alternatively, you could have put it in the EXCEPTION portion of the code. For more information on exceptions, see PL/SQL Exceptions on page 13 11. Defining the Error Message Using SRW.MESSAGE In PL/SQL, you can define an error message and raise it in Oracle Reports message region with a PL/SQL packaged procedure, SRW.MESSAGE. (Note: You can also define and raise errors within the user exit program. For more information, see Raising Errors from the 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 error number and string you wish. Below are examples of using SRW.MESSAGE to raise an error.
14 14
Examples: 1. Suppose you have a user exit named STORE to which you want to pass salary values from Oracle Reports. To do so, you could write the 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 its 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 a message to the SRWERB buffer, SRW.USER_EXIT_FAILURE will be FALSE, and Oracle Reports will not raise an error message. If the user exit program does write a message to the SRWERB buffer, then SRW.USER_EXIT_FAILURE will be TRUE, and Oracle Reports will raise the message, STORE user exit failed. Check its code. 2. Assume you have a user exit named BIG_EXIT. Assume also that BIG_EXIT contains code to check itself for errors in three different locations. If it finds an error, it will return (EXEC IAF PUT) one of the following values: A if portion A of BIG_EXIT failed, B if portion B of BIG_EXIT failed, and C if portion C of BIG_EXIT failed. 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.);
User Exit Interface
14 15
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
RWEATS
This user exit converts an attribute value, stored in Oracle Reports internal format, to an associated string retrieved from the Oracle Reports message file. This user exit is used by Oracle Reports when documenting your reports stored in the database using File>Administration>Report Doc. Syntax
SRW.USER_EXIT(rweats source destination attribute_num);
where:
source destination attribute_num
Is the table.column value to be converted. Is the name of the Oracle Reports object into which the converted value will be placed. Is the attribute number of the Oracle Reports database table column.
Table
SRW2_LAYOUT SRW2_PARAM_FORM SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT
Column
UNITS UNITS ORIENT RUN_FLAGS RUN_FLAGS
Attributes
1 1 2 3 4
Description
Report Unit of Measurement Parameter Form Unit of Measurement Panel Print Order Use Character Units in Designer Use Character Units in Browser
14 16
Table
SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT TOOL_PLSQL SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_LAYOUT SRW2_COLUMN SRW2_COLUMN SRW2_COLUMN SRW2_FRAME SRW2_FIELD SRW2_FIELD SRW2_COLUMN SRW2_COLUMN SRW2_BOILERPLATE SRW2_FRAME
Column
RUN_FLAGS RUN_FLAGS RUN_FLAGS RUN_FLAGS RUN_FLAGS RUN_FLAGS RUN_FLAGS TYPE SETTINGS SETTINGS SETTINGS SETTINGS SETTINGS SETTINGS SETTINGS SETTINGS SETTINGS SETTINGS SETTINGS SOURCE_ID COMPUTE_ID RESET_ID GROUP_ID SOURCE_ID PGN_RESET DATA_TYPE FILE_TYPE GRAPH_TYPE FORMATFLAG
Attributes
5 6 7 8 9 10 11 12 13 14 15 16 18 19 20 21 22 23 24 25 25 25 25 25 25 26 27 27 28
Description
Disable Host Disable Split Disable Zoom Start in Zoom Show Browser Title Show Browser Hint Line Show Browser Status Report Trigger Type Display SettingsReport Section Display SettingsField Display Display SettingsShow Comment Icons Display SettingsShow Names Display SettingsShow Field Outlines Display SettingsShow Boilerplate Outlines Display SettingsShow Frame Outlines Display SettingsShow Page Break Icons Display SettingsShow Page Protect Icons Display SettingsShow Keep w/ Anchoring Icons Display SettingsShow Anchors Column Source Column Compute Column Reset Repeating Frame Group Field Source Field Page Numbering Reset Repeating Frame Column/Parameter Datatype Column Format Type Boilerplate Format Type Plate Frame/RFrame Region
User Exit Interface
14 17
Table
SRW2_FIELD SRW2_BOILERPLATE SRW2_OG_DOCUMENT SRW2_FRAME SRW2_FIELD SRW2_BOILERPLATE SRW2_OG_DOCUMENT SRW2_FRAME SRW2_FIELD SRW2_BOILERPLATE SRW2_OG_DOCUMENT SRW2_FRAME SRW2_FIELD SRW2_BOILERPLATE SRW2_OG_DOCUMENT SRW2_FRAME SRW2_FIELD SRW2_BOILERPLATE SRW2_OG_DOCUMENT SRW2_FRAME SRW2_FIELD SRW2_BOILERPLATE SRW2_OG_DOCUMENT SRW2_FRAME SRW2_FIELD SRW2_BOILERPLATE SRW2_OG_DOCUMENT SRW2_FRAME SRW2_FIELD
Column
FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG
Attributes
28 28 28 29 29 29 29 30 30 30 30 31 31 31 31 32 32 32 32 33 33 33 33 34 34 34 34 35 35
Description
Field Region Boilerplate Region Oracle Graphics Document Region Frame/RFrame Vertical Sizing Field Vertical Sizing Boilerplate Vertical Sizing Oracle Graphics Document Vertical Sizing Frame/RFrame Horizontal Sizing Field Horizontal Sizing Boilerplate Horizontal Sizing Oracle Graphics Document Horizontal Sizing Frame/RFrame Print Condition Type Field Print Condition Type Boilerplate Print Condition Type Oracle Graphics Document Print Condition Type Frame/RFrame Print Condition Object Field Print Condition Object Boilerplate Print Condition Object Oracle Graphics Document Print Condition Object Frame/RFrame Print Condition Default Field Print Condition Default Boilerplate Print Condition Default Oracle Graphics Document Print Condition Default Frame/RFrame Page Break Before Field Page Break Before Boilerplate Page Break Before Oracle Graphics Document Page Break Before Frame/RFrame Page Break After Field Page Break After
14 18
Table
SRW2_BOILERPLATE SRW2_OG_DOCUMENT SRW2_FRAME SRW2_FIELD SRW2_BOILERPLATE SRW2_OG_DOCUMENT SRW2_FRAME SRW2_FIELD SRW2_BOILERPLATE SRW2_OG_DOCUMENT SRW2_FIELD SRW2_BOILERPLATE SRW2_QUERY SRW2_GROUP SRW2_GROUP SRW2_GROUP SRW2_COLUMN SRW2_COLUMN SRW2_COLUMN SRW2_FRAME SRW2_FRAME SRW2_FIELD SRW2_FIELD SRW2_FIELD SRW2_FIELD SRW2_BOILERPLATE SRW_DISPLAY_TAG SRW_DISPLAY_TAG SRW_DISPLAY_TAG SRW_DISPLAY_TAG
Column
FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG FORMATFLAG ALIGNMENT ALIGNMENT MAX_ROWS GLF_TYPE CROSS_PROD PRODUCT_ID FLAGS FLAGS OPERATOR DIRECTION DIRECTION FORMATFLAG PGN_FLAGS PGN_FLAGS PGN_FLAGS TYPE FONTSTYLE FONTWEIGHT FONTSIZE DASHSTYLE
Attributes
35 35 36 36 36 36 37 37 37 37 38 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
Description
Boilerplate Page Break After Oracle Graphics Document Page Break After Frame/RFrame Page Protect Field Page Protect Boilerplate Page Protect Oracle Graphics Document Page Protect Frame/RFrame Keep w/Anchoring Object Field Keep w/Anchoring Object Boilerplate Keep w/Anchoring Object Oracle Graphics Document Keep w/ Anchoring Object Field Justification Boilerplate Justification Query Maximum Rows Group Filter Group Cross Product Group Within Cross Product Column Use in Break Column Read from File Column Function Repeating Frame Print Direction Repeating Frame Column Mode Field Hidden Field Page Numbering Include Header Field Page Numbering Include Body Field Page Numbering Include Trailer Boilerplate Type (Charactermode) Font Style Font Boldness Font Size Dash Appearance
User Exit Interface
14 19
Table
SRW_DISPLAY_TAG SRW_DISPLAY_TAG SRW_DISPLAY_TAG SRW_DISPLAY_TAG
Column
CAPSTYLE JOINSTYLE LINEPAT FILLPAT
Attributes
57 58 59 59
Description
Capital Letter Style Joined Line Style Line Pattern Fill Pattern
Rules: 1. RWECAT Syntax If the specified source contains no value, the destination column will be blank.
This user exit concatenates strings, appending source to the end of destination.
SRW.USER_EXIT(rwecat source destination);
where:
source destination
Is the string to be concatenated. Is the name of the Oracle Reports object into which the string will be placed.
RWECPF Syntax
This user exit copies the data in source and places the result in destination.
SRW.USER_EXIT(rwecpf source destination);
where:
source destination
Is the name of the Oracle Reports object whose value is to be copied. Is the name of the Oracle Reports object into which the value will be placed.
Note: RWECPF is useful for LONGs, LONG RAWs, and RAWs because of PL/SQLs 256character limit. RWECPF supports 64,000 bytes. RWECTY This user exit converts column properties and source information into a columntype string retrieved from the Oracle Reports message file. Input values should be the FLAGS and SOURCE columns from the SRW2_COLUMN table. This user exit is used by Oracle Reports when documenting reports stored in the database using File>Administration>Report Doc. For more information on the structure of the SRW2_COLUMN table, see SRW2_COLUMN on page 18 15.
14 20
Syntax
SRW.USER_EXIT(rwecty flag source destination);
where:
flag
Is the FLAGS column value from the SRW2_COLUMN table for the object whose value is to be copied. Is the name of the Oracle Reports object whose value is to be copied. Is the name of the Oracle Reports object into which the value will be placed.
source destination
RWEPLS
This user exit converts PL/SQL source stored in LONG RAW columns into PL/SQL source text. This user exit is used by Oracle Reports when documenting your reports stored in the database using File>Administration>Report Doc. Syntax
SRW.USER_EXIT(rwepls source1 source2 destination);
where:
source1 source2 destination
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 the the Oracle Reports tables. Is a formula column of datatype Character that is assigned 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. It is called userexit.rdf. The location of the report may vary according to your operating system. For more information about subject, see the Developer/2000 Installation Guide for your operating system.
User Exit Interface
14 21
User Exit Call
Assume you would like to call the UE_EMP_PLAN user exit. From a formula 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;
Example User Exit
Following is an example user exit. This user exit can be found in the file ue_samp1.pc. For more information about the location of ue_samp1.pc, see the Developer/2000 Installation Guide for your operating system.
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>
14 22
/*+ | 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, well 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. | +*/
User Exit Interface
14 23
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 NPCompleteness}, { 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;
14 24
/*+ | 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; } } /*+ | Error Case: We didnt 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 */ } /* successful return */
User Exit Interface
14 25
14 26
CHAPTER
15
Call Interface
he call interface enables you to call Oracle Reports executables from 3GL programs you write. You should know the following about the 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 R25RUN executable 15 5 Note: For more information on how to call your 3GL programs from a report, see User Exit Interface on page 14 1.
Call Interface
15 1

A call interface is a set of standard procedures that you can call in your 3GL programs. Oracle Reports is shipped with several such procedures (written in C)one for each of the following Oracle Reports executables: Executable R25CONV R25MREP R25RUN (bitmapped) R25RUN (character mode) R25DES (bitmapped) R25ISV (Windows) Procedure Names RWCCON, RW2CON RWCMOV, RW2MOV RWCRRB, RW2RRB RWCRUN, RW2RUN RWCSRB, RW2SRB RWCSRV, RW2SRV
For example, assume that you have written a Pro*FORTRAN program and you want it to run an Oracle Reports report (using the character mode R25RUN executable). To do so, you add a RWCRUN or RW2RUN procedure call to your program. (Details on which of the two procedures to use is discussed in the syntax portion of this chapter.) Note: To use the call interface, your program must be written with one of the ORACLE Programmatic Interface host languages (Ada, C, COBOL, FORTRAN, Pascal, or PL/l). When you invoke R25CONV and R25MREP with the call interface, you will get whichever executable (bitmapped or charactermode) is shipped for your platform.
Steps to Build a Procedure Call

We suggest the following steps to produce a program that contains a procedure call to Oracle Reports: 1. Write a program using one of the ORACLE Programmatic Interface host languages (Ada, C, COBOL, FORTRAN, Pascal, or PL/l). Include in your program one or more procedure calls. Details on the procedure call syntax are in the next section. Compile your program. This will create an object file.
2.
15 2
3.
Each Oracle Reports procedure call was written in C. Those C programs were compiled, and their resulting object files were shipped with Oracle Reports. Link your program with the Oracle Reports object file(s) it references.
Procedure Call Syntax

There are two types of procedures that are shipped with Oracle Reports:

those that take one parameter (a valid Oracle Reports command line for the executable being called) those that take two parameters (a valid Oracle Reports command line for the executable being called, and the length of that string)
(The procedures that take two parameters are useful if your programming language does not handle nullterminated strings.) Below are the names of the Oracle Reports C procedures: Executable R25CONV R25MREP R25RUNbitmapped R25RUNcharacter mode R25DESbitmapped R25ISVWindows Examples in C Ptoc (1 param) RWCCON RWCMOV RWCRRB RWCRUN RWCSRB RWCSRV Proc (2 params) RW2CON RW2MOV RW2RRB RW2RUN RW2SRB RW2SRV
Examples of the R25RUN procedure calls are (illustrated here in C): Executable R25RUN (b (bitmapped) d) R25RUN (character mode) R25ISV (Windows) R25RUN (character mode) Procedure Name RWCRRB RWCRUN RWCSRV RWCRUN Procedure Call Syntax long g rwcrrb ( /*_ / char h _*/) /) long rwcrun ( /*_ char _*/ ) long rwcsrv ( /*_ char _*/ ) long rwcrun ( /*_ char _*/ )
Call Interface
15 3
Executable R25RUN (b d) (bitmapped) R25RUN (character ( h mode) d ) R25ISV (Windows)
Procedure Name RW2RRB RW2RUN RW2SRV
Procedure Call Syntax long g rw2rrb / char h *, long l /) ( /*_ * _*/ long g rw2run ( /*_ / char h *, long l * _*/ /) long rw2srv ( /*_ char *, long * _*/ )
An example Oracle Reports R25RUN procedure call (in a typical C program) follows: OneParameter Call
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;
TwoParameter Call
Procedure Call Error Checking

If the procedure call encounters an error, it will return a positive number 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 in the examples above, Oracle Reports will attempt to log on to that ORACLE account. If the calling program has already logged on to ORACLE, a userid and password should not be included in the command line, so that Oracle Reports will use the logon that is already active. Oracle Reports will log off ORACLE only if it logged on. If the calling program had previously logged on, the logon will still be active on return from Oracle Reports.
2.
3.
15 4
4.
The ONSUCCESS and ONFAILURE keywords for R25DES and R25RUN determine whether Oracle Reports performs a COMMIT, a ROLLBACK, or nothing after a report runs or fails. The procedure call may be a maximum of 2047 alphanumeric characters. 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 pass arguments from your program to a C subroutine may differ. Refer to your compiler documentation for more details on interfacing with C procedure calls. Oracle Reports can share a database connection with another product (e.g., Oracle Graphics) when both are run as part of the same process. Note, however, that if Oracle Reports is specifically run in the background (e.g., SRW.RUN_REPORT with BACKGROUND=YES), the database connection cannot be shared.
5. 6.
7.
Example Programs that Call R25RUN (RWCRUN)

Below are six example programs that make a procedure call to Oracle Reports R25RUN executable. Each program is written in a different ORACLE 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 VAX compilers, and linked with the Oracle Reports library. To determine the library name on your machine, see the Developer/2000 Installation Guide for your operating system. Note: The exact syntax of your subroutine calls may differ from those below, depending on your host language compiler.
Call Interface
15 5
Ada
Below is an example of an Ada program that calls R25RUN:

with TEXT_IO; use TEXT_IO ; procedure srwada is usr S RES LEN : : : : STRING(1..11) := Scott/Tiger; STRING(1..160); STRING(1..10); 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 ();
15 6
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(); }
COBOL
Below is an example of a COBOL program that calls R25RUN:

IDENTIFICATION DIVISION. PROGRAMID. COBREP. ENVIRONMENT DIVISION. DATA DIVISION. WORKINGSTORAGE SECTION. * 01 OPTIONS. 02 OPTIONTEXTPIC 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 RETURNCODE PIC S9(9) COMP. PROCEDURE DIVISION. MAINPROGRAM. CALL RWCRUN USING BY REFERENCE OPTIONS GIVING RETURNCODE. DISPLAY Return code after first call to rwcrun is RETURNCODE STOP RUN.
FORTRAN
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
Call Interface
15 7
status = rwcrun (%REF(command)) write(*,1) status 1 format(1x,I4) end
Pascal
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.
PL/l
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;
15 8
CHAPTER
16
Integrating with Other Products

racle Reports can be used in conjunction with a number of other O products. You should know about Oracle Reports integration with the following:

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
16 1
ORACLE7 Server
Oracle Reports supports the ORACLE7 Server, including the following new features:
Stored Procedures. You can reference stored procedures from anyplace in Oracle Reports that accepts PL/SQL. Note: Stored procedures cannot reference PL/SQL that is defined within Oracle Reports (e.g., external PL/SQL libraries and the SRW package). Stored procedures also cannot return a value to Oracle Reports.
National Language Support. Oracle Reports retrieves and displays data in the format defined by the National Language Support facilities of the ORACLE7 Server.
Connecting to ORACLE and Other Databases

Oracle Reports is fully integrated with ORACLE. All Oracle Reports reports are based on data in ORACLE. This data resides in tables within the data dictionary. Oracle Reports accesses data in the database you reference in your queries. You can connect to a local database, a remote database (through SQL*Net), or other databases (through SQL*Net with SQL*Connect). In addition to getting data from the database, Oracle Reports can store reports in the database, if specified. For more information about File>Connect, refer to your online help. You can also connect to other databases using ODBC. For more information about ODBC, see the Developer/2000 Installation Guide for your operating system.
SQL*Net
SQL*Net lets you run Oracle Reports and other Oracle applications rapidly and efficiently on machines that are remote from ORACLE. You can use the most appropriate hardware without sacrificing any access. In many cases, more users can be supported and resource sharing for departmental computing is easy. SQL*Net is an extension of the ORACLE architecture using network communications between processes. It connects the client (the application) to the server (ORACLE), allowing for multiple concurrent connections. Utilities and user programs run identically, whether data is local or remote.
16 2
Use SQL*Net to connect to a remote database in order to access data to use in Oracle Reports. You must have SQL*Net installed on your system and configured for the TCP/IP system. The general syntax for using 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 network prefix for TCP/IP and must always be specified. You can omit any optional parameter, but you must include comma separators for any parameter you skip. username password net_prefix hostname Your ORACLE user identification. Your ORACLE password. The network prefix. For TCP/IP systems, this prefix is always T (or t). The name or alias of the remote system (or host) you want to connect to. This name must be defined in the hosts file on your client system. The default node is identified by the alias sqlnet. A single character that represents the system ID of the database you want to access on the remote system. This character must be defined in the database listing file on the remote system. This parameter is case sensitive. The size (in bytes) of the context area used by the driver to pass data between ORACLE and TCP/IP. This value may be between 4 and 4096; larger values result in faster transfer of data arrays but consume more memory. The default in 4096.
system_id
buffer_size
Examples: 1. This example shows how to use TCP/IP to connect to the Oracle Reports account SCOTT/TIGER on the host boston. The database 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 data between ORACLE and TCP/IP.
$ R25DES scott/tiger@T:boston:A,2000
16 3
OLE2
Oracle Reports is an OLE2 container. You can include OLE2 objects in your reports. The sections that follow describe:

including OLE2 object activating OLE2 objects
Including OLE2 Objects
You can include OLE2 objects in a report in one of two ways:

in the data model in a boilerplate object
Including OLE2 Objects in OLE2 objects can be stored in the database or the filesystem. To access the Data Model OLE2 objects in the database, you first select the appropriate column in your query. In the Column property sheet, you then select OLE2 for Format. To include the object in your layout, you default the layout and a field or a button (e.g., for video) is created for it. (If you do not want to redefault the layout, you can also just create a field or a button in the Layout editor and select the OLE2 column as its Source.) You can access OLE2 objects in files through the data model if you have a database column that contains the filenames of the objects. You select the column in your query and, in the Column property sheet, you then check Read from File and select OLE2 for its format. This tells Oracle Reports to treat the columns contents as pointers to OLE2 objects. When you default the layout, the behavior is the same as if the OLE2 objects were stored directly in the database. Including OLE2 Objects in To create an OLE2 boilerplate object in your report layout, you can do Boilerplate either 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 in and accept the dialog box to define the type, source, and whether the object is linked or embedded. Note that all of these items must be defined to create an OLE2 object. If you cancel out of the dialog box, the object is not created.
Activating OLE2 Objects
To activate an OLE2 object in your report layout, move your cursor over the object, and click and hold the right mouse button. This displays a popup menu. From the popup menu, select the Object item. The Object menu item brings up a submenu of actions that can be performed by the objects server.
16 4
PL/SQL
Oracle Reports Version 2.5 supports PL/SQL Version 1.0. Within Oracle Reports you can enter PL/SQL in the following places:

external libraries 13 16 attached libraries 13 16 report triggers 13 17 local program units 13 22 group filters 13 23
formulas 13 25 validation triggers 13 27 format triggers 13 28 action triggers 13 32
Oracle Reports also provides an integrated PL/SQL Development Environment for creating, compiling, and debugging PL/SQL. Oracle Reports also provides packaged PL/SQL procedures, functions, and exceptions that you can reference within Oracle Reports. For more information on the use of PL/SQL within Oracle Reports, see PL/SQL in Oracle Reports on page 13 15.
Oracle Forms
You can reference an Oracle Reports report from Oracle Forms. When you 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 to your Oracle Forms Users Guide. Rules: 1. When calling a report from Oracle Forms, you cannot populate a detail query with a record group. You can only populate master queries with record groups. Oracle Reports can share a database connection with another product (e.g., Oracle Forms) when both are run as part of the same process. Note, however, that if Oracle Reports is specifically run in the background (e.g., SRW.RUN_REPORT with BACKGROUND=YES), the database connection cannot be shared.
2.
16 5
Oracle Graphics
You can reference an Oracle Reports report from Oracle Graphics and an Oracle Graphics display from Oracle Reports. For more information on calling a report from Oracle Graphics, see the Oracle Graphics Reference Manual. When you reference a display from a report, you have the option of passing data and/or parameters from your report to the display. The sections 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
Referencing a Display
To reference a display, you create an Oracle Graphics object in the Layout editor with the Oracle Graphics tool. As with any other layout object, where you place the object determines where and how frequently it will print. For example, placing an Oracle Graphics object inside a repeating frame causes it to print once for each instance of the repeating frame. After you create the Oracle Graphics object, you need to fill out its property sheet. At a minimum, you must supply Oracle Reports with the name of the Oracle Graphics display you want to reference (Display Name on the O.G. Display tab). For more information on the Oracle Graphics property sheet, see Oracle Graphics Properties on page 8 73. When you run the report, the display is executed and the output from the display is placed in the Oracle Graphics object that you created in the Layout editor. If you do not specify any report columns or parameters to be passed from the report to the display, the display will retrieve its data from the database. Note: You do not explicitly need to specify a database connection for Oracle Graphics in this case. Oracle Reports will either share the database session with Oracle Graphics or have Oracle Graphics establish a second database session using the same logon string. Oracle Reports can share a database connection with another product when both are run as part of the same process. Note, however, that if Oracle Reports is specifically run in the background (e.g., SRW.RUN_REPORT with BACKGROUND=YES), the database connection cannot be shared.
16 6
Executing a Display
In Oracle Graphics Version 2.5, displays are automatically updated when opened, unless you specify otherwise. In Oracle Graphics Version 2.0, you must enter a PL/SQL procedure similar to the following in the Timer or Open Trigger to ensure that the query 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 the Oracle Graphics Developers Guide.
Passing Data
When you reference a display, you may want to pass data from the report to the display for the following reasons:
If the report filters the data, you can have that filtering reflected in the display. For example, if you use a group filter in your report to restrict a groups records, then you should pass the data from the report to the display. Otherwise, the display fetches the data itself and the data used in the display will not reflect the group filter in the report. If the report contains a summary, you can use that summary in the display. For example, if your report contains a percent of total summary that you want to use in your display, you need to pass that summary to the display. Otherwise, you would somehow have to create the same summary in the display. If the data used in the display has already been fetched by the report, you can save the display from having to retrieve the data again.
16 7
In order to pass data between a report and a display, you must do two things:

In the query for your display, select columns that match the columns or parameters you want to pass from the report. In the O.G. Query tab of the Oracle Graphics property sheet in your report, specify Display Query, select a Source, and map the columns or parameters in the report to the columns in the display.
Creating Your Display Query
In the query for your display, you need to have columns in your SELECT list that correspond to the columns or parameters you want to pass from your report. The columns in the SELECT list must be of the same datatype as the columns or parameters you intend to pass from the report. For example, suppose you are creating a display that will use 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 what percent each employees salary is of the total salaries in the department.
In your Oracle Graphics display, you write a query named query0 with the following SELECT statement:
SELECT ENAME, SAL, 1 PCT FROM EMP
Notice that for each column that you are going to be passing from the report, you have a corresponding item of the same datatype in the SELECT list of the query (ENAME for RW_ENAME, SAL for RW_SAL, and PCT for RW_PCT_TOTAL). Mapping the Data In the Oracle Graphics property sheet, you need to map the columns or parameters in the report to the columns in the display query. You do this as follows: 1. 2. 3. In Display Query on the O.G. Query tab, enter the name of the query used by the Oracle Graphics display. In Source, select the group (or one of its ancestors) that contains the columns that map to the display columns and parameters In the list of columns and parameters under Report Column, select the columns and parameters you want to pass to the displays query.
16 8
4.
For each report column or parameter you select, enter the name of its 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 to display columns as follows: Report Column RW_ENAME RW_SAL RW_PCT_TOTAL Display Column ENAME SAL PCT
When the display is called, rather than retrieving the values of ENAME, SAL, and DEPTNO from the database, it will retrieve the values of RW_ENAME, RW_SAL, and RW_PCT_TOTAL from your report.
Passing Parameters
In your Oracle Graphics display, you may have parameters that modify the displays output depending upon the value entered at runtime. For example, suppose your display uses the following query:
SELECT ENAME, SAL FROM EMP WHERE DEPTNO = :DNUMBER
The value of DNUMBER is provided to the display at runtime. To supply a value for a display parameter from your report, you map a value in your report to the parameter. You do this as follows: 1. In the list of columns and parameters under Report Column on the O.G. Query tab, select the columns and parameters you want to pass to parameters in the display. For each report column or parameter you select, enter the name of the parameter in the display to which you want it passed under Display Parameter.
2.
Based on our example above, you would map the report column to the display parameter as follows: Report Column DEPTNO Display Parameter DNUMBER
At runtime, the value of DEPTNO in the report will be substituted for DNUMBER in the display.
16 9
Oracle Mail
When you run an Oracle Reports report, you can send the output of to Oracle Mail users. To do this, you specify Mail for the DESTYPE parameter and the usernames for the DESNAME parameter. For more information 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 DBA should ensure that this command file sets up the Oracle Mail database before ORASEND is called and resets to the Oracle Reports database on return from ORASEND. Note: You can call any mail system from the command file, but only Oracle Mail is supported.
Oracle Terminal
Oracle Reports requires mappingskey mappings and terminal definitionsto 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 with Version 1.3 of an ORACLE Precompiler or a later version. Specifically, Oracle Reports considers the routine a user exit. You invoke the routine through the SRW.USER_EXIT packaged procedure. Depending on the contents of the routine, Oracle Reports can pass values to a user exit 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 your 3GL programs. Oracle Reports is shipped with several such procedures. For more information, see Call Interface on page 15 1.
16 10
PART
IV
Internals
CHAPTER
17
Performance and Tuning

Y 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 from SQL*ReportWriter Version 1.1, see the Reports Migration Manual. Note: The information that follows makes suggestions on how to improve the performance of your reports in Oracle Reports. These suggestions are intended as general principles for performance tuning. Oracle Corporation does not warrant that implementing these suggestions will result in improved performance in every possible case.
17 1
Performance Monitoring
Before you start tuning your reports, you should gather performance statistics to determine what, if any, performance problems you have. There are two ways to monitor performance:

Oracle Reports tracing 17 2 ORACLEs SQL TRACE facility 17 2
The advantage of Oracle Reports tracing is that it provides detailed information on where the report time is being spent (e.g., fetching from the database, formatting the report, etc.). The advantage of SQL TRACE is that it provides you with the exact query information, which you can use to tune your queries.
Oracle Reports Tracing The best way to monitor your reports performance is to use Oracle
Reports tracing executable arguments. To do so, you do the following: 1. Specify a filename using the TRACEFILE keyword on the command line or Trace File in the Trace Settings dialog box (via Tools>Trace). Specify TRACE_APPEND/REPLACE using the TRACEMODE keyword on the command line or Trace Mode in the Trace Settings dialog box (via Tools>Trace). Specify TRACE_ALL or TRACE_PRF using the TRACEOPTS keyword on the command line or check All or Profile Messages in the Trace Settings dialog box (via Tools>Trace). Run the report for which you want the performance data.
2.
3.
4.
SQL TRACE
The TRACE function provides you with the exact statements that are being parsed. Once you have them, you can time them in SQL*Plus, and multiply these times with the expected number of rows to retrieve from the database. (Always compare apples to apples, i.e., send output to a filenot to the screen. Do not change anything in the SQL statements when moving it to SQL*Plus; even the slightest change in the WHERE clause can make a big difference in the performance.) There are two ways to trace your reports: on a user level, and a system level. We recommend the user level (because you can find more easily the information you need), although the steps for both methods are below. For more information on SQL TRACE, see the ORACLE7 Server SQL Language Reference Manual.
17 2
Performing a Userlevel Trace 1. 2. Open the report for which you want the performance data. Create a reportlevel formula column names SQLTRACE that has the 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 Form trigger. 3. Run the report. A new file, <some_number>.trc will be created in either ORACLE_HOME/rdbms/log, or the destination indicated by the init.ora parameter USER_DUMP_DEST. (The date stamp on the file can help you determine which .trc file is yours.) 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 Systemlevel Trace 1. 2. Insert these statements into your init.ora file: SQL_TRACE=TRUE and
TIMED_STATISTICS=TRUE.
4.
Shutdown, then restart your database. Every interaction with the database will be traced, and the ORACLE_HOME/rdbms/log is likely to grow very large.
Design Interface Suggestions

Poor performance while building your reports in the designer is normally a result of a missing (or improperly set) operatingsystem or database resource. For more information, see the Developer/2000 Installation Guide for your operating system. Within Oracle Reports, you can do the following to increase the speed of the designer reports faster:

specify designtime preferences 17 4 create templates for your reports 17 4
17 3
Design Preferences
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 from compiling PL/SQL every time you accept a property sheet or leave a PL/SQL field. Suppressing List Retrieval on Dialog Box Entry, reduces the amount of time it takes to bring up a dialog box because Oracle Reports does not have to retrieve the lists in the dialog box. Setting Object Access to File or Database bypasses the Display dialog box when you access files, other modules, or database objects.
Report Templates
If certain report elements are repeated in many of the reports you create, you should consider creating templates for your reports. You create and use a template as follows: 1. 2. 3. 4. Create a report definition with only the common report elements (e.g, some boilerplate text or images) in it. Save the report definition. When you need to create a new report, open the report definition that you created to be a template. Modify the report definition and save it under a different name. Note: When you create a default layout for a report that uses your template, make sure that you use the Default Layout tool. If you create a default layout from the Tools menu, it will overwrite everything in the Layout editor. Rationale: Using templates saves time because you do not have to always recreate the same objects and settings each time you build a new report.
17 4
Data Model Suggestions

This section describes performance tuning suggestions for the data model 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
Number of Queries
Reduce the number of queries in your report as much as possible. In general, the fewer queries you have, the faster your report will run. While multiquery data models are often easier to understand, singlequery data models tend to execute more quickly. The only times you should use multiquery data models are:

when youre fetching many large columns from the parent and only a few small columns from the child when youre trying to do things that SELECT does not support directly (e.g., multiway outer join) when you have complex views (e.g., distributed queries or GROUP BY queries) when you need but dont have or want to use a view
Rationale: For a onequery report, Oracle Reports opens only one cursor to fetch all of the master and detail records. For a twoquery report, Oracle Reports opens two cursorsone for each queryafter appending the detail querys link to the WHERE clause of the detail query. Therefore, for each master record fetched in the master query, Oracle Reports must rebind, execute, and fetch data from the detail query.
17 5
SQL Statements Faster
Performing operations in SQL is faster than performing them in Oracle Reports or PL/SQL. The list below explains the most common cases where using SQL would improve performance:

perform calculations directly in your query rather than in a formula or summary use a WHERE clause instead of a group filter or Format Trigger to exclude records use the SUBSTR function to truncate character strings instead of truncating in Oracle Reports
Rationale: SQL can perform calculations more quickly than a summary or formula. WHERE and SUBSTR can reduce unnecessary fetching because they operate on the data during rather than after data retrieval.
Oracle Reports Query Modifications
Oracle Reports modifies your queries in the following cases:
For each link you create, Oracle Reports will append a clause to the child query as specified in the link. For example, suppose you 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 child column, a SQL Clause of WHERE, and a Condition of = (equal to), 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 multiquery matrix report data models. For more information, see Matrices on page 17 9.
For each database column with Break Order set, Oracle Reports will 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
17 6
These SQL statements will be sent to the database, and it is then the job of the SQL optimizer to determine the optimal way to get the data from the database and return it to Oracle Reports. The optimizer will determine whether to use indexes, which table to use as the driving table in the query, etc. Refer to your ORACLE7 Server Application Developers Guide for more information on tuning SQL statements. Refer to your ORACLE7 Server Concepts Manual for more information about the SQL optimizer.
Indexes
Have indexes on columns used in the SELECT statements WHERE clauses, on database key columns, and on the table(s) in the detail queries. Indexes have little impact on master queries because those queries access the database only once. However, indexes significantly improve performance of master/detail reports. The lower the ratio of master to detail records, the more important indexes on the detail query becomes for twoquery reports. Rationale: Indexes are recommended for tables in the detail queries, because Oracle Reports implicitly creates a WHERE clause from the parent/child relationships and adds it to the detail query.
SRW.DO_SQL Statements
Use the packaged procedure SRW.DO_SQL only when necessary. In those cases where it is necessary, assign it to a group that fetches only a few records, or to a reportlevel object (which will parse, open a cursor, and execute only once). SRW.DO_SQL enables you to add any DDL or DML operation to your report. This functionality is very valuable, but it can also be very expensive if used unwisely. Rationale: Just like queries, SRW.DO_SQL statements are parsed, open a cursor to the database, and execute the statement. Unlike queries, however, an SRW.DO_SQL statement will do those things each time its owner (e.g., a group) fetches data. (For example, if your SRW.DO_SQL statement is owned by a group that fetches 10 records, the statement will be parsed 10 times, 10 cursors will be opened, and the statement will be executed 10 times.) For this reason, computations (e.g., :sal + :com) should be performed within the query or PL/SQL, instead of SRW.DO_SQL owned by a group.
CDE_MM.GET_REF
Only use the packaged procedure CDE_MM.GET_REF when necessary. Rationale: CDE_MM.GET_REF is intended to reduce the amount of temporary space used by Oracle Reports. Oracle Reports will not cache a column retrieved via CDE_MM.GET_REF in a temporary file. While this reduces the need for temporary space, it slows performance because the columns values must always be retrieved from the database.
17 7
Maximum Rows and Group Filters
Use the Maximum Rows property in the Query property sheet (or the SRW.SET_MAXROW packaged procedure) to reduce the number of records retrieved by the reports queries. When designing a report that fetches many records or accesses information across a network with much traffic, you may want to restrict the amount of data retrieved so the report will run more quickly during testing. Rationale: Maximum Rows in the Query property sheet restricts the number of records fetched by the query. A group filter determines which records to include and which records to exclude. Since Maximum Rows actually restricts the amount of data retrieved, it is faster than a group filter in most cases. If you are using a Filter of Last or Conditional, Oracle Reports must retrieve all of the records in the group before applying the filter criteria. As a result, Maximum Rows or a Filter of First is faster. When you specify a Filter of First n for a group, Oracle Reports retrieves as many arrays as necessary to get the first n records of the group. The size of the array retrieved is determined by the ARRAYSIZE parameter. As a result, a Filter of First may retrieve more records than necessary. For example, if you specify a Filter of First 5 and an ARRAYSIZE such that each array contains 10 records, 5 records that will not be used by the report will be retrieved. When you specify Maximum Rows for a query, Oracle Reports only retrieves the number of records that you specify. A Maximum Rows setting of 5 results in only 5 records being retrieved. Typically, Maximum Rows is faster than a Filter of First because it only retrieves as many records as needed. The performance difference, however, may vary depending upon the ARRAYSIZE you have specified. Note: You should be cautious when using Maximum Rows for queries upon which a group depends. For example, if you set Maximum Rows to 5 on a child query, then a summary of the child contained in the parent group will only use the five records that are retrieved by the query.
Unused Data Model Objects
Make sure that you remove or suppress any data model objects that are not actually used in your report. If your data model includes a query that is only used in certain cases (i.e., when a parameter is set to a certain value), you can conditionally suppress the query with the SRW.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 Model editor. This can unnecessarily slow down your report unless you remove or suppress any unnecessary queries.
17 8
Break Columns
When you create a break group, place as few columns as possible in the group. Whenever possible, keep the number of break columns per break group to one. In addition, you should try to ensure that the break column is as small as possible. A break column that is shorter in length will typically give better performance than a break column that is longer. For larger break columns, it may help performance to use the SUBSTR function to reduce the length of the column. Rationale: For each break group, Oracle Reports prepends its break columns to the ORDER BY clause of the query. (The only exception to this rule is when the break column is a formula column.) By minimizing the number of break columns in your break groups, you minimize the number of columns that are added to the ORDER BY clause. The fewer the columns added to the ORDER BY clause the less the processing that needs to be done when the query runs. The size of the key that Oracle Reports uses internally to build indices will also be smaller, resulting in better performance.
Multiple Layouts, One If you want to display the same data more than once in the output, use the same data model object as the source for all of the layout objects. Source
Oracle Reports can display data from a single source multiple times in the report output. For example, suppose you want to display all employees who are making $2000 or more in one list and all employees making less than $2000 in another. To accomplish this, you write one query that selects all of the data. Then you create two separate layouts based on the same data. In one layout, the repeating frame will contain a Format Trigger that only displays instances when SAL is $2000 or more. In the other, the repeating frame will contain a Format Trigger that only displays instances when SAL is less than $2000. Rationale: A report that fetches the data once and lays it out multiple times runs faster than a report that retrieves the data once for each different layout of the data.
Matrices
You can improve the performance of matrix reports with:

fewer queries WHERE clauses Note: Crossproduct groups always cause fetching ahead. The reason for this is that to crosstabulate the data in a crossproduct group, Oracle Reports must first fetch all of the data.
17 9
Fewer Queries
As with other types of reports, fewer queries are faster. If possible, you should use one query for your matrix reports to improve performance. Rationale: For a onequery report, Oracle Reports opens only one cursor to fetch all of the master and detail records. For a multiquery report, Oracle Reports opens multiple cursors.
WHERE Clauses
Consider adding a WHERE clause for the matrix filler query in a multiquery data model. If you are using a multiquery data model and your dimension queries are restricted by a WHERE clause, adding a WHERE clause to the matrix filler query ensures that you do not retrieve more records than are necessary. For example, suppose that you had the following queries for your dimensions:
Q_Dept: Q_Job: SELECT DEPTNO FROM DEPT WHERE DEPTNO < 100 SELECT DISTINCT JOB FROM EMP WHERE DEPTNO < 100
To ensure that your filler query only retrieves the records that are necessary, 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 be retrieved from the database, regardless of what you selected in Q_Dept and Q_Job. Note: If you added a WHERE clause that did not use the subqueries (e.g., WHERE EMP.DEPTNO = DEPT.DEPTNO), the query would be executed once for each combination of values in the crossproduct. This can lead to excessive execution of the filler query, if the crossproduct has a lot of combinations.
17 10
Rationale: Oracle Reports does not add a WHERE clause on the filler query in a multiquery matrix data model. The reason for this is to ensure that the filler query will only be executed once. (Otherwise, the query would be executed once for each combination of values in the crossproduct.) However, if your dimension queries significantly restrict the number of records retrieved, the lack of a WHERE clause on the filler query could cause a large number of unnecessary records to be 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 of unnecessary records from being retrieved.
Layout Suggestions
This section describes performance tuning suggestions for the layout of your report. It includes the following topics:

unused frames 17 11 transparent objects 17 12 nongraphical 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
Unused Frames
Remove any unnecessary frames from the layout. When Oracle Reports creates a default layout for you, it puts frames around virtually everything. The reason for this is to protect the objects in the frames from being overwritten by other objects in the output. If you know from experience that the objects in a frame are not in danger of being overwritten, you can eliminate the frame without adversely affecting your report output. Rationale: The fewer objects in the layout, the fewer objects Oracle Reports must format at runtime. As a result, performance is better when you reduce the number of objects in the layout.
17 11
Transparent Objects
Give layout objects (e.g., frames and repeating frames) a transparent border and fill pattern. Rationale: Transparent objects do not need to be rendered in a PostScript file. As a result, processing is faster when objects are transparent.
Make your nongraphical layout objects (e.g., boilerplate text or fields Sizing for NonGraphical Objects with text) fixed in size, i.e., Vertical and Horizontal Sizing of Fixed. In particular, making repeating frames and their contents fixed in size can improve performance. Rationale: Nongraphical objects that are variable in size require more processing because Oracle Reports must determine their size before formatting them. Nongraphical objects that are fixed in size do not require this additional processing because their size is already known.
Sizing for Graphical Objects
Make your graphical layout objects (e.g., images and Oracle Graphics objects) variable in size, i.e., Vertical and Horizontal Sizing of Variable. Rationale: Graphical objects that are fixed in size usually need to have their contents scaled to fit inside of the object. Scaling an objects contents requires more processing. If the object is variable in size, it can grow or shrink with the contents, and scaling is not necessary.
Reduce Image Resolution
Use Format>Drawing Options>Reduce Image Resolution on image objects whose size you reduce Layout editor. Rationale: When you reduce the size of an image, it requires less information to display it than when it was larger. Reduce Image Resolution eliminates the unnecessary information and reduces the amount of space needed to store the image. This can be particularly useful for large, multicolored images.
Word Wrapping
Make fields that contain text one line long and ensure that their contents fit within their specified width (e.g., by using the SUBSTR function). Rationale: If a field with text spans more than one line, then Oracle Reports must use its wordwrapping algorithm to format the field. Ensuring that a field only takes one line to format avoids the additional processing of the wordwrapping algorithm.
Formatting Attributes
Minimize the use of different formatting attributes (e.g., fonts) within the same field or boilerplate text. Rationale: If text in a field or boilerplate object contains numerous different formatting attributes, it requires longer to format.
17 12
Format Triggers
Place PL/SQL in the Format Trigger of the object with the lowest frequency possible. For example, PL/SQL in the Format Trigger of a frame instead of a field typically makes the report run faster. Rationale: The PL/SQL in Format Trigger is executed for each instance of its object. The lower the frequency of the object, the fewer times the PL/SQL will be executed and the faster the report will run.
Total Number of Pages Limit your use of total number of pages (e.g., Total Number of Logical
Pages) as the source of fields. Rationale: When you use a total number of pages field source, Oracle Reports must save all of the pages in temporary storage in order to determine the total number of pages. This can significantly increase the amount of temporary disk space used by Oracle Reports and the additional writing to files can slow performance.
Oracle Graphics Integration
If an Oracle Graphics display referenced by a report uses some or all of the same data as the report, pass the data from the report to the display. Rationale: If the report and the display use the same data, passing the data reduces the amount of fetching that needs to be done. If you do not pass the data from the report to the display, the data is actually fetched twice: once for the report and once for the display. For more information about passing data from a report to a display, see Oracle Graphics on page 16 6.
PL/SQL
This section describes performance tuning suggestions for PL/SQL in your 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
17 13
PL/SQL Versus User Exits
Depending upon the circumstances, PL/SQL or a user exit may perform better. Following are the items you should consider when deciding 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 on the group or report level, then use PL/SQL. If a report does not need to be portable use user exits, instead of PL/SQL, to perform DML. User exits are especially beneficial when the action is executed for each record in a large report, or requires a large number of complex computations.
Rationale: PL/SQL is highly recommended, because it allows the code to be procedural and still portable. PL/SQL also offers performance advantages when referencing reportlevel objects. User exits will perform better, but they require linking and are not portable. It makes sense to include a user exit if the action required will be executed for every record in a very large report or performs numerous calculations. A PL/SQL procedure makes more sense if the action is only for each group or at the report level. Furthermore, not everything can be done in PL/SQL; some actions like controlling external devices have to be done in a C program. Note: If there is no performance tradeoff or other good reason to use a user exit, you should use PL/SQL because it is easier and portable.
PL/SQL Versus SRW.DO_SQL for DML
Use PL/SQL for DML, unless you want to pass parameters to your DML statements. Rationale: Writing DML statements in PL/SQL is faster than an SRW.DO_SQL call containing the same statement. The reason to use SRW.DO_SQL for DML statements is that it can concatenate bind parameters to construct the DML statement. For example, you can have SRW.DO_SQL create a table whose name is determined by a parameter entered on the runtime parameter form:
SRW.DO_SQL (CREATE TABLE || :tname || (ACOUNT NUMBER NOT NULL PRIMARY KEY, COMP NUMBER (10,2)));
Stored Procedures Versus Local PL/SQL
Use stored procedures for PL/SQL that performs database operations. Use local PL/SQL for PL/SQL that does not involve database operations.
17 14
Rationale: Because stored procedures run in ORACLE, they can perform database operations more quickly than PL/SQL that is local to your report. Exceptions: If you are on a heavily loaded network with very slow response time, using stored procedures may not be faster for database operations. Similarly, if your server is significantly faster than your local machine, then using local PL/SQL may not be faster for nondatabase operations.
Local PL/SQL Versus External PL/SQL Libraries
Write your PL/SQL as locally as possible. Use the Program Units node of your report in the Object Navigator instead of an external PL/SQL library. Rationale: Local PL/SQL executes more quickly than a reference to a procedure or function in an external PL/SQL library. As a result, you should only use external PL/SQL libraries when the benefits of sharing the code across many applications outweighs the performance overhead.
SRW.SET_ATTR
Minimize the number of calls to SRW.SET_ATTR by specifying multiple attributes in one call. You can specify multiple attributes per call to SRW.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 the PL/SQL will run.
Execution Suggestions
This section describes performance tuning suggestions for the execution of your report. It includes the following topics:

executable arguments 17 15 the Previewer 17 17
Executable Arguments
Oracle Reports has a number of executable arguments that can affect performance. These arguments are listed below:

ARRAYSIZE LONGCHUNK PARAMFORM RUNDEBUG
17 15
COPIES MODE
These arguments can be entered from a command line or the Runtime Settings dialog box. ARRAYSIZE For Oracle Reports ARRAYSIZE executable argument (e.g., ARRAYSIZE=10), enter as value as large as you can, especially if you are using Oracle Reports in a clientserver environment. The array size is measured in kilobytes, not rows. ARRAYSIZE means that Oracle Reports can use that number of kilobytes of memory per query in executing your report. Oracle Reports uses ORACLEs array processing which fetches multiple 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 batch processes. Rationale: The larger the array size, the more rows that can be fetched simultaneously; therefore, fewer calls to the database will be made. The benefit of increasing the array size is further noticed in a distributed environment, where network traffic is usually the bottleneck, and overhead associated with the number of packets sent over the network is significant. LONGCHUNK For Oracle Reports LONGCHUNK executable argument (e.g., LONGCHUNK=10), enter a value as large as you can. (Refer to your Installation and Users Guide for the recommended amount for your machine.) LONGCHUNK determines the size of the increments in which Oracle Reports will retrieve a LONG value. The LONGCHUNK size is measured in kilobytes. Rationale: By increasing LONGCHUNK as much as possible, you can reduce the number of increments it takes Oracle Reports to retrieve LONG values. PARAMFORM If you do not want to change the parameters in a report, you should set PARAMFORM=NO. This causes Oracle Reports to bypass the Runtime Parameter Form when you run the report. Rationale: By hiding the Runtime Parameter Form when you dont need it, you eliminate an unnecessary step in running the report.
17 16
RUNDEBUG
Turn off the RUNDEBUG executable argument. RUNDEBUG causes Oracle Reports to perform more error checking when it runs your report. This extra error checking is useful when you are designing a report, but, when a report goes into production, you probably no longer need extra error checking. For more information about RUNDEBUG, see RUNDEBUG on page 1 28. Rationale: The extra error checking done by RUNDEBUG slows down the report.
COPIES
When printing to PostScript, specify COPIES=1. Rationale: If COPIES is set to something greater than one for a PostScript report, Oracle Reports must save the pages in temporary storage in order to collate them. This can significantly increase the amount of temporary disk space used by Oracle Reports and the additional writing to files can slow performance.
MODE
Select a MODE of Character to produce charactermode output. Note that on Windows, this causes Oracle Reports to format the report using the Oracle Reports ASCII driver. Rationale: A MODE of Character means that the report will be formatted directly in ASCII (rather than being formatted in PostScript and converted to ASCII). In addition, the Oracle Reports ASCII driver is faster than the Generic/Text Only Windows driver.
Previewer
Avoid fetching ahead when sending report output to the Previewer. Avoiding fetchaheads causes the first page to display more quickly than it otherwise would. Rationale: The Previewer is sometimes slowed by things that require fetching ahead. For example, if the total number of pages in a report appears on the very first page of the report, then the entire report must be processed before the first page can be displayed in the Previewer. The following items can all result in fetching ahead when referenced before 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
Crossproduct groups also cause fetching ahead. In order to crosstabulate the data in a crossproduct group, Oracle Reports must first fetch all of the data.
17 17
It should be noted that these items are not really performance problems. They slow down the Previewer, but they do no affect performance when writing to a file or some other destination. Note: A column can cause fetching ahead even if it is not displayed. For example, a grand total may not appear in the report output, but, since it is in the report, fetching ahead may still occur when Oracle Reports calculates it.
System Suggestions
Oracle Reports performance will be strongly affected by the performance of your overall system. This section describes what you can do to improve performance based on your system. It includes the following topics:

storage 17 18 operating system setup 17 19 client/server 17 19
Storage
The location in which you store things and how you search for them can also affect performance. The list below shows the storage issues that can affect performance:

storage location (file or database) file searching table sharing
File or Database Storage
Store modules in files to enhance performance. Store modules in the database for security. If you open a report from or save a report to a database, some Oracle Reports tables will be put into memory. As a result, you need to ensure that you have enough resources to cache the tables. For more information, see the Developer/2000 Installation Guide for your operating system. Rationale: For modules, writing to and reading from files tends to be much faster than the database. Exception: If you must use a busy network or slow machine to access the files, you may not realize performance gains from storing in files.
17 18
File Searching
Specify path variables to speed up file searching and creation/access of temporary files. (Recall that Oracle Reports provides two environment variables, REPORTS25_PATH and REPORTS25_TMP, that govern where to search for files and where to store temporary files.) For REPORTS25_PATH, specify the path in which files referenced by the report are located. For REPORTS25_TMP, specify a path that has sufficient free space for temporary files and is on a device with fast response time (e.g., a RAM disk). Rationale: REPORTS25_PATH is the default path in which Oracle Reports will search for files (e.g., link file boilerplate). By specifying the path in which the files referenced by the report are located, you can reduce the amount of searching Oracle Reports needs to perform to retrieve the files. (By using REPORTS25_PATH instead of hardcoding the paths in the report definition, you also maintain the portability of your report.) REPORTS25_TMP is the path in which Oracle Reports will create its temporary files.
Table Sharing
Use one set of tables for several report designers. ORACLE enables several report designers to share one set of Oracle Reports tables. Rationale: Sharing tables enables you to share reports among developers, and only caches one set of tables. This will provide better performance when opening a report from or saving a report to the database, and save some memory.
OperatingSystem Setup
If you invoke an Oracle Reports executable, your operating system account should have enough system resources to do so. (Procedures are available for checking if a process is missing a needed resource.) For more information, see the Developer/2000 Installation Guide for your operating system. If you have a powerful server and a fast network, you may want to have Oracle Reports running on the server. If not or if you plan on doing a lot of interactive reporting (e.g., drill down), consider having Oracle Reports on your local machine. You should contact your system administrator to find out which of these arrangements is best for you. Rationale: In a client/server environment, the performance of Oracle Reports can be seriously affected by the following:

Client/Server
speed and load of the client and server machines the network traffic
17 19
17 20
CHAPTER
18
Storage
Y 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 filesearching method 18 9 Oracle Reports environment variables 18 10
database storage Oracle Reports database tables (includes descriptions of Oracle Reportsspecific tables and integrated Oracle tools tables) 18 12 database storage requirements 18 31 database table security and restrictions 18 31
Oracle Reports memory and disk space requirements 18 32
Storage
18 1
Oracle Reports File Storage

Some systems allow (or require) you to append extensions to the end of file names when you save them. On these systems, Oracle Reports suggests the following extensions:
File .afc .aff .au .avi .cal .bmp .cgm .gif .jfi .moo .odf .oif .pal .pcx .pic
Contents? AIFC sound (binary file) AIFF sound (binary file) AU sound (binary file) Windows video (binary file) CALS image (binary file) BMP image (binary file) CGM drawing (binary file) GIFF image (binary file) JFIF image (binary file) Quicktime video (binary file) Oracle drawing (binary file) Oracle image (binary file) color palette (binary file) PCX image (binary file) PICT image (binary file)
Portable?
When Used?
When Created?
in Previewer, associat- Not created ed with button in Previewer, associat- Not created ed with button in Previewer, associat- Not created ed with button in Previewer, associat- Not created ed with button in layout, parameter form painter in layout, parameter form painter in layout, parameter form painter in layout, parameter form painter in layout, parameter form painter Edit>Export Edit>Export Edit>Export Edit>Export Edit>Export
in Previewer, associat- Not created ed with button in layout, parameter form painter in layout, parameter form painter in layout, parameter form painter in layout, parameter form painter in layout, parameter form painter Edit>Export Edit>Export Edit>Export Edit>Export Edit>Export
18 2
File .pld
Contents? PL/SQL library (text file)
Portable? YES
When Used? File>Administration>Convert useful for sourcecontrolling, and viewing when debugging (see Caution, below)
When Created? File>Save, File>Save As
.pll
PL/SQL library (binary file with source/Pcode)
YES, because Edit>Attach LiFile>Save, File>Save As PL/SQL is re braries, then can refcompiled erence in any PL/SQL when open/ run by the DESTYPE parameter in layout, parameter form painter File>Open, File>Run, File>Administration>Convert faster t open f to from/save / t to this format than the database File>Run prevents users from reading/ modifying the definition, and is smaller than .rdf file File>Administration>Convert useful for sourcecontrolling, and viewing when debugging (see Caution, below) Query property sheet (external query), also File>Import in Previewer, associated with button R25MREP or any text editor Edit>Export File>Save, File>Save As, File>Administration>Convert
.prt
character mode Yes printer definition (text file) Sun raster image (binary file) report definition (binary file with source/Pcode) YES, because PL/SQL is re compiled p when open/ run
.ras .rdf
.rep
report definition (binary file with only Pcode)
YES, when it doesnt have compiled PL/ SQL YES
File>Administration>Generate, File>Administration>Convert File>Administration>Convert
.rex
one or more report definitions (text file)
.sql
query definition (text file) (also, see Note, below) SND sound (binary file)
YES
File>Save, File>Save As Not created
.snd
Storage
18 3
File .tif
Contents? TIFF image (binary file) WAVE sound (binary file)
Portable?
When Used?
When Created?
in layout, Edit>Export parameter form painter in Previewer, associated with button Not created
.wav
Note: SQL scripts shipped with Oracle Reports are also files with extension .sql. For more information, see Using SQL Scripts on page 19 2. Caution: Oracle Corporation does not support modules that have been modified by editing .rex or .pld files. Caution: Printer definition files are only used at runtime by reports run in a charactermode environment or reports run with the Oracle Reports ASCII Driver. For reports that run on bitmapped platforms, printer codes and printer definitions are ignored, as their function is replaced by the settings available from the Format menu (e.g., font and weight). Caution: When you export an object from Oracle Reports to CGM, the object may be broken into multiple objects in CGM. For example, if you export a rectangle that has a fill pattern, this object will become two objects in CGM. One object is created for the rectangle itself and one object for the fill pattern. OLE2 Objects OLE2 objects can be displayed by Oracle Reports. For OLE2 objects stored in the database, set Format in the Column property sheet to OLE2. For OLE2 objects stored in files, select Read from File and set Format to OLE2 in the Column property sheet (this assumes that the database column contains the names of OLE2 objects). Other Oracle Reports Files Depending upon the options you specify, Oracle Reports may generate any 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 4
For more information on files created by Oracle Reports, see Determining Which Files Are Being Used on page 19 6. The preferences file is described below.
Preferences Files
The preferences that you set via Tools>Tools Options are saved and retrieved from a preferences file. (This file contains preferences for all other Oracle tools products as well.) If you do not have your own preferences file, Oracle Reports gets preferences from a global preferences file created during installation. When you edit the preferences and save them, Oracle Reports creates your own local preferences file. Once you have your own preferences file, Oracle Reports will use that file instead of the global preferences file. The exact names and locations of these files may be operating systemdependent. For more information, see the Developer/2000 Installation Guide for your operating system. The contents of the preferences file are portable, but, if you move it to another operating system, you must ensure that you place it in the correct location with the correct name for that platform.
Important Files Shipped with Oracle Reports

Six types of files that are shipped with Oracle Reports are especially important 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
Storage
18 5
Note: The file information below is provided to help you learn about Oracle Reports file types and their intended usage. The exact names and locations of these files may be operating systemdependent. For the exact names and their locations, see the Developer/2000 Installation Guide for your operating system.
Executable Files
Executables are binary files that you use to invoke Oracle Reports, convert and run reports, etc.. Executables are either oneword names, which you can type (along with keywords) at a command prompt; or icons that you invoke from a bitmapped desktop. The executables are commonly 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, see the Reports Migration Manual.
Installation Files
Installation files are SQL scripts used to install Oracle Reports. For more information on the files you will use to install Oracle Reports, see the Developer/2000 Installation Guide for your operating system. Demo files have two file formats: .rex files and .sql scripts. The report definitions in text file format (files with an extension of .rex) contain the definitions of the introductory and advanced reports discussed in the Building Reports Manual. The script files (files with an extension of .sql) create the sample database tables used by the introductory and advanced reports. These files are commonly found in the demo subdirectory or folder. Administration files are .sql scripts with which you can perform administrative tasks more quickly and easily. These scripts are commonly found in the admin subdirectory or folder. For more information on .sql scripts, see Using SQL Scripts on page 19 2.
Demo Files
Administration Files
18 6
Printer Definition and Driver Files
Printer definition files (files with an extension of .prt) are text files (e.g., ASCII, EBCDIC) containing definitions (label and formatting codes) for one or more types of printers. There are several printer definition files shipped with Oracle Reports which are commonly found in the ORACLE_HOME/reports25/admin/printer subdirectory or folder. Caution: Printer definitions are not necessary for reports that you plan to run on bitmapped platforms. They are optionally used by reports designed to run in a charactermode environment.
Terminal Definition Files
There are two types of terminal files shipped with Oracle Reports: Terminal/key definition files Are text files with entries for the various terminal types and their key mappings.
Terminal/key files Are binary files, created via the Oracle Terminal utility, that uniquely identify the various terminals and 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 or folder. 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 that you plan to run on bitmapped platforms. They are only necessary if for reports designed to run in a charactermode environment.
Font Mapping File
Oracle Reports supports font aliases. The font mappings used by Oracle Reports are defined in the file uifont.ali. You can alter these mappings by editing this file. The location of this file varies according to your operating system. For more information on the files you will use to install Oracle Reports, see the Developer/2000 Installation Guide for your operating system. Note: Oracle Reports will look for the font mapping file in the location specified via the environment variable TK2_FONTALIAS. If TK2_FONTALIAS is not specified, Oracle Reports will look in the default location for your operating system.
Storage
18 7
Temporary Files
Oracle Reports creates the following temporary files during report execution:
Swap files are created when you run a report that requires multiple passes to format (e.g., a report that has forward references such as a field with Source of &Total Logical Pages). The swap file contains a first pass copy of each page of the report that Oracle Reports uses to determine the length of the report and resolve any forward references. By the time all of the pages have formatted, this file will be approximately twice the size of the final ouput. While developing a report, you should exclude forward 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 fetched from 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 each column is just enough to contain the current value, not the maximum 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 file contains tree structures built to traverse the data according to the relationships defined in the reports data model. The size of this file 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 Oracle Reports places temporary files using REPORTS25_TMP. For more information, see REPORTS25_TMP on page 18 11.
18 8
Temporary File Size
Temporary files can grow very large for a number of reasons. To avoid having large temporary files, consider the following:
Perform calculations in queries, if possible. This can reduce the size of data caching file because the report does not need to retrieve as much data as it would if the calculations were performed 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 it reduces the size of the tree structure in the file. Eliminate forward referencing (e.g., fields with Source of &Total Logical Pages), if possible. This can eliminate the swap file because Oracle Reports does not have to save a copy of the report output in the swap file before formatting.
File Security and Restrictions

Oracle Reports uses your operating system environment to determine the security of modules stored in files. The way in which you acquire permission to access modules stored in files is operating systemdependent. For more information, refer to your operating system manual.
FileSearching Method
When you reference a file in Oracle Reports, it searches for the file in the following order: 1. 2. 3. 4. 5. The path prefixed to the filename (e.g., /home/jsmith), if any. The path that your operating system considers the current path. The path specified in the environment variable REPORTS25_PATH. The path specified in the environment variable ORACLE_PATH. Your location when you invoked Oracle Reports. Note: If you do not enter an extension, Oracle Reports appends one before performing the search. If the file is not found, Oracle Reports then searches for the file without the extension. For more information about printer and terminal definition search order, see Printer and Terminal Definistions on page 18 10.
Storage
18 9
For more information icon file search order, see Icon Files on page 18 10.
Printer and Terminal Definitions

Printer Definitions
In charactermode environments, you may use printer and terminal definition files. Printer definitions are searched for as follows: 1. 2. 3. 4. The path that your operating system considers the current path. The path specified in the environment variable REPORTS25_PATH. The path specified in the environment variable ORACLE_PATH. The ORACLE_HOME/reports25/admin/printer subdirectory or folder.
Terminal Definitions
Terminal definitions are searched for as follows: 1. 2. 3. The path specified in the environment variable REPORTS25_TERMINAL. The path specified in the environment variable ORACLE_TERMINAL. The ORACLE_HOME/reports25/admin/terminal subdirectory or folder.
Icon Files
If you create a button in Oracle Reports, you can assign it an icon instead 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_ICON environment variable.
Oracle Reports Environment Variables

In addition to environment variables provided by ORACLE and your base operating system, Oracle Reports provides environment variables you can use to define default directories for various Oracle Reports files. These environment variables are:

REPORTS25_PATH 18 11 REPORTS25_TERMINAL 18 11 REPORTS25_TMP 18 11 TK21_ICON 18 12
18 10
REPORTS25_PATH
Purpose: This environment variable is used to locate reports and external objects that you use in your reports, such as PL/SQL libraries, external queries, and external boilerplate. It enables you to create reports that are easily portable across operating systems by preventing the need to hardcode directory paths. Creation: Define REPORTS25_PATH in the same fashion you define other environment variables on your operating system, keeping in mind such platformspecific rules as path length, etc.. In addition to directory paths, you can specify the keyword DB when you define REPORTS25_PATH. This instructs Oracle Reports to search the 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 search the database to which you connected when you began your Oracle Reports session. If you dont define REPORTS25_PATH, Oracle Reports will first search the current directory. If the file is not there, it will search ORACLE_HOME/reports25. For more information about REPORTS25_PATH, see the Developer/2000 Installation Guide for your operating system. REPORTS25_TERMINAL Purpose: This environment variable is used to locate terminal definitions that you use in your charactermode reports. The path you specify for this variable takes precedence over the ORACLE_TERMINAL environment variable. Creation: Define REPORTS25_TERMINAL in the same fashion you define other environment variables on your operating system, keeping in mind such platformspecific rules as path length, etc.. REPORTS25_TMP Purpose: This environment variable establishes the directory in which you wish to store Oracle Reports temporary files. Oracle Reports will use only one directory for this purpose; do not define more than one. Creation: Define REPORTS25_TMP in the same fashion you define other environment variables on your base operating system, keeping in mind such platformspecific rules as path length, etc.
Storage
18 11
If you dont define REPORTS25_TMP, it will default to the temporary directory used by your base operating system. For more information about REPORTS25_TMP, see the Developer/2000 Installation Guide for your operating system. TK21_ICON Purpose: This environment variable establishes the directory in which you wish to store icons used for buttons in your layout. Oracle Reports will use only one directory for this purpose; do not define more than one. Creation: Define TK21_ICON in the same fashion you define other environment variables on your base operating system, keeping in mind such platformspecific rules as path length, etc..
Database Table Storage

There are three sets of tables used with Oracle Reports: Demo tables Contain sample data used by the introductory and advanced reports documented in Building Reports Manual. Contain your own data. Contain reports, external queries, and external PL/SQL libraries.
Data tables Oracle Reports tables
Knowing about the Oracle Reports tables enables you to:

modify the report on reports, which are reports shipped with Oracle Reports that run against the Oracle Reports tables create your own reports that run against the Oracle Reports tables
Oracle Reports Tables
When you save a module to the database, its definition is stored in the Oracle Reports tables. These tables comprise the following:

Oracle Reportsspecific tables 18 13 integrated Oracle product tables 18 27
For security purposes, Oracle Reports provides a view of each of its tables. The descriptions that follow are of the views of these tables, except where noted.
18 12
Caution: Oracle Corporation does not guarantee the functionality or integrity of modules whose table definitions have been modified via SQL*Plus (or another database tool) not specifically intended to modify the Oracle Reports tables. Also, be aware that Oracle Corporation reserves the right to change the names or structures of its tables at any time and without notice.
Oracle Reports specific Tables
Oracle Reportsspecific tables contain module and reportlevel object definitions. These tables are used solely by Oracle Reports, and are not shared with other Oracle products. Through the use of views and public synonyms, users can see information about modules they own or to which they have been granted access.
SRW2_ANCHOR Name
OWNER MODID ITEMID TAG DISP_ORDER HEAD_ID HEAD_EDGE HEAD_PCT TAIL_ID TAIL_EDGE TAIL_PCT NUM_POINTS POINTS COLLAPSE
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(10) DECIMAL(2) DECIMAL(8) DECIMAL(10) DECIMAL(2) DECIMAL(8) DECIMAL(2) RAW(250) DECIMAL(1)
Comment
Report Owner Report ID Anchor ID Display Tag Anchor Display List Order Anchor Head ID Edge of Parent Object Percent Across Parent Object Edge Anchor Tail ID Edge of Anchored Object Percent Across Anchored Object Number of Points Anchor Points Collapsible Anchor
SRW2_BODY_ LOCATION Name

OWNER MODID START_X
Null?
NOT NULL NOT NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10)
Comment
Report Owner Report ID Horizontal Starting Point
Storage
18 13
Name
START_Y LOC_ORDER
Null?
NULL NULL
Type
DECIMAL(10) DECIMAL(5)
Comment
Vertical Starting Point Location Order
SRW2_BOILERPLATE Name
OWNER MODID ITEMID NAME TAG DISP_ORDER FORMATFLAG PRE_CODE POST_CODE X Y WD HT PAGE TYPE NUM_POINTS POINTS POINTSLFID CLOSE ARCFILL ARROWSTYLE ROTANGLE GRAPH_TYPE GRAPH_LFID GRAPH_LEN LINKEDFILE
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(30) DECIMAL(10) DECIMAL(5) DECIMAL(10) VARCHAR(250) VARCHAR(250) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(5) DECIMAL(5) RAW(250) DECIMAL(10) DECIMAL(1) DECIMAL(1) DECIMAL(1) DECIMAL(5) DECIMAL(5) DECIMAL(10) DECIMAL(10) VARCHAR(250)
Comment
Report Owner Report ID Boilerplate ID Boilerplate Name Display Tag Boilerplate Display List Order Format Flags Before Object Printer Code After Object Printer Code Boilerplate XCoordinate Boilerplate YCoordinate Boilerplate Width Boilerplate Height Page on which Object Appears Polygon Type Number of Points Boilerplate Points Pointer to LONG Closed Object Fill Pattern for Arc Arrow End Style Rotation Angle Type of Graphic Format Pointer to LONG Length of Graphic Link File
18 14
Name
MIN_WIDOWS MIN_ORPHAN MAX_LINES TEXT_WRAP ALIGNMENT SPACING OLE_LFID OLE_LEN
Null?
NULL NULL NULL NULL NULL NULL NULL NULL
Type
DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(2) DECIMAL(5) DECIMAL(10) DECIMAL(10) DECIMAL(10)
Comment
Minimum Number of Widow Lines Minimum Number of Orphan Lines Maximum Number of Lines Text Wrap Style Boilerplate Alignment Text Spacing Pointer to LONG Length of OLE object
SRW2_COLUMN Name
OWNER MODID ITEMID NAME TAG DISP_ORDER GROUP_ID SOURCE SOURCE_ID COMPUTE_ID RESET_ID PROD_ORDER NULL_VALUE INPUT_MASK OPERATOR DATA_TYPE FILE_TYPE WIDTH FLAGS PRECISION SCALE
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(30) DECIMAL(10) DECIMAL(5) DECIMAL(10) DECIMAL(2) DECIMAL(10) DECIMAL(10) DECIMAL(10) VARCHAR(250) VARCHAR(250) VARCHAR(250) DECIMAL(2) DECIMAL(2) DECIMAL(2) DECIMAL(10) DECIMAL(5) DECIMAL(5) DECIMAL(5)
Comment
Report Owner Report ID Column ID Column Name Display Tag Column Display Order Group ID Column Source Name Column Source ID Compute Group (% of Totals) Reset Group ID Product Order Value if Null Format Mask Aggregation Function Column Datatype File Type/Read rom File Maximum Value Width Column Flags Value Precision Value Scale
Storage
18 15
Name
X Y WD HT DFLT_LBL DFLT_WID DFLT_HGT DEREF_ID ODATA_TYPE PARA_TYPE PLOV_RTYPE PLOV_SLISTID PLOV_SELECT PLOV_COL REFDTYPE
Null?
NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) VARCHAR(250) DECIMAL(5) DECIMAL(10) DECIMAL(10) DECIMAL(2) DECIMAL(2) DECIMAL(2) DECIMAL(10) VARCHAR(250) VARCHAR(250) DECIMAL(2)
Comment
XCoordinate YCoordinate Column Width Column Height Default Column Label Default Column Width Default Column Height Development Environment ID ORACLE Datatype Parameter Datatype List of Values Type LOV Listid LOV SELECT Statement LOV Column Reference Datatype
18 16
SRW2_DATA_MODEL Name
OWNER MODID ITEMID SETTINGS DFLT_TYPE ZOOMPOWER WINDOW_X WINDOW_Y WINDOW_WD WINDOW_HT UIFLAGS GRIDINTC GRIDSNPC HALIGN VALIGN DECURREF_ID
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(5) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(1) DECIMAL(1) DECIMAL(10)
Comment
Report Owner Report ID Data Model ID Display Settings Default Type Magnification Horizontal Window Location Vertical Window Location Window Width Window Height Painter Settings Flag Grid Spacing Number of Snap Points Per Grid Spacing Horizontal Alignment Vertical Alignment Reference ID Counter
SRW2_DISPLAY_TAG Name
OWNER MODID ITEMID CM_TEXT CM_FILL CM_BORD PENWID ADD_FLAGS TEXTPAT TEXTFORE TEXTBACK
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(250) VARCHAR(250) VARCHAR(250) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(5) DECIMAL(5)
Comment
Report Owner Report ID Display Tag ID Text Attributes Fill Attributes Border Attributes Pen Width Flags for Image Information Text Pattern Text Foreground Color Text Background Color
Storage
18 17
Name
LINEPAT LINEFORE LINEBACK FILLPAT FILLFORE FILLBACK FONTFACE FONTSIZE FONTSTYLE FONTWEIGHT CHARSET CHARWIDTH BASELINE KERNING DASHSTYLE CAPSTYLE JOINSTYLE TRANSMODE
Null?
NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5)
Comment
Line Pattern Line Foreground Color Line Background Color Fill Pattern Fill Foreground Color Fill Background Color Font Type Font Size Font Style Font Boldness Character Set Width of Characters Baseline Text Kerning Dash Appearance Line End Style Joined Line Style Object Creation Style
SRW2_ELEMENT Name
OWNER MODID ITEMID ALIAS EXPR DESC_EXPR QUERYID SEL_ORDER DATA_TYPE WIDTH SCALE PRECISION ODATA_TYPE
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(250) VARCHAR(250) VARCHAR(250) DECIMAL(10) DECIMAL(5) DECIMAL(2) DECIMAL(10) DECIMAL(5) DECIMAL(5) DECIMAL(2)
Comment
Report Owner Report ID Element ID Alias Expression Expression Description Pointer to Query SELECT Order Element Datatype Element Width Element Scale Element Precision ORACLE Datatype
18 18
SRW2_FIELD Name
OWNER MODID ITEMID NAME TAG DISP_ORDER FORMATFLAG PRE_CODE POST_CODE X Y WD HT PAGE PGN_FLAGS PGN_START PGN_INCR PGN_RESET SOURCE_ID CONTINUED ALIGNMENT TEXT_WRAP MIN_WIDOWS MIN_ORPHAN MAX_LINES MASK
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(30) DECIMAL(10) DECIMAL(5) DECIMAL(10) VARCHAR(250) VARCHAR(250) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(2) DECIMAL(5) DECIMAL(5) DECIMAL(5) VARCHAR(250)
Comment
Report Owner Report ID Field ID Field Name Display Tag Field Display Order Format Flags Before Object Printer Code After Object Printer Code Field XCoordinate Field YCoordinate Field Width Field Height Page on which Object Appears Page Numbering Flags Page Numbering Start Value Page Numbering Increment Value Page Numbering Reset Value Field Source ID Field Continued From Field Alignment Text Wrap Style Minimum Number of Widowed Lines Minimum Number of Orphaned Lines Maximum Number of Lines per Page Field Format Mask
Storage
18 19
Name
NULL_VALUE SPACING
Null?
NULL NULL
Type
VARCHAR(250) DECIMAL(10)
Comment
Format if Null Text Spacing
SRW2_FRAME Name
OWNER MODID ITEMID NAME TAG DISP_ORDER FORMATFLAG PRE_CODE POST_CODE X Y WD HT PAGE GROUP_ID CONTINUED DIRECTION MIN_WIDOWS MIN_ORPHAN MAX_LINES BETWEEN_X BETWEEN_Y RESERVED
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(30) DECIMAL(10) DECIMAL(5) DECIMAL(10) VARCHAR(250) VARCHAR(250) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(5) DECIMAL(10) DECIMAL(10) DECIMAL(10)
Comment
Report Owner Report ID Frame ID Frame Name Display Tag Frame Display Order Format Flags Before Object Printer Code After Object Printer Code Frame X coordinate Frame Y coordinate Frame Width Frame Height Page on which Frame Appears Associated Group Group Continued From Frame Print Direction Minimum Number of Widowed Lines Minimum Number of Orphaned Lines Maximum Number of Lines per Page Between Record Area X Dimension Between Record Area Y Dimension Space Reserved for Matrices
18 20
SRW2_GROUP Name
OWNER MODID ITEMID NAME TAG DISP_ORDER PTAG QUERY_ID PARENT_ID QLF_TYPE QLF_ARG QLF_COLUMN GLF_TYPE GLF_ARG GLF_COLUMN RLF_TYPE RLF_ARG RLF_COLUMN CROSS_PROD PRODUCT_ID NUM_POINTS POINTS X Y WD HT DFLT_DIR
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(30) DECIMAL(10) DECIMAL(5) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(2) DECIMAL(5) DECIMAL(10) DECIMAL(2) DECIMAL(5) DECIMAL(10) DECIMAL(2) DECIMAL(5) DECIMAL(10) DECIMAL(1) DECIMAL(10) DECIMAL(5) RAW(250) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5)
Comment
Report Owner Report ID Group ID Group Name Display Tag Group Display Order Display Tag for Points Query this Group Comes From Parent Group (0 if Top Group) Querylevel Filter Querylevel Filter Argument Querylevel Filter Column Grouplevel Filter Grouplevel Filter Argument Grouplevel Filter Column Rowlevel Filter Rowlevel Filter Argument Rowlevel Filter Column Cross Product Flag Cross Product Parent ID Number of Points Incoming Line from Previous Group XCoordinate YCoordinate Group Width Group Height Default Direction
Storage
18 21
SRW2_LAYOUT Name
OWNER MODID ITEMID SETTINGS ZOOMPOWER UNITS ORIENT UNITS_WID UNITS_HGT CHAR_WID CHAR_HGT BODY_WID BODY_HGT PAGE_WID PAGE_HGT PRINT_WID PRINT_HGT X_PANELS Y_PANELS HEADERS TRAILERS WINDOW_X WINDOW_Y WINDOW_WD WINDOW_HT RUN_FLAGS TITLE HINT STATUS MAXHEADERS MAXTRAILERS
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(2) DECIMAL(2) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(5) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) VARCHAR(250) VARCHAR(250) VARCHAR(250) DECIMAL(5) DECIMAL(5)
Comment
Report Owner Report ID Layout ID Display Settings Magnification Units of Measurement Orientation, Page Print Order Width in Units Height in Units Character Width Character Height Body Width Body Height Page Width Page Height Printable Area Width Printable Area Height XCoordinate YCoordinate Number of Header Pages Number of Trailer Pages Horizontal Window Location Vertical Window Location Window Width Window Height Runtime Flags Previewer Title Previewer Hint Previewer Status Maximum Header Pages Maximum Trailer Pages
18 22
Name
MAXBODY_ACR MAXBODY_DWN INTERN_VER INTERN_VER2 APPLSTATE UIFLAGS GRIDINTC GRIDSNPC HALIGN VALIGN RRECTCNR_WD RRECTCNR_HT
Null?
NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
DECIMAL(5) DECIMAL(5) DECIMAL(2) DECIMAL(4) DECIMAL(6) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(1) DECIMAL(1) DECIMAL(10) DECIMAL(10)
Comment
Maximum Body Width Maximum Body Height SRW Development Future Expansion Future Expansion Painter Settings Flag Grid Spacing Number of Snap Points Per Grid Spacing Horizontal Alignment Vertical Alignment Horizontal Corner Radius of Rounded Rectangle Vertical Corner Radius of Rounded Rectangle
SPACING JUSTIFIC ARROWSTYLE UITAG NEXTLISTID IDROLESLIST
NULL NULL NULL NULL NULL NULL
DECIMAL(10) DECIMAL(5) DECIMAL(1) DECIMAL(10) DECIMAL(10) DECIMAL(10)
Line Spacing Setting Justification Setting Arrow Style Setting Painter Settings Display Tag Next List ID ID of Roles List
SRW2_LAYOUT_ GROUP Name

OWNER MODID ITEMID DISP_ORDER FORMATFLAG NCHILDREN
Null?
NOT NULL NOT NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(10) DECIMAL(10)
Comment
Report Owner Report ID Layout ID Display Order Format Flag Number of Children
Storage
18 23
SRW2_LINK Name
OWNER MODID ITEMID TAG DISP_ORDER PARENT_ID P_COLUMN CHILD_ID C_COLUMN CLAUSE OPERATOR NUM_POINTS POINTS
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(2) DECIMAL(2) DECIMAL(5) RAW(250)
Comment
Report Owner Report ID Link ID Display Tag Link Display Order Parent Group ID Parent Column ID Child Group ID Child Column ID SQL Clause Link Operator Number of Points Link Points
SRW2_MATRIX Name
OWNER MODID ITEMID NAME TAG DISP_ORDER PAGE DOWN_ID ACROSS_ID GROUP_ID
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(30) DECIMAL(10) DECIMAL(5) DECIMAL(5) DECIMAL(10) DECIMAL(10) DECIMAL(10)
Comment
Report Owner Report ID Matrix ID Matrix Name Display Tag Matrix Display Order Page on which Object Appears Vertical Frame Horizontal Frame Group
SRW2_MODULE Name
OWNER MODID MODNAME
SRW2_MODULE is a view on TOOL_MODULE. Null?

NOT NULL NOT NULL NULL
Type
VARCHAR(30) DECIMAL(10) VARCHAR(61)
Comment
Module Owner Module ID Module Name
18 24
Name
MODTYPE PRODUCT
Null?
NULL NULL
Type
NUMBER NUMBER
Comment
Module Type Product
SRW2_OG_DOCUMENT Name
OWNER MODID ITEMID NAME TAG DISP_ORDER FORMATFLAG PRE_CODE POST_CODE X Y WD HT PAGE OG_DNAME OG_QNAME OG_SLOC GROUP_ID
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(30) DECIMAL(10) DECIMAL(5) DECIMAL(10) VARCHAR(250) VARCHAR(250) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) VARCHAR(250) VARCHAR(250) DECIMAL(5) DECIMAL(10)
Comment
Report Owner Report ID Object ID Object Name Display Tag Document Display Order Format Flags Before Object Printer Code After Object Printer Code Document X coordinate Document Y coordinate Document Width Document Height Page on which Document Appears Document Name Query Name Storage Location Associated Group
SRW2_OGD_ COLUMN_MAP Name

OWNER MODID ITEMID SRW_COLID
Null?
NOT NULL NOT NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10)
Comment
Report Owner Report ID Parameter Form ID Report Column ID
Storage
18 25
Name
OG_COLTYPE OG_COLNAME
Null?
NULL NULL
Type
DECIMAL(5) VARCHAR(250)
Comment
Display Column Type Display Column Name
SRW2_QUERY Name
OWNER MODID ITEMID NAME TAG DISP_ORDER EXT_QUERY NET_LOGON TEMP_TABLE TEMP_FLAGS EXEC_FREQ MAX_ROWS X Y WD HT QUERYLFID
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(30) DECIMAL(10) DECIMAL(5) VARCHAR(250) VARCHAR(250) VARCHAR(30) DECIMAL(5) DECIMAL(2) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10)
Comment
Report Owner Report ID Query ID Query Name Display Tag Query Display Order External Query Name SQL*Net Logon Temporary Table Name Temporary Table Flags Execution Frequency Maximum Number of Rows to Fetch XCoordinate Y<+>Coordinate Query Width Query Height Pointer to SELECT Statement Text
SRW2_TEXT_ SEGMENT Name

OWNER MODID ITEMID TAG SEG_TEXT SEG_ORDER
Null?
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) VARCHAR(250) DECIMAL(5)
Comment
Report Owner Report ID Text Segment ID Display Tag Text Segment Text Segment Order
18 26
Integrated Oracle Product Tables and Other Objects

Integrated Oracle product tables contain module definitions, and may be shared with other Oracle products. Through the use of database views and public synonyms, users can see information about modules they own or to which they have been granted access. TOOL_ACCESS Name
PRODUCT OWNER MODID GRANTEE
Null?
NULL NOT NULL NOT NULL NULL
Type
VARCHAR(30) VARCHAR(30) DECIMAL(10) VARCHAR(30)
Comment
Product Name Module Owner Module ID User to Whom Access Granted
TOOL_COMMENT Name
OWNER MODID ITEMID OBJECT_ID CMTLFID_S CMTLFID_T
Null?
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10)
Comment
Module Owner Module ID Item (comment) ID ID of Commented Object LONG Field ID (sound comment) LONG Field ID (text comment)
TOOL_DEPEND Name
OWNER MODID ITEMID DEP_MODID DEP_ITEMID DEP_TYPE DEPCHANGED
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) VARCHAR(250) VARCHAR(1)
Commen
Module Owner Module ID Item ID (optional) Module Dependent On Item Dependent On (optional) Dependency Type (product defined) DependentObject Has Changed
Storage
18 27
TOOL_LIBRARY Name
PRODUCT OWNER MODID LIBNAME
Null?
NULL NOT NULL NOT NULL NULL
Type
VARCHAR(30) VARCHAR(30) DECIMAL(10) VARCHAR(255)
Comment
Product Name Module Owner Module ID Name of Library
TOOL_LRAW Name
OWNER MODID ID LPAGEID LFLEN N DATALEN DATA
Null?
NOT NULL NOT NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(10) LONG RAW
Comment
Module Owner Module ID Long Field ID LONG RAW Page ID LONG RAW Field ID LONG Field Sequence Number LONG Field Length Long RAW Data Chunk
TOOL_LRAW_ID Name
ID
TOOL_LRAW_ID is a sequence that is used to generate LONG RAW data IDs. Type
NUMBER(10)
Comment
Next LONG RAW ID to Use
TOOL_LTEXT Name
OWNER MODID ID LPAGEID LFLEN N DATALEN DATA
Null?
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(5) DECIMAL(10) LONG
Comment
Module Owner Module ID LONG Field ID LONG Page ID LONG Field Length LONG Field Sequence Number LONG Field Length LONG Text Chunk
18 28
TOOL_LTEXT_ID Name
ID
TOOL_LTEXT_ID is a sequence that is used to generate LONG text IDs. Type

NUMBER(10)
Comment
Next LONG ID to Use
TOOL_MODID Name
MODID
TOOL_MODID is a sequence that is used to generate module IDs. Type

NUMBER(10)
Comment
Next Module ID to Use
TOOL_MODULE Name
PRODUCT MODTYPE MODID NEXT_ITEMID OWNER MODNAME CREATOR CREATE_DATE CREATE_VER MODIFIER MOD_DATE MOD_VER COPYRIGHT REQ_ROLE TCS_VER VGS_VER
Null?
NULL NULL NOT NULL NULL NOT NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL
Type
VARCHAR(30) VARCHAR(30) DECIMAL(10) DECIMAL(10) VARCHAR(30) VARCHAR(30) VARCHAR(30) DATE DECIMAL(8) VARCHAR(30) DATE DECIMAL(8) VARCHAR(250) VARCHAR(30) DECIMAL(8) DECIMAL(8)
Comment
Product Name Module Type Module ID Next Available Internal ID Module Owner Module Name User Who Created the Module Creation Date Product Version Created With User Who Last Modified the Module Modification Date Product Version Modified With Module Copyright Notice Role Required to Run this Module Version of TCS Version of VGS
Storage
18 29
Name
DE_VER ROS_VER
Null?
NULL NULL
Type
DECIMAL(8) DECIMAL(8)
Comment
Version of DE Version of ROS
TOOL_PLSQL Name
OWNER MODID ITEMID OBJECT_ID TYPE NAME PLSLFID_ST PLSLFID_EP
Null?
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(4) VARCHAR(30) DECIMAL(10) DECIMAL(10)
Comment
Module Owner Module ID Item (program unit) ID Associated Object ID (optional) Type of Program Unit (optional, product defined) Name of Program Unit LONG Field ID of PL/SQL Source Text LONG Field ID of PL/SQL Encoded Program Unit
ROSSTRINGS Name
OWNER MODID GROUPID STRINGID LFID LEN CS STR
Null?
NOT NULL NOT NULL NOTNULL NOT NULL NOT NULL NOT NULL NOT NULL
Type
VARCHAR(30) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) DECIMAL(10) LONG RAW
Comment
User Module ID Group ID ID for String Instances in Module For ROS Use Data (String) Length Character Set Data (String)
18 30
Establishing Database Security and Restrictions

There are three types of restrictions you can place on Oracle Reports users:

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 ORACLEs GRANT and REVOKE commands, providing extra measures of control. All restrictions placed through GRANT and REVOKE still apply.
Controlling Access to Oracle Reports
A user will be unable to access Oracle Reports unless the user is granted access to Oracle Reports tables by running the srw2grnt.sql script. To revoke a users access to Oracle Reports, run the srw2rvke.sql script. Users may access another users module stored in the database. To do this, the module creator must grant other users access to it by first ensuring the other users have access to the tables in which the modules are stored, then doing the following: 1. 2. Select File>Administration>Module Access to display the Module Access List dialog box. Enter a username (or PUBLIC) in the Module Access List dialog box. If you type PUBLIC, all users that have been granted access to the systemowned tables will have access to the module. Note: Only a modules creator can grant access to that module to other users. Also, only an modules creator can modify the module, even if the creator has granted access to others.
Controlling Access to Other Users Modules
Database Storage Requirements

Oracle Reports tables require approximately one megabyte of storage when empty. When using Oracle Reports with ORACLE, only one set of tables is created and therefore only one megabyte is needed initially per installation. As you create modules and run reports, the database space requirements will naturally increase.
Storage
18 31
Note: Because this information can vary from system to system and across dissimilar hardware, this information is only provided to give you a general idea of database storage requirements. For more information, see the Developer/2000 Installation Guide for your operating system.
Memory and Disk Space Requirements

Oracle Reports has the following memory requirements: Item Runtime Engine Designer Engine Memory 56 meg 7 meg Disk Space 26 meg 26 meg
As you create modules and run reports, these memory and disk requirements will naturally increase. In particular, complex reports that use many images and graphics can significantly increase disk and RAM requirements. If you use a total number of pages in your report (e.g., &Total Logical Pages), Oracle Reports needs to keep its temporary files in order to determine the total number of pages in the report. This can also significantly increase your disk space and RAM requirements. Note: Because this information can vary from system to system and across dissimilar hardware, the table above is only provided to give you a general idea of memory requirements. For more information, see the Developer/2000 Installation Guide for your operating system.
18 32
PART
Administration
CHAPTER
19
Administration
f you are responsible for administering Oracle Reports, you should 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
Administration
19 1
Using SQL Scripts

Oracle Reports is shipped with several SQL scripts, with which you can quickly perform some database administration that might otherwise require significantly more time. To run any of the SQL scripts, you log on to SQL*Plus and then type the following:
START script_name
where:
script_name
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*Plus Users Guide and Reference Manual.
SQL Script Descriptions
Below is an alphabetized list of each SQL script and its purpose. These scripts should initially appear in the admin subdirectory. For more information, see the Developer/2000 Installation Guide for your operating system. Note: All of these scripts, with the exception of srw2drop.sql, should only be used by DBAs. srw2drop.sql droprep.sql srw2grnt.sql Deletes the Oracle Reportsspecific tables. Deletes one report. Grants privileges to the specified user(s) so they can create and modify modules stored in the Oracle Reportsspecific tables. Installs the Oracle Reportsspecific tables. Limits at once the number of output pages that the specified user(s) may print for a report. This prevents loss of many pages when a report is improperly designed. Creates the PRODUCT_PROFILE and USER_PROFILE tables for ORACLE Version 6. It also creates two views on these tables, which is what users (nonDBAs) see. Creates the PRODUCT_PROFILE and USER_PROFILE tables for ORACLE7. It also creates two views on these tables, which is what users (nonDBAs) see.
srw2bild.sql srw2lmt.sql
srw2pup.sql
srw2pup7.sql
19 2
srw2rvke.sql
Revokes privileges of the specified user(s) so they cannot create and modify modules stored in the Oracle Reportsspecific tables. Deletes the integrated Oracle tools tables. Grants privileges to the specified user(s) so they can create and modify modules stored in the integrated Oracle tools tables. Installs the integrated Oracle tools tables. Revokes privileges of the specified user(s) so they cannot create and modify modules stored in the integrated Oracle tools tables. Deletes the VGS tables. Grants privileges to the specified user(s) so they can modify the VGS tables. Installs the VGS tables. Revokes privileges of the specified user(s) so they cannot modify the VGS tables. Deletes the ROS tables. Grants privileges to the specified user(s) so they can modify the ROS tables. Installs the ROS tables.
tooldrop.sql toolgrnt.sql
toolbild.sql toolrvke.sql
vgdrop.sql vggrnt.sql vgbild.sql vgrvke.sql rosdrp.sql rosgnt.sql ros.sql
Installing Tables
To install the Oracle Reports tables, do the following using SQL*Plus 1. 2. 3. 4. Run the toolbild.sql script to create the integrated Oracle tools tables. Run the ros.sql script to create the ROS tables. Run the vgbild.sql script to create the VGS tables. Run the srw2bild.sql script to create the Oracle Reportsspecific tables.
Caution: These tables must be created in the order specified above.
Administration
19 3
Granting User Privileges

To grant a user privileges to create and modify modules stored in the database, do the following in SQL*Plus: 1. Run the toolgrnt.sql script. You are prompted to specify the username(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 those users.
2.
Run the rosgnt.sql script. You are prompted to specify the username(s) to whom you wish to grant privileges.

3.
Run the vggrnt.sql script. You are prompted to specify the username(s) to whom you wish to grant privileges.

4.
Run the srw2grnt.sql script. You are asked to specify the user(s) to whom you wish to grant privileges.

Revoking User Privileges

To revoke a users privileges to create and modify modules stored in the 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 future users. Enter one or more usernames to revoke the privileges of only those users.
19 4
Upgrading from Previous Versions of Oracle Reports

To upgrade from a previous version of SQL*ReportWriter to Oracle Reports, you need to run the R25MREP executable. For more information, see the Reports Migration Manual.
Dropping Version 1.1 Tables

After youve installed Oracle Reports and its accompanying tables, and converted all of your reports using R25MREP, youll want to drop your SQL*ReportWriter Version 1.1 tables. To do this, do the following in SQL*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 Viceversa
To move reports that are stored in operating system files to the database or the reverse, you can do one of the following:
Open the report and then select File>Save As.... Save the report to the database or a file. If desired, you can then delete the original version of the report using operating system commands (for files) or File>Administration>Delete (for the database). Use R25CONV. For more information, see R25CONV on page 1 9.
Deleting Modules
To delete modules stored in operating system files, delete the files using the appropriate operating system commands. To delete modules from the database, you can do any of the following:
Select File>Administration>Delete..., then select the module (report, external query, or external PL/SQL library) you want to delete. Use the droprep.sql script to delete a report from the database.
Administration
19 5
Documenting Reports
To print documentation about one or more reports, select File>Administration>Report Doc. This will run a report on your reports stored in the database. When the Runtime Parameter Form appears, you can enter a full or partial report name to indicate for which report(s) you want the report to be run. % or _ can be used as wildcards 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, depending upon the executable you invoked and the operation youre performing. The sections that follow cover the following topics:

files you create 19 6 files Oracle Reports creates 19 7
Files You Create
The table below shows what files you must provide to Oracle Reports as input, depending upon the executable being used and operation being performed: R25DES R25RUN
ALWAYS NEEDS THIS FILE OR .REP REP FILE ALWAYS NEEDS THIS FILE OR .RDF FILE
FILETYPE
R25CONV
FOR SOURCE, IF STYPE IS RDFFILE
R25MREP
report definition file RUN/PRINT AND <report name>.rdf CONVERT, IF STYPE IS RDFFILE report runfile <report name>.rep
report text file f <filename >.rex terminal description file character mode only keystroke file character mode only V2.0 printer p description file <dflt>
CONVERT, IF STYPE IS REXFILE ALWAYS
FOR SOURCE, IF STYPE IS REXFILE
FOR SOURCE, IF STYPE IS REXFILE
IF BATCH IS NO IF KEYIN IS SPECIFIED ALWAYS
IF KEYIN IS SPECIFIED RUN
19 6
FILETYPE
V1.1 printer definition file <printdef.dat>
R25DES
R25RUN
R25CONV
R25MREP
ALWAYS
Files Created By Oracle The table below shows what files Oracle Reports creates, depending upon the executable being used and operation being performed: Reports
FILETYPE R25DES R25RUN
R25CONV
FOR DEST, IF DTYPE IS RDFFILE
R25MREP
FOR DEST, IF DTYPE IS RDFFILE
report definition file SAVE, SAVE AS, OR <report name>.rdf CONVERT, IF DTYPE IS RDFFILE p report runfile <report name>.rep rep GENERATE OR CONVERT, CONVERT IF DTYPE IS REPFILE SAVE, SAVE AS, OR CONVERT, IF DTYPE IS REXFILE RUN/PRINT, IF DESTYPE IS FILE IF PROFILER IS YES IF ERRFILE IS SPECIFIED IF TRACEFILE IS SPECIFIED RUN/PRINT, IF DESTYPE IS PRINTER
FOR DEST, IF DTYPE IS REPFILE FOR DEST, IF DTYPE IS REXFILE
FOR DEST, IF DTYPE IS REPFILE FOR DEST, IF DTYPE IS REXFILE
report text file filename <f lename>.rex
report output file <report name>.lis p g file profiler log <temp> error log file <temp> trace log file trace.dat
IF DESTYPE IS FILE IF PROFILER IS YES IF ERRFILE IS SPECIFIED IF TRACEFILE IS SPECIFIED IF DESTYPE IS PRINTER IF KEYOUT IS SPECIFIED PRINT SCREEN
printer output file
keystroke file IF KEYOUT charactermode only IS SPECIFIED Print Screen log file PRINT charactermode only SCREEN
Administration
19 7
FILETYPE
V2.0 printer p description file <dflt> record caching files idx<number> and dat<number> in <temp> memory swap files (only y created if needed) d d) <t <temp> >
R25DES
R25RUN
R25CONV
R25MREP
ALWAYS
RUN/PRINT
RUN/PRINT
RUN/PRINT
RUN/PRINT
IF NEEDED DURING CONVERSION
19 8
PART
VI
Appendixes
APPENDIX
Environment and GUI Differences

hen you invoke Oracle Reports, it provides you with the native W lookandfeel and functionality that your environment or GUI supports. For example, Oracle Reports provides image support when your environment supports images (i.e., in bitmapped environments); otherwise, it cannot (e.g., in charactermode). As a result, if you are designing a report in an environment or GUI other than the one in which it will be run, you need to be aware of the the following:

differences of environments and GUIs A 2 report design for charactermode environments A 3 report conversion across GUIs A 4
A1
Environment and GUI Differences Overview

This section is divided into two parts:

environment differences GUI differences
Environment Differences
There are two types of environments in which you can run Oracle Reports:

bitmapped charactermode
BitMapped Environments
A bitmapped environment has a unit of Pixel, and typically supports a mouse. Interaction with the host computer is continuous. As a result, a users work is immediately validated. An advantage of bitmapped environments is that they are graphical; a disadvantage is that they increase network traffic. GUIs run in bitmapped environments, only. A charactermode environment has a unit of Character, typically 80x24, and infrequently supports a mouse. Interaction with the host computer occurs at the field level; i.e., a field of information is sent to the host computer when a user navigates from a field. Charactermode environments require less network traffic than bitmapped environments, but more than blockmode environments; they validate a users work more frequently than blockmode environments, but less frequently than bitmapped environments. Oracle Reports is supported on the following GUIs of the bitmapped environment: Macintosh, Motif System, and Microsoft Windows. Although these GUIs have fairly similar functionality, you need to be aware of their differences if you are building reports on a GUI other than the one on which users will run them. Below are two categories of GUI differences:

CharacterMode Environments
GUI Differences
those that do not affect a reports portability those that affect a reports portability
Examples of GUI differences that do not affect a reports portability are the appearance of interface elements (e.g., check boxes are not squares on all GUIs), the contents and operation of the file dialog box, the contents and operation of the Windows menu, the methodology for invoking help, etc.
A2
Differences that do affect a reports portability are available system fonts and their associated attributes (such as weight, style, etc.), colors, and the dotsperinch (DPI) used to display your GUI. For more information 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 be run in character mode, you can use the following settings/menu items:

Page Height/Width Report Width x Height Use Character Units in Designer Convert Bitmapped 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, you must recompile the PL/SQL in the report before running it. 1. When displaying a character mode report in the bitmapped Previewer of the designer, Oracle Reports uses Report Width x Height to choose the font to display. The font may be slightly larger or smaller than the actual character cell size. As a result, when you run a report designed for character mode in the bitmapped Previewer, you may see some truncation.
For more information about designing reports for character mode, see Create CharacterMode Reports in Chapter 8 of Building Reports Manual.
A3
Report Conversion Across GUIs

If you move a report from one GUI to another, be aware of how the following GUI differences may affect the report: fonts, colors, and dotsperinch (DPI). Fonts A font (i.e., a font type, style, size, etc.) that is found in your GUI might not be available in the target GUI. You can handle this in one of two ways:

Use a font that you know exists on the target GUI or one that maps well to the default font of the target GUI. Modify the font mapping file, uifont.ali, to ensure that the fonts map correctly. For more information about uifont.ali, see Font Mapping File on page 18 7. For more information about font mapping, see Font Mapping on page A 5.
Colors A color found in your GUI might not be available in the target GUI. 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 on many platforms:

blue magenta red cyan green yellow
DPI The dotsperinch (DPI) that your monitor uses may not be the same as the DPI used by the person who runs the reportthis is true even if you both use the same GUI. The DPI only affects how alphanumeric characters wordwrap on the screen. As a result, if you design a report that may be displayed in the Previewer, then try to use the same DPI as the people who will run it. For this reason, you may also want to avoid giving layout objects fixed sizing. When DPI is different, fixed sizing may cause text to word wrap differently.
A4
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 in the 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 a predefined identifier/string. For example, both US7ASCII and 1 are valid values, and refer to the same character set. The <size> dimension must be an explicit size, in points. The following is a list of recognized names and their numeric equivalents: Styles plain italic oblique underline outline shadow inverted overstrike blink Weights ultralight extralight light demilight medium demibold bold extrabold ultrabold Numeric Value 0 1 2 4 8 16 32 64 128 Numeric Value 1 2 3 4 5 6 7 8 9
A5
Widths ultradense extradense dense semidense normal semiexpand expand extraexpand ultraexpand
Numeric Value 1 2 3 4 5 6 7 8 9
Styles can be combined using the plus sign (+). For example:
Arial..Italic+Overstrike = Helvetica.12.Italic.Bold
All strings are caseinsensitive in mapping. Font faces are likely to be casesensitive on lookup, depending on the platform and surface, so care should be taken with names used on the righthand side; but they will be mapped caseinsensitively. The backslash (\) is used as a continuation character. Comments can be included as follows:
/* comment */ # comment ; comment
Font Mapping Verification
To verify that your uifont.ali file is correct, you can use fontchk. This program will check your file to ensure there are no errors. Enter the following to parse your font mapping file:
fontchk filename
A6
Font Mapping Example
Below is a sample font mapping file that could be used with Oracle Reports.
[ Global ] # Put mappings for all surfaces here. Windows = helvetica = courier = times = helvetica = helvetica = times = helvetica
# Mapping from MS Arial Courier New Times New Roman Modern MS Sans Serif MS Serif Small Fonts
# Mapping from Macintosh New Century Schlbk = new century schoolbook New York = times [ Printer ] # Put mappings for all printers here. /* Put mappings for PostScript level 1 printers here. */
[ Printer:PostScript1 ]
# Mapping from MS Windows Roman = palatino Script = itc zapf chancery FixedSys = courier System = helvetica # Mapping from Macintosh 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 = \ RyuminLight83pvRKSJH...Light..JEUC courier...Bold..JEUC = \ GothicBBBMedium83pvRKSJH...Medium..JEUC courier...Medium..SJIS = \ RyuminLight83pvRKSJH...Light..JEUC
A7
courier...Bold..SJIS = \ GothicBBBMedium83pvRKSJH...Medium..JEUC times...Medium..JEUC = \ RyuminLight83pvRKSJH...Light..JEUC times...Bold..JEUC = \ GothicBBBMedium83pvRKSJH...Medium..JEUC times...Medium..SJIS = \ RyuminLight83pvRKSJH...Light..JEUC times...Bold..SJIS = \ GothicBBBMedium83pvRKSJH...Medium..JEUC helvetica...Medium..JEUC = \ RyuminLight83pvRKSJH...Light..JEUC helvetica...Bold..JEUC = \ GothicBBBMedium83pvRKSJH...Medium..JEUC helvetica...Medium..SJIS = \ RyuminLight83pvRKSJH...Light..JEUC helvetica...Bold..SJIS = \ GothicBBBMedium83pvRKSJH...Medium..JEUC [ Printer:PostScript2 ] /* Put mappings for PostScript level 2 printers here. */ # Mapping from MS Windows Roman = palatino Script = itc zapf chancery FixedSys = courier System = helvetica # Mapping from Macintosh 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 = \ RyuminLight83pvRKSJH...Light..JEUC courier...Bold..JEUC = \ GothicBBBMedium83pvRKSJH...Medium..JEUC courier...Medium..SJIS = \ RyuminLight83pvRKSJH...Light..JEUC courier...Bold..SJIS = \ GothicBBBMedium83pvRKSJH...Medium..JEUC
A8
times...Medium..JEUC = \ RyuminLight83pvRKSJH...Light..JEUC times...Bold..JEUC = \ GothicBBBMedium83pvRKSJH...Medium..JEUC times...Medium..SJIS = \ RyuminLight83pvRKSJH...Light..JEUC times...Bold..SJIS = \ GothicBBBMedium83pvRKSJH...Medium..JEUC helvetica...Medium..JEUC = \ RyuminLight83pvRKSJH...Light..JEUC helvetica...Bold..JEUC = \ GothicBBBMedium83pvRKSJH...Medium..JEUC helvetica...Medium..SJIS = \ RyuminLight83pvRKSJH...Light..JEUC helvetica...Bold..SJIS = \ GothicBBBMedium83pvRKSJH...Medium..JEUC [ Display ] # Put mappings for all display surfaces here. # Put mappings for Motif displays here
[ Display:Motif ]
# Mapping from MS Windows Courier = courier Roman = lucida Script = lucidabright FixedSys = fixed System = lucida # Mapping from Macintosh Avant Garde = helvetica Bookman = times [ Display:CM ] # Put mappings for all CM displays here. # These are DECspecific, 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
A9
A 10
APPENDIX

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 on charactermode platforms. They are not needed on bitmapped platforms. This information is provided here only for the convenience of those who are designing reports in bitmap for use in character mode.
B1
Purpose of Printer Definitions

A printer definition file acts like a translator for the printer: it tells the printer how to handle bolding, underlining, printing graphical characters used in lines/boxes, etc. Unlike Version 1.1, printer definition files are text files (e.g., ASCII, EBCDIC) that do not require any 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
Descriptions
Oracle Reports is shipped with several printer definitions, some of which are described below: dec.prt Is a generic printer file for most DEC printers that supports 66x80 page sizes for the LN03, LPS40, LP05, and LA50 printers. Is a generic printer file that prints in landscape mode and supports 66x132 page sizes. Is the same as dec, but supports 66x132 page sizes. Is the same as decland, but supports 66x180 page sizes. Is a generic printer file that ignores highlighting attributes and supports 66x80 page sizes. Is a generic printer file for the HP LaserJet printer that supports 66x80 page sizes. Is the same as hpl, but supports 66x132 page sizes. Is a PostScript printer file that prints in a landscape mode and supports 110x51 pages sizes. Is a PostScript printer file that prints in a landscape mode and supports 132x66 pages sizes. Is a PostScript printer file that prints in a portrait mode and supports 85x66 pages sizes. Is a PostScript printer file that prints in a portrait mode and supports 132x120 pages sizes.
decland.prt decwide.prt dec180.prt dflt.prt hpl.prt hplwide.prt pslan110.prt pslan132.prt psport85.prt pspor132.prt
B2
wide.prt wide180.prt
Is a generic printer file that ignores highlighting attributes and supports 66x132 page sizes. Is the same as wide, but supports 66x180 page sizes.
Note: You might not have all of the printer definitions described above, and you may have others. This is because the set of printer definitions shipped with Oracle Reports is systemspecific. See your Installation and Users Guide for details on the printer definitions you have.
Location
For more information about the location of packaged printer definition files, 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 the following:

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), you can create or modify them using any text editor. Remember to save the files as text when you are through. Then, to use the new or modified printer definition, specify it using the DESFORMAT keyword. For more information, see Referencing Printer Definitions on page B 13. To create or modify a printer definition, it is critical that you understand the required syntax of the file. Its syntax is described in the section below.
Printer Definition File Syntax

There are many printer code names (e.g., after report) that may be used to define a printer definition. Some printer code names are used for both character mode and PostScript printer definitions. Others are meaningful only for character or PostScriptbased output. The code names are listed below. The italicized words are described after the lists.
B3
Common for Character and PostScript Codes Code Name and Syntax after report gen_string Usage Is the gen_string to be sent to the printer after the report has finished printing. This code is typically used to ensure that the next print job starts on a new page of paper. Is like AFTER REPORT, only gen_string is sent before the report begins to print. Is the gen_string to be sent to the printer after each physical page (i.e., each printer page), including the last. Is the gen_string to be sent to the printer after each physical page (i.e., each printer page), except the last. Is a userdefined or Oracle Reports recognized code. See *string* below. Is the height of the report, in characters. Is the name of the printer. Is the width of the report, in characters.
before report gen_string after page gen_string
between page gen_string
code *string* gen_string height integer printer string width integer
Characterspecific Codes
Code Name and Syntax automargin
Usage Specifies that a carriage retun not be added at the end of the file when the character in the last column is not null. Specifies that a formfeed not be executed at the end of a page on which the last row is not blank. Is the string g to be used to draw the center of the h b bottom edge d of a b box ( (8). ) Is the string g to be used to draw the b bottomleft l corner of a b box ( (7). ) Is the string g to be used to draw the b h corner of a box b (9). ( ) bottomright
autopage
box bottom center gen_string i box bottom left gen_string i box bottom right g i gen_string
B4
Code Name and Syntax box center center i gen_string box center left gen_string box center right g gen_string i box horizontal gen_string box top center gen_string box top left gen_string box top right gen_string box vertical gen_string hilight backspace gen_string
Usage Is the string g to be used to draw the b (5). ( ) center of a box Is the string to be used to draw the center of the left edge of a box (4). Is the string g to be used to draw the center of the h right h edge d of a b box ( (6). ) Is the string to be used to draw the top and bottom edges of a box. Is the string to be used to draw the center of the top edge of a box (2). Is the string to be used to draw the top left corner of a box (1). Is the string to be used to draw the top right corner of a box (3). Is the string to be used to draw the left and right edges of the box. Prints a bold or underlined character by printing the character, backing up,and then reprinting the character. The backing up is done according to thegen_string (e.g., esc [0m). Simulates bold/underline by prinitng the line and then reprinting items to be bold or underlining items as appropriate. Is the gen_string to be used to make the printer print in landscape mode. Is the gen_string to be used at the end of each line of a page. Is the gen_string to be used to put the printer back at the beginning of the current line.
hilight overstrike
landscape gen_string linefeed gen_string return string gen_string
B5
PostScriptspecific Codes
Code Name and Syntax postscript where: integer gen_string
Usage Is the indicator that the printer definition file is for a PostScript printer.
Is an integer, without quotes. For character printers, is a combination of the following 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 the following, in any order, that must be surrounded by 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 bold italic font BOTTOMMARGIN, i.e., switches the bottom margin 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 the nonprintable margin MONOSPACE, i.e., switches to monospace spacing (enforce character matrix)
B6
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 be fitted on the page vertically PAGEWD, i.e., sets the number of characters to be 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 proportional spacing (dont enforce character matrix) RIGHTMARGIN, i.e., sets the width of the right margin 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
string
Is one or more alphanumeric characters, including punctuation, that must be surrounded by doublequotes. Is one of two types of code names: usercreated, and Oracle Reportsrecognized. A userdefined code name is any code that you create. A packaged code is a code name that Oracle Reports will use when you select an attribute (e.g., BOLD) from a layout objects Display Sheet dialog box.

*string*
bold off bold on bold italic underline off bold italic underline on bold underline off bold underline on
B7
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 to use a usercreated generalized string on an object, instead of a packaged string, do one of the following:

select the Printer Code tab for the layout object, then type your printer 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. 2. 3. 4. Only one printer definition may be found in each printer definition file. Codes may appear in any order; for example, the code named, HEIGHT, may be the last code in the file. Codes must be separated by spaces or returns; therefore, multiple codes may appear on the same line. New lines and spaces are treated identically; that is, if you put a return at the end of the line, the return will be interpreted as a space. Exception: When a return is placed within a string, the return is interpreted as a return. When specifying printer codes, extra spaces, capitalization, and order are ignored. For example, all of the following would be considered identical:
bold underline off bold UNDERLINE OfF Underline Bold Off
5.
B8
6.
Some operating systems may require singlequotes, instead of doublequotes for strings. Also, your printer definition file may be casesensitive. Like Version 1.1, printer codes with leading zeros are considered the same; for example, codes 001 and 1 are identical. If you enter a blank string () for the after page code, linefeeds will be inserted until a new page is started. The HILIGHT OVERSTRIKE and HILIGHT BACKSPACE codes are mutually exclusive. In addition, if a recognized printer sequence (e.g., BOLD ON or BOLD OFF) is specified in a file with the HILIGHT codes, the recognized printer sequence will take precedence.
7. 8. 9.
10. When you specify a printer definition file for DESFORMAT, Oracle Reports will search for the file as follows:

Oracle Reports looks for the file in the path specified in DESFORMAT or the current directory, if no path is specified. If the previous attempt fails, Oracle Reports appends the prt extension and looks for the file in the path specified in DESFORMAT or the current directory, if no path is specified. If the previous attempt fails, Oracle Reports looks for the file in the directory containing printer definition files shipped with Oracle Reports. For that location, see the Developer/2000 Installation Guide for your operating system. If the previous attempt fails, Oracle Reports appends the prt extension and looks for the file in the directory containing printer 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)
B9
after page return linefeed
control(L) control(J)
Example of declno3.prt:
printer dec LNO3 height width 66 80
return linefeed 10 after report control(L) after page control(L) box box box box box box box box box box box horizontal vertical top left top center top right center left center center center right bottom left bottom center bottom right | + + + + + + + + + esc [1m esc [0m
code box on code box off code bold on code bold off
code underline on esc [4m code underline off esc [0m code 500 esc [2N
Example of dec180.prt:
printer dec180 height 66
B 10
width
180
before report control(L) after report control(L) after page control(L) return linefeed code code code code control(J) esc esc esc esc [1m [0m [4m [0m
bold on bold off underline on underline off
Example of hplwide.prt:
printer hplwide height width 66 132
before report esc (s0P esc &k2S esc &17.27c66F after report control(L) after page control(L) return linefeed control(J) code bold on esc code bold off esc code underline on esc code underline off esc
(s7B (s0B &dD &d@
Example of psport85.prt: The following is a fullycommented postscript printer description file. Be aware, however, that the dashes are not supported as comment indicators. Only the percent signs (%) can be used to indicate comments in a PostScript file.
printer postscript portrait postscript height 66 width 85 return linefeed set printer type
declare this a PostScript printer height of the page in characters width of the page in characters unnecessary for PostScript unnecessary for PostScript
B 11
The following portion of the printer definition file sets up the printer by sending PostScript function calls to it.
before report PORTRAIT 12 FONTSIZE 8.5 PAPERWD 11 PAPERHT 66 PAGEHT 85 PAGEWD 0.2 LEFTMARGIN 0.2 RIGHTMARGIN 0.2 TOPMARGIN 0.2 BOTTOMMARGIN NORMAL
%% %% %% %% %% %% %% %% %% %% %%
set portrait mode pick a suitable font size 8.5 x 11 paper size each page is 80 x 66 leave small border
set up normal Courier font
after report unnecessary for PostScript after page unnecessary for PostScript
The following codes are box character mappings used by Oracle Reports for line drawing. Do not modify them.
box box box box box box box box box box box horizontal vertical top left top center top right center left center center center right bottom left bottom center bottom right a b c d e f g h i j k
B 12
The following section sets up the postscript printer codes. These are much like other printer codes except that they are plain text codes. The codes are inserted directly into the PostScript output stream.
code box on code box off code bold on code bold off BOX NORMAL BOLD NORMAL
code underline on UNDERLINE code underline off UNDERLINESTOP code italic on code italic off OBLIQUE NORMAL BOLDOBLIQUE NORMAL BOLD UNDERLINE NORMAL UNDERLINESTOP OBLIQUE UNDERLINE NORMAL UNDERLINESTOP BOLDOBLIQUE UNDERLINE NORMAL UNDERLINESTOP
code bold italic on code bold italic off
code bold underline on code bold underline off
code italic underline on code italic underline off
code bold italic underline on code bold italic underline off
code 1 PROPORTIONAL /TimesBold 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 to know what the following keywords mean: DESTYPE, DESNAME, and DESFORMAT. DESTYPE is the type of device to which the report output will be sent (e.g., a printer). DESNAME is name of the device to which the report will be output (e.g., myprinter). DESFORMAT is the file name that contains the printer definition you want to use.
B 13
You can specify arguments for the aforementioned keywords in three places: the command line, Parameter Form property sheet, and the Runtime Parameter Form. Examples of how to do so are below. The examples assume that your printers name is HQFLOOR1, and your new printer definition file is named NEWDEF. Command Line Example Parameter Properties Runtime Parameter Form Name DESTYPE DESNAME DESFORMAT Value printer HQFLOOR1 newdef
R25DES MYNAME/MYPASS DESTYPE=PRINTER DESNAME=HQFLOOR1 DESFORMAT=NEWDEF
Purpose of Terminal Resources

Terminal resources are a collection of related data that specify your terminals capabilities. They contain terminal definitions to describe the attributes of different terminals (e.g., screen width and height, graphics capabilities, etc.) to Oracle Reports. In addition, terminal resources associate application functions with specific terminal keys, using what are known as key bindings. These resources are stored in terminal resource files.
Packaged Terminal Resource Files

This section is divided into two parts: a description of some the terminal resource files shipped with Oracle Reports, and the location of the terminal resource files. You need to know the following about packaged terminal resource files:

descriptions B 15 location B 15
B 14
Descriptions
Oracle Reports is shipped with several terminal resource files, some of which are described below: dflt.res Is a generic resource file that provides a minimum of key bindings and resources. It is used if no resource file is specified at invocation of Oracle Reports. Is a resource file that contains the definition and key bindings for a Sun4 terminal. Is a resource file that contains the definition and key bindings for Sun10 terminal. Is a resource file that contains the definition and key bindings for a VT100 terminal. Is a resource file that contains the definition and key bindings for a VT220 terminal. Is a resource file that contains the definition and key bindings for a VT320 terminal.
sun4.res sun10.res vt100.res vt220.res vt320.res
Note: You might not have all of the terminal resource files described above, and you may have others. This is because the set of terminal resource files shipped with Oracle Reports is systemspecific. See your Developer/2000 Installation Guide for details on the terminal resource files you have. Location For more information about the location of packaged terminal definition files, see the Developer/2000 Installation Guide for your operating system.
Creating or Modifying Terminal Resources

Resource files for Oracle Reports are created and maintained using a tool called Oracle Terminal. In order to modify your terminal resource files, you need access to the Oracle Terminal resource editor ot.
B 15
You can only use the Oracle Terminal resource editor to configure terminal resources for an application if the application was built with Oracle Terminal support. For Oracle Reports, this means you cannot configure terminal resources for the bitmapped version. In addition, the charactermode resources you can configure are restricted to the following:

key bindings terminal definitions
You cannot change the appearance of the runtime interface (dialog boxes, etc.) We recommend that when you modify terminal resources for character mode terminals, you use the charactermode ot executable, as described below. Although you can edit resources for any platform on any platform, you must generate key bindings on the platform for which they will be used. Since youll be using charactermode executables, you need to know the charactermode notational convention for representing function keys. Function keys for both Oracle Reports and Oracle Terminal are represented by the name of the function enclosed in square brackets (e.g., [Next Page]). You can refer to a keypad diagram or the Show Keys screen (accessible through Help) for a mapping of these function keys to physical keys on your keyboard. Note: It is beyond the scope of this documentation to exhaustively cover Oracle Terminals capabilities. Nor can we provide a tutorial for Oracle Terminal. Be aware that this discussion is limited to the aspects of Oracle Terminal that relate to Oracle Reports. In addition, the following examples do not include certain tasks, such as adding devices to the list of devices recognized by Oracle Reports, that can more properly be considered administrative in nature. For more information on Oracle Terminal and the different types of resources you can edit with it, see your Oracle Terminal Users Guide. Oracle Terminal replaces the SQL*ReportWriter V1.1 utility TERMDEF.
B 16
Modifying Key Bindings
You can modify key bindingsthe designations that attach certain keys to certain functionsbut Oracle Reports defines the functions to which you can bind keys. Steps to Modify Key Bindings Use your operating system copy command to copy the resource file containing the key bindings you want to modify, and save the file under a unique name. (You are generally not allowed writeaccess to files used by Oracle Reports; this will 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 to modify. Note: You can also include the name of the resource file in your commandline 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 information necessary to precisely locate the resource file. The ot Main Window The resource editors main window appears. Use this window to choose the product (e.g., Oracle Reports), the device, 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 values appears, displaying all the products whose resources you can modify using ot. Select Oracle Reports from the list. Press [Next Field] until the cursor is positioned at the field next to Device. Press [List]. A list of values appears, displaying the names of all the terminals with available terminal resource files. Select your terminal type from this list. Press [Invoke Menu] to access the main menu, then select Function>Edit Keys.
4.
5.
The Key Binding Editor The ot key binding editor is displayed. Using this editor, you can change any key binding for your application.
B 17
6.
Select a component by pressing [Next Field] until you reach the Component list, then pressing [Select] with the cursor positioned on the component you want to modify. Note: If a component has further subcomponents, pressing [Select] will not select the component. Instead, it will cause the next lower level in the hierarchy of components to be displayed in the component list. A component in this case represents a part of Oracle Reportseither a location, such as the Runtime Parameter Form or the Previewer, or a class of actions, such as navigationfor which a grouping of key bindings is valid. Global key bindings are valid from anywhere in the runtime engine. Common key bindings are valid 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 key binding definition table. This table shows all the actions that are a part of 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 to change. Replace the name of the key to which the action is currently bound with the name of the key you want to use. Once you have made the desired changes, select OK. The main window is displayed. Here you can apply or cancel your modifications, as desired. If you wish to cancel your modifications, press [Invoke Menu], then select File>Close, or File>Quit, and do 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 your resource file. Instead, you have saved the changes you want to make to the resource file. To actually incorporate the new key bindings 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 you made to the key binding.
9.
B 18
An alert appears, telling you that your resources file has been successfully generated. Accept the alert. Note: If you receive an error message instead, consult your Oracle Terminal Users Guide. 12. Press [Invoke Menu], then select File>Save. Though you seem to be duplicating step 11, you are actually saving a very different file in this step. You are saving the resource file, and can now use it to determine the key bindings your terminal uses 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 Oracle Reports charactermode runtime engine and display the Show Keys screen. 14. Enter the following on the command line, once again including all necessary path information:
r25run term=resfile
In the command above, the argument term=resfile serves two purposes: it tells Oracle Reports which terminal resource file you want to use, and this, in turn, identifies your terminal to Oracle Reports. In order to use the new key bindings you just created, the resfile portion of the argument must refer to the resource file you just 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. They should reflect the changes you made to the key bindings.
Modifying Terminal Definitions
Terminal definition file contain information about the capabilities of different terminal types. They apply only to charactermode and blockmode terminals, and any terminals emulating such devices. Oracle Reports ships several terminal definition files for such standard terminals as the DEC family of VT100, VT220, and VT320 terminals. If necessary, you can modify any one of these to provide a definition for a nonstandard terminal. Terminal definitions, unlike key bindings, describe a terminals intrinsic capabilities. Therefore, the following steps show where and how to change terminal definition, but make no actual changes. We recommend that you do not change the terminal definition unless you are creating a new definition for a nonstandard terminal and are provided with all necessary specifications by your terminals documentation.
B 19
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 resource file. Once in the main window, specify Oracle Reports as the product. For information on how to do this, see The ot Main Window on page B 17. Then press [Invoke Menu] and select Function>Edit Devices....
2.
The Device Class Editor The device class editor is displayed. The device class editor displays all devices included in the specified product (in this case, Oracle Reports). It also shows all ancestor classes of the devices (i.e., for a VT220 terminal, an ancestor class might be character mode). Use this editor to select the specific device whose terminal definition you want to modify. If you need to add a definition for a nonstandard terminal, it is generally easier to select a similar terminal and modify its terminal definition, then save the modifications under 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 not appear, your terminal may be on a lower level in the device hierarchy. To the right of the class list is a graphical representation of the device hierarchy. Use this to trace your terminals ancestry. When you find its ancestor, position the cursor on that device in the class list and press [Accept]. Follow the class levels down until the designation for your terminal appears in the class list. Position the cursor on the terminal name and press [Select]. 4. Edit Device... is highlighted. Press [Next Field] until the cursor is located on the Edit Device button, then press [Accept].
The Device Display Definition Screen The device display definition screen is shown. This is a list of device characteristics that Oracle Reports refers to when communicating with your terminal. Change any of these values by pressing [Next Field] until the cursor is located at the appropriate field and entering the desired value. The buttons, Attributes..., Modifiers..., Standard Keys..., and User Keys... lead to further dialogs that enable you to modify other aspects of the terminal definition. See your Oracle Terminal Users Guide for more information on these dialogs.
B 20
Unless you specifically intend to create a new terminal definition file for a nonstandard terminal, do not change any of these values. They are fixed according to device, and not userdefinable. If you are creating a new terminal definition file for a nonstandard terminal, refer to the documentation for your terminal for the proper values to use. 5. When you are finished modifying the file, press [Invoke Menu] and select Windows, then select the main window, which is identified by the name of the resource file you are editing. Exit out of Oracle Terminal without saving, or save, generate, and save your resource file. For more information on saving, see Saving Your Modifications on page B 18. In this case, however, you may wish to use Save As... so you do not overwrite the original file.
Terminal Definition Rules

1. Some operating systems may require singlequotes, instead of doublequotes for strings. Also, your terminal resource file may be casesensitive. See your Installation and Users Guide for details. When you specify a terminal resource file, Oracle Reports will search for the file first in the path specified, then in the current directory, if no path is specified, and finally in the directory allocated by Oracle Reports for the terminal resource files. The location of this directory is installationspecific. For more information about the location of files, see the Developer/2000 Installation Guide for your operating system.
2.
Referencing Terminal Resource Files

To use a terminal resource file other than the default, specify it with the term keyword on the command line when you invoke the charactermode runtime executable, as follows:
R25RUN MYNAME/MYPASS TERM=VT220
Make sure to specify all necessary path information.
B 21
B 22
APPENDIX
National Language Support

W ith National Language Support (NLS), you can do the following:

specify the language in which the Oracle Reports executables should display and accept input create modules that can be translated easily specify the language in which to run a Oracle Reports module, so that its result (output) is in the language you specifyeven if the data in ORACLE is in a different language, and even if the module 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
C1
Definition and Purpose of NLS

NLS is a product of Oracle Corporation, which enables you to interact with its products, such as Oracle Reports and ORACLE, in your native language. NLS provides support for the following:
processing data in the various character encoding schemes used by computer hardware it supports both singlebyte and multibyte character encoding schemes it supports the client and server using different character encoding schemes, and transparently converts data between them
operating languagedependent Oracle Tools it displays error messages and hints in multiple languages it formats dates and numbers using language and territory conventions it sorts character data according to alphabetic conventions it enables you to specify languagedependent operations for each session
designing a module (e.g., a report) that runs in multiple languages
Specifying NLS_LANG, DEV_NLS_LANG, and USER_NLS_LANG

NLS_LANG is an environment variable. If you want to use any NLS feature, you must set this environment variable so that Oracle Reports can locate the NLS components. Define NLS_LANG in the same fashion you define other environment variables on your base operating system, keeping in mind such platformspecific rules as path length, etc.. For the purposes of bidirectional support, you can also set the following environment variables:

DEV_NLS_LANG specifies the language for the Oracle Reports designer. USER_NLS_LANG specifies the language for Oracle Reports runtime.
C2
Overriding NLS Defaults

This section describes how you can override NLS defaults by doing the following:

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
Using ALTER SESSION
You can use the ALTER SESSION SQL command, to override the NLS defaults. An ideal place to do this is in the After Form trigger. For example, suppose you create some parameters (such as language, territory, etc.), and a user specifies values for them on the Runtime Parameter Form: you could then alter the session as they specified. Caution: If NLS_LANG is not defined, an ALTER SESSION statement is not executed. As a reminder, you can specify the following NLS parameters for the ALTER SESSION command: Parameter NLS_LANGUAGE NLS_TERRITORY NLS_DATE_FORMAT NLS_DATE_LANGUAGE NLS_NUMERIC_ CHARACTERS NLS_ISO_CURRENCY NLS_CURRENCY NLS_SORT Description language used by ORACLE to return messages and errors territory used for default date and currency masks default format used for dates default language used for dates decimal character and group separator ISO international currency symbol local currency symbol character sort sequence
For details on these parameters, see the ORACLE7 SQL Language Reference Manual.
C3
Using Date and Number Formats
The following formats are meaningful for NLS:
Date Element D DY DAY WW IW MON MONTH RM I, IY, IYY, IYYY BC, AD, B.C., A.D. AM, PM., A.M., P.M.
What Is Returned digit for the day (17) name of the day (abbreviated) name of the day (padded with blanks to length of 9 characters) digit for the week, calculated by the algorithm int((dayjan1)/7) digit(s) of the ISO week name of the month (abbreviated) name of the month (padded with blanks to the length of 9 characters) character for the Roman numeral month last 1, 2, or 3 digit(s) of the ISO year BC or AD indicator (with or without periods) AM or PM indicator (with or without periods)
For more information on ISO and its date format masks, see the ORACLE7 SQL Language Reference Manual. Number Element D G L C What Is Returned character that separates the integer and decimal portions of a number character that separates groups in the integer portion of a number local currency symbol ISO currency symbol
C4
Using NLS Parameters/Functions in SQL Functions
Wherever you use SQL, you can use the following NLS parameters to override default NLS behavior. SQL Function TO_DATE TO_NUMBER NLS Parameter NLS_DATE_LANGUAGE NLS_NUMERIC_CHARACTERS, NLS_CURRENCY, NLS_ISO_CURRENCY TO_CHAR NLS_DATE_LANGUAGE, NLS_NUMERIC_CHARACTERS, NLS_CURRENCY, NLS_ISO_CURRENCY NLS_UPPER NLS_LOWER NLS_INITCAP NLSSORT NLS_SORT NLS_SORT NLS_SORT NLS_SORT
For details on these parameters, see the ORACLE7 SQL Language Reference Manual.
Using CONVERT to Convert Data
You can use the SQL function CONVERT to sort convert data. This function converts the binary representation of a character string in one character set to another. For a complete description of CONVERT, see the ORACLE7 SQL Language Reference Manual. You can use the SQL function NLSSORT to sort character data. This function replaces a character string with the equivalent sort string used by the sort mechanism. For a binary sort, the sort string is the same as the input string. The linguistic sort technique operates by replacing each character string with some other binary values, chosen so that sorting the resulting string produces the desired sorting sequence. When a linguistic sort is being used, NLSSORT returns the binary values used to replace the original string. This section covers the following:

Using NLSSORT to Sort Character Data
comparing strings in a WHERE clause controlling an ORDER BY clause
C5
Comparing Strings in a WHERE Clause
Character strings in a WHERE clause are compared using the characters binary values: a character is greater than another if it has a higher binary value in the database character set. Because the sequence of characters based on their binary values may not match the alphabetic sequence for a language, the comparisons often do not follow alphabetic conventions. Examples: Suppose you have a column (COL1) that contains the values ABC, ABZ, BCD and A umlaut BC in the ISO 8859/1 8bit character set. 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 higher numeric value than B. As a result, you can perform linguistic comparisons using NLSSORT in the WHERE clause, as follows:
WHERE NLSSORT(column) operator NLSSORT(string)
Notice that NLSSORT has to be used on both sides of the comparison operator. Examples:
SELECT COL1 FROM TAB1 WHERE NLSSORT(COL1) > NLSSORT(B)
If a German linguistic sort is being used, this will not return strings beginning with A umlaut, because A umlaut comes before B in the German alphabet. If a Swedish linguistic sort is being used, those strings would be returned, because A umlaut comes after Z in the Swedish alphabet. Controlling an ORDER BY If a linguistic sorting sequence is in use, then NLSSORT is implicitly Clause used on each character item in the ORDER BY clause. As a result, the sort mechanism (linguistic or binary) used for an ORDER BY is transparent to the application. However, if the NLSSORT function is explicitly specified for a character item in an ORDER BY item, then the implicit NLSSORT is not done. In other words, the NLSSORT linguistic replacement is only applied once, not twice.
C6
The NLSSORT function is generally not needed in an ORDER BY clause, 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 example below) 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, so that you can translate them. If your report is stored in an .rdf file, the strings are in ui_strings. If your report is stored in the database, the strings are in a public synonym called ROSSTRINGS. After the strings are translated, the report will run normally, unless the translated strings occupy more space than before they were translated. If they do, and layout objects are Fixed or Contracting, the strings may be truncated, or overflow to the next page. (Recall that text and data overflow; images and graphics are truncated if their layout object is Fixed or Contracting and is smaller than what it is trying to format.) Translation tools will be available with NLS*Workbench to assist the translation of applications. For a complete description of the NLS*WorkBench and its features, refer to the NLS*WorkBench Reference Guide.
C7
Printer Definitions and NLS

When using NLS in character mode, you should define the physical page width of the report as one character less than the page width defined in the printer definition. Otherwise, multibyte characters might start on the last character space of a line and have to overflow to the next line in order to complete. For example, if the physical page width is 80 characters and the width in the printer definition is 80 characters, a multibyte character might start on the 80th character. Since multibyte characters may not be separated, the line would have to overflow to an 81st character in order to complete the multibyte character. To avoid this, the physical page width should be set to 79 for the report.
Bidirectional Support
NLS support for MiddleEastern and North African languages includes bidirectional support for languages whose natural writing direction is righttoleft. Bidirectional support allows developers to control:
layout direction, which includes displaying items with labels at the right of the item and correct placement of check boxes and radio buttons reading order, which includes righttoleft (RTL) or lefttoright (LTR) text direction alignment, which includes switching pointoforigin from upper left to upper right
In addition to the NLS_LANG environment variable, bidirectional applications may use two additional NLS_LANG environment variables:

DEVELOPER_NLS_LANG USER_NLS_LANG
Four properties are used to specify the appearance of objects in bidirectional applications:

Align Direction (for an object) Direction (for the report)
C8
The bidirectional properties are added to objects in the following hierarchy:

Module Boilerplate Field External Boilerplate Button Parameter Form Biolerplate
Objects not in this list either do not require bidirectional support (e.g., images) or they are automatically defaulted from one of the above objects properties.
C9
C 10
APPENDIX
Naming Conventions
hen working with modules and reportlevel objects in Oracle W Reports, you must follow certain naming conventions. You should know the naming conventions for the following:

modules D 2 data model objects D 2 layout objects D 3 parameter form objects D 3
Naming Conventions
D1
Module Naming Conventions

When working with modules, you must follow certain naming conventions. The conventions you follow depend upon whether the module is stored in the database or an operating system file.
Database Objects
The naming conventions for Oracle Reports modules stored in the database are similar to the SQL naming standards. Specifically, module names:

can be up to 30 bytes long must begin with a letter are not casesensitive 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)
Files
When naming objects that are stored in operating system files, you must follow the naming conventions for database objects (see previous section) plus the file naming conventions of your operating system. If you are saving an object as an operating system file, it is stored in ASCII 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 the SQL naming standards. Specifically, data model object names:

can be up to 30 bytes long must begin with a letter are not casesensitive can contain letters, numbers, and the special characters $, #, @, and _ cannot duplicate the name of another data model object of the same type in the same report
D2
Parameter Name Restrictions
In addition to the above data model object naming conventions, parameter names must not be the same as any Oracle Reports object name or R25RUN command line keywords. For more information on the 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 SQL naming standards. Specifically, layout object names:

can be up to 30 bytes long must begin with a letter are not casesensitive can contain letters, numbers, and the special characters $, #, @, and _ cannot duplicate the name of another layout object of the same type in the same report
Parameter Form Object Naming Conventions

When working with parameter form objects, you must follow certain naming conventions. The naming conventions are the same as the SQL naming standards. Specifically, parameter form object names:

can be up to 30 bytes long must begin with a letter are not casesensitive can contain letters, numbers, and the special characters $, #, @, and _ cannot duplicate the name of another parameter form object of the same type in the same report
Naming Conventions
D3
D4
APPENDIX
SQL Topics
o make creating and maintaining external and reportlevel queries easier, 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 Definition Language (DDL) E 9
For more information on SQL, see the ORACLE7 Server SQL Language Reference Manual.
SQL Topics
E1
Using the Tables and Columns Dialog Box

To make building a SELECT statement for your external or reportlevel query, you can select Tables/Columns from the Tools menu. This displays the Tables and Columns dialog box. From this dialog box, you can construct a SELECT statement without writing any SQL yourself.
Using Aliases
You can use aliases in your query SELECT statement as you would in any other SELECT statement. For more information on aliases, see the ORACLE7 Server SQL Language Reference Manual. If you use an alias for a column, that alias becomes the name of the column in Oracle Reports. Aliases and Parameters When using an alias in conjunction with a parameter, you must be cautious about changing the column associated with the alias. For example, suppose you created the following SELECT statement for your query:
SELECT &NAME NAME, &PAY PAY FROM EMP
Assume that when you initially build the report, &NAME is the name of a CHAR column and &PAY is the name of a NUMBER column. If at runtime you enter the name of a column for the &NAME parameter that is not a CHAR column, you will get an error. Because the name of the alias is unchanged, Oracle Reports assumes that the column has the same datatype as when you built the report (i.e., CHAR).
Inserting Comments
You can insert comments directly into your SELECT statement using Oracles 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 Query property sheet to enter comments.
E2
Reviewing SELECT Statement Errors

The SELECT statement for an external or reportlevel query is parsed when you accept or attempt to perform an operation that would close the property sheet. If you have made a SQL error, an error message is displayed in a dialog box. A pointer (==>) will appear in the error message at the point where the error occurred. After you accept the error message, your cursor will be placed at the error.
Referencing Columns and Parameters

In SQL or PL/SQL, you can reference Oracle Reports columns and parameters. When you run the report, the values of the Oracle Reports columns and parameters are substituted for their references in the SQL or 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 to specify an Initial Value or Value If Null for the parameter or column, respectively, if the query will not parse correctly without the value. For example, a query must have a FROM clause. If you create a query that uses a lexical reference for the FROM clause, the parameter corresponding to the lexical reference must have an Initial Value (e.g., EMP) so that the SELECT statement is valid. Parameters with a Datatype of Character are not padded, unless you explicitly pad them in a SQL statement. If an Oracle Reports column is a summary with a Reset At setting of Page, the column cannot be referenced (via bind or lexical reference) in a query. For example, if AVG_SAL is a summary column that computes the average salary for each page of your report, the following bind reference would be invalid:
SELECT SAL FROM EMP WHERE SAL > :AVG_SAL
2. 3.
SQL Topics
E3
4.
A query can only contain references to columns with a Type of Database belonging to a group above the query (i.e., a group that is a parent or an ancestor of the query). For example, suppose group G_1 contains a database column named SAL and belongs to query Q_1. Group G_1 owns another query named Q_2. You could reference SAL in Q_2 but not in Q_1. A query can only contain references to a summary or formula column whose source column is below the query. For example, suppose you create a summary column named SUM_SAL in group G_1. SUM_SAL summarizes the column named SAL, which is also in group G_1. G_1 belongs to query Q_1 and owns another query named Q_2. Therefore, query Q_1 can contain a reference to SUM_SAL, but query Q_2 cannot contain such a reference. If a reference is made to a parameter with a Datatype of Date is used in an expression, a TO_DATE function should be used.
5.
6.
Bind References
Bind references are used to replace a single value in SQL or PL/SQL, such as a character string, number, or date. Specifically, bind references may be used to replace expressions in SELECT, WHERE, GROUP BY, ORDER BY, HAVING, CONNECT BY, and START WITH clauses of queries. Bind references may not be referenced in FROM clauses or in place of reserved words or clauses. You create a bind reference by entering a colon (:) followed immediately by the column or parameter name. If you do not create a column or parameter before making a bind reference to it in a SELECT statement, Oracle Reports will create a parameter for you by default. Rules: 1. Bind references must not be the same name as any reserved SQL keywords. For more information, see the ORACLE7 Server SQL Language Reference Manual.
Following are some examples of bind references: SELECT Clause

SELECT CUSTID, NVL(COMMPLAN, :DFLTCOMM) COMMPLAN FROM ORD
The value of DFLTCOMM replaces null values of COMMPLAN in the rows selected. WHERE Clause
SELECT ORDID, TOTAL FROM ORD WHERE CUSTID = :CUST
The value of CUST is used to select a single customer.
E4
GROUP BY Clause
SELECT NVL(COMMPLAN, :DFLTCOMM) COMMPLAN, SUM(TOTAL) TOTAL FROM ORD GROUP BY NVL(COMMPLAN, :DFLTCOMM)
All nonaggregate expressions such as NVL(COMMPLAN, :DFLTCOMM) in the SELECT clause must be replicated in the GROUP BY clause. HAVING 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 minimum total of orders. ORDER BY Clause
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 as the 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 of an expression in the SELECT list. CONNECT BY and START WITH Clauses References in CONNECT BY and START WITH clauses are used in the same way as they are in the WHERE and HAVING clauses.
PL/SQL
procedure double is begin; :my_param := :my_param*2; end;
The value of myparam is multiplied by two and assigned to myparam.
Lexical References
Lexical references are placeholders for text that you embed in a SELECT statement. You can use lexical references to replace the clauses appearing 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 a parameter that is then referenced lexically in SQL. Look at the example below.
SQL Topics
E5
You create a lexical reference by entering an ampersand (&) followed immediately by the column or parameter name. A default definition is not provided for lexical references. Therefore, you must do the following:
Before you create your query, define a column or parameter in the data model for each lexical reference in the query. For columns, you must enter Value if Null, and, for parameters, you must enter Initial Value. Oracle Reports uses these values to validate a query with a lexical reference. Create your query containing lexical references.
Rules: 1. 2. 3. You cannot make lexical references in a PL/SQL statement. If a column or parameter is used as a lexical reference in a query, its Datatype must be Character. If you want to use lexical references in your SELECT clause, you should 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 label for whatever value you enter for the lexical on the Runtime Parameter Form. See the example below. If you use lexical references in your SELECT clause, you must specify the same number of items at runtime as were specified in the reports data model. In addition, each value you specify for your lexical references at runtime must have the same datatype as its Initial Value. Look at the example below. An Oracle Reports link should not depend upon a lexical reference. That is, neither the child column of a link or its table name should be determined by a lexical reference. To achieve this functionality, you need to create a link with no columns specified and then enter the SQL clause (e.g., WHERE) for the link directly in the query. For example, your parent and child queries might be written as follows:
Parent Query: Child Query: SELECT DEPTNO FROM EMP SELECT &PARM_1 COL_1, &PARM2 COL_2 FROM EMP WHERE &PARM_1 = :DEPTNO
4.
5.
Note how the WHERE clause makes a bind reference to DEPTNO, which was selected in the parent query. Also, this example assumes that you have created a link between the queries in the Data Model editor with no columns specified.
E6
6.
A lexical reference cannot be used to create additional bind variables after the After Form trigger fires. For example, suppose you have a query like the following (note that the WHERE clause is replaced by a lexical reference):
SELECT ENAME, SAL FROM EMP &where_clause
If the value of the WHERE_CLAUSE parameter contains a reference to a bind variable, you must specify the value in the After Form trigger or earlier. You would get an error if you supplied the following 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 report would run. Following are some examples of lexical references: SELECT Clause
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 columns selected at runtime. For example, you could enter DEPTNO as the value for P_EMPNO on the Runtime Parameter Form. Note that in this case,
you should use aliases for your columns. Otherwise, if you change the columns selected at runtime, the column names in the SELECT list will not match the Oracle Reports columns and the report will not run. FROM Clause
SELECT ORDID, TOTAL FROM &ATABLE ATABLE can be used to change the table from which columns are selected at runtime. For example, you could enter ORD for ATABLE at
runtime. If you dynamically change the table name in this way, you may also want to use lexical references for the SELECT clause (look at the previous example) in case the column names differ between tables. WHERE Clause
SELECT ORDID, TOTAL FROM ORD WHERE &CUST CUST can be used to restrict records retrieved from ORD. Any form of
the WHERE clause can be specified at runtime. GROUP BY Clause

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.
SQL Topics
E7
HAVING Clause
SELECT CUSTID, SUM(TOTAL) TOTAL FROM ORD GROUP BY CUSTID HAVING &MINTOTAL
The value of MINTOTAL could, for example, be used to select customers with a minimum total of orders. ORDER BY Clause
SELECT ORDID, SHIPDATE, ORDERDATE, TOTAL FROM ORD ORDER BY &SORT
The value of SORT can be used to select SHIPDATE, ORDERDATE, ORDID, or any combination as the sort criterion. It could also be used to add on to the query, for example to add a CONNECT BY and START WITH clause. CONNECT BY and START WITH Clauses Multiple Clauses Parameters in CONNECT BY and START WITH clauses are used in the same way as they are in the WHERE and HAVING clauses.
SELECT &COLSTABLE COLSTABLE could be used to change both the SELECT and FROM clauses 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 BY
clauses at runtime. For example, you could enter WHERE SAL > 1000 ORDER BY DEPTNO for &WHEREORD at runtime. PL/SQL and SQL
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 BY clause at runtime. The Initial Value of the parameter &BREAK_COL is
JOB. At runtime, the user of the report can provide a value for a parameter called GROUP_BY_COLUMN (of Datatype Character). In the Validation Trigger for GROUP_BY_COLUMN, you call the following PL/SQL procedure and pass it the value of GROUP_BY_COLUMN:
E8
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 around the break column the user chooses. Notice how in SQL, you make a lexical reference to BREAK_COL. In PL/SQL, you must make a bind reference to BREAK_COL because lexical references are not allowed in PL/SQL.
Using DML or DDL

If you want to use DML or DDL in your PL/SQL, you should use the SRW.DO_SQL packaged function. Note that SRW.DO_SQL should only 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 and DDL, see the ORACLE7 Server SQL Language Reference Manual. Because of Oracle Reports processing model, it is recommended that you only use DDL in the Before Report and After Report triggers. For more information on these report triggers, see Trigger Properties on page 13 17. DML can be entered from any field that takes PL/SQL. Note: The use of SRW.DO_SQL adds some overhead to the running of the report.
SQL Topics
E9
E 10
APPENDIX
Pattern and Color Palette

O racle Reports is shipped with the following palettes:

pattern F 2 color F 4
F1
Pattern Palette
This section describes the Oracle Reports pattern palette. A sample of each pattern in the palette, along with its name, appears below:
F2
F3
Color Palettes
Oracle Reports is shipped with the following types of color palettes:

default color palette supplemental color palette
Default Color Palette
The default color palette is the one Oracle Reports uses if you do not specify another one in your preferences. The color palette file is named vgid.ros. For more information about the location of this file on your system, see the Developer/2000 Installation Guide for your operating system. The default color palette is defined by the following rules: 1. The upperleft region of the palette contains 16 commonly used colors with the following names:
black gray red yellow white darkgray darkred darkyellow green cyan blue magenta darkgreen darkcyan darkblue darkmagenta
2. 3.
The lowerleft region of the palette contains eight empty cells into which you can place custom defined colors. The next five columns are composed of varying shades of gray. Each color is named gray<value>, according to its percentage gray value. The values range from 4 to 96, in increments of 4. For example, valid color names include gray96, gray92, and gray4. The remainder of the palette contains colors specified by varying percentages 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 its RGB 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 is composed of five major regions, each containing 36 colors in a 6x6 arrangement. These colors are defined by the following rules:
4.
F4
The red value increases as the colors progress from left to right within each major region. The green value increases as the colors progress from top to bottom within each major region. The blue value increases as the major regions progress from left to right, with all of the colors in a single region using the same blue value.
Supplemental Color Palette
Oracle Reports is shipped with the following color palettes that you can import into a display, or specify in the Tools Options dialog, thus overriding the default color palette:

grayscale color palette Oracle CDE1 color palette
For more information about the location of these color palette files, see the Developer/2000 Installation Guide for your operating system. Grayscale The grayscale color palette is composed entirely of varying shades of gray. It is defined by the following rules: 1. 2. The first two colors are named black and white. The remainder of the palette contains colors specified by varying percentages of gray. Each color is named gray<value>, according to 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 the leftmost cell in the next), the gray value for each color is .5 less than the one before it. After gray12.5, the gray value for each color is .25 less than the one before it. The gray values continue to decrease to the last color in the palette, named gray0.
F5
Oracle CDE1
The Oracle CDE1 color palette was the default color palette in Oracle Reports 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 varying percentages of red, green, and blue (RGB) components. The percentage value for each component is: 0, 40, 55, 70, 85, or 100. Each color is named r<value>g<value>b<value>, according to its RGB 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 six major 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 to right within each major region. The green value increases as the colors progress from top to bottom within each major region. The blue value increases as the major regions progress from left to right, with all of the colors in a single region using the same blue value.
F6
Glossary
A
alert An interface element that notifies you of a condition that occurred because of your last action. You must respond to an alert. alias A secondary name used in a SQL statement to reference a table, view, or column. alignment (Field Properties) The method used to position data within a field; i.e., to the left, right, center, flush/left, flush/right, or flush/center of the defined width of a field. ancestor group A group that owns another group, either directly or indirectly. anchor A layout object used to fix a spot on one object to a spot on another object, ensuring the position of the first object in relation to the second object. anchored object The object, known as the child object, which is anchored or attached to another object, known as the parent object. anchoring object The object, known as the parent object, to which another object, known as the child object, is anchored or attached. argument 1. An expression within the parentheses of a function, supplying a value for the function to operate on. For example, in the expression f(x), x is the argument. 2. Clauses containing Oracle Reports executable keywords and their specified values. For example, DESTYPE=FILE is an argument. Arrange menu The menu with which you organize the graphical objects in the editor and specify attributes for the editor components. ASCII Acronym for American National Standard Code for Information Interchange. attribute See setting.
B
bind 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 a SELECT statement.
Glossary 1
body A report region that contains the bulk of the report layout (text, graphics, data, and computations). The report body appears between the report header and trailer pages. boilerplate Text and/or graphics that appear in a report every time it is run. In some products this is called constant text or graphics. border A userdefined outline around a layout object, usually used to highlight its contents. Oracle Reports draws borders such that half the width of the border lies outside the edge of the object, and half inside the edge, as shown below. See also edge.
button 1. An interface element used to select an action item, display a dialog box, or acknowledge the current condition. 2. A usercreated layout object that only appears in the Previewer, and, when pressed, executes a userspecified action.
C
call interface An interface that enables you to invoke Oracle Reports executables from other Oracle products, such as Oracle Forms, or a userwritten 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 or copy another object, or until you quit Oracle Reports. CMDFILE An argument that allows you to specify a file that contains a set of arguments for R25DES or R25RUN. column 1. A data model object created automatically for each column expression in a querys SELECT list, or created manually to perform summaries, formulas, or act as a placeholder. 2. A vertical list of data contained in a database table. A column has a column name and a specific data type. column expression An expression in a SELECT statement that defines which database column(s) are retrieved. It may be a column name or a valid SQL expression referencing a column name.
break column A column assigned to a break group. break group A group used to categorize, or break, the records contained in a report into sets. It does this by establishing a hierarchy for the fetched data. All data in columns belonging to a break group are above the data in columns belonging to other groups. This causes each record fetched for a break group, to only display once, while multiple related records in other groups can be displayed. break order (Column Properties) A setting that indicates the order in which to display a break columns data. Valid options are Ascending and Descending. break report A report containing a break group.
Glossary 2
column heading See label. command line An operatingsystem command line. Oracle Reports can be invoked from a command line using a number of parameters. Not found on all platforms. comment A multiline field in which you can enter explanatory information about an Oracle Reports object. commit To make changes to data (INSERTs, UPDATEs, DELETEs) in the database permanent. Before changes are stored, both the old and new data exist so that changes can be stored or the data can be restored to its prior state. compile To translate a PL/SQL construct into binary, executable format. In Oracle Reports, PL/SQL constructs must be compiled before they are executed. computation (Column Properties) A setting used to perform runtime calculations on data fetched from the database. These calculations are a superset of the kinds of calculations that can be done directly with a SELECT statement. See also formula column, summary column. computed column See computation. condition (Query/Link Properties) An operator that defines the parent querys relationship to the child query in a parentchild relationship. Confine mode Layout editor mode that prevents child objects from being moved or resized on or outside their parent objects. connect To log on to a database. You must connect if you want to create or modify queries or run a report. construct A PL/SQL code structure. There are two types of constructs: nonvalue constructs do not return a value; value constructs return a value.
coordinates (x,y) The location points for objects appearing in an editor. x and y coordinates determine the horizontal (X) and vertical (Y) placement of layout objects. copy To store a replica of a selected object in the Clipboard, so that it may be pasted elsewhere in an editor if desired. cross product Group that owns two or more other groups and performs a mathematical cross product (i.e., correlates values between them). crosstab See matrix cell. cursor 1. A small icon representing the mouse pointer. The shape of the cursor will vary, depending on the tool you have selected in the designer. 2. A work area in which ORACLE stores the current SQL statement, and if the statement is a query, the results column headings and one row of the result. cut To delete one or more Oracle Reports objects and store them in the Clipboard, so that they may be pasted elsewhere in an editor if desired.
D
Datatype (Column and Field Properties) A setting that specifies the type of data contained in a column, parameter, or field. May be Character, Number, Date, Long, Long Raw, or Raw. data model A relational model that defines what data should be fetched from the database, what values should be computed, and how data should be ordered in a report. Oracle Reports objects that define the data model are queries, groups, columns, parameters, and links.
Glossary 3
database A set of dictionary tables and user tables that are treated as a unit. Also called a server. database cursor See cursor. DATE An ORACLE datatype. A date column may contain a date and time between January 1, 4712 BC and December 31, 4712 AD. default A value that Oracle Reports assigns to a setting if you do not specify one. Also, an Oracle Reports object (such as a group, field, frame, etc.) that Oracle Reports creates so that you do not need to create it yourself. DESFORMAT An argument that specifies the characteristics of the reports output device named in DESNAME. designer The interface, invoked by R25DES, through which you define a module. DESNAME An argument that specifies the name of the output device to which the report will be sent. DESTYPE An argument specifying the kind of output device to which the report will be sent (e.g., printer, file, mail). detail query When defining a master/detail report, the detail query retrieves all related records for each record retrieved by the master, or parent, query. dialog box A partial screen or window that prompts you to enter some piece(s) of information necessary to complete an operation. Dialog boxes are accessed extensively via the various menus. disabled An interface element state that means a menu item, button, etc., cannot be used in the current context; i.e., it does not respond to keyboard or cursor/mouse input. display format See format mask.
E
EBCDIC Acronym for Extended BinaryCoded 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 an editor (e.g., cut, copy, paste, etc.). editing region The area of a editor in which you can create, modify, position, or delete objects while viewing their graphical representations. editor A work area in which you define the data model (Data Model editor), the layout (Layout editor), and the Runtime Parameter Form (Parameter Form editor) for your report. enabled An interface element state that means that a menu item, button, etc., can be used in the current context, that is, it responds to keyboard or cursor/mouse input. enclosing object An object that contains another object. An object is considered to be enclosed by another object only if all of the following are true: both objects belong to the same region (Body, Margin, Header, or Trailer); 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 borders of the 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, and operations on their values.
Glossary 4
external PL/SQL library A PL/SQL package, function, or procedure that can be referenced by the same or multiple reports and by other Oracle products, any number of times. These are executed on the module side, not the database or server side. external query ANSIstandard SQL SELECT statement that can be referenced within the same or multiple reports, and by other Oracle products, any number of times. These are executed by the database or server.
F
field 1. An interface element in which you enter, edit, or delete data that either defines an object or makes a processing choice. Fields appear in property sheets, dialog boxes, and lists of values. 2. A layout object that defines the appearance of a columns data. field label See label. file column A column whose value is a filename. Each file column will display either the filename or the actual contents of the file (e.g., ASCII and CGM files) based upon the Link setting in the columns property sheet. If you specify that you want to link to the file, its contents will appear. If you do not want to link to the file, only its filename will appear. File menu A menu that lists a set of operations to perform on the selected module. fill area The area within an object to which a fill (color or pattern) should be applied. Each object has two fill areas: inside the objects border, and inside the objects edge. filter See group filter.
Flex mode Layout editor mode that automatically resizes or shrinks parent objects when child objects are moved or resized, and adjusts the positions of other layout objects that might otherwise be affected by the repositioning or resizing of the objects. foreign key A value or column in one table that refers to a primary key in another table. form layout A default layout style in which labels appear to the left of fields, and each record prints on a separate logical page. form letter layout A default layout style that intermixes boilerplate and fields, wrapping lines at word breaks. format mask (Field Properties) A setting that defines the appearance of the value of a field. For example, a format mask is used to specify the display of currency amounts and dates. Format menu The menu used to specify attributes affecting the appearance of objects in the editor. format trigger A PL/SQL function executed before the object to which it is associated is printed, allowing you to dynamically change the formatting attributes of that object. formula column A usercreated column that gets its data from a PL/SQL function or expression, a user exit, a SQL statement, or any combination of these. frame A layout object used to enclose other layout objects and control the formatting, frequency, and positioning of several objects simultaneously. FROM A required clause of the SQL SELECT statement that identifies the tables or views from which data is selected.
Glossary 5
function 1. (Column Properties) A setting with which you specify which operation (e.g., First, Last, Sum, % of Total, etc.) you want to use to compute the value of a summary column. 2. A PL/SQL value construct that requires a name and the full PL/SQL syntax, including declarations and the BEGIN and END keywords.
H
header An optional report region that can contain introductory material for the report, including text, graphics, data, and computations. The report header appears first, before the body and trailer. heading node A node in the Object Navigator denoting a type of object which can be contained within or associated with a report. Selecting a heading node does not select an object in the report. See also node, Object Navigator. Help menu A menu that lists various ways to access Oracle Reports online help system. hidden (Field Properties) A property that specifies whether Oracle Reports will suppress the indicated field at its location in the layout. If Hidden is specified, the fields value will appear only where referenced in text objects (using &fieldname). horizontal sizing (Layout objects) A setting that determines how the horizontal size of the layout object will change at runtime to accommodate the objects or data within it. Valid options are Contract, Expand, Fixed, and Variable. horizontal spacing (Repeating Frame Properties) The amount of space that should appear horizontally between instances of a repeating frame.
G
generate (File menu) To translate the report definition into a binary, executable file. grant To give a user access to a module. Only a modules creator can grant its access to other users. group A data model object that is created automatically to contain all the columns selected by a query, or created by the user to modify the hierarchy of the data appearing in a report; it is used primarily for creating breaks in a report, as well as for resetting computations. See also break group. GROUP BY An optional clause of a SELECT statement which identifies the level of summarizing to be performed before fetching data from the database. group filter A PL/SQL function that restricts the data fetched by a group. group name (Group Properties) The name of a group. Groups are named so they can be referenced by other objects. groups query The query that selects data for the group. GUI An acronym for graphical user interface.
I
icon 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 editors both text and graphics, but you may import only text into single and multiline fields.
Glossary 6
index An optional structure associated with a table that is used by ORACLE or another server or database to locate rows of the table quickly, and (optionally) to guarantee that every row is unique. Insert mode A mode in which each character you type is inserted into your text at the cursor, without overtyping adjacent characters. The opposite of Replace mode.
J
join Combining data from two (or more) tables in a single SELECT statement. justification See alignment.
link A data model object used to define a master/detail (parentchild) relationship between a group and a query. list of values A list of valid options for a field in the designer or a parameter in the Runtime Parameter form. logical page One page of your actual report (it may be displayed on one or more physical pages). login account A username and password to access ORACLE or another server or database. This account is usually separate from an operating system account.
M
mailing label layout A default layout that displays records in one or more columns on the page. Fields appear directly beneath each other in a single repeating frame. margin An optional report region that appears at the top and bottom of each logical page in the body region. The margin may include any layout object, but typically contains boilerplate and fields (for page numbers, page totals, grand totals, and current date and time). master/detail layout A default layout in which the detail records appear below the master records. Master records appear in form layout style, while detail records appear in tabular layout style. matrix cell A repeat direction that displays each record of a repeating frame as a cell of a matrix. See also matrix report.
L
label A heading created for each field appearing in a report layout. Labels are boilerplate objects. layout A formatting model that uses layout objects to define the positioning and appearance of the data in your report. Layout objects are frames, repeating frames, fields, boilerplate, anchors, and buttons. lexical reference A reference to a lexical parameter. See also lexical parameter. lexical parameter A parameter used to replace a clause in a SELECT statement (e.g., GROUP BY, ORDER BY, etc.), enabling you to specify a value for the clause at runtime. link file The name of a file to which a boilerplate object is associated. At runtime, Oracle Reports imports the files contents into your report layout.
Glossary 7
matrix layout A default layout, resembling a grid, that formats the four sets of data necessary for a matrix report; one set of data displays as a row of labels, one as a column of labels, one set creates the grid, and one set fills the cells of the grid. See also matrix report. matrix report A crosstabulation of four sets of data: one set of data displays across the page; one set of data displays down the page; one set of data is the crossproduct, determining all possible locations in which the across and down data relate and placing a cell in those locations; and one set of data displays as the filler of the cells. menu A list of available choices from which you can choose what action to take next or what interface element to access next. module An object that can be shared by more than one report, as well as by other Oracle products. Reports, external queries, and external PL/SQL libraries constitute Oracle Reports modules. multiline field A field in the designer that extends for several lines, allowing you to scroll vertically through the information.
node A line in the Object Navigator. A node denotes either one object in a report or one type of object which can be contained within or associated with a report. Nodes can optionally contain such information about an object as whether it has associated PL/SQL, is anchored to another object, etc. See also heading node, Object Navigator. noncaching column A report column that references a database column of datatype NOCACHE. nonvalue construct A PL/SQL code structure that does not return a value. Nonvalue constructs include procedures and packages. NULL value The absence of a value. A null value should mean only that nothing is known about the value.
O
object An item that defines one portion of a module (e.g., a column object defines all information about the column: its datatype, width, name, etc.). Most objects have property sheets, with which you can modify their definitions. Object Navigator The Oracle Reports window containing a list of objects in all currently opened reports. The list appears in outline form, and enables the user to accomplish several tasks related to managing reports; e.g., editing property sheets, renaming objects, and deleting objects. See also node, heading node.
N
nested matrix Matrix report in which either the across and/or down dimension contains one or more master/detail relationships. There is no limit to the amount of nesting allowed. NOCACHE A datatype indicating that the data will be fetched when the page on which it appears is formatted (instead of fetched and cached until formatted).
Glossary 8
OLE2 Object Linking and Embedding V2. For more information, see your Microsoft documentation. ORDER BY An optional clause used in a SQL SELECT statement to specify the order in which the results of a query are to be fetched. Oracle Reports Server A batch report executable found only on Microsoft Windows. The executable is loaded once when a report is launched by another Developer/2000 tool and remains in memory. It enables you to manage the execution 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, stored in a file, printed on paper, or sent to other users via Oracle*Office. overflow When an objects contents cannot fit on the current logical page. In the event of overflow, some of the contents are moved to the next logical page.
P
packaged function 1. A PL/SQL function, shipped with Oracle Reports, that can be referenced anywhere in a report or external PL/SQL library. 2. See function. palette An interface element that displays all tools, colors, and patterns available in an editor. page break (Layout objects) A setting that controls whether to move the current object and its children to the next logical page. You can set page breaks to occur before or after the current object appears in the report output.
pagedependent reference A value in the report that relies on the formatting of the report. For example, the Total Number of Logical Pages and a summary with Reset At of Page are page dependent references. page height (Report Properties) The height of the physical page. page width (Report Properties) The width of the physical page. panel The number of physical pages needed to print one logical page. parameter A variable that you can change at runtime. parent group (Query Properties) A group that owns a query or another group. parent/child relationship Way in which to define 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 the current cursor location. paste buffer See Clipboard. pattern A graphical property of certain layout objects, such as frames, repeating frames, fields, and boilerplate. physical page The size of a page that is output by your printer. PL/SQL A procedural extension of SQL that provides programming constructs such as blocks, conditionals, and procedures. .pll file A file with an extension of .pll that contains an external PL/SQL library in binary format. preference A setting that affects the behavior of the design or runtime interface.
Glossary 9
Previewer The interface with which you view and scroll through report output online. primary key A column in a database table whose members consist of unique values that can be used to identify a row in a table. print condition (Layout objects) A setting that defines how frequently an Oracle Reports object is printed relative to other Oracle Reports objects. print direction (Repeating Frame Properties) The direction in which each instance of a repeating frame prints relative to the prior instance. The valid options are Across, Across/Down, Down, and Down/Across. printer control code In a printer definition file, an escape sequence to which you assign a printer code that can be referenced in a report. procedure A PL/SQL nonvalue construct that requires a name and the full PL/SQL syntax, including declarations and the BEGIN and END keywords. product order (Column Properties) The order in which groups are evaluated in the cross product when computing summaries. property See setting. property sheet A rectangular area that appears in a window, displaying all of the information for one object (e.g., a query). protocol A string you can enter when connecting to a database or server that allows you to connect to a remote database or server. .prt file A file with an extension of .prt that contains a printer definition in text (e.g., ASCII or EBCDIC) format.
Q
query A SQL SELECT statement that specifies the data you wish to fetch for the report. query name (Query and Group Properties) A setting that identifies a query. quit (File menu) An option that terminates an Oracle Reports session and returns the user to the operating system. On some systems, Quit is Exit.
R
R25CONV An executable command that converts a report definition from one storage format (i.e., database, .rdf file, .rep file, .rex file) to another. R25DES An executable command that invokes Oracle Reports designer, with which you can define and run reports. R25MREP An executable command that converts Version 1.1 reports to Version 2.5 reports, stored either in database tables or files. R25RUN An executable command that runs a previously defined report(s). radio button A twochoice list (similar to a check box), appearing in sets of two or more, only one of which may be either on or off at any given time. .rdf file A file with an extension of .rdf that contains a single report definition in binary format. .rdf files are used to both run and edit reports. read consistency The ability to query the data at a single point in time. This ensures that all the data in a report is internally consistent. record One row fetched by a SQL SELECT statement.
Glossary 10
region The area in a report that owns the objects being defined. Valid regions are Header, Body/Margin, and Trailer. rename (File menu) A menu option used to change the name of a module. .rep file A file with an extension of .rep that contains a single report definition in binary format. .rep files are used solely to run reports; you cannot edit a .rep file. repeating frame A layout object used to display rows of data that are fetched for a group. Replace mode A mode in which each alphanumeric character you type replaces the current character at the cursor. The opposite of Insert mode. report A module that defines all of the information about itself, including its history, page size, references to other modules, and use of reportlevel objects. reportlevel objects The objects that are used to define a reports data model and layout. Reportlevel objects are assigned to a single report, and cannot be shared by other reports or other Oracle products. Oracle Reports objects include reports, queries, external queries, external PL/SQL libraries, groups, columns, parameters, links, frames, repeating frames, fields, boilerplate, and anchors. reset (Column Properties) A setting that specifies the group at which the value of a column summary is to be reset to 0. revert (File menu) An option enabling you to reset the current module definition to the most recently saved state. .rex file A file with an extension of .rex that contains a report definition stored in text (e.g., ASCII or EBCDIC) format. .rex files are used to port reports from one platform to another.
row 1. One set of fields in a table; for example, the fields representing one employee in the example table EMP. 2. One set of fields in the output of a query. run (File menu) To produce the report output. runfile See .rep file. running summary A column summary which returns cumulative values of the function between reset points. Runtime Parameter Form A screen or window appearing optionally at runtime in which a user can modify print options and parameters prior to report execution. runtime The time during which Oracle Reports is running a report.
S
script A file containing SQL statements that you can run in SQL*Plus to quickly perform database administration. Several SQL scripts are shipped with Oracle Reports. scroll region See multiline field. SELECT statement A SQL statement that specifies which rows and columns to fetch from one or more tables or views. session In R25DES, the period between invoking Oracle Reports and quitting Oracle Reports. In R25RUN, the period between running a report and quitting it. setting An attribute of an object that determines the effect or presentation of that object. Examples of properties include Vertical Sizing, Page Width and Datatype. sibling An object that is at the same level as another object in a hierarchy, either directly or indirectly.
Glossary 11
source (Column and Field Properties) For columns, the name of the column whose values will be summarized. For fields, the column or parameter whose data will be displayed in the field. SQL A standard interface for storing and retrieving information in a relational database or server. SQL is an acronym for Structured Query Language. .sql file A file with an extension of .sql that contains a query stored in text (e.g., ASCII or EBCDIC) format. Any report you create can reference any query you create or to which you have been granted access. SQL statement A SQL instruction to ORACLE. A SELECT statement is one type of SQL statement. subprogram A named PL/SQL construct. Packages, functions, and procedures constitute subprograms. subtotal See summary column. summary column A column, with a type of summary, which computes subtotals, grand totals, running totals, and other summaries of the data in a report, using one of the packaged summary functions provided by Oracle Reports. system variable One of the variables that are provided with Oracle Reports (e.g., &Logical Page, DESTYPE).
T
tabbed property sheet See property sheet. table A named collection of related information, stored in a relational database or server, in a twodimensional grid that is made up of rows and columns. tabular A default layout displaying labels at the top of the page and rows of data underneath the labels.
TERM An argument that enables you to specify a file that describes the terminal from which you are using R25DES or R25RUN. 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 the application or interface element that appears in that window. title page See header. toggle A setting that can be turned either on or off. For example, you can toggle between insert and replace mode when typing data. tool An icon that appears in an Oracle Reports editor. Tools are used to perform actions on objects in a report. toolbar Portion of an Oracle Reports editor containing tools that serve as shortcuts for common menu selections (e.g., File>Save, Edit>Cut, etc.). Tool palette Portion of an Oracle Reports editor containing tools that provide a means of creating, deleting, or modifying report objects via interaction with the graphical user interface (e.g., drawing tools, text tool, query tool, etc.) They do not have menu equivalents. Tools menu A menu that provides access to several tools for use in building reports; e.g., the Default Layout and Parameter forms, several editors, the PL/SQL Interpreter, debugging tools, etc. trailer A optional report region that can contain closing material for the report, including text, graphics, data, and computations. The report trailer appears last, following the header and body.
Glossary 12
transaction A sequence of SQL statements that ORACLE treats as a single unit. trigger A PL/SQL construct that is executed, or fired, at a specific time during the formatting of a report.
U
USERID An argument which allows you to specify your ORACLE username and password with an optional SQL*Net address. user exit A way in which to pass control (and possibly arguments) from Oracle Reports to another Oracle product or 3GL, and then return control (and possibly arguments) back to Oracle Reports.
vertical spacing (Repeating Frame Properties) The amount of space that should appear vertically between instances of a repeating frame. view A virtual table whose rows do not actually exist in the database. A virtual table is based on a table that is physically stored in the database. View menu A menu that lists choices for customizing the features provided by the the Oracle Reports editors; e.g., whether to display the rulers, the grid, the toolbar, etc.
W
width (Column and Parameter Properties, layout objects) The width of a column, parameter, or layout object. Windows menu A menu that lists all of the Oracle Reports windows that are open or iconized.
V
value construct A PL/SQL code structure that returns a value. Value constructs include functions and expressions. vertical sizing (Layout objects) A setting that determines how the vertical size of the layout object will change at runtime to accommodate the objects or data within it. Valid options are Contract, Expand, Fixed, and Variable.
Glossary 13
Glossary 14
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 83 for field, 8 58
Numbers
3GL programs. See call interface (3GL calls Oracle Reports executables); user exits (report calls the 3GL)
A
ACCESS keyword for R25DES, 1 46 Accessing multimedia objects in the Previewer, 11 8 Action for button, 8 81 triggers, 13 32 Ada, Pro*Ada, 14 3 Add to parameter LOV, 6 51 Additional default layout tool, 7 15 Administration access to other users modules, 18 31 controlling access to Oracle Reports, 18 31 deleting reports, 19 5 determining which files are used, 19 6 documenting reports, 19 6 establishing database security, 18 31 granting user privileges, 19 4 moving reports between files and the database, 19 5 revoking user privileges, 19 4 upgrading from previous versions, 19 5
Index 1
Alias font, 18 7 in SELECT statement, E 2 with parameters, E 2 All but first print condition, 8 16 All but last print condition, 8 16 All print condition, 8 16 Anchor information, 12 7 Anchor properties, 8 62 % down/across object edge, 8 69 % down/across parent edge, 8 69 collapse horizontally, 8 69 collapse vertically, 8 70 object, 8 69 object edge, 8 69 parent, 8 69 parent edge, 8 69 Anchors examples, 8 63 implicit algorithm, 2 43 rules, 8 67 tool, 7 14 Arguments. See executables, arguments; user exit, passing values Arrange menu. See online help system ARRAYSIZE keyword for R25DES, 1 37 keyword for R25RUN, 1 20 performance, 17 16 ASCII driver invoking, 1 31 performance advantages, 17 17 Attached libraries, 13 16 Attributes, changing via PL/SQL: SRW.SET_ATTR, 13 58 via PL/SQL: SRW.SET_ATTR, character mode only, 13 61 via PL/SQL: SRW.SET_ATTR, TEXT, 13 61 via PL/SQL: SRW.SET_ATTR, WEIGHT, 13 61 Automatic login, 1 7 Average, summary function, 6 32
B
BACKGROUND keyword for R25DES, 1 46 keyword for R25RUN, 1 31 Backward compatibility, stored program unit stubs, 13 34 BATCH keyword for R25CONV, 1 15 keyword for R25RUN, 1 26 Bidirectional support, C 8 Bind parameters. See bind references Bind references, E 4 creating, E 4 examples, E 4 in PL/SQL constructs, 13 32 rules, E 4 Bitmapped environment definition of, A 2 GUI differences, A 2 report conversion across GUIs, A 4 Block types. See PL/SQL, construct types Body, 7 5 Boilerplate See also boilerplate properties; parameter form 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 3 suppressing for detail records, 13 29 Boilerplate properties, 8 59 comment, 8 27 format, 8 60 format trigger, 13 28 horizontal sizing, 8 4
Index 2
keep with anchoring object, 8 6 link file, 8 60 minimum widow lines, 8 62 name, 8 8 page break after, 8 9 page break before, 8 11 page protect, 8 12 print condition, 8 15 printer codes, 8 26 vertical sizing, 8 20 Borders, 7 16 conditional color via PL/SQL: SRW.SET_ATTR, BBCOLOR, 13 59 via PL/SQL: SRW.SET_ATTR, BORDERWIDTH, 13 59 via PL/SQL: SRW.SET_ATTR, BORDPATT, 13 59 via PL/SQL: SRW.SET_ATTR, FBCOLOR, 13 59 BREAK. See PL/SQL packaged procedures, SRW.BREAK Break order, 6 18 adds to the ORDER BY clause, 17 6 default, 6 18 examples, 6 19 options, 6 18 performance of break columns, 17 9 rules, 6 20 BUFFERS keyword for R25DES, 1 42 keyword for R25RUN, 1 26 Builtin packages, in Object Navigator, 12 8 Button properties action, 8 81 action trigger, 13 32 label, 8 83 name, 8 8 text string, 8 83 Buttons rules, 8 80 tool, 7 14
C
C, Pro*C, 14 3 Call interface definition of, 15 2 error checking, 15 4 examples, 15 5, 15 6, 15 7, 15 8 rules, 15 4 steps to call Oracle Reports from a 3GL, 15 2 syntax, 15 3 Cautions .rex files, 18 4 boilerplate, 8 60 cgm files, 18 4 converting reports, must recompile, A 3 DDL and DML, PL/SQL, 13 44 DDL and DML, R25DES, 1 42 DDL and DML, R25RUN, 1 25 DDL and DML, report triggers, 13 20 format trigger, 13 30 global defaulting rule, 2 41 installing tables, 19 3 KEYIN, R25RUN, 1 30 KEYOUT, R25RUN, 1 30 NLS_LANG, C 3 Oracle Reports tables, 18 13 overflow, 8 23 parameter form editor, 9 5 print condition, 8 18 printer codes, 8 26 printer definitions, B 1 R25RUN, no compile, 1 18 READONLY, EXEC ORACLE, 14 8 READONLY, EXEC SQL, 14 5 READONLY, PL/SQL, 13 44 READONLY, R25DES, 1 42 READONLY, R25RUN, 1 25 READONLY, report triggers, 13 20 references in PL/SQL, 13 33 terminal definitions, B 1 user exits, 13 72 CDE_MM, 13 40 CDE_MM.GET_REF, 13 40 Centering objects horizontally, 8 63 vertically, 8 64
Index 3
Central tables, Oracle Reports tables. See Oracle Reports tables Character datatype, 6 20 Character mode designing for, A 3 environment, A 2 ouput, 1 31 output, performance advantage, 17 17 Character sets converting, C 5 sorting, C 5 support of multiple, C 2 Characters per page, runtime setting, 4 14 Child column, 6 12 rules, 6 12 Child query, 6 12 rules, 6 12 CMDFILE keyword for R25CONV, 1 14 keyword for R25DES, 1 36 keyword for R25RUN, 1 19 COBOL, Pro*COBOL, 14 3 Collapse, anchors examples, 8 65, 8 66 horizontally, 8 69 vertically, 8 70 Colors conversion across GUIs, A 4 palette, F 4 via PL/SQL: SRW.SET_ATTR, BBCOLOR, 13 59, 13 62 via PL/SQL: SRW.SET_ATTR, BFCOLOR, 13 59, 13 62 via PL/SQL: SRW.SET_ATTR, FBCOLOR, 13 59, 13 62 via PL/SQL: SRW.SET_ATTR, FFCOLOR, 13 60, 13 62 Column heading. See label Column mode, 8 29 example, 8 31 rules, 8 32 Column properties, 6 17 break order, 6 18 comment tab, 6 27 compute at, 6 29 datatype, 6 20
format, 6 21 formula, 13 25 function, 6 32 name, 6 22 product order, 6 33 read from file, 6 23 reset at, 6 39 source, 6 40 summary, 6 32 value if null, 6 24 width, 6 25 Columns See also column properties bind references, E 4 child, 6 12 lexical references, E 5 parent, 6 13 properties, 6 17 view by hierarchy, 12 11 view by type, 12 12 Command line interface parameter validation, 13 18 R25CONV for converting report definitions, 1 9 R25DES for creating/modifying reports, 1 35 R25RUN for running generated reports, 1 18 Commands, SQL commands in user exits, 14 5 Comment tab column property sheet, 6 27 group property sheet, 6 17 parameter property sheet, 6 52 query property sheet, 6 8 Comments for layout objects, 8 27 for parameter form boilerplate, 10 5 for parameter form fields, 10 3, 10 5 for report, 4 15 COMMIT ONFAILURE for R25DES, 1 45 ONFAILURE for R25RUN, 1 29 ONSUCCESS for R25DES, 1 44 ONSUCCESS for R25RUN, 1 29 READONLY for R25DES, 1 41 READONLY for R25RUN, 1 24
Index 4
Common layout properties, 8 2 rules, 8 2 Compiling See also user exits PL/SQL, compiling, 13 37 Compute at, 6 29 default, 6 29 examples, 6 29 rules, 6 31 Conditions, filter, 13 23 example, 13 24 rules, 13 24 Conditions, link, 6 12 default, 6 13 options, 6 12 Confine mode, 7 9 Constrained mode, 7 8 Constructs definition of, 13 2 restrictions, 13 33 types supported in Oracle Reports, 13 2 which are valid for different objects, 13 15 CONTEXT_FAILURE. See PL/SQL packaged exceptions, SRW.CONTEXT_FAILURE Contract sizing, 8 20 Control key, for flex mode, 7 9 CONVERT function, C 5 Converting 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 16 NLS, C 7 reports from V1.1 to V2.5, 19 5 COPIES keyword for R25DES, 1 39 keyword for R25RUN, 1 23 performance, 17 17 Count, summary function, 6 32 Creating See also DDL bind references, E 4 database security, 18 31 lexical references, E 5
Cross product groups for matrix, 8 72 performance, 17 9 rules, 2 35 tool, 5 6 CURRENCY keyword for R25DES, 1 40 keyword for R25RUN, 1 23 Current date, field source, 8 56 Customizing function keys, B 17
D
Data converting via CONVERT function, C 5 sorting via NLSSORT function, C 5 Data Definition Language, E 9 Data Manipulation Language, E 9 Data model defaulting, 2 2 performance, 17 5 Data model editor accessing, 5 3 components, 5 3 definition and purpose, 5 2 painting region, 5 3 popup menu, 5 7 status line, 5 7 Data model objects column properties, 6 17 database column properties, 6 27 formula column properties, 6 41 group properties, 6 14 if unused, 17 8 link properties, 6 8 parameter properties, 6 45 placeholder column properties, 6 42 query properties, 6 2 summary column properties, 6 27 Data/Selection tab, parameter properties, 6 50 Database automatic login, 1 7 explicit login, 1 7 objects in Object Navigator, 12 8
Index 5
remote login, 1 8 storage requirements, 18 31 Database column properties, 6 27 general tab, 6 17 rules, 6 27 Datatype of column, 6 20 character, 6 20 date, 6 20 long, 6 20 long raw, 6 20 number, 6 20 options, 6 20 raw, 6 20 REF, 6 20 rules, 6 21 Varchar, 6 21 Varchar2, 6 21 Datatype of field, 8 42 rules, 8 42 Datatype of parameter, 6 47 default, 6 47 options, 6 47 rules, 6 47 Datatype of parameter form field, 10 2 Date datatype, 6 20 field source, 8 56 format masks, 8 44 DDE package, definition of, 13 39 DDL, E 9 caution with SRW.DO_SQL, 13 44 SRW.DO_SQL, syntax of, 13 43 via PL/SQL packaged procedure, SRW.DO_SQL, 13 2 DEBUG package, definition of, 13 39 Debugger. See Oracle Procedure Builder DECIMAL keyword for R25DES, 1 40 keyword for R25RUN, 1 24 Default parameter values. See initial value Default parameters. See packaged parameters Default print condition, 8 16 Defaulting, 2 1 data model, 2 2 implicit anchor algorithm for layout objects, 2 43
layout, 2 4 parameter form, 2 47 print condition algorithm for layout objects, 2 47 Deleting See also DDL pages, layout, 7 20 pages, parameter form, 9 9 reports, 19 5 Depressed appearance of buttons, rules, 8 82 DESFORMAT keyword for R25DES, 1 39 keyword for R25RUN, 1 22 DESNAME keyword for R25DES, 1 38 keyword for R25RUN, 1 21 DEST keyword for R25CONV, 1 13 DESTYPE keyword for R25DES, 1 37 keyword for R25RUN, 1 20 Details, suppressing labels when no records, 13 29 DEV_NLS_LANG, C 2 Development environment. See Oracle Procedure Builder Device type for output. See destination type Dialog boxes, page numbering, 8 52 Dimension repeating frames, in Object Navigator, 12 8 Disable host, character mode runtime setting, 4 13 split, character mode runtime setting, 4 13 zoom, character mode runtime setting, 4 13 Disk space requirements, 18 32 Display, Oracle Graphics name, 8 76 query, 8 79 Displaying reports as PostScript output via R25DES, 1 37 in PostScript format via R25RUN, 1 20 DML, E 9 via PL/SQL, 13 2 DO_SQL. See PL/SQL packaged procedures, SRW.DO_SQL
Index 6
DO_SQL_FAILURE. See PL/SQL packaged exceptions, SRW.DO_SQL_FAILURE Documentation set, ii Documenting reports, 19 6 DPI affect in wordwrapping, A 4 Dropping Version 1.1 tables, 19 5 droprep.sql script, 19 2 DTYPE keyword for R25CONV, 1 12 Dummy variable, placeholders. See placeholders DUNIT keyword for R25CONV, 1 15
E
Edit menu. See online help system Editors accessing, 9 5 icon in Object Navigator, 12 6 Empty string for executable arguments, 1 5 Enclosing object, 8 15 determining, 2 43 Environment variables, 18 10 REPORTS_TMP, 18 11 REPORTS25_PATH, 18 11 REPORTS25_TERMINAL, 18 11 setting NLS_LANG, C 2 TK21_ICON, 18 12 Environments. See bitmapped environment; blockmode environment; charactermode environment ERRFILE keyword for R25DES, 1 45 keyword for R25RUN, 1 30 Errors See also PL/SQL, exceptions checking for and defining user exit errors, 14 13 for the call interface, 15 4 messages you raise via PL/SQL, 13 50 raising from user exits, 14 9 Establishing database security, 18 31 Examples alignment, conditional, 13 61 anchor, 8 63
attributes changed via PL/SQL, SRW.SET_ATTR, 13 61 borders, conditional, 13 61, 13 62 break order, 6 19 call to R20RUN written in Ada, 15 6 call to R20RUN written in C, 15 6 call to R20RUN written in COBOL, 15 7 call to R20RUN written in FORTRAN, 15 7 call to R20RUN written in Pascal, 15 8 call to R20RUN written in PL/l, 15 8 colors, conditional, 13 62, 13 63 column mode, 8 31 compute at, 6 29 DDL via PL/SQL, 13 45 faces, conditional, 13 63 field values changed via PL/SQL, 13 64, 13 65 filter condition, 13 24 filter type, 6 16 fonts, conditional, 13 63 format masks, conditional, 13 61, 13 62 format trigger, 13 28 formula, 13 25 hidden, 8 50 horizontal sizing, 8 5 justification, conditional, 13 63 keep with anchoring object, 8 7 link, 6 10 logical page size, 4 3 matrix, 8 71 maximum records per page, 8 34 minimum widow lines, 8 51 minimum widow records, 8 34 page numbering, 8 54 page numbers via PL/SQL, 13 48 page protect, 8 12 patterns, conditional, 13 61 PL/SQL function, 13 5 PL/SQL procedure, 13 8 PL/SQL SRW.PROGRAM_ABORT, 13 53 PL/SQL SRW.SET_ATTR, AFTCODE, 13 61 PL/SQL SRW.SET_ATTR, BBCOLOR, 13 62 PL/SQL SRW.SET_ATTR, BEFCODE, 13 61 PL/SQL SRW.SET_ATTR, BFCOLOR, 13 62 PL/SQL SRW.SET_ATTR, BORDERWIDTH, 13 61, 13 62
Index 7
PL/SQL SRW.SET_ATTR, BORDPATT, 13 62 PL/SQL SRW.SET_ATTR, CUSTOM, 13 63 PL/SQL SRW.SET_ATTR, FACE, 13 63 PL/SQL SRW.SET_ATTR, FBCOLOR, 13 62 PL/SQL SRW.SET_ATTR, FFCOLOR, 13 62 PL/SQL SRW.SET_ATTR, FILLPATT, 13 61, 13 62 PL/SQL SRW.SET_ATTR, FORMATMASK, 13 61, 13 62 PL/SQL SRW.SET_ATTR, GCOLOR, 13 63 PL/SQL SRW.SET_ATTR, GSPACING, 13 63 PL/SQL SRW.SET_ATTR, HJUST, 13 61, 13 63 PL/SQL SRW.SET_ATTR, STYLE, 13 63 PL/SQL SRW.SET_ATTR, SZ, 13 63 PL/SQL SRW.SET_ATTR, TEXT, 13 61, 13 63 PL/SQL SRW.SET_ATTR, WEIGHT, 13 63 PL/SQL subprogram, 13 22 PL/SQL, SRW.CONTEXT_FAILURE, 13 43 PL/SQL, SRW.DO_SQL, 13 45 PL/SQL, SRW.DO_SQL_FAILURE, 13 46 PL/SQL, SRW.GET_PAGE_NUM, 13 48 PL/SQL, SRW.GETERR_RUN, 13 47 PL/SQL, SRW.INTEGER_ERROR, 13 48 PL/SQL, SRW.MAXROW_INERR, 13 49 PL/SQL, SRW.MAXROW_UNSET, 13 50 PL/SQL, SRW.MESSAGE, 13 51 PL/SQL, SRW.NULL_ARGUMENTS, 13 52 PL/SQL, SRW.RUN_REPORT, 13 55 PL/SQL, SRW.RUN_REPORT_ BATCHNO, 13 57 PL/SQL, SRW.RUN_REPORT_ FAILURE, 13 58 PL/SQL, SRW.SET_FIELD_CHAR, 13 64 PL/SQL, SRW.SET_FIELD_DATE, 13 65 PL/SQL, SRW.SET_FIELD_ NUMBER, 13 65 PL/SQL, SRW.SET_MAXROW, 13 66 PL/SQL, SRW.TRUNCATED_ VALUE, 13 70 PL/SQL, SRW.UNKNOWN_QUERY, 13 71 PL/SQL, SRW.UNKNOWN_USER_ EXIT, 13 71 PL/SQL, SRW.USER_EXIT, 13 72
PL/SQL, SRW.USER_EXIT_ FAILURE, 13 74 placeholder column, 6 43 print condition, 8 17 printer codes, conditional, 13 61 product order, 6 34 queries, 6 5 raising messages via PL/SQL, 13 51 read from file, 6 23 reducing query fetch via PL/SQL, 13 66 reset at, 6 39 SELECT statement, 6 5 send portions of a report to different recipients, 13 55 source for field, 8 57 spacing, conditional, 13 63 style, conditional, 13 63 text color, conditional, 13 63 text size, conditional, 13 63 text spacing, conditional, 13 63 user exit call, 13 54, 13 72, 14 22 user exit call passing a value, 13 54, 13 72 user exit error checking, 13 72, 14 22 user exit program, 14 22 user exit, complete, 14 21 vertical sizing, 8 21 Exceptions, PL/SQL exceptions, 13 12 EXEC IAF GET, 14 6 EXEC IAF PUT, 14 6 EXEC ORACLE statements, 14 7 avoid with READONLY=YES, 14 8 EXEC SQL statements, 14 5 avoid with READONLY=YES, 14 5 Executables arguments, 1 3 brief explanation of each executable, 1 2 how to omit keywords, 1 6 how to view command line options, 1 3 invoking, 1 3 names, 1 3 syntax rules, 1 4 Expand sizing, 8 21 Explicit login, 1 7 External PL/SQL libraries, deleting, 19 5
Index 8
External queries deleting, 19 5 field in query property sheet, 6 3 External query properties, SQL SELECT Statement errors, E 3
F
Face, conditional example, 13 63 Fetching reducing via Maximum Rows, 17 8 reducing via WHERE clause, 17 10 setting ARRAYSIZE for, 17 16 Field properties, 8 41 comment, 8 27 datatype, 8 42 format mask, 8 42 format trigger, 13 28 hidden, 8 49 horizontal sizing, 8 4 keep with anchoring object, 8 6 minimum widow lines, 8 51 name, 8 8 page break after, 8 9 page break before, 8 11 page numbering, 8 52 page protect, 8 12 print condition, 8 15 printer codes, 8 26 source, 8 56 vertical sizing, 8 20 Fields See also field properties; parameter form fields names, D 3 placing in layout editor, 8 41 rules, 8 41 tool, 7 14 File Menu. See online help system Files administration files, 18 6 ASCII output, 1 31 being used by Oracle Reports, 19 6 demo files, 18 6 executable files, 18 6 filesearching method, 18 9
formats supported, 18 2 generated by Oracle Reports, 19 7 important files shipped with Oracle Reports, 18 5 installation files, 18 6 printer definition files, 18 7 security and restrictions, 18 9 sending reports via R25DES, 1 37 sending reports via R25RUN, 1 20 temporary, 18 8 terminal definition files, 18 7 Fill pattern, via PL/SQL: SRW.SET_ATTR, FILLPATT, 13 60 Fills color tool, 7 15 via PL/SQL: SRW.SET_ATTR, BFCOLOR, 13 59 via PL/SQL: SRW.SET_ATTR, FFCOLOR, 13 60 Filters, group, 6 15 condition, 13 23 type, 6 15 First group filter type, 6 16 print condition, 8 16 summary function, 6 32 Fixed sizing, 8 21 Flex mode, 7 9 Font aliases, 18 7 color via PL/SQL: SRW.SET_ATTR, FACE, 13 60 conditional, example, 13 63 face via PL/SQL: SRW.SET_ATTR, FACE, 13 59 style via PL/SQL: SRW.SET_ATTR, STYLE, 13 60 Font, conversion across GUIs, A 4 Footers. See Margins Form height for Runtime Parameter Form, 4 10 Form letter reports, possible truncation in, 2 41 Form width for Runtime Parameter Form, 4 10
Index 9
Format attributes, performance cost, 17 12 files supported, 18 2 for boilerplate, 8 60 Format masks, 8 42 adding to list of values, 8 42 examples, 8 47 for dates, 8 44 for numbers, 8 45 rules, 8 49 via PL/SQL: SRW.SET_ATTR, FORMATMASK, 13 60 Format menu. See online help system Format triggers, 13 28 example, 13 28 options, 13 28 performance, 17 13 rules, 13 30 FORMSIZE keyword for R25CONV, 1 16 Formula column properties, 6 41 general tab, 6 41 rules, 6 41 Formulas, 13 25 examples, 13 25 options, 13 25 rules, 13 26 tool, 5 6 FORTRAN, Pro*FORTRAN, 14 3 Forward references. See pagedependent references Frame properties, 8 28 comment, 8 27 format trigger, 13 28 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, 8 15 printer codes, 8 26 vertical sizing, 8 20 Frames See also frame properties if unused, 17 11 names, D 3
select tool, 7 10 tool, 7 13 Frequency in Object Navigator, 12 8 print condition, 8 80 Function calls, call interface. See call interface Functions. See PL/SQL, functions Functions, column, 6 32 options, 6 32 rules, 6 32
G
General tab database column property sheet, 6 17 formula column property sheet, 6 41 group properties, 6 15 parameter properties, 6 47 placeholder column property sheet, 6 44 query property sheet, 6 2 summary column property sheet, 6 28 GET. See EXEC IAF GET GET_PAGE_NUM. See PL/SQL packaged procedures, SRW.GET_PAGE_NUM GETERR_RUN. See PL/SQL packaged functions, SRW.GETERR_RUN Global variables, 13 8 See also placeholders Grant, using SQL scripts, 19 4 Graphics boilerplate, 8 80 format, boilerplate, 8 60 format, column, 6 21 image, boilerplate, 8 60 image, column, 6 23 link file, boilerplate, 8 60 read from file, 6 23 Group properties, 6 14 comment tab, 6 17 filter, 6 15 filter condition, 13 23 filter performance, 17 8 filter type, 6 15 general tab, 6 15 name, 6 16
Index 10
Groups See also group properties parent, 6 13 rules, 6 15 view by hierarchy, 12 11 view by type, 12 12 GUIs differences, A 2 differences affecting report conversion, A 4
I
Icons, search path, 18 10 Image accessing, 11 10 boilerplate in Object Navigator, 12 9 in buttons, 11 10 Image viewer magnify tool, 11 11 panning tool, 11 11 Images formats supported, 18 2 resolution performance cost, 17 12 Indexes, 17 7 Initial value, parameter, 6 48 rules, 6 48 Input mask, rules, 6 49 Input mask for parameters, 6 48 default, 6 49 Inserting. See DML Installing integrated Oracle tools tables, 19 3 Oracle Reports tables, 19 3 Instances, keeping together, minimum widow records for repeating frames, 8 34 INTEGER_ERROR. See PL/SQL packaged exceptions, SRW.INTEGER_ERROR Integrated Oracle product tables description, 18 27 installing, 19 3 TOOL_ACCESS, 18 27 TOOL_COMMENT, 18 27 TOOL_DEPEND, 18 27 TOOL_LIBRARY, 18 28 TOOL_LRAW, 18 28 TOOL_LRAW_ID, 18 28 TOOL_LTEXT, 18 28 TOOL_LTEXT_ID, 18 29 TOOL_MODID, 18 29 TOOL_MODULE, 18 29 TOOL_PLSQL, 18 30 TOOL_ROSSTRINGS, 18 30
H
HAVING clauses added by Oracle Reports, 17 6 option for links, 6 13 Headers. See Margins Heading, label. See label Headings, in Object Navigator, 12 7 Help menu. See online help system Hidden, 8 49 example, 8 50 Hide first column for parameter LOV, 6 52 Hierarchical views columns by group, 12 11 columns by type, 12 12 group by structure, 12 11 group by type, 12 12 in Object Navigator, 12 10 layout objects by structure, 12 13 layout objects by type, 12 14 Horizontal frame for matrix, 8 8 Horizontal sizing, 8 4 examples, 8 5 rules, 8 23 to enhance performance, 17 12 Horizontal spacing, 8 33 default, 8 33 rules, 8 33 Host languages, 14 3 Host, disabling for character mode, 4 13
Index 11
Integration See also Oracle Reports calls to 3GLs 3GL calls to Oracle Reports, 15 1 call interface, 16 10 connecting to ORACLE and other databases, 16 2 OLE, 16 4 ORACLE, 16 2 Oracle Graphics, 16 6 Oracle Mail, 16 10 Oracle Terminal, 16 10 PL/SQL, 13 1, 16 5 SQL*Net, 16 2 user exit interface, 16 10 Interfaces See also call interface; PL/SQL user exits, 14 1 with other products, 16 1 Interpreter, 13 35 Invoking executables, 1 3 Invoking Oracle Terminal, B 17
Keywords how to omit them on the command line, 1 6 how to view command line options, 1 3
L
Label, 8 83 controlling printing, 8 15 suppressing when no detail records, 13 29 Label for buttons, rules, 8 83 Language, NLS, C 7 Languages Host languages, 14 3 PL/SQL, 13 1 Last group filter type, 6 16 print condition, 8 17 summary function, 6 32 Layout defaulting, 2 4 implicit anchor algorithm, 2 43 print condition algorithm, 2 47 Layout editor, 7 1 accessing, 7 3 components, 7 3 definition and purpose, 7 2 margins, 7 21 navigation, 7 20 painting region, 7 3 popup menu, nonOLE2 objects, 7 18, 9 7 popup menu, OLE2 objects, 7 19 report regions, 7 4 status line, 7 17 Layout objects common properties, 8 2 making transparent for performance, 17 12 view by hierarchy, 12 13 view by type, 12 14 Layout properties, common, 8 2 comment, 8 27 format trigger, 13 28 horizontal sizing, 8 4 keep with anchoring object, 8 6 page break after, 8 9 page break before, 8 11
J
Justification conditional, example, 13 61, 13 62, 13 63 via PL/SQL: SRW.SET_ATTR, HJUST, 13 60
K
Keep with anchoring object, 8 6 examples, 8 7 rules, 8 7 rules for conflicting properties, 8 2 Keeping objects together keep with anchoring object, 8 6 minimum widow records, 8 34 page protect, 8 12 Key bindings definition, B 17 modifying, B 17 steps to edit, B 17, B 19 Keystroke capture KEYIN, 1 30 KEYOUT, 1 30
Index 12
page protect, 8 12 print condition, 8 15 printer codes, 8 26 rules, 8 2 vertical sizing, 8 20 Leading via PL/SQL: SRW.SET_ATTR, CUSTOM, 13 60 via PL/SQL: SRW.SET_ATTR, GSPACING, 13 60 Lexical parameters. See lexical references Lexical references, E 5 creating, E 5 examples, E 7 rules, E 6 Lines, color tool, 7 16 Lines in Object Navigator. See Nodes Lines, minimum widow for boilerplate, 8 62 for field, 8 51 Link file for boilerplate field, 8 60 tool, 7 14 Link properties, 6 8 child query, 6 12 examples, 6 10 parent column, 6 13 parent group, 6 13 SQL clause, 6 13 Linking, call interface, 15 3 Links, data model description, 6 8 rules, 6 11 tool, 5 6 without columns specified, 6 13 LIST package, definition of, 13 39 Literal references, 13 33 Local tables. See Oracle Reports tables LOGFILE keyword for R25CONV, 1 14 keyword for R25RUN, 1 25 Logical page definition, 11 4 number, field source, 8 56
size, 4 3 Login automatic, 1 7 explicit, 1 7 remote, 1 8 Long datatype, 6 20 setting retrieval size, 1 30, 1 45 Long raw datatype, 6 20 LONGCHUNK keyword for R25DES, 1 45 keyword for R25RUN, 1 30 performance, 17 16
M
Magnify previewer, 11 7 tool, data model editor, 5 6 tool, layout editor, 7 11 Mail sending parts of reports to different users, 13 54 sending reports to Oracle*Mail via R25DES, 1 37 sending reports to Oracle*Mail via R25RUN, 1 21 Mailing label layout style, possible truncation in, 2 41 Main menu in the Previewer, 11 3 Maintaining reports, R25DES, 1 35 Mappings, font, 18 7 Margins, 7 5, 7 21 in Object Navigator, 12 9 overflowing, 7 21 Mask. See PL/SQL packaged procedures, SRW.SET_ATTR Masks, format, 8 42 format masks, 8 80 Master/Detail keeping details with master, 8 13 keeping instances together, 8 34 Matrix objects, names, D 3
Index 13
Matrix properties cross product group, 8 72 example, 8 71 horizontal frame, 8 8 rules, 8 71 vertical frame, 8 73 Matrix reports, 2 27 data model requirements, 2 27 layout defaulting, 2 27 performance, 17 9 rules, 2 35 Maximum body pages for report, 4 5 Maximum header pages for report, 4 5 Maximum records per page, 8 33 examples, 8 34 rules for conflicting properties, 8 2 Maximum rows, query, 6 4 default, 6 4 options, 6 4 performance, 17 8 rules, 6 4 Maximum trailer pages for report, 4 6 Maximum, summary function, 6 32 MAXROW_INERR. See PL/SQL packaged exceptions, SRW.MAXROW_INERR MAXROW_UNSET. See PL/SQL packaged exceptions, SRW.MAXROW_UNSET Memory requirements, 18 32 Menu item selection, v Menus, 3 1 MESSAGE. See PL/SQL packaged procedures, SRW.MESSAGE Messages. See errors Minimum widow lines, boilerplate, 8 62 rules, 8 62 Minimum widow lines, field, 8 51 examples, 8 51 Minimum widow records for repeating frame, 8 34 examples, 8 34 rules, 8 35 Minimum, summary function, 6 32 Minus/plus in Object Navigator, 12 5 MLSLABEL, 6 21
MODE keyword for R25DES, 1 46 keyword for R25RUN, 1 31 performance, 17 17 Modifying key bindings, invoking Oracle Terminal, B 17 Modifying reports, R25DES, 1 35 MODULE keyword for R25DES, 1 36 keyword for R25RUN, 1 18 Modules deleting, 19 5 naming conventions, D 2 stored in files, 18 2 Multimedia, accessing in Previewer, 11 8
N
Names for boilerplate objects, 8 8 for buttons, 8 8 for columns, 6 22 for executables, 1 3 for fields, 8 8 for frames, 8 8 for groups, 6 16 for OLE2 objects, 8 8 for Oracle Graphics displays, 8 8 for parameter form boilerplate, 10 4 for parameter form fields, 10 2 for parameters, 6 49 for queries, 6 5 for repeating frames, 8 8 Naming conventions buttons, D 3 for boilerplate objects, D 3 for columns, D 2 for executables, 1 3 for fields, D 3 for frames, D 3 for groups, D 2 for matrix objects, D 3 for modules, D 2 for parameter form boilerplate, D 3 for parameter form fields, D 3 for parameters, D 2
Index 14
for queries, D 2 for repeating frames, D 3 OLE2 objects, D 3 Oracle Graphics displays, D 3 National language support bidirectional support, C 8 converting data, C 5 definition of, C 2 overriding defaults, C 3 sorting data, C 5 specifying NLS_LANG, C 2 translating reports, C 7 using ALTER SESSION, C 3 using format masks, C 4 using NLS parameters/functions, C 5 Navigation in the Previewer, 11 5 Navigator menu. See online help system NLS_CURRENCY, C 3 NLS_DATE_FORMAT, C 3 NLS_DATE_LANGUAGE, C 3 NLS_ISO_CURRENCY, C 3 NLS_LANG, C 2 NLS_LANGUAGE, C 3 NLS_NUMERIC_CHARACTERS, C 3 NLS_SORT, C 3 NLS_TERRITORY, C 3 NLSSORT function, C 5 Nodes editor icon, 12 6 format, 12 5 heading, 12 7 in Object Navigator, 12 5 object icon, 12 6 PL/SQL icon, 12 6 plus/minus, 12 5 types of, 12 7 NonORACLE user exits, 14 3 nonvalue constructs, PL/SQL, nonvalue constructs, 13 6 NULL_ARGUMENTS. See PL/SQL packaged exceptions, SRW.NULL_ARGUMENTS
Number datatype, 6 20 Number format masks, 8 45 Number of pages for parameter form, 4 11 Numbering, page, 8 52
O
Object Navigator accessing, 12 2 components, 12 3 definition and purpose, 12 2 hierarchical views in, 12 10 nodes in, 12 5 object tree, 12 3 popup menu, 12 4 view data model by structure, 12 11 view data model by type, 12 12 view layout by structure, 12 13 view layout by type, 12 14 Object of print condition, 8 15 default, 8 15 options, 8 15 rules, 8 19 Object tree, in Object Navigator, 12 3 Objects, Oracle Reports See also changing attributes via PL/SQL, SRW.SET_ATTR referencing in PL/SQL, 13 32 referencing in user exit calls, 14 10 size via PL/SQL: SRW.SET_ATTR, FACE, 13 60 OCI user exits, 14 3 OLE objects, property sheet, 8 84 OLE2 object properties, name, 8 8 OLE2 objects activating, 16 4 boilerplate in the layout, 16 4 columns in the data model, 16 4 integration with Oracle Reports, 16 4 popup menu, 7 19 show object types, 7 19 tools, 7 15 OLE2 package, definition of, 13 39 ONFAILURE keyword for R25DES, 1 45 keyword for R25RUN, 1 29
Index 15
ONSUCCESS keyword for R25DES, 1 44 keyword for R25RUN, 1 29 OPS$ ID, 1 8 ORA_FFI package, definition of, 13 39 ORA_NLS package, definition of, 13 39 ORA_PROF package, definition of, 13 39 ORACLE Call Interface user exits, 14 3 integration with Oracle Reports, 16 2 NonORACLE user exits, 14 3 Precompiler Interface user exits, 14 3 Oracle Graphics integration with Oracle Reports, 16 6 performance with Oracle Reports, 17 13 tool, 7 14 Oracle Graphics display, 8 73 placing in Layout painter, 8 75 Oracle Graphics display properties display column, 8 78 display name, 8 76 display parameter, 8 77 display query, 8 79 name, 8 8 report column, 8 79 report column, for display parameters, 8 77 source, 8 80 Oracle Procedure Builder, 13 35 interpreter, 13 35 packages, 13 39 program unit editor, 13 35 Oracle Programmatic Interface See also call interface supported host languages, 15 2 Oracle Reports Server, invoked by R25RUN BACKGROUND=YES, 1 31 Oracle Reports tables description, 18 12 installing, 19 3 Oracle*Mail. See Mail ORDER BY clauses, added to by Oracle Reports, 17 6
ORIENTATION keyword for R25DES, 1 46 keyword for R25RUN, 1 30 Output device type. See destination type OVERWRITE keyword for R25CONV, 1 14
P
Packaged user exits. See user exits, packaged Packages. See PL/SQL, packages Page break after, 8 9 rules, 8 9 rules for conflicting properties, 8 2 Page break before, 8 11 rules, 8 11 rules for conflicting properties, 8 2 Page dimensions for report, character mode default, 4 14 options, 4 14 Page height for report, 4 6 default, 4 6, 4 10 options, 4 6, 4 10 rules, 4 6, 4 10 Page numbering, 8 52 dialog box, 8 52 example of changing via PL/SQL, 13 48 examples, 8 54 include, 8 53 increment by, 8 54 reset at, 8 54 rules, 8 56 start at, 8 54 Page protect, 8 12 examples, 8 12 rules, 8 14 rules for conflicting properties, 8 2 Page size, character mode setting, 4 14 Page width for report, 4 7 default, 4 7 options, 4 7 rules, 4 7 Page, maximum records, 8 33 examples, 8 34 Pagedependent references, 8 25
Index 16
Pages creating layout, 7 20 creating parameter form, 9 9 deleting layout, 7 20 deleting parameter form, 9 9 using as field source, 8 57 Pages, keeping objects together on keep with anchoring object, 8 6 minimum widow records, 8 34 page protect, 8 12 PAGESIZE keyword for R20CONV, 1 15 keyword for R25DES, 1 42 keyword for R25RUN, 1 27 Palettes color, F 4 pattern names, F 2 Panel number, field source, 8 57 Panel print order, 4 7 default, 4 8 options, 4 8 PARAM keyword for R25DES, 1 47 keyword for R25RUN, 1 32 Parameter form boilerplate properties, 10 4 name, 10 4 type, 10 5 Parameter Form defaulting, 2 47 Parameter form editor, 9 1 components, 9 5 definition and purpose, 9 4 navigation, 9 8 objects, 9 5 pages, 9 5, 9 8 painting region, 9 5 popup menu, 9 7 Parameter form field properties, 10 2 datatype, 10 2 name, 10 2 source, 10 3 Parameter form properties form height, 4 10 form width, 4 10 number of pages, 4 11 previewer title, 4 11 Parameter form, runtime, 9 2
Parameter properties, 6 45 add to list of values, 6 51 comment tab, 6 52 data/selection tab, 6 50 datatype, 6 47 general tab, 6 47 hide first column, 6 52 initial value, 6 48 input mask, 6 48 name, 6 49 remove from list of values, 6 51 restrict list to predetermined values, 6 51 SELECT statement, 6 51 static list, 6 51 validation trigger, 13 27 value, 6 52 width, 6 49 Parameter references, E 3 bind, E 4 lexical, E 5 rules, E 3 Parameters replacing multiple values via lexical, E 5 system, 6 45 user, 6 45 PARAMFORM keyword for R25DES, 1 36 keyword for R25RUN, 1 19 performance, 17 16 Parent columns, 6 13 Parent group, 6 13 Parentchild relationships. See links, data model Parsing, 6 6 Pascal, Pro*Pascal, 14 3 Passing arguments. See user exits, passing values Patterns names of, F 2 via PL/SQL: SRW.SET_ATTR, BORDPATT, 13 59 Performance ARRAYSIZE, 17 16 ASCII driver, 17 17 break columns, 17 9 CDE_MM.GET_REF, 17 7
Index 17
COPIES, 17 17 data model suggestions, 17 5 design interface suggestions, 17 3 design preferences, 17 4 external libraries, 17 15 file searching, 17 19 format triggers, 17 13 formatting attributes, 17 12 image resolution, 17 12 indexes, 17 7 local PL/SQL, 17 14 LONGCHUNK, 17 16 matrix reports, 17 9 maximum rows and group filters, 17 8 MODE, 17 17 monitoring, 17 2 number of queries, 17 5 Oracle Graphics integration, 17 13 Oracle Reports query modifications, 17 6 PARAMFORM, 17 16 PL/SQL, 17 13 previewer, 17 17 report templates, 17 4 RUNDEBUG, 17 17 runtime, 17 15 sizing, 17 12 SQL statements faster, 17 6 SQL TRACE, 17 2 SRW.DO_SQL, 17 7, 17 14 SRW.SET_ATTR, 17 15 storage, 17 18 stored procedures, 17 14 system suggestions, 17 18 table sharing, 17 19 total number of pages, 17 13 tracing, 17 2 transparent objects, 17 12 unused frames, 17 11 word wrapping, 17 12 Physical page definition, 11 4 number, field source, 8 57 PL/l, Pro*PL/l, 14 3 PL/SQL, 13 1 See also PL/SQL packaged exceptions, functions, procedures column and parameter references, E 3 compiling, error messages, 13 38
compiling, multiple constructs, 13 37 compiling, single constructs, 13 37 construct types, 13 2 description of, 13 2 development environment. See Oracle Procedure Builder editing in Program Unit editor, 13 35 errors, trapping with exceptions, 13 11 exceptions, manually created, 13 11 exceptions, packaged, 13 11, 13 12 functions, definition of, 13 4 functions, examples of, 13 5 functions, syntax of, 13 4 global variables, advantage of, 13 8 icon in Object Navigator, 12 6 interpreter, 13 35 nonvalue constructs, definition of, 13 6 nonvalue constructs, types of, 13 6 objects with, 13 15 overview, 13 2 package, definition of, 13 41 packages, examples of, 13 9 packages, syntax of, 13 9 performance, 17 13 procedures, definition of, 13 6 procedures, examples of, 13 8 procedures, syntax of, 13 7 purpose of, 13 2 referencing Oracle Reports objects in, 13 32 restrictions within Oracle Reports, 13 33 rules, 13 33 SRW package and its contents, 13 41 SRW package, overview of, 13 41 stored program unit stubs, 13 34 supported versions, 13 33 trapping success or failure in, 13 11 types of, 13 2 usage of, 13 2 usercreated packages, definition of, 13 8 valid constructs for each object, 13 15 value constructs, definition of, 13 4 value constructs, types of, 13 4 PL/SQL exceptions definition of, 13 11 example of packaged one, 13 13 packaged with Oracle Reports, 13 12 packaged with PL/SQL, 13 12 packaged, definition of, 13 11
Index 18
PL/SQL function, used as a formula, 13 25 PL/SQL packaged exceptions descriptions of, 13 41 SRW.CONTEXT_FAILURE, 13 42 SRW.DO_SQL_FAILURE, 13 46 SRW.INTEGER_ERROR, 13 48 SRW.MAXROW_INERR, 13 48 SRW.MAXROW_UNSET, 13 49 SRW.NULL_ARGUMENTS, 13 51 SRW.PROGRAM_ABORT, 13 52 SRW.RUN_REPORT_BATCHNO, 13 57 SRW.RUN_REPORT_FAILURE, 13 57 SRW.TRUNCATED_VALUE, 13 70 SRW.UNKNOWN_QUERY, 13 70 SRW.UNKNOWN_USER_EXIT, 13 71 SRW.USER_EXIT_FAILURE, 13 73 PL/SQL packaged functions definition of, 13 41 SRW.GETERR_RUN, 13 47 PL/SQL packaged procedures CDE_MM.GET_REF, 13 40 definition of, 13 41 SRW.BREAK, 13 41 SRW.DO_SQL, 13 43 SRW.GET_PAGE_NUM, 13 47 SRW.MESSAGE, 13 50 SRW.REFERENCE, 13 53 SRW.RUN_REPORT, 13 54 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_ADDOPTION, 13 67 SRW.TRACE_END, 13 67 SRW.TRACE_REMOPTION, 13 68 SRW.TRACE_START, 13 68 SRW.USER_EXIT, 13 71 SRW.USER_EXIT20, 13 73 PL/SQL subprograms, 13 22 PL/SQL text example, 13 22 Placeholder column properties, 6 42 example, 6 43 general tab, 6 44 rules, 6 44
Placeholders, tool, 5 6 Placement of fields, 8 41 of Oracle Graphics display, 8 75 of repeating frames, 8 28 Plus/minus, in Object Navigator, 12 5 PostScript, printer definitions, B 2 Preferences, file, 18 5 Preview formatting screen output via R25DES, 1 37 formatting screen output via R25RUN, 1 20 Previewer See also previewer runtime settings accessing, 11 3 accessing multimedia objects in, 11 8 components, 11 3 definition and purpose, 11 2 magnifying the contents, 11 7 modifying components, 11 4 moving from section to section, 11 5 navigation, 11 5 performance, 17 17 splitting the viewing region, 11 6 title, 11 4 viewing region, 11 4 Previewer runtime settings characters per page, 4 14 disable host, 4 13 disable split, 4 13 disable zoom, 4 13 hint line, 4 13 start in zoom, 4 15 status line, 4 14 suppress previewer title, 4 15 title, 4 11 use character units in designer, 4 15 Print condition, 8 15 algorithm for *Default for layout objects, 2 47 examples, 8 17 rules, 8 18 rules for conflicting properties, 8 2 type, 8 15
Index 19
Print direction, 8 35 default, 8 36 examples, 8 36 options, 8 35 rules, 8 39 Printer sending parts of a report to different ones, 13 54 sending previewer output to, 11 11 sending reports to via R25RUN, 1 20 Printer codes, 8 26 after, 8 27 before, 8 27 conditional, example, 13 61 examples, 8 26 tab, 8 26 via PL/SQL: SRW.SET_ATTR, AFTCODE, 13 59 via PL/SQL: SRW.SET_ATTR, BEFCODE, 13 59 Printer definitions creating or modifying, B 3 description of, B 2 example of, B 9 file syntax of, B 3 filesearching method, 18 10 packaged with Oracle Reports, B 2 Printer name, destination name. See destination type Printing, controlling frequency, 8 15 AUTOCOMMIT keyword for R25DES, 1 49 keyword for R25RUN, 1 34 PRINTJOB keyword for R25DES, 1 47 keyword for R25RUN, 1 32 Privileges granting to users, 19 4 revoking from users, 19 4 Pro*Ada call interface, 15 6 user exits, 14 3 Pro*C call interface, 15 6 user exits, 14 3
Pro*COBOL call interface, 15 7 user exits, 14 3 Pro*FORTRAN call interface, 15 7 user exits, 14 3 Pro*Pascal call interface, 15 8 user exits, 14 3 Pro*PL/l call interface, 15 8 user exits, 14 3 Procedure calls. See call interface Procedures. See PL/SQL, procedures Product order, 6 33 examples, 6 34 rules, 6 38 PROFILE See also Tracing keyword for R25DES, 1 43 keyword for R25RUN, 1 28 Program Unit editor, 13 35 name list, 13 36 object list, 13 36 type list, 13 36 PROGRAM_ABORT. See L/SQL packaged exceptions, SRW.PROGRAM_ABORT Properties data, 6 1 layout, 8 1 Property sheet navigation, v Property sheets boilerplate, 8 59 column, 6 17 database column, 6 27 field, 8 41 formula column, 6 41 frame, 8 28 group, 6 14 OLE object, 8 84 Oracle Graphics display, 8 73 parameter, 6 45 parameter form boilerplate, 10 4 parameter form field, 10 2
Index 20
placeholder column, 6 42 query, 6 2 repeating frame, 8 28 report trigger, 13 17 summary column, 6 27 PUT. See EXEC IAF PUT
Q
Queries See also query properties reducing fetch via PL/SQL, SRW.SET_MAXROW, 13 66 referencing columns and parameters, E 3 tool, 5 6 Query properties, 6 2 child column, 6 12 comment tab, 6 8 condition, 6 12 external query, 6 3 general tab, 6 2 maximum rows, 6 4 name, 6 5 SELECT statement, 6 5 SELECT statement example, 6 5 SELECT statement rules, 6 6
R
R25CONV BATCH keyword, 1 15 CMDFILE keyword, 1 14 definition of, 1 9 DEST keyword, 1 13 DTYPE keyword, 1 12 DUNIT keyword, 1 15 FORMSIZE keyword, 1 16 LOGFILE keyword, 1 14 OVERWRITE keyword, 1 14 PAGESIZE keyword, 1 15 SOURCE keyword, 1 11 STYPE keyword, 1 11 USERID keyword, 1 7, 1 10 USERID rules, 1 10, 1 11 R25DES ACCESS keyword, 1 46 ARRAYSIZE keyword, 1 37
AUTOCOMMIT keyword, 1 49 BACKGROUND keyword, 1 46 BUFFERS keyword, 1 42 CMDFILE keyword, 1 36 COPIES, 1 39 COPIES keyword, 1 39 CURRENCY keyword, 1 40 DECIMAL keyword, 1 40 definition of, 1 35 DESFORMAT keyword, 1 39 DESNAME keyword, 1 38 DESTYPE keyword, 1 37 displaying reports as PostScript output via, 1 37 ERRFILE keyword, 1 45 LONGCHUNK keyword, 1 45 MODE keyword, 1 46 MODULE keyword, 1 36 ONFAILURE keyword, 1 45 ONSUCCESS keyword, 1 44 ORIENTATION keyword, 1 46 PAGESIZE keyword, 1 42 PARAM keyword, 1 47 PARAMFORM keyword, 1 36 PRINTJOB keyword, 1 47 PROFILE keyword, 1 43 READONLY keyword, 1 41 REPORT keyword, 1 36 RUNDEBUG keyword, 1 44 sending reports to files via, 1 37 sending reports to Oracle*Mail users via, 1 37 sending reports to printers via, 1 37 sending reports to the screen via, 1 37 THOUSANDS keyword, 1 40 TRACEFILE keyword, 1 48 TRACEMODE keyword, 1 48 TRACEOPTS keyword, 1 48 USERID keyword, 1 7 R25MPRT. See Oracle Reports Migration Guide R25MREP. See Oracle Reports Migration Guide R25RUN ARRAYSIZE keyword, 1 20 AUTOCOMMIT keyword, 1 34 BACKGROUND keyword, 1 31 BATCH keyword, 1 26 BUFFERS keyword, 1 26 CMDFILE keyword, 1 19
Index 21
COPIES keyword, 1 23 CURRENCY keyword, 1 23 DECIMAL keyword, 1 24 definition of, 1 17 DESFORMAT keyword, 1 22 DESNAME keyword, 1 21 DESTYPE keyword, 1 20 displaying reports in PostScript format via, 1 20 ERRFILE keyword, 1 30 KEYIN keyword, 1 30 KEYOUT keyword, 1 30 LOGFILE keyword, 1 25 LONGCHUNK keyword, 1 30 MODE keyword, 1 31 MODULE keyword, 1 18 ONFAILURE keyword, 1 29 ONSUCCESS keyword, 1 29 ORIENTATION keyword, 1 30 PAGESIZE keyword, 1 27 PARAM keyword, 1 32 PARAMFORM keyword, 1 19 PRINTJOB keyword, 1 32 PROFILE keyword, 1 28 READONLY keyword, 1 24 REPORT keyword, 1 18 RUNDEBUG keyword, 1 28 sending reports to files via, 1 20 sending reports to Oracle*Mail users via, 1 21 sending reports to printers via, 1 20 sending reports to the screen via, 1 20 TERM keyword, 1 20 THOUSANDS keyword, 1 23 TRACEFILE keyword, 1 33 TRACEMODE keyword, 1 33 TRACEOPTS keyword, 1 33 USERID keyword, 1 7 Raw datatype, 6 20 RAW MLSLABEL, 6 21 RDF file. See .rdf Read from file, 6 23 examples, 6 23 rules, 6 24 READONLY avoid with EXEC ORACLE, 14 8 avoid with EXEC SQL, 14 5
avoid with SRW.DO_SQL, 13 44 keyword for R25DES, 1 41 keyword for R25RUN, 1 24 Records maximum per page for repeating frame, 8 33 minimum widow for repeating frame, 8 34 REF, datatype of column, 6 20 REFERENCE. See PL/SQL packaged procedures, SRW.REFERENCE References to external PL/SQL libraries, 13 16 to external queries, 6 3 References to parameters and columns, E 3 bind, E 4 lexical, E 5 rules, E 3 Referencing terminal resource files, B 21 Remote login, 1 8 Remove from parameter LOV, 6 51 Rep file, .rep. See .rep Repeating frame properties, 8 28 column mode, 8 29 comment, 8 27 format trigger, 13 28 horizontal sizing, 8 4 horizontal spacing, 8 33 keep with anchoring object, 8 6 maximum records per page, 8 33 minimum widow records, 8 34 name, 8 8 page break after, 8 9 page break before, 8 11 page protect, 8 12 print condition, 8 15 print direction, 8 35 printer codes, 8 26 source, 8 39 vertical sizing, 8 20 vertical spacing, 8 40 Repeating frames See also repeating frame properties names, D 3 placing in layout editor, 8 28 tool, 7 13
Index 22
REPORT keyword for R25DES, 1 36 keyword for R25RUN, 1 18 Report query properties, 6 2 regions, 7 4 Report body. See body Report margins. See margins Report properties charactermode settings, 4 11 comment, 4 15 for parameter form, 4 11 for report, 4 7, 4 9 for report header, 4 5 for report length, 4 5 for report trailer, 4 6 for Runtime Parameter Form, 4 10 form height, 4 10 form width, 4 10 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 previewer title, 4 11 runtime settings, 4 11 unit of measurement, 4 9 Report templates, 17 4 Report triggers, 13 17 when trigger fires, 13 17 Reports converting (R25CONV) via call from 3GL program, 15 2, 15 3 converting report definitions, 1 9 creating printer definitions for, B 3 creating terminal definitions for, B 15 defining and maintaining, 1 35 deleting, 19 5 designing (R25DES) via call from 3GL program, 15 2, 15 3 documenting, 19 6 modifying key bindings for, B 17 moving between files and the database, 19 5 on reports, 19 6
running (R25ISV) via call from 3GL program, 15 2, 15 3 running multiple, 13 54 upgrading (R25MREP) via call from 3GL program, 15 2, 15 3 upgrading from previous versions, 19 5 REPORTS_TMP, 18 11 REPORTS25_PATH, 18 11 REPORTS25_TERMINAL, 18 11 Reset at, 6 39 example, 6 39 options, 6 39 rules, 6 40 Reset group. See reset; reset at Reshaping tool, 7 11 Restricting parameter values format of, 6 48 to list of values, 6 51 via validation trigger, 13 27 Restrictions. See rules Revoking access, using SQL scripts, 19 4 Rex file. See .rex Right mouse button, in Object Navigator, 12 4 ros.sql script, 19 3 rosdrop.sql script, 19 3 rosgnt.sql script, 19 3 Rotating rules, 7 10 tool, 7 10 Rules for bind references, E 4 for break order, 6 20 for call interface, 15 4 for child columns in a link, 6 12 for child query in a link, 6 12 for column datatype, 6 21 for column format, 6 22 for column functions, 6 32 for column width, 6 26 for compute at, 6 31 for database columns, 6 27 for designing character mode reports, A 3 for executable syntax, 1 4 for external queries, 6 3
Index 23
for filter conditions, 13 24 for formula columns, 6 41 for formulas, 13 26 for groups, 6 15 for initial value, 6 48 for input mask, 6 49 for lexical references, E 6 for links, 6 11 for maximum rows, 6 4 for parameter datatype, 6 47 for parent groups in a link, 6 13 for PL/SQL, 13 33 for placeholder columns, 6 44 for product order, 6 38 for read from file, 6 24 for reset at, 6 40 for searching in Object Navigator, 12 16 for SELECT statement, 6 6 for SQL clause, 6 14 for summary source, 6 40 for type of filter, 6 16 for user exits, 14 12 for validation triggers, 13 27 for value if null, 6 25 for width of parameter, 6 50 logical page size, 4 5 report column, for display column, 8 79 report column, for display parameter, 8 77 rules for terminal definitions, B 21 RUN_REPORT. See PL/SQL packaged procedures, SRW.RUN_REPORT RUN_REPORT_BATCHNO. See PL/SQL packaged exceptions, SRW.RUN_REPORT_BATCHNO RUN_REPORT_FAILURE. See PL/SQL packaged exceptions, SRW.RUN_REPORT_FAILURE RUNDEBUG keyword for R25DES, 1 44 keyword for R25RUN, 1 28 performance, 17 17 Runfile. See .rep Running reports displaying as PostScript via R25DES, 1 37
displaying as PostScript via R25RUN, 1 20 from the command line, 1 18 multiple, 13 54 sending portions to different mailids, 13 54 sending portions to different printers, 13 54 sending to files via R20RUN, 1 20 sending to files via R25DES, 1 37 sending to Oracle*Mail users via R20RUN, 1 21 sending to Oracle*Mail users via R25DES, 1 37 sending to printers via R20RUN, 1 20 sending to printers via R25DES, 1 37 sending to the screen via R20RUN, 1 20 sending to the screen via R25DES, 1 37 via call from 3GL program, 15 2, 15 3 Running summary, 6 39 Runtime parameter form, 9 2 access, 9 2 definition and purpose, 9 2 pages, 9 8 Runtime settings characters per page, 4 14 convert bitmapped 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 previewer title, 4 11 start in zoom, 4 15 suppress previewer title, 4 15 use character units in designer, 4 15 RWEATS user exit description of, 14 16 syntax, 14 16 RWECAT user exit syntax, 14 20 V2.0 & V1.1 packaged user exit, 14 20 RWECPF user exit description of, 14 20 syntax, 14 20
Index 24
RWECTY user exit description of, 14 20 syntax, 14 21 RWENOP. See placeholders RWEPLS user exit, description of, 14 21
S
Scaling, performance cost, 17 12 Screen sending reports to via R25DES, 1 37 sending reports to via R25RUN, 1 20 Scripts droprep.sql, 19 2 ros.sql, 19 3 rosdrop.sql, 19 3 rosgnt.sql, 19 3 srw2bild.sql, 19 2 srw2drop.sql, 19 2 srw2grnt.sql, 19 2 srw2lmt.sql, 19 2 srw2pup.sql, 19 2 srw2pup7.sql, 19 2 srw2rvke.sql, 19 3 toolbild.sql, 19 3 tooldrop.sql, 19 3 toolgrnt.sql, 19 3 toolrvke.sql, 19 3 using in Oracle Reports, 19 2 vgbild.sql, 19 3 vgdrop.sql, 19 3 vggrnt.sql, 19 3 vgrvke.sql, 19 3 Searching in Object Navigator, 12 16 Secure systems datatypes, 6 21 Security, database, establishing, 18 31 SELECT statement bind references, E 4 errors, E 3 for parameter LOV, 6 51 lexical references, E 5 parameter and column references, E 3 query, 6 5 Selecting tool, layout editor, 7 9 tool, data model editor, 5 6
Sending reports to files via R25DES, 1 37 to files via R25RUN, 1 20 to Oracle*Mail users via R25DES, 1 37 to Oracle*Mail users via R25RUN, 1 21 to printers via R25DES, 1 37 to printers via R25RUN, 1 20 to the screen via R25DES, 1 37 SET TRANSACTION READONLY. See SRW.DO_SQL SET_ATTR. See PL/SQL packaged procedures, SRW.SET_ATTR SET_FIELD_CHAR. See PL/SQL packaged procedures, SRW.SET_FIELD_CHAR SET_FIELD_DATE. See PL/SQL packaged procedures, SRW.SET_FIELD_DATE SET_FIELD_NUM. See PL/SQL packaged procedures, SRW.SET_FIELD_NUM SET_MAXROW. See PL/SQL packaged procedures, SRW.SET_MAXROW Shift key, for constrained mode, 7 8 Show object types (OLE2), 7 19 Size conditional text, example, 13 63 rules, 8 23 via PL/SQL: SRW.SET_ATTR, SZ, 13 60 Skip, hidden, 8 80 Sound accessing, 11 8 in buttons, 11 8 Sound dialog forward, 11 8 options, 11 9 play, 11 9 record, 11 9 rewind, 11 9 slidebar, 11 9 stop, 11 9 Source for field, 8 56 example, 8 57 options, 8 56 rules, 8 57 Source for Oracle Graphics display, 8 80 Source for parameter form field, 10 3 rules, 10 3
Index 25
Source for repeating frame, 8 39 Source for summary column, 6 40 rules, 6 40 SOURCE keyword for R25CONV, 1 11 Spacing horizontal, 8 33 vertical, 8 40 vertical via PL/SQL: SRW.SET_ATTR, CUSTOM, 13 60 vertical via PL/SQL: SRW.SET_ATTR, GSPACING, 13 60 Special characters, asterisks in fields, 8 24, 8 49 Split function in previewer horizontally, 11 6 vertically, 11 6 SQL scripts packaged with Oracle Reports, 19 2 statements in user exits, 14 5 TRACE, 17 2 using NLS, C 3, C 5 SQL clause, 6 13 default, 6 13 options, 6 13 rules, 6 14 SQL SELECT statement errors, E 3 SQL*Net, 16 2 SRW2_ANCHOR, 18 13 SRW2_BODY_LOCATION, 18 13 SRW2_BOILERPLATE, 18 14 SRW2_COLUMN, 18 15 SRW2_DATA_MODEL, 18 17 SRW2_DISPLAY_TAG, 18 17 SRW2_ELEMENT, 18 18 SRW2_FIELD, 18 19 SRW2_FRAME, 18 20 SRW2_GROUP, 18 21 SRW2_LAYOUT, 18 22 SRW2_LAYOUT_GROUP, 18 23 SRW2_LINK, 18 24 SRW2_MATRIX, 18 24 SRW2_MODULE, 18 24
SRW2_OG_DOCUMENT, 18 25 SRW2_OGD_COLUMN_MAP, 18 25 SRW2_QUERY, 18 26 SRW2_TEXT_SEGMENT, 18 26 srw2bild.sql script, 19 2 srw2drop.sql script, 19 2 srw2grnt.sql script, 19 2 srw2lmt.sql script, 19 2 srw2pup.sql script, 19 2 srw2pup7.sql script, 19 2 srw2rvke.sql script, 19 3 SRWERB for raising user exit errors, 14 9 User exits, SRWERB, 14 9 Standard deviation, summary function, 6 32 Start in zoom, runtime setting, 4 15 START WITH clauses added by Oracle Reports, 17 6 option for data links, 6 13 Static list, for parameter LOV, 6 51 Status line in data model editor, 5 7 in layout editor, 7 17 Storage, 18 1 Stored program units, stubs, 13 34 String, empty, 1 5 Style, conditional text, example, 13 63 STYPE keyword for R25CONV, 1 11 Sum, summary function, 6 32 Summary, tool, 5 6 Summary column properties, 6 27, 6 32 compute at, 6 29 function, 6 32 general tab, 6 28 product order, 6 33 reset at, 6 39 source, 6 40 Supported file formats, 18 2 Suppress boilerplate labels (headers), 13 29 previewer title, runtime setting, 4 15
Index 26
Syntax call interface, 15 3 EXEC IAF GET, 14 6 EXEC IAF PUT, 14 7 EXEC SQL, 14 5 how to view command line options, 1 3 PL/SQL compiler errors, 13 38 PL/SQL function, 13 4 PL/SQL procedure, 13 7, 13 9 rules for executables, 1 4 RWEATS packaged user exit, call to, 14 16 RWECAT packaged user exit, call to, 14 20 RWECPF packaged user exit, call to, 14 20 RWECTY packaged user exit, call to, 14 21 user exit call, 14 8, 14 10 System output device, sending reports to default devices via R25RUN, 1 21 System parameters, 6 45
T
Tables data tables, 18 12 demo tables, 18 12 dropping Version 1.1 tables, 19 5 integrated, 18 27 Oracle Reports, 18 13 Oracle Reports tables, 18 12 SRW2_ANCHOR, 18 13 SRW2_BODY_LOCATION, 18 13 SRW2_BOILERPLATE, 18 14 SRW2_COLUMN, 18 15 SRW2_DATA_MODEL, 18 17 SRW2_DISPLAY_TAG, 18 17 SRW2_ELEMENT, 18 18 SRW2_FIELD, 18 19 SRW2_FRAME, 18 20 SRW2_GROUP, 18 21 SRW2_LAYOUT, 18 22 SRW2_LAYOUT_GROUP, 18 23 SRW2_LINK, 18 24 SRW2_MATRIX, 18 24 SRW2_MODULE, 18 24 SRW2_OG_DOCUMENT, 18 25 SRW2_OGD_COLUMN_MAP, 18 25
SRW2_QUERY, 18 26 SRW2_TEXT_SEGMENT, 18 26 TOOL_ACCESS, 18 27 TOOL_COMMENT, 18 27 TOOL_DEPEND, 18 27 TOOL_LIBRARY, 18 28 TOOL_LRAW, 18 28 TOOL_LRAW_ID, 18 28 TOOL_LTEXT, 18 28 TOOL_LTEXTID, 18 29 TOOL_MODID, 18 29 TOOL_MODULE, 18 29 TOOL_PLSQL, 18 30 TOOL_ROSSTRINGS, 18 30 Templates, report, 17 4 Temporary files, 18 8 minimizing size, 18 9 TERM, keyword for R25RUN, 1 20 Terminal definitions description of, B 14 filesearching method, 18 10 modifying, B 19 packaged with Oracle Reports, B 14 specifying on command line via R25RUN, 1 20 Terminal resource files how to reference, B 21 rules for usage, B 21 Terminal resources creating or modifying, B 15 modifying key bindings, B 17 modifying terminal definition, B 19 Text color tool, 7 17 conditional color, example, 13 63 conditional spacing, example, 13 63 tool, 7 13 Text string, 8 83 TEXT_IO package, definition of, 13 39 THOUSANDS keyword for R25DES, 1 40 keyword for R25RUN, 1 23 Title, Previewer, 11 4 TK21_ICON, 18 12
Index 27
Tool palette data model editor, 5 5 layout editor, 7 7 parameter form editor, 9 6 TOOL_ACCESS, 18 27 TOOL_COMMENT, 18 27 TOOL_DEPEND, 18 27 TOOL_ENV package, definition of, 13 39 TOOL_ERR package, definition of, 13 39 TOOL_LIBRARY, 18 28 TOOL_LRAW, 18 28 TOOL_LRAW_ID, 18 28 TOOL_LTEXT, 18 28 TOOL_LTEXT_ID, 18 29 TOOL_MODID, 18 29 TOOL_MODULE, 18 29 TOOL_PLSQL, 18 30 TOOL_RES package, definition of, 13 39 TOOL_ROSSTRINGS, 18 30 Toolbar, in Object Navigator, 5 5, 7 7, 9 6, 12 3 toolbild.sql script, 19 3 tooldrop.sql script, 19 3 toolgrnt.sql script, 19 3 toolrvke.sql script, 19 3 Tools menu. See online help system Total logical pages field source, 8 57 performance, 17 13 Total panels, field source, 8 57 Total physical pages field source, 8 57 performance, 17 13 TRACEFILE keyword for R25DES, 1 48 keyword for R25RUN, 1 33 TRACEMODE keyword for R25DES, 1 48 keyword for R25RUN, 1 33 TRACEOPTS keyword for R25DES, 1 48 keyword for R25RUN, 1 33
Tracing performance monitoring, 17 2 systemlevel, 17 3 userlevel, 17 3 Trailer page, 7 6 Tranlsation, NLS, C 7 Transparent objects, performance improvement, 17 12 Triggers action, 13 32 format, 13 28 report, 13 17 validation, 13 27 which report trigger to use, 13 17 Truncation packaged exception to handle successfully, 13 70 possible in form letter reports, 2 41 possible in mailing label reports, 2 41 Trusted ORACLE datatypes, 6 21 Type of filter, 6 15 examples, 6 16 options, 6 16 rules, 6 16 Type of parameter form boilerplate, 10 5 Type of print condition, 8 15 default, 8 17 options, 8 16 Typographic conventions, v
U
uifont.ali, 18 7 Unit of measurement, 4 9 default, 4 9 options, 4 9 UNKNOWN_QUERY. See PL/SQL packaged exceptions, SRW.UNKNOWN_QUERY UNKNOWN_USER_EXIT. See PL/SQL packaged exceptions, SRW.UNKNOWN_USER_EXIT Updating. See DML
Index 28
Upgrading reports from previous versions, 19 5 Use character units in designer, 4 15 User exits, 14 1 See also placeholders (for RWENOP); user exits, packaged call, syntax when passed, 14 8 calling from Oracle Reports, 14 10 DDL, avoid with READONLY, 14 5 definition of, 14 2 error checking, example, 14 22 error messages, defining with SRW.MESSAGE, 14 14 errors, checking via SRW.USER_EXIT_FAILURE, 14 13 errors, raising from the exit, 14 9 errors, raising in PL/SQL, 14 13 example call, 14 22 example, call with PL/SQL error checking, 14 14, 14 15 example, call without error checking, 14 11 example, complete, 14 21 EXEC IAF GET, 14 6 EXEC IAF PUT, 14 7 EXEC ORACLE, 14 7 EXEC SQL, 14 5 implementing, 14 9 nonORACLE, 14 3 OCI (ORACLE Call Interface), 14 3 ORACLE commands, performing, 14 7 Oracle Precompiler Interface, 14 3 performance, 17 14 READONLY, avoid with DDL, 14 5 screen I/O, performing, 14 4 SQL commands, performing, 14 5 SRWERB buffer, 14 9 steps to build, 14 3 supported functions, 14 5 syntax, call, 14 10 syntax, call when passed, 14 8 types, 14 2 values from Oracle Reports, passing, 14 6 values to Oracle Reports, passing, 14 6 writing the program, 14 4 User exits, packaged RWEATS, 14 16
RWECAT, 14 20 RWECPF, V2.0 and V1.1, 14 20 RWECTY, 14 20 RWEPLS, 14 21 Userdefined buttons accessing images, 11 10 accessing sound, 11 8 accessing video, 11 10 USER_EXIT. See PL/SQL packaged procedures, SRW.USER_EXIT USER_EXIT_FAILURE. See PL/SQL packaged exceptions, SRW.USER_EXIT_FAILURE USER_NLS_LANG, C 2 USERID keyword for R25CONV, 1 7, 1 10 keyword for R25DES, 1 7 keyword for R25RUN, 1 7 rules for R25CONV, 1 10, 1 11 Users granting them privileges, 19 4 parameters, 6 45 revoking their privileges, 19 4
V
Validation command line parameters, 13 18 trigger for parameters, 13 27 Value, for parameter LOV, 6 52 Value constructs, PL/SQL, value constructs, 13 4 Value if null, column property, 6 24 rules, 6 25 Varchar, 6 21 Varchar2, 6 21 Variable sizing, 8 21 Variables, placeholders. See placeholders variables, global. See global variables Variance, summary function, 6 32 Version 1.1 tables, dropping, 19 5 Vertical frame for matrix, 8 73
Index 29
Vertical sizing, 8 20 default, 8 21 examples, 8 21 options, 8 20 rules, 8 23 to enhance performance, 17 12 Vertical spacing, 8 40 default, 8 40 rules, 8 40 vgbild.sql script, 19 3 vgdrop.sql script, 19 3 vggrnt.sql script, 19 3 vgrvke.sql script, 19 3 Video accessing, 11 10 in buttons, 11 10 Video dialog mute, 11 10 play, 11 10 stop, 11 10 slidebar, 11 10 sound, 11 10 View menu. See online help system Viewing region, Previewer, 11 4
W
WHERE clauses added by Oracle Reports, 17 6 adding to matrix query, 17 10 for performance, 17 6 option 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 34 rules, 8 35 rules for conflicting properties, 8 2 Width of column, 6 25 default, 6 25 options, 6 25 rules, 6 26 Width of layout object border, via PL/SQL: SRW.SET_ATTR, BORDERWIDTH, 13 59 Width of parameter, 6 49 default, 6 50 options, 6 49 rules, 6 50 Window menu. See online help system Word wrapping, 8 41 performance cost, 17 12
Z
Zoom See also magnify disable for character mode, 4 13 start in for character mode, 4 15
Index 30
Packaged Procedures, Functions,Exception

SRW.BREAK SRW.CONTEXT_ FAILURE SRW.DO_SQL SRW.DO_SQL_FAILURE SRW.GETERR_RUN SRW.GET_PAGE_NUM SRW.INTEGER_ERROR SRW.MAXROW_INERR SRW.MAXROW_UNSET SRW.MESSAGE SRW.NULL_ARGUMENTS SRW.PROGRAM_ABORT SRW.REFERENCE SRW.RUN_REPORT SRW.RUN_REPORT_BATCHNO SRW.RUN_REPORT_FAILURE SRW.SET_ATTR SRW.SET_FIELD_CHAR SRW.SET_FIELD_DATE SRW.SET_FIELD_NUM SRW.SET_MAXROW SRW.TRACE_ADD_OPTION SRW.TRACE_END SRW.TRACE_REM_OPTION SRW.TRACE_START SRW.TRUNCATED_VALUE SRW.UNKNOWN_QUERY SRW.UNKNOWN_USER_EXIT SRW.USER_EXIT SRW.USER_EXIT20 SRW.USER_EXIT_FAILURE
Description
Stops report execution. Stops report when a program unit is run from the wrong context. Executes a specified SQL statement. Stops report when a failure occurs in SRW.DO_SQL. Returns an error message if a failure occurs in SRW.RUN_REPORT. Returns the current page number. Stops report when an invalid integer argument is passed. Stops report when a failure occurs in SRW.SET_MAXROW. Stops report when a failure occurs setting the maximum rows for a query. Displays a specified message and message number. Stops report when a required argument is missing. Stops report when you raise it. Adds the specified object to the dependency list of a program unit. Executes the specified R25RUN command. Stops report when SRW.RUN_REPORT used with BATCH=NO. Stops report when a failure occurs in SRW.RUN_REPORT. Applies attribute settings to layout objects. Sets the value of a character field. Sets the value of a date field. Sets the value of a number field. Sets the maximum number of rows to be retrieved by the specified query. Applies the trace options mask. Stops the logging of trace information. Removes trace options. Begins the logging of trace information. Stops report when a value is truncated. Stops report when a query name is not found by SRW.SET_MAXROW.
Pg.
13 41 13 42 13 43 13 46 13 47 13 47 13 48 13 48 13 49 13 50 13 51 13 52 13 53 13 54 13 57 13 57 13 58 13 64 13 64 13 65 13 66 13 67 13 67 13 68 13 68 13 70 13 70
Stops report when user exit not found by SRW.USER_EXIT or SRW.USER_EXIT20. 13 71 Calls the specified user exit with two arguments. Calls the specified user exit with five arguments. Stops report execution when a user exit fails. 13 71 13 73 13 73
Packaged Procedures, Functions,Exception

SRW.BREAK SRW.CONTEXT_ FAILURE SRW.DO_SQL SRW.DO_SQL_FAILURE SRW.GETERR_RUN SRW.GET_PAGE_NUM SRW.INTEGER_ERROR SRW.MAXROW_INERR SRW.MAXROW_UNSET SRW.MESSAGE SRW.NULL_ARGUMENTS SRW.PROGRAM_ABORT SRW.REFERENCE SRW.RUN_REPORT SRW.RUN_REPORT_BATCHNO SRW.RUN_REPORT_FAILURE SRW.SET_ATTR SRW.SET_FIELD_CHAR SRW.SET_FIELD_DATE SRW.SET_FIELD_NUM SRW.SET_MAXROW SRW.TRACE_ADD_OPTION SRW.TRACE_END SRW.TRACE_REM_OPTION SRW.TRACE_START SRW.TRUNCATED_VALUE SRW.UNKNOWN_QUERY SRW.UNKNOWN_USER_EXIT SRW.USER_EXIT SRW.USER_EXIT20 SRW.USER_EXIT_FAILURE
Description
Stops report execution. Stops report when a program unit is run from the wrong context. Executes a specified SQL statement. Stops report when a failure occurs in SRW.DO_SQL. Returns an error message if a failure occurs in SRW.RUN_REPORT. Returns the current page number. Stops report when an invalid integer argument is passed. Stops report when a failure occurs in SRW.SET_MAXROW. Stops report when a failure occurs setting the maximum rows for a query. Displays a specified message and message number. Stops report when a required argument is missing. Stops report when you raise it. Adds the specified object to the dependency list of a program unit. Executes the specified R25RUN command. Stops report when SRW.RUN_REPORT used with BATCH=NO. Stops report when a failure occurs in SRW.RUN_REPORT. Applies attribute settings to layout objects. Sets the value of a character field. Sets the value of a date field. Sets the value of a number field. Sets the maximum number of rows to be retrieved by the specified query. Applies the trace options mask. Stops the logging of trace information. Removes trace options. Begins the logging of trace information. Stops report when a value is truncated. Stops report when a query name is not found by SRW.SET_MAXROW.
Pg.
13 41 13 42 13 43 13 46 13 47 13 47 13 48 13 48 13 49 13 50 13 51 13 52 13 53 13 54 13 57 13 57 13 58 13 64 13 64 13 65 13 66 13 67 13 67 13 68 13 68 13 70 13 70
Stops report when user exit not found by SRW.USER_EXIT or SRW.USER_EXIT20. 13 71 Calls the specified user exit with two arguments. Calls the specified user exit with five arguments. Stops report execution when a user exit fails. 13 71 13 73 13 73
Chapter Number and Name

Chapter 1, Executables Chapter 2, Defaulting Chapter 3, Menus Chapter 4, Report Properties Chapter 5, Data Model Editor Chapter 6, Data Model Properties
Description
Describes executables and their command line arguments. Describes the defaulting mechanism of Oracle Reports. Menus are described in the online help system. Describes the report property sheet. Describes the components of the Data Model editor. Describes the property sheets of the following: query 62 link 68 group 6 14 database column 6 27 summary column 6 27 formula column 6 41 placeholder column 6 42 parameter 6 45 Describes the components of the Layout Editor. 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 userdefined button 8 80 OLE2 object 8 84 Describes the components of the parameter form editor. Describes the property sheets of parameter form fields and boilerplate. Describes the components of the Previewer. Describes the components of the Object Navigator. Describes the usage of PL/SQL in Oracle Reports. Describes how to create and implement user exits. Describes the interface for calling Oracle Reports from 3GL programs. Describes using Oracle Reports with other products. Describes tips for improving report performance. Describes how Oracle Reports uses files and databases. Describes how to administer Oracle Reports.
Chapter 7, Layout Editor Chapter 8, Layout Properties
Chapter 9, Parameter Form Editor Chapter 10, Parameter Form Properties Chapter 11, Previewer Chapter 12, Object Navigator Chapter 13, PL/SQL Interface Chapter 14, User Exit Interface Chapter 15, Call Interface Chapter 16, Integrating with Other Products Chapter 17, Performance and Tuning Chapter 18, Storage Chapter 19, Administration
Chapter Number and Name

Chapter 1, Executables Chapter 2, Defaulting Chapter 3, Menus Chapter 4, Report Properties Chapter 5, Data Model Editor Chapter 6, Data Model Properties
Description
Describes executables and their command line arguments. Describes the defaulting mechanism of Oracle Reports. Menus are described in the online help system. Describes the report property sheet. Describes the components of the Data Model editor. Describes the property sheets of the following: query 62 link 68 group 6 14 database column 6 27 summary column 6 27 formula column 6 41 placeholder column 6 42 parameter 6 45 Describes the components of the Layout Editor. 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 userdefined button 8 80 OLE2 object 8 84 Describes the components of the parameter form editor. Describes the property sheets of parameter form fields and boilerplate. Describes the components of the Previewer. Describes the components of the Object Navigator. Describes the usage of PL/SQL in Oracle Reports. Describes how to create and implement user exits. Describes the interface for calling Oracle Reports from 3GL programs. Describes using Oracle Reports with other products. Describes tips for improving report performance. Describes how Oracle Reports uses files and databases. Describes how to administer Oracle Reports.
Chapter 7, Layout Editor Chapter 8, Layout Properties
Chapter 9, Parameter Form Editor Chapter 10, Parameter Form Properties Chapter 11, Previewer Chapter 12, Object Navigator Chapter 13, PL/SQL Interface Chapter 14, User Exit Interface Chapter 15, Call Interface Chapter 16, Integrating with Other Products Chapter 17, Performance and Tuning Chapter 18, Storage Chapter 19, Administration
Readers Comment Form

Name of Document: Reports Reference Manual Part No. A324891 Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of 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 Manager Oracle Corporation 500 Oracle Parkway Redwood City, CA 94065 U.S.A. Fax: (415) 5067200 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* *A32489-1*
A324891
Release 2.5

Oracle Reports Reference Manual 2.5

Enviado por

Dados do documento

Descrição original:

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Oracle Reports Reference Manual 2.5

Enviado por

Direitos autorais:

Formatos disponíveis

Reports Reference Manual

Reports Reference Manual

Read This First

Read This First

Oracle Reports Documentation and Related Information

Reports Reference Manual GUI Version

Oracle Reports Documentation

Read This First

How to Use this Book

Major Sections of this Book

Reports Reference Manual GUI Version

UPPERCASE Initial Caps

Read This First

Your Comments Are Welcome

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

PART III Chapter 13

Reports Reference Manual GUI Version

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

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

by command line by icon

Help on Command Line Options

Executable Syntax Rules

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

explicit login 1 7 automatic login 1 7 remote login 1 8

Reports Reference Manual GUI Version

where the following are valid keyword=value arguments:

The following PL/SQL library conversions can be performed using R25CONV:

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

where the following are valid keyword=value arguments:

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Default: Rules: 1. BATCH

Reports Reference Manual GUI Version

Any valid filename in the current directory.

Reports Reference Manual GUI Version

NO means do not perform extra runtime error checking. Default: ONSUCCESS NO

Reports Reference Manual GUI Version

Examples: 1. Following is an example of R25RUN specifying a parameters value:

Reports Reference Manual GUI Version

Any valid filename. trace.dat

Reports Reference Manual GUI Version

where the following are valid keyword=value arguments:

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version

Default: Rules: 1. PAGESIZE

Reports Reference Manual GUI Version

Any valid filename in the current directory.

Reports Reference Manual GUI Version

Reports Reference Manual GUI Version