+ All Categories
Home > Documents > Oracle Developer: Build Reports

Oracle Developer: Build Reports

Date post: 12-Sep-2021
Category:
Author: others
View: 3 times
Download: 1 times
Share this document with a friend
Embed Size (px)
of 402 /402
....................................................................................... 43212GC10 Production 1.0 April 1999 M08693 Oracle Developer: Build Reports Volume 2 • Student Guide
Transcript
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

Recommended