Untitled DocumentCopyright Oracle Corporation, 1999. All rights
reserved.
This documentation contains proprietary information of Oracle
Corporation. It is provided under a license agreement containing
restrictions on use and disclosure and is also protected by
copyright law. Reverse engineering of the software is prohibited.
If this documentation is delivered to a U.S. Government Agency of
the Department of Defense, then it is delivered with Restricted
Rights and the following legend is applicable:
Restricted Rights Legend Use, duplication or disclosure by the
Government is subject to restrictions for commercial computer
software and shall be deemed to be Restricted Rights software under
Federal law, as set forth in subparagraph (c) (1) (ii) of DFARS
252.227-7013, Rights in Technical Data and Computer Software
(October 1988).
This material or any portion of it may not be copied in any form or
by any means without the express prior written permission of Oracle
Corporation. Any other copying is a violation of copyright law and
may result in civil and/or criminal penalties.
If this documentation is delivered to a U.S. Government Agency not
within the Department of Defense, then it is delivered with
“Restricted Rights,” as defined in FAR 52.227-14, Rights in
Data-General, including Alternate III (June 1987).
The information in this document is subject to change without
notice. If you find any problems in the documentation, please
report them in writing to Education Products, Oracle Corporation,
500 Oracle Parkway, Box SB-6, Redwood Shores, CA 94065. Oracle
Corporation does not warrant that this document is
error-free.
All references to Oracle and Oracle products are trademarks or
registered trademarks of Oracle Corporation.
All other products or company names are used for identification
purposes only and may be trademarks of their respective
owners.
.....................................................................................................................................................
Oracle Developer: Build Reports iii
.....................................................................................................................................................
Contents
What Is Oracle Developer? 1-5
Introducing the Oracle Developer Release 6.0 Components 1-9
Report Builder Components 1-13
Customizing Your Oracle Reports Session 1-21
Oracle Reports Environment Variables 1-25
Oracle Reports Help Options 1-27
Introducing the Course Application 1-29
Summary 1-31
Practice Session: Lesson 1 1-34
Lesson 2: Designing and Running Reports Overview 2-3
Designing Reports 2-5
Design Considerations 2-7
Running a Report 2-17
Summary 2-29
Practice Session: Lesson 2 2-32
.....................................................................................................................................................
iv Oracle Developer: Build Reports
.....................................................................................................................................................
Contents
Report Executables 3-5
Practice Session: Lesson 3 3-26
Lesson 4: Creating Reports Using the Report Wizard Overview
4-3
Invoking Report Builder and the Report Wizard 4-5
Creating a Tabular Report Using the Wizard 4-7
Creating Other Report Styles 4-23
Summary 4-33
Practice Session: Lesson 4 4-36
Lesson 5: Enhancing Reports in the Live Previewer Overview
5-3
What Is the Live Previewer? 5-5
Modifying a Report in the Live Previewer 5-7
Summary 5-22
Practice Session: Lesson 5 5-25
Lesson 6: Managing Report Templates Overview 6-3
Using the Report Templates 6-5
Modifying a Template 6-7
Summary 6-17
Practice Session: Lesson 6 6-20
.....................................................................................................................................................
Oracle Developer: Build Reports v
.....................................................................................................................................................
Contents
Storage Methods and Requirements 7-5
Documenting Your Reports 7-9
Summary 7-19
Practice Session: Lesson 7 7-22
Lesson 8: Enhancing Reports Using the Data Model: Creating Queries
and Groups
Overview 8-3
Changing the Group Structure 8-13
The Group Hierarchy 8-15
Filtering Data in a Group 8-21
Adding New Data 8-23
Using Data Links to Structure Data 8-36
Efficiency Issues: Multiple- or Single-Query Hierarchy 8-42
Summary 8-44
Practice Session: Lesson 8 8-47
Lesson 9: Enhancing Reports Using the Data Model: Creating Columns
Overview 9-3
The Data Model Column Types 9-5
Maintaining Database Columns 9-7
Using a Database Column to Output Contents of a File 9-9
.....................................................................................................................................................
vi Oracle Developer: Build Reports
.....................................................................................................................................................
Contents
Creating Formula Columns 9-21
Creating Placeholder Columns 9-23
Summary 9-27
Practice Session: Lesson 9 9-30
Lesson 10: Enhancing Reports Using the Layout Model Overview
10-3
Viewing the Layout Model Regions 10-5
Viewing the Report Sections in the Layout Model 10-7
Designing Multipanel Reports 10-9
Creating Layout Objects 10-19
Creating Additional Layouts in a Report 10-23
Creating Variable Length Lines 10-25
Displaying a Multimedia File from a Button 10-27
Creating Explicit Anchors 10-29
Practice Session: Lesson 10 10-36
Lesson 11: Modifying Properties Overview 11-3
Modifying Layout Object Properties 11-5
Displaying File Contents with a Link File 11-7
Modifying Common Layout Properties 11-13
Sizing Objects 11-15
.....................................................................................................................................................
Contents
Modifying Properties of a Repeating Frame 11-37
Summary 11-43
Practice Session: Lesson 11 11-46
Lesson 12: Creating and Using Report Parameters Overview 12-3
Creating User Parameters 12-5
Creating a List of Values 12-15
Referencing System Parameters 12-19
Summary 12-27
Practice Session: Lesson 12 12-30
Lesson 13: Embedding a Chart in a Report Overview 13-3
Creating and Embedding a Graphics Chart in a Report 13-5
Embedding an Existing Chart in a Report 13-9
Summary 13-11
Practice Session: Lesson 13 13-14
Lesson 14: Enhancing Matrix Reports Overview 14-3
The Matrix Data Model 14-5
Matrix Layout 14-7
Summary 14-19
Practice Session: Lesson 14 14-22
.....................................................................................................................................................
viii Oracle Developer: Build Reports
.....................................................................................................................................................
Contents
Types of Triggers in Reports 15-5
Using Report Triggers 15-7
Writing Common Code 15-27
Practice Session: Lesson 15 15-32
Lesson 16: Using the Report Builder Built-In Package Overview
16-3
Contents of the Report Builder Built-in Package 16-5
Outputting Messages 16-7
Restricting Data 16-15
Initializing Fields 16-17
Practice Session: Lesson 16 16-28
Lesson 17: Maximizing Performance Using the Reports Server Overview
17-3
Why Use a Remote Server? 17-5
Reports Server Architecture and Configuration 17-9
Reports Server Clustering 17-11
Summary 17-33
Practice Session: Lesson 17 17-36
.....................................................................................................................................................
Oracle Developer: Build Reports ix
.....................................................................................................................................................
Contents
Different Development and Run-Time Environments 18-5
Developing Reports to Run in Different GUIs 18-7
Building Character Mode Reports 18-9
Building Reports to Run in Different Languages 18-13
Summary 18-17
Practice Session Solutions: Lesson 1 A-3
Practice Session Overview: Lesson 2 A-8
Practice Session Solutions: Lesson 2 A-9
Practice Session Overview: Lesson 3 A-14
Practice Session Solutions: Lesson 3 A-15
Practice Session Overview: Lesson 4 A-18
Practice Session Solutions: Lesson 4 A-19
Practice Session Overview: Lesson 5 A-24
Practice Session Solutions: Lesson 5 A-25
Practice Session Overview: Lesson 6 A-30
Practice Session Solutions: Lesson 6 A-31
Practice Session Overview: Lesson 7 A-34
Practice Session Solutions: Lesson 7 A-35
Practice Session Overview: Lesson 8 A-37
Practice Session Solutions: Lesson 8 A-38
Practice Session Overview: Lesson 9 A-44
Practice Session Solutions: Lesson 9 A-45
Practice Session Overview: Lesson 10 A-51
Practice Session Solutions: Lesson 10 A-52
Practice Session Overview: Lesson 11 A-57
Practice Session Solutions: Lesson 11 A-58
Practice Session Overview: Lesson 12 A-61
Practice Session Solutions: Lesson 12 A-62
.....................................................................................................................................................
x Oracle Developer: Build Reports
.....................................................................................................................................................
Contents
Practice Session Overview: Lesson 13 A-65
Practice Session Solutions: Lesson 13 A-66
Practice Session Overview: Lesson 14 A-69
Practice Session Solutions: Lesson 14 A-70
Practice Session Overview: Lesson 15 A-75
Practice Session Solutions: Lesson 15 A-76
Practice Session Overview: Lesson 16 A-81
Practice Session Solutions: Lesson 16 A-82
Practice Session Overview: Lesson 17 A-90
Practice Session Solutions: Lesson 17 A-91
Appendix B: Table Descriptions and Data Summit Sporting Goods
Database Diagram B-2
S_CUSTOMER Description B-3
S_CUSTOMER Data B-4
S_EMP Description B-9
S_EMP Data B-10
S_ITEM Description B-13
S_ITEM Data B-14
S_PRODUCT Description B-17
S_PRODUCT Data B-18
Appendix C: Frequently Asked Questions Frequently Asked Questions
C-2
Frequently Asked Questions and Answers C-3
Appendix D: Oracle Rdb Overview What Is Oracle Rdb? D-2
.....................................................................................................................................................
Oracle Developer: Build Reports xi
.....................................................................................................................................................
Contents
Appendix E: Introduction to Query Builder What Is Query Builder?
E-3
The Query Builder Window E-7
Building a New Query E-9
Datasource Components E-11
Including Additional Tables E-19
Operators E-31
Appendix F: Object Features in Oracle Developer
Overview F-3
Summary F-29
Appendix G: Using the Layout Editor in Oracle Developer Overview
G-3
Why Use the Layout Editor? G-5
How to Access the Layout Editor G-7
The Layout Editor Components G-9
Creating and Modifying Objects in the Layout G-11
Formatting Objects in the Layout G-19
Coloring Objects and Text G-21
Importing Images and Drawings G-25
Summary G-27
.....................................................................................................................................................
Contents
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
Objectives
At the end of this lesson, you should be able to do the
following:
• Describe the matrix Data Model objects
• Describe the matrix Layout objects
• Create and modify matrix summaries
• Display zeros in cells with no value
Oracle Developer: Build Reports 14-3
......................................................................................................................................................
......................................................................................................................................................Overview
Overview
Introduction Matrix or cross product reports show cells of
information that relate to values appearing across the top and down
the left side of the report.
In an earlier lesson you created a matrix report and matrix with
group report using the Report wizard.
In this lesson, you modify the data model and layout objects to
enhance your matrix reports.
Objectives At the end of this lesson, you should be able to do the
following:
• Design a matrix Data Model
• Design a matrix Layout Model
• Modify a matrix structure
• Create additional matrix summaries
14-4 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
1 Cross product group 4 Cell column is the source of a cross
product summary that becomes the cell content
2 Row and Column groups 5 Row and Column summaries
3 Cell group
The Matrix Data Model
......................................................................................................................................................The
Matrix Data Model
The Matrix Data Model
Introduction To maintain and enhance the structure of a matrix
report, you must understand the Data Model objects and their
interdependency.
What Does the Wizard Create? The Data Model opposite is the matrix
report created in an earlier lesson. It demonstrates the structure
of the Matrix and Matrix with Group styles.
Simple Matrix Style The wizard creates three data groups:
• Department records (the rows)
• Salary records (the values used to calculate the matrix
cells)
There is an extra group that surrounds the row and column groups.
It is called the cross product group and contains the summary
column that forms each cell value, SumSalary, as well as the
summaries to total the row and column values.
To create a cross product group, use the Cross Product tool in the
vertical toolbar.
Matrix with Group The data model is identical, except for the
addition of a break group, similar to a master/detail
hierarchy.
The break group exists one level above, and outside, the matrix
group. The entire cross product group, with its contents, repeats
for each record in the break group.
14-6 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
3 Matrix object, the intersection of the two repeating frames
2 Repeating frame for columns (Across)
4 Matrix with Group style: Outer repeating frame for break
group
Copyright Oracle Corporation, 1999. All rights reserved.
The Matrix Layout
......................................................................................................................................................Matrix
Layout
Matrix Layout
Introduction Although the supplied templates create good-looking,
professional report output, they do not help to explain the layout
objects in a classroom environment. The number of objects and their
interdependency are more complex in matrix reports than in the
other styles covered so far.
This section explains the objects by showing an expanded layout
where each outer object is slightly larger than its contents.
What Does the Wizard Create? The layout for a Matrix report is more
complex than other styles because of the special relationship
between the row and column groups and the cell values.
Simple Matrix Style The wizard creates the following objects:
• One repeating frame with Print Direction of Down to hold the row
values
• One repeating framewith Print Direction of Across to hold the
column values
• A field for the summary of the cell values; the source is
SumSalary, which resides in the cross product group
• Fields for the row and column values, as well as for the row,
column, and report summaries if applicable
• A matrix object that corresponds to the cross product group; this
object intersects the row and column repeating frames, and contains
the cell field
Matrix with Group The Matrix with Group style is identical except
for the addition of a repeating frame that surrounds the entire
matrix layout and corresponds to the break group in the Data
Model.
14-8 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
2 Product Order = G_TITLE
Creating Matrix Summaries
......................................................................................................................................................Creating
Matrix Summaries
Creating Matrix Summaries
Introduction When creating row or column summaries, or the summary
for the cell values, use the summary tool in the vertical toolbar,
but ensure that you create the summaries inside the cross product
group (but outside the row and column groups).
This section discusses an extra property that applies only to cross
product summaries, the Product Order property.
Setting the Product Order The wizard sets a sensible default for
this property. You do not need to alter the setting, but you need
to understand this property if you create complex matrix reports,
or add columns to an existing matrix report.
The product order defines the order in which Report Builder
evaluates the groups in the cross product for a summary.
Product Order also defines the frequency of a summary, formula, or
placeholder column in a cross product group. That is, the column
has one value for each combination of values in its Product Order
groups.
The Product Order list of values provides all possible group
combinations.
In the matrix report:
• F_SumSalPerTITLE has one value for each job title (G_TITLE)
• F_SumSALARY, the matrix cell, has one value for each combination
of G_DEPT and G_TITLE, so the Product Order is G_DEPT
G_TITLE.
The Reset At option has the same effect as in other report styles.
When you create summaries with the wizard, each summary resets for
each occurrence of the group. For example, the department summary
resets for each department. If you want the summary values to
accumulate throughout the report, change Reset At to a higher
level, such as Report.
Source Column Reset At Product Order
F_SumSALPerDEPT_NAME G_DEPT G_DEPT
F_Sum_SALPerTITLE G_TITLE G_TITLE
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
Building a Nested Matrix
......................................................................................................................................................Building
a Nested Matrix
Building a Nested Matrix
Introduction The nested matrix style, which you created with the
wizard by adding an extra level in the Rows tab, has some specific
features. This section briefly describes the Data Model and Layout
Model, pointing out the differences from the Matrix with Group
style. It also explains how summaries evaluate the extra group
level of a nested matrix.
What Is in the Nested Matrix Data Model? The wizard creates the
same objects as for a simple matrix structure. In addition, it
creates an additional break group for each level of nesting.
The cross product group encloses the additional break groups as
well as the two original dimension groups of the rows and
columns.
Creating the Cross Product Group If you enhance the existing Data
Model to include an additional level of nesting, the existing cross
product group does not recognize any newly created group. You must
create the cross product group after you create all the groups that
you want in the nested matrix.
How to Recreate the Cross Product Group 1 Delete the existing cross
product group.
Note: The cross product summaries are automatically deleted.
2 Create the new groups that you need.
3 Recreate the cross product group. Use the cross product tool
(AxB) to click and drag a region surrounding the break groups and
the two dimension groups (rows and columns).
4 Use the reenterable wizard to recreate the summaries.
Differences Between a Nested Matrix and a Matrix with Group •
Matrix with Group Data Model: The cross product group is the child
of a parent
break group at a level above and outside the cross product.
• Nested Matrix Data Model: The cross product contains three or
more groups: one or more levels of break group and two dimensional
groups to form rows and columns.
Note: You can mix these styles. That is, you can create a Matrix
with Group report where the matrix has several nested levels within
it.
14-12 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
Nested Matrix Layout
......................................................................................................................................................Building
a Nested Matrix
What Is in the Nested Matrix Layout Model? The wizard creates the
same objects as for a simple matrix structure. It also creates the
following objects:
• One repeating frame for each additional break group, nested
within the same overall matrix structure
• One matrix object for each additional break group
The exact appearance depends on whether the extra level is in the
Row or in the Column tab. The diagram opposite shows nested
rows.
In the Object Navigator, you can see the matrix structure in the
Dimension and Frequency nodes. These nodes exist only if there is a
matrix. You do not see a node for the matrix object name, but it
does have properties. You can open the property palette in the
Layout Model only.
Creating a Matrix Object When possible, use the wizard to create
your matrix reports, since the layout consists of many layers and
interdependent objects.
If you resize the repeating frames, take care to maintain the
intersection between them, otherwise you might destroy the matrix
object. Report Builder gives you a warning message if this is
likely to happen.
If you destroy the matrix object, or want to create the matrix
structure yourself, you must recreate the matrix object. Each
matrix object intersects and determines the relationship between
two and only two repeating frames.
How to Create the Matrix Object 1 Make sure that the two related
repeating frames intersect each other correctly.
2 Select both repeating frames (Shift-Select).
Note: if you do not select both frames, you receive an error
message: REP-3100: Matrix must include at least 1 Down and 1 Across
repeating frame.
3 Choose Insert—>Layout Matrix.
4 Move the matrix object back through the layout layers until it is
behind the cell field (Arrange—>Move Backward). This step is not
necessary to make the report run, but it is useful to see the cell
field if the matrix has a solid fill.
14-14 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
Creating Matrix Summaries
......................................................................................................................................................Building
a Nested Matrix
Creating Nested Matrix Summaries The wizard creates nested
summaries in the cross product group.
If you create or alter a nested summary, you must set the Product
Order correctly. Always test the report output very carefully to
ensure that the summaries are displaying exactly the value you
expect.
Setting the Product Order Remember, the Product Order indicates the
way in which Report Builder evaluates a summary. Product Order also
determines the position (frequency) of the summary if you use the
reenterable wizard.
The diagram opposite shows three summary fields created by the
wizard:
• F_SumSALperTITLE: Total salary for each column of job title.
Displayed once for each title.
• F_SumSALperDEPT: Total salary for each department row nested
within a specific region row. Displayed once for each combination
of region/department.
• F_SumSALARY: The cell value. Displayed once for each combination
of region/department/title.
The diagram also shows a fourth summary, F_Sum_REG_NAME, which you
might want to create yourself, to produce a subtotal for each
region.
1 Create another summary in the cross product group.
2 Create a layout field and place it as shown in the diagram, in
the R_G_REG_NAME repeating frame (use the Object Navigator to
identify it). The following table shows the property
settings.
Field Name Reset At Product Order
F_SumSALPerTITLE G_TITLE G_TITLE
F_SumSALPerDEPT G_DEPT_NAME G_DEPT_NAME
Field Name Reset At Product Order
F_Sum_REG_NAME G_REG_NAME G_REG_NAME
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
Displaying Zeros
......................................................................................................................................................Building
a Nested Matrix
Displaying Zeros in Cells with No Value The field that displays
each cell of the matrix is sourced to a summary column, such as
SumSalary.
If there is no value for a particular row/column combination, the
summary column is null and therefore the cells displayed as a blank
field.
You can very simply change the blank to zero or any default value
you choose.
To display zeros, open the property palette for either the cell
field or the SumSalary summary column and set the Value if Null
property to zero.
14-18 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
Summary
• Consider creating or modifying a template with extra
spacing
• Data and layout reflect cross product structure
• Matrix-specific:
......................................................................................................................................................Summary
Summary
Let the Wizard and Template Work for You Use the wizard to create
your matrix, even if you need to modify it later. Allowing the
wizard to create the initial layout model saves you a lot of
time.
If you make many modifications to your wizard reports, consider
creating or modifying a template to include object spacing
horizontally and vertically, between frames, fields, and so on.
This helps you to select and manipulate the objects in the Layout
Model.
Note: Remember, you can override the default template properties
for the Matrix and Matrix with Group sections of an existing
template.
Matrix Structure The Data Model and Layout Model of a matrix report
contain special features, and relationships between objects, to
reflect the cross product structure of the report.
Matrix-Specific Objects and Properties Matrix reports include
special objects, and properties:
• Data Model: Cross Product group; Product Order property
• Layout Model: Matrix object
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
Practice 14 Overview
• Building a nested matrix report
• Adding summaries to the nested matrix report
• Displaying zeros for summary values and restricting columns per
page
• Displaying more meaningful column information and rotating the
text
Oracle Developer: Build Reports 14-21
......................................................................................................................................................
......................................................................................................................................................Practice
Session Overview: Lesson 14
• Opening and changing an existing matrix report
• Building a nested matrix report
• Adding summaries to the nested matrix report
• Displaying zeros for summary values and restricting the number of
columns per page
• Displaying more meaningful column information and rotating the
text
Introduction In this practice session you use an existing matrix
report to investigate the different methods of displaying the cell
values and the implications. You use an existing external query to
create a nested matrix report. You then add row and column-level
summaries to the report and display zeros for null values. If you
have time, include the product names instead of the product IDs and
rotate the names.
14-22 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
Practice Session: Lesson 14 1 Open report p4q6.rdf.
a Use the Report wizard to apply a template file to the report. The
file corpmat.tdf should be located in your working directory. The
new template gives you spaces between the layout objects to make it
easier to see the different objects in the Layout editor.
b How many repeating frames do you have?
c Change the properties of the cell object to display zero for a
null value.
d Run and test the report.
e Close the report without saving it.
2 Create a new report, importing the external query p4q6.sql from
your working directory.
a Choose the following settings:
Report Style Matrix
Level 2 - Name
Matrix Totals Sum of the cell field
Oracle Developer: Build Reports 14-23
......................................................................................................................................................
......................................................................................................................................................Practice
Session: Lesson 14
b Change the labels and widths for the following fields:
c Run the report.
d Which summaries were created?
e Use the Data Model editor to create summaries for each month and
for the level month and product.
f Use the Layout editor to create the fields. You will have to
expand the appropriate repeating frame.
g Run and test the report.
h Save the report as p14q2.rdf. Do not close it.
3 Continue with the report from the previous exercise.
a Add zeros for null values in the cells.
b Make sure that the report shows only three product columns on
each page.
c Format all numeric data to be right aligned.
d Add commas and two decimal places where appropriate.
e Run and test the report.
f Save the report as p14q3.rdf, and close it.
Field Label Width
NAME Customer 10
PRODUCT_ID Product 5
MONTH Month 4
SUMTOTALVALUE Total 5
......................................................................................................................................................Lesson
14: Enhancing Matrix Reports
If You Have Time 4 Open the report as p14q3.rdf.
a Make the necessary changes in the Data Model editor to include
the product name.
b In the Layout Model editor delete the product_id field and insert
a boilerplate object to display the product name. Rotate this
object by 90 degrees.
c Run and test the report.
d Save the report as p14q4.rdf and close it.
................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
Objectives
At the end of this lesson, you should be able to do the
following:
• Describe the different types of triggers
• Describe sample uses of triggers
• Write and reference common code
• Create a PL/SQL library
......................................................................................................................................................Overview
Overview
Introduction This lesson identifies different trigger types and
creates conditional trigger code to control report output. It also
explains how to improve productivity and maintenance by sharing and
reusing commonly referenced code.
Objectives At the end of this lesson, you should be able to do the
following:
• Describe the different types of triggers
• Describe sample uses of the different types of triggers
• Write and reference common code
• Create and reference a PL/SQL library
15-4 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
Types of Triggers in Reports
Report:
Data Model:
• Formula (column)
• Filter (group)
• Parameter validation
Copyright Oracle Corporation, 1999. All rights reserved.
Trigger Code
......................................................................................................................................................Types
of Triggers in Reports
Types of Triggers in Reports
Introduction You can code PL/SQL in a variety of triggers in a
report to provide conditional or additional processing at run time.
This session discusses examples of each type of PL/SQL
trigger.
The Three Trigger Types • Report:
- A set of five report-level triggers. Each trigger fires at a
different stage of the report execution.
- Access report triggers from the Report Triggers node in the
Object Navigator.
• Data Model:
- Column formula fires each time the column is processed.
- Group filter fires for each record in the group.
- Parameter validation fires when the run-time parameter form is
displayed and when the user leaves the parameter field.
- Access data model triggers in the property palette of a data
model object— column, group, or parameter—or the corresponding
layout object—field, repeating frame, or parameter field.
• Layout:
- Format triggers on most layout objects (excluding anchors). Each
trigger fires as the layout object is processed.
- Access format triggers in the property palette of a layout
object.
Note: Report Builder does not allow data manipulation language
(DML) commands—INSERT, DELETE, UPDATE—in layout format
triggers.
Trigger Code When you create a trigger such as a report trigger or
a PL/SQL formula, the Program Unit editor supplies a template for
the function block, giving the basic syntax that you require.
You can change the name of the function.
The value that you return must match the return datatype in the
function declaration.
15-6 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
1 If After Parameter Form returns FALSE, the cursor returns to the
run-time parameter form. If the run-time parameter form is not
displayed, control returns to the calling program.
2 If READONLY=Yes, Report Builder implicitly sets the read-only
transaction (SET TRANSACTION READONLY) after the Before Report
Trigger fires.
3 If READONLY=Yes, Report Builder implicitly ends the read-only
transaction (COMMIT) after the final page and before the After
Report Trigger fires.
Copyright Oracle Corporation, 1999. All rights reserved.
Using Report Triggers
......................................................................................................................................................Using
Report Triggers
Using Report Triggers
Introduction Report triggers enable you to execute PL/SQL functions
at specific times during the execution and formatting of your
report. These triggers enable you to:
• Customize the formatting of your report
• Perform initialization tasks
• Access the database
Report triggers must return a boolean value—true or false.
Accessing the Report Triggers You can access the report triggers
from the Object Navigator. Open the Report Triggers node and
double-click on the object icon of the required trigger to open the
program unit.
Trigger Fires Use to Before Parameter Form
Before run-time parameter form is displayed; fires even if
parameter form is suppressed
Access and change parameter values (initial or command line),
global variables; create temporary tables; insert into tables to be
queried
After Parameter Form
After run-time parameter form is displayed; fires even if parameter
form is suppressed
Access and change parameter values (initial, command line, or
user-entered); create temporary tables; insert into tables to be
queried
Before Report Before a report executes: after queries are parsed,
but before records are fetched
Carry out initialization procedures
Between Pages Before each page is formatted, except the first page;
in Previewer, fires only once for each page, even if you revisit
the page
Carry out customized page formatting; insert or update values in
tables
After Report After you exit the Previewer, or after report output
is sent to its destination; fires on success only
Clean up initial processing, such as deleting temporary
tables
15-8 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
Using Report Triggers After Parameter Form
• Example: build dynamic WHERE clause FUNCTION AfterPForm RETURN
BOOLEAN IS BEGIN IF :p_customer IS NULL THEN
:p_where_clause := ’’; ELSE
• Query syntax: SELECT ID, NAME FROM CUSTOMER
ORDER BY NAME
ORDER BY NAME &p_where_clause
......................................................................................................................................................Using
Report Triggers
Creating a Dynamic WHERE Clause Use the After Parameter Form report
trigger to build a dynamic WHERE clause depending on the value of a
bind parameter that the user enters at run time.
There are two possibilities at run time:
• The bind parameter is NOT NULL:
The WHERE clause restricts the query; therefore the Oracle server
makes use of an existing index when retrieving data.
• The bind parameter is NULL:
The WHERE clause is also NULL; therefore the Oracle server uses a
full table scan to retrieve all records.
15-10 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
Using Data Model Triggers Group Filter
• Restrict records in a group
• Perform PL/SQL for each record FUNCTION G_empGroupFilter RETURN
BOOLEAN IS BEGIN IF :name = ’Operations’ AND :salary > 3000
THEN
RETURN(my_function); ELSE
Oracle Developer: Build Reports 15-11
......................................................................................................................................................
......................................................................................................................................................Using
Data Model Triggers
• Using a PL/SQL group filter
• Validating a parameter value
Using a PL/SQL Group Filter Use a group filter when you want to do
the following:
• Restrict records in a specific group, depending on other
processing in the report; that is, when a WHERE clause in a query
is not applicable
• Perform some PL/SQL processing for each record in a group
A group filter is useful when you want to restrict group values of
a lower group in the group hierarchy.
The function must return a boolean value:
• True: the record is included
• False: the record is excluded
Report Builder fetches all records and applies the group filter to
each record. Therefore avoid group filters as a method of
restricting many records in a group.
Note: You cannot add a filter to a matrix cross product
group.
Example Use a group filter that calls a function for some records
in the G_emp group, depending on the department in the master
group.
1 Open the property palette for the G_emp group.
2 Change Group Filter to PL/SQL.
The PL/SQL Filter property appears.
3 Choose the PL/SQL Filter property to open the PL/SQL
editor.
4 Enter the code. This filter code must return a boolean value,
true or false.
Note: It is more efficient to use a WHERE clause in a query when
possible. You cannot use a WHERE clause in this case, because you
want to process all records and call the function for some.
15-12 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
Using Data Model Triggers
• You cannot reassign values to parameters or columns in this
trigger
FUNCTION DESTYPEValidTrigger RETURN BOOLEAN IS BEGIN IF :DESTYPE =
’Printer’ THEN
RETURN(FALSE); ELSE
Parameter Validation
• Example: do not allow report output to be sent directly to a
printer
Oracle Developer: Build Reports 15-13
......................................................................................................................................................
......................................................................................................................................................Using
Data Model Triggers
Validating a Parameter Value Both system parameters and user
parameters have a Validation Trigger property, in which you can
write a PL/SQL function to validate the value of the
parameter.
The trigger code must return a boolean value—true or
false—depending on whether the validation is successful or
not.
If the returned value is false, the cursor remains in the parameter
and the user has the following two options:
• Enter a different value
• Cancel the report
You can test the value of a parameter, but you cannot change the
value. If you want to assign a new value to the parameter, use the
After Parameter Form report trigger.
Example To prevent report output from being sent directly to a
printer, test the value of the DESTYPE system parameter.
1 Open the property palette for the DESTYPE parameter.
2 Choose Validation Trigger to open the PL/SQL editor.
3 Enter the code and make sure that the value Printer has an
initial capital.
15-14 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
Using Layout Triggers
• Exist on most layout objects
• Can suppress an entire layout section (master group frame): no
records fetched
• Can suppress the display of individual records (repeating frame):
all records fetched
Oracle Developer: Build Reports 15-15
......................................................................................................................................................
......................................................................................................................................................Using
Layout Model Triggers
Using Layout Model Triggers
Introduction Most layout objects contain a format trigger; it is
one of the common properties of a layout object.
Format triggers enable you to modify the display of objects
dynamically at run time or to suppress display altogether.
The trigger must return a boolean value—true or false.
The following pages discuss some examples of format triggers.
Suppressing the Entire Layout for a Query Because Report Builder is
driven by the layout, you can use a format trigger on a group frame
to conditionally suppress the entire layout associated with a
query. In this case, the query does not retrieve any data.
Suppressing Individual Records Do not use format triggers to
suppress individual records that you can restrict on the Data
Model. For example, a format trigger on a repeating frame does not
prevent data from being retrieved, it simply determines whether or
not you see it in the output.
Therefore it is more efficient to restrict individual records using
the Maximum Records property in a query or a First type of group
filter when possible.
Note: Summaries compute against all data fetched by the Data Model.
If you suppress records in the layout only, summaries give
misleading results.
15-16 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
1 Boilerplate text: Position behind column heading frame, or
position below and create collapsible anchor to column
heading
2 Column heading frame does not display; Suppressed by format
trigger
Copyright Oracle Corporation, 1999. All rights reserved.
Displaying a Text String in Place of Column Headings
Dept: f_deptno
Name Salary
Name Salary
Dept: 10
Dept: 40
2
......................................................................................................................................................Using
Layout Model Triggers
Coding a Format Trigger on a Frame
Requirement: Display a Text String In Place of Column Headings
Display a master-detail report for departments and employees. If a
department has no employees, suppress the detail column heading
frame and display a piece of text instead.
Example 1 Create a summary column, :count_emp, in the master group
that counts the
number of employee records (reset = master group).
2 Create a piece of boilerplate text, “No employees in this
department”.
3 Position the text behind the column heading frame.
4 Code a format trigger on the column heading: function
hide_headings return boolean is begin
if :count_emp = 0 then return(false);
else return(true);
end if;
end;
5 Either code the reverse logic in the format trigger of the
boilerplate text item created in step 2 or ensure that the column
heading frame has a solid fill.
Note: You should code format triggers at the highest possible level
of the layout hierarchy. The format trigger on the column headings
frame suppresses all objects enclosed by the frame. Do not
duplicate code unnecessarily by coding the same trigger on all
individual objects in the frame; this can cause increased
processing and maintenance overheads.
15-18 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
1 One repeating frame is positioned behind the other or positioned
below with collapsing anchor
2 Report output run by payment clerks
3 Report output run by other employees
Copyright Oracle Corporation, 1999. All rights reserved.
Employee Details
f_name f_date f_salary
......................................................................................................................................................Using
Layout Model Triggers
Coding a Format Trigger on a Repeating Frame
Requirement: Dynamically Alter the Display of Records Dynamically
In a report of employee details, display salaries if the user is a
payment clerk, but hide salaries and alter the appearance of
remaining fields when any other employee runs the report.
Example 1 In the layout, create two repeating frames sourced by the
same group. One
repeating frame must contain a salary field, the other must
not.
Note: You can create two separate default layouts and modify the
layout as required.
2 Place one repeating frame behind the other.
3 Add a format trigger to suppress the top repeating frame (the one
that contains the salary field), or alternatively use conditional
formating:
function pay_clerks_see_this return boolean is begin
if :user_type = ’PAY_CLERK’ then return(true);
else return(false);
end if;
end;
Note: User_type can be a column or parameter that is initialized at
run time.
4 Either code the reverse logic on the other repeating frame or
ensure that the top repeating frame (containing salary) has a solid
fill.
15-20 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
1 Report for payment clerks shows all fields
2 Report for other employees shows gap where salary is hidden
Copyright Oracle Corporation, 1999. All rights reserved.
Dynamically Hiding Fields
Biri 07-APR-91 1100
......................................................................................................................................................Using
Layout Model Triggers
Format Trigger on a Field
Requirement: Dynamically Hide Fields Given the same employee
details report as before, hide the salary field without rearranging
the other fields in the repeating frame. The report contains a gap
in the layout when the salary field is not displayed.
Example Place the format trigger on the salary field to display it
only when payment clerks run the report. The code is the same as
before:
function pay_clerks_see_this return boolean is begin
if :user_type = ’PAY_CLERK’ then return(true);
else return(false);
end if;
end;
In this example you do not need to create any additional layout
object or code.
15-22 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
1 Format Trigger on F_Address2 field references the column
ADDRESS2
2 Create anchors, with Collapse Vertically=Yes, on fields below the
suppressed field
Copyright Oracle Corporation, 1999. All rights reserved.
f_name
f_address1
f_address2
f_address3
f_address4
Suppressing Null Fields in a Letter Heading
FUNCTION label_field RETURN BOOLEAN IS BEGIN IF :address2 IS NULL
THEN
RETURN(FALSE); ELSE
RETURN(TRUE); END IF; END;
FUNCTION label_field RETURN BOOLEAN IS BEGIN IF :address2 IS NULL
THEN
RETURN(FALSE); ELSE
......................................................................................................................................................Using
Layout Model Triggers
Coding a Format Trigger on a Field
Requirement: Suppress Null Fields in an Address The letter opposite
includes a customer address. Address lines in a database often have
optional fields to provide for a variable number of lines in an
address.
You want to suppress fields that are NULL, so that the address does
not contain large spaces between existing lines.
Example 1 Code a format trigger on the optional field to suppress
the field when the value
is NULL.
2 Create an anchor from the field below, up to the optional field.
Set the Collapse Vertically property to Yes. Repeat for all fields
below the optional field to avoid any unwanted space in the
label.
15-24 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
1 Transparent rectangle 3 Summary column name (created in Data
Model)
2 Repeating Frame, Vertical Elasticity = Variable
4 Format trigger on transparent rectangle
Copyright Oracle Corporation, 1999. All rights reserved.
f_1 f_2 f_3
1 2
FUNCTION spacing RETURN BOOLEAN IS BEGIN IF MOD(:count_column, 3) =
0 THEN
RETURN(TRUE); ELSE
RETURN(FALSE); END IF; END;
FUNCTION spacing RETURN BOOLEAN IS BEGIN IF MOD(:count_column, 3) =
0 THEN
RETURN(TRUE); ELSE
......................................................................................................................................................Using
Layout Model Triggers
Coding a Format Trigger on a Boilerplate Object
Requirement: Insert Spacing Between Groups of Records Display
additional spacing between a defined number of records; for
example, group every three records together.
Example 1 Create a transparent rectangle inside the repeating frame
to increase spacing
conditionally at run time.
2 In the repeating frame property palette, set Vertical Elasticity
to Variable.
3 In the Data Model, create a summary column named COUNT_COLUMN
that counts the number of records retrieved (Reset=Report).
4 On the rectangle, create a format trigger that references the
summary column, as shown on the opposite page.
Note: You can vary the number of records in each group dynamically
at run time by creating a parameter.
15-26 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
Writing Common Code
At Report level
• File—>Open: add to existing library
• Attach library to report
......................................................................................................................................................Writing
Common Code
Writing Common Code
Introduction If you use the same program unit in several places in
a report, or in multiple reports, consider writing the code once as
a report-level program unit, or in a PL/SQL library, and then call
the program unit when you require it in your PL/SQL trigger code;
this enables you to maintain the code in one place.
Even if you do not use the code many times, consider writing
anything other than very simple PL/SQL blocks at report level, to
simplify maintenance.
Remember that you can also code stored procedures and functions in
the database; you must decide whether server-side or client-side
processing is more efficient in each case.
Two Ways to Create Report-Level Program Units • In the Object
Navigator, select the Program Units node and create a new
program unit.
• From the menu, select Program—>PL/SQL Editor. Choose New to
create a new program unit.
Writing Code as Report-Level Program Units You can create a
report-level program unit that contains a function, procedure, or
package, and that you call from any object in the same report. You
cannot reference a report-level program unit from a different
report.
Three Ways to Create Library Program Units • In the Object
Navigator, select the PL/SQL Libraries node and create a new
library.
• From the menu, select File—>New—>PL/SQL Library.
• From the menu, select File—>Open to open an existing library
and create additional program units.
Referencing Code from a PL/SQL Library You can reference library
code in a report trigger by attaching one or more libraries to one
or more report definitions, which enables you to reference the same
code in multiple reports.
To attach a library to a report, open the report definition, select
the Attached Libraries node in the Object Navigator, and add each
library that you need in the report.
15-28 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
Examples • Building a dynamic WHERE clause • Validating a parameter
value • Dynamically altering record display • Suppressing null
fields
Common code • Report-level program units • PL/SQL libraries
Oracle Developer: Build Reports 15-29
......................................................................................................................................................
......................................................................................................................................................Summary
Summary
Using PL/SQL Triggers Choose the most applicable type of trigger
for your requirement.
Report-level triggers fire once for each of the five events during
the report execution.
Data Model triggers can affect which records are processed and how
they are processed.
Layout triggers affect the way in which objects are
formatted.
Writing Common Code Use report-level program units or PL/SQL
libraries for common code requirements to improve productivity and
maintenance.
Objects That Must Return a Value The following table is a reminder
of the Report Builder triggers that must always return a value, and
it shows the values that are acceptable.
Trigger Type Valid Values Result if False
Report trigger True, False Abort execution
Group filter True, False Do not process record
Validation trigger True, False Return to parameter form
Format trigger True, False Do not format object
PL/SQL Formula (column) Computation: Character, Number, Date
N/A
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
Practice 15 Overview
• Creating and using a report-level PL/SQL function
• Creating and using an external PL/SQL library
• Creating a PL/SQL group filter
Oracle Developer: Build Reports 15-31
......................................................................................................................................................
......................................................................................................................................................Practice
Session Overview: Lesson 15
• Creating and using a report-level PL/SQL function
• Creating and using an external PL/SQL library
• Creating a PL/SQL group filter
Introduction In this practice session you create a format trigger,
or use conditional formatting to display one of two layouts for the
same data, depending on a parameter value at run time. You also
conditionally flag some records in a report by creating and
referencing a report-level (local) PL/SQL function. You then move
the code into a new PL/SQL library and alter the reference to use
the library function instead.
If you have time, restrict the number of records processed in a
report by creating your own group filter.
15-32 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
Practice Session: Lesson 15 1 Create a new report, using
p15q1.sql.
a Display the records in two different layouts, showing different
columns in each.
b Create a Group Above layout using the following columns from the
query:
c Create a Tabular layout using the following columns from the
query:
d Make sure that only the Group Above layout is displayed when you
choose a destination of Screen, and only the Tabular layout is
displayed when you choose a destination of Preview. To test the
result, display the DESTYPE parameter in the report. Make sure that
you can enter a parameter value at run time.
Hint: As an alternative to coding Format triggers, you can also use
Conditional Formatting.
e Save the report as p15q1.rdf.
Group Column
G_CUSTOMER CUSTOMER_ID
G_ID ID
......................................................................................................................................................Practice
Session: Lesson 15
2 Continue with the previous report.
a Modify the report so that the Tabular (Preview) layout displays
an extra column that indicates, with an asterisk, those orders that
were shipped more than 15 days after the order date.
b Remember to change destination to Preview during testing.
c Move the function code into a new PL/SQL library, named
p15lib.pll.
d Call the external function from your report, instead of calling
the report-level function.
e Save the report to p15q2.rdf.
3 Continue with the previous report.
a Modify the same layout to display additional spacing between
every two records.
b Save the report as p15q3.rdf and close it.
If You Have Time 4 Open report p15q1.rdf.
a Write your own group filter to restrict the number of customers
displayed depending on the value of a parameter that you enter at
run time.
Hint: You need to create two parameters to keep track of how many
records have been processed compared to the cutoff number of
records required.
b Test the report several times by changing the cutoff parameter at
run time.
c Save the report as p15q4.rdf.
15-34 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
15: Coding PL/SQL Triggers in Reports
16-2 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Objectives
At the end of this lesson, you should be able to do the
following:
• Describe the package contents
• Execute a drill-down report
• Modify visual attributes dynamically
......................................................................................................................................................Overview
Overview
Introduction This lesson provides examples of the contents and use
of the Report Builder built-in package. The package contains
program units that you can reference in your PL/SQL code.
Objectives At the end of this lesson, you should be able to do the
following:
• Describe the contents of the Report Builder built-in
package
• Output messages at run time
• Execute a drill-down report
• Modify visual attributes dynamically at run time
16-4 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Contents of the SRW Package
SRW.BREAK SRW.SET_ATTR
SRW.DO_SQL SRW.RUN_REPORT
......................................................................................................................................................Contents
of the Report Builder Built-in Package
Contents of the Report Builder Built-in Package
Introduction The Report Builder built-in package, known as the SRW
package, contains procedures, functions, and exceptions that can
help you to do the following:
• Control report execution
• Initialize layout fields
• Call user exits
• Dynamically set format attributes, such as font style and fill
patterns
Referencing the Contents of the Package You can reference any part
of the SRW package in a PL/SQL statement in any PL/ SQL area of a
report, such as a layout format trigger or a report-level
trigger.
Rules
• You can only call the contents of the SRW package from within
Report Builder. Other tools, such as Form Builder, do not recognize
this package.
• You must always reference an SRW procedure, function, or
exception by preceding it with the package name, SRW; for example,
SRW.MESSAGE, SRW.DO_SQL.
16-6 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Outputting Messages Warning WHEN <exception> THEN
SRW.MESSAGE(999, ’Warning: report continues’);
WHEN <exception> THEN SRW.MESSAGE(999, ’Warning: report
continues’);
Error WHEN <exception> THEN SRW.MESSAGE(999, ’Error: report
terminated’);
WHEN <exception> THEN SRW.MESSAGE(999, ’Error: report
terminated’); RAISE SRW.PROGRAM_ABORT;
Exceptions SRW.INTEGER_ERROR SRW.NULL_ARGUMENTS
......................................................................................................................................................Outputting
Messages
Outputting Messages
Introduction The SRW.MESSAGE packaged procedure displays a message
with a code and text string, which you specify. The message is
displayed in the following format:
MSG-code: text
The message is displayed in a small dialog box. The user must
acknowledge the message before continuing.
Message Code and Text You can enter a code number from zero up to
10 digits. If you enter a number of fewer than five digits, the
code is displayed with leading zeros.
You can enter a text string to a maximum of 190 characters,
excluding the code number. You can embed extra spaces to display
your message neatly in the message dialog box. Reports does not
suppress extra spaces in the message text.
Is It a Warning or an Error? SRW.MESSAGE does not implicitly
terminate the report execution. You can choose to issue a warning
message that enables the report to continue execution after the
user accepts the message.
To force the report to terminate after outputting the message,
raise the exception SRW.PROGRAM_ABORT.
Note: You cannot suppress or replace the default message that
Report Builder gives if you abort a report. Your own error message
augments the existing messages.
Causes of Exceptions
Exception Name Cause SRW.INTEGER_ERROR You entered a code that is
not a numeric integer. SRW.NULL_ARGUMENTS You omitted either the
code number or text message
or both.
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Copyright Oracle Corporation, 1999. All rights reserved.
Executing a Report
......................................................................................................................................................Executing
a Nested Report
Executing a Nested Report
Introduction Use SRW.RUN_REPORT to execute a second report from
within a report process. For example:
• Output parts of a report to different destinations
• Divide a large report into several smaller reports that can be
run conditionally
Both Reports Use the Same Process SRW.RUN_REPORT starts only one
run-time process; it does not start a new process for each report
execution.
Example Run a report called MANAGERS that retrieves the employee
record for each manager. Call the EMPS report (for example, from a
group filter). EMPS retrieves the employee records of all employees
managed by the current manager only.
Sample code to implement this example appears on the following
page.
16-10 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Executing a Report Example SRW.RUN_REPORT
(’Report=EMPS DESTYPE=FILE DESNAME=’||:LAST_NAME||’.LIS BATCH=YES
MGRNO=’||TO_CHAR(:ID));
SRW.RUN_REPORT_FAILURE SRW.RUN_REPORT_BATCHNO
SRW.RUN_REPORT_FAILURE SRW.RUN_REPORT_BATCHNO
......................................................................................................................................................Executing
a Nested Report
Example Function Code
Note: Use LAST_NAME to create the output filename for each manager;
use ID to restrict the EMPS query.
Causes of Exceptions Report Builder raises a specific exception
that applies to the SRW.RUN_REPORT procedure in two cases:
Displaying Report Failure Message If the detail report fails during
execution, you can display information about the cause by using the
SRW.GETERR_RUN function.
...
...
BEGIN SRW.RUN_REPORT
(’REPORT=EMPS DESTYPE=FILE DESNAME=’||:LAST_NAME||’.LIS BATCH=YES
MGRNO=’||TO_CHAR(:ID));
RETURN(TRUE); EXCEPTION WHEN SRW.RUN_REPORT_FAILURE THEN
SRW.MESSAGE(100, ’Error executing EMPS report’); RAISE
SRW.PROGRAM_ABORT; END;
Exception Name Causes SRW.RUN_REPORT_FAILURE Detail report does not
exist.
Detail report failed during execution. SRW.RUN_REPORT_BATCHNO BATCH
parameter is used inconsistently:
master report running with BATCH=YES, called a detail report with
BATCH=NO.
16-12 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Copyright Oracle Corporation, 1999. All rights reserved.
Executing a Drill-Down Report
......................................................................................................................................................Executing
a Nested Report
Calling a Drill-Down Report You can call the SRW.RUN_REPORT
procedure from a button in your master report and display the
detail report in a second previewer window on the screen.
How to Create a Drill-Down Report 1 Create a button in the master
report within the repeating frame.
2 Display the button property palette. Under the Button Behavior
node, change the Type property to PL/SQL, then select the PL/SQL
Trigger property to display the Program Unit editor.
3 Enter the function as described in the previous example. Do not
include the BATCH parameter, since you want to display the detail
report interactively in a second previewer.
4 Compile and close the Program Unit editor.
5 Run the master report.
For reports that you send to a file, do not include the pathname
when coding the DESNAME parameter. Allow the REPORTS60_PATH
variable to search the correct path for the report.
Testing Drill-Down Reports During Development To test a drill-down
report, use the Reports Runtime. Remember that buttons are not
active in the Report Builder Live Previewer.
16-14 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Restricting Data
Q_EMP
G_EMP
Oracle Developer: Build Reports 16-15
......................................................................................................................................................
......................................................................................................................................................Restricting
Data
Restricting Data
Introduction Use SRW.SET_MAXROW to restrict the maximum number of
records you want to retrieve for a specified query. Report Builder
uses only the retrieved rows of the query in subsequent processing,
such as computations and summaries.
Suppressing a Query At run time, you can choose not to display any
data from a query by setting the maximum number of records to zero.
This prevents Report Builder from retrieving any records from the
database.
Example Below is a function to display data for the Q_emp query
only if a value of one or more is entered in a run-time parameter
called HOW_MANY:
FUNCTION FETCHIT RETURN BOOLEAN IS
BEGIN IF :HOW_MANY >= 1 THEN SRW.SET_MAXROW (’Q_emp’,
:how_many); ELSE SRW.SET_MAXROW(’Q_emp’, 0); END IF;
RETURN(TRUE);
EXCEPTION WHEN SRW.MAXROW_UNSET THEN SRW.MESSAGE (100, ’Data was
fetched before SRW.MAXROW was called’); RAISE SRW.PROGRAM_ABORT;
WHEN SRW.MAXROW_INERR THEN SRW.MESSAGE(200, ’Contact someone
clever!’); RAISE SRW.PROGRAM_ABORT;
END;
You must set SRW.SET_MAXROW in the Before Report trigger; that is,
after the query has been parsed but before it has been executed. If
you call it after the Before Report trigger, Report Builder raises
the SRW.MAXROW_UNSET exception.
If you handle SRW.MAXROW_INERR, always raise SRW.PROGRAM_ABORT,
because your report has an internal problem and you cannot
guarantee the outcome.
16-16 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Initializing Fields
Page: F_NEWPAGE
Layout editor
my_page number; BEGIN
my_page number; BEGIN
Page: 5
......................................................................................................................................................Initializing
Fields
Initializing Fields You can dynamically initialize the value in a
layout field by using the relevant SET_FIELD packaged procedure;
for example:
• SRW.SET_FIELD_CHAR (0, ’a text string’)
• SRW.SET_FIELD_NUM (0, 1234)
• SRW.SET_FIELD_DATE (0, ’01-JAN-95’)
The first argument is always 0 (zero); you can set the value of the
current object.
These procedures are relevant only in the format trigger of a field
of the correct type. If you use a procedure that conflicts with the
field type, it has no effect in the report; Report Builder ignores
the code and does not raise an error.
Why Use SRW.SET_FIELD? You might want to retrieve the current
logical page number and recalculate the value before displaying
it.
Example Create a function to display the logical page number + 3 in
a field called F_NEWPAGE.
Because the logical page number variable is available only in the
report layout, not in the Data Model, you cannot calculate the
value in a data column. Therefore you use a layout field to get the
current page number and output a new number by initializing the
same field.
Make use of a packaged procedure called SRW.GET_PAGE_NUM to
retrieve the current logical page number into a local PL/SQL
variable, as in the format trigger code opposite.
16-18 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Performing DDL Statements Example SRW.DO_SQL(’CREATE TABLE
SRW_LOG
(RPT_NAME VARCHAR2(40), REC_NUM NUMBER, MSG_TEXT
VARCHAR2(80))’);
SRW.DO_SQL(’INSERT INTO SRW_LOG (RPT_NAME, REC_NUM, MSG_TEXT)
VALUES (’’PAY_REPORT’’, TO_CHAR(:ID),
:LAST_NAME||’’PAY REPORT RUN’’)’);
......................................................................................................................................................Performing
DDL Statements
Introduction The SRW.DO_SQL packaged procedure executes any
specified SQL statement from within Report Builder.
Why Use SRW.DO_SQL? Use SRW.DO_SQL to perform DDL statements
dynamically, during run time. For example, create a temporary table
and insert rows into it during execution.
You can also perform DML statements using this procedure, but DML
statements run faster if you code them directly within a PL/SQL
block. Code DML statements in the SRW.DO_SQL procedure only if
necessary. For example:
• To insert records into a permanent table in the database, code
DML in a PL/SQL block.
• To insert records into a temporary table that does not exist
until run time, code DML in SRW.DO_SQL.
Querying from Temporary Tables If you want to create a temporary
table and reference it in a query in the same report, the table
must exist before the Before Report trigger fires. That is when
Report Builder parses its queries. Therefore you must create this
table in the Before Parameter Form or After Parameter Form report
trigger.
16-20 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Setting Format Attributes
Tuesday, 01 Sep
......................................................................................................................................................Setting
Format Attributes
Introduction The SRW.SET_<attributes> packaged procedures
apply specified format attributes to the current layout object:
frame, repeating frame, field, or boilerplate object.
Why Use a Format Attribute? Some of the reasons that you would want
to use format attributes are:
• To change the visual appearance of layout objects conditionally,
depending on values in a repeating frame, or on run-time parameter
values
• To switch to different printer trays as your report formats
• To place a logo or standard links in an HTML document
• To define a bookmark in an HTML or PDF document
Coding a Format Attribute You can code the packaged procedure in a
function as a local or report-level program unit, or in a PL/SQL
library. This is useful if you want a common format attribute in
more than one object or more than one report. You can then call the
function whenever required, from the format trigger of a specific
object.
As an alternative to a PL/SQL library, in the Object Navigator you
can drag and drop report-level program units between different
reports. However, note that this creates a copy of the program unit
in each report, rather than a reference to one piece of code.
16-22 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Setting Format Attributes
Printer tray control
Define a bookmark
......................................................................................................................................................Setting
Format Attributes
Example Conditionally set the following attributes if salary equals
2000:
FUNCTION SAL_MASK RETURN BOOLEAN IS
BEGIN IF :SALARY > 2000 THEN
SRW.SET_BACKGROUND_FILL_COLOR(‘darkyellow’);
SRW.SET_FILL_PATTERN(‘sandpaper’);
SRW.SET_FONT_STYLE(SRW.ITALIC_STYLE);
Using Format Attributes in Character-Mode Reports Some attributes
are applicable to character environments only; some are for
bitmapped environments only.
If you include a bitmapped attribute and then run the report in
character mode, or the reverse, Report Builder ignores the code and
does not cause an error. This enables you to develop a report for
use in a different environment.
Attribute Value Background fill color Dark yellow Fill pattern
Sandpaper Font style Italic Font face Helvetica Font weight Extra
bold Text color Dark blue
16-24 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Summary
......................................................................................................................................................Summary
Summary • The SRW package contains procedures, functions, and
exceptions.
Remember that you can raise the exception SRW.PROGRAM_ABORT in your
PL/SQL code to stop report processing at any time.
• The SRW package provides a number of features, including:
- Drill-down reports, using SRW.RUN_REPORT in a button
- Support for DDL statements, using SRW.DO_SQL, to enable you to
create or drop temporary tables from PL/SQL code in a report
- Conditional formatting and display using SRW.SET<attr>
attributes
16-26 Oracle Developer: Build Reports
......................................................................................................................................................
......................................................................................................................................................Lesson
16: Using the Report Builder Built-In Package
Practice 16 Overview