Reports6i Secrets For Developers

Oracle Reports - Secrets for Developers October 19, 1999 by Sriyani De Silva Page 1 _____________________________________________________________________________________________________________
Oracle Reports - Secrets for Developers
Sriyani De Silva Principal Support Analyst Oracle Asia Pacific Global Support Centre Melbourne - Australia
Contents
ORACLE REPORTS - SECRETS FOR DEVELOPERS........................................................................................1 INTRODUCTION...................................................................................................................................3 AUDIENCE..............................................................................................................................................3 OBJECTIVES ...........................................................................................................................................3 ACKNOWLEDGMENTS .............................................................................................................................3 1. HINTS, TIPS AND FUNDAMENTAL CONCEPTS. ........................................................................4 1.1 UPGRADING FROM A PREVIOUS RELEASE.............................................................................................4 1.1a) History of releases....................................................................................................................4 1.1b) Upgrade Path ...........................................................................................................................5 1.2 BUILDING OR MODIFYING A REPORT ...................................................................................................6 1.2a) Data Model ..............................................................................................................................6 1.2b) Layout Model .........................................................................................................................10 1.2c) How the Data Model and Layout Model are related................................................................15 1.3 RUNNING A REPORT ........................................................................................................................16 1.3a) Basic requirements .................................................................................................................16 1.3b) Destination types - where should the output go? .....................................................................16 1.3c) Different ways of calling a report ...........................................................................................17 1.3d) User input at runtime - the Parameter Form ...........................................................................17 1.4 PRINTING FROM ORACLE REPORTS ..................................................................................................18 1.5 WEB REPORTS AND THE REPORTS SERVER .......................................................................................19 1.6 USING ORACLE REPORTS WITH OTHER PRODUCTS............................................................................20 2. TROUBLESHOOTING....................................................................................................................22 2.1 DEBUGGING ...................................................................................................................................22 2.2 SOME COMMON ERRORS AND HOW TO RESOLVE THEM .......................................................................23 CONCLUSION......................................................................................................................................24
Introduction
Audience
This paper is written for application developers who have had some basic technical experience with Oracle Reports as a reporting tool.
Objectives
The aim is to share with you, in a concise and simple format, fundamental concepts about the various aspects of Oracle Reports, starting from building or modifying a report, through to troubleshooting methods for quick resolution of errors.
Acknowledgments
I extend my appreciation and thanks to the staff at Oracle, both in Melbourne and Auckland, whom I have worked with since 1994. The many customers I have worked with, for their technical input and diversity of thought. To the Oracle Education staff for the numerous opportunities they offered me to teach Oracle Reports, and to my family and friends, for their encouragement and support.
1. Hints, Tips and Fundamental Concepts.

1.1 Upgrading from a previous release 1.1a) History of releases
In the beginning, there was RPT. This was a character mode reporting tool that was based on SQL statements. This tool can still be found as a component in the earlier releases of Oracle Applications. Then there was SQL*Reportwriter 1.1. This was part of the Oracle V6 tools that included SQL*Forms 3.0. There is no Oracle migration utility to move reports from RPT to SQL*Reportwriter, so the SQL statements have to be copied manually or via a third-party tool. The first GUI reporting tool was introduced approximately six years ago. This was called Oracle Reports 2.0 and was part of the Coorperative Development Environment (CDE1) suite of products, which included Oracle Forms 4.0. This was followed by CDE2 which comprised of the first version of Oracle Reports 2.5 and Oracle Forms 4.5. CDE2 later became known as Developer/2000, and is now known as Oracle Developer. There have been numerous versions of Oracle Reports. The table below is a summary, together with Oracle Forms, which is the closest relation to Oracle Reports. Product Suite Oracle V6 Tools CDE1 CDE2 Developer/2000 1.x Developer/2000 2.x Oracle Developer 6.0 Oracle Developer 6i Beta Reports Version SQL*ReportWriter 1.1 Oracle Reports 2.0 Oracle Reports 2.5 (early versions) Oracle Reports 2.5 Oracle Reports 3.0 Oracle Reports 6.0 Oracle Reports 6i Forms Version SQL*Forms 3.0 Oracle Forms 4.0 Oracle Forms 4.5 (early versions) Oracle Forms 4.5 Oracle Forms 5.0 Oracle Forms 6.0 Oracle Forms 6i
1.1b) Upgrade Path

When choosing to upgrade from one release to another, it is not always possible to upgrade directly to a particular release. Instead, it may have to be a two step process. For example, here are some valid upgrade paths: SQL*ReportWriter 1.1 > Oracle Reports 2.0 > 2.5 > 3.0 > 6.0 > 6i SQL*ReportWriter 1.1 > Oracle Reports 2.5 > 6i Oracle Reports 2.5 > 6.0 or 6i Oracle Reports 3.0 > 6.0 or 6i It may be apparent from the examples above, but the key point to note here is that any report prior to 2.5, MUST be upgraded to 2.5 first. Once a report is saved in version 2.5, it can be upgraded to 3.0, 6.0 or 6i directly. The reason why SQL*ReportWriter 1.1 is included here is to give this topic a broader perspective. However most installations today will be running a much higher version of Developer.
1.2 Building or modifying a report

When building a new report or modifying an existing one, it is paramount that you always keep two things in mind. The Data Model and the Layout Model. The Data Model is where decisions are made about what data is to be selected from the database. The Layout Model is where the appearance of the report output is decided. These two sections of a report are discussed in more detail below.
1.2a) Data Model
Queries, Groups and Columns

The Data Model is used to define all the Queries that select the required data for the report. The query Columns are then structured into Groups. So a report can have one or more queries, a query can have one or more groups, and a group can have one or more columns. In what sequence the groups are structured, is extremely important in determining the heirarchy of your data, and ultimately the layout of the report. For example, if a report is to display all employees by department, then department becomes the parent group, employee becomes the child group. Here is a diagram to illustrate this:
This example may seem rather trivial, but it forms the basic building block for more complex reports.
The same concept can be extended to multiple queries. The example above is a straight SELECT * FROM EMP, however another way of listing all employees by department, is to select all the departments in one query, all the employees in another query, and then link the two queries using their primary and foreign keys.
Single Query with join clauses vs Multiple Queries with Links

From a performance perspective, it is better to have fewer queries because it translates to fewer trips to the database. Wherever possible, include the table joins within the SELECT statement, rather than linking queries in the Data Model. On the other hand, one must also ensure that the SELECT statements are not too cumbersome. When multiple queries are linked within the Data Model, they automatically enforce an outer join. For example, if there is a DEPT query and an EMP query which are linked in the Data Model and not in the SELECT clause, then any departments that do not have any employees will still appear in the output. This can be achieved in a single query by using the outer-join syntax in the join clause of the SELECT statement. For example: WHERE DEPT.DEPTNO = EMP.DEPTNO(+) Using this syntax, you achieve two things: One - the number of queries are minimized thereby reducing network traffic and improving performance; Two - an outer join is created, thereby ensuring the listing of all parent records, regardless of whether they have any child records or not.
Sort Order
The group heirarchy also determines the sort order of the data. The ORDER BY clause in the SELECT statement can only ever override the LAST group in any given query. So the sorting of records is first determined by the sequence of the groups within a query, then the sequence of the columns within a group, and finally, the last group in a query can be sorted by the ORDER BY clause. Note that to change the sort order, groups and columns can be re-positioned by drag and drop, within the Data Model window, not in the Object Navigator.
Column Aliasing
When writing queries in Oracle Reports, always specify column aliases to keep column names clear and readable. This is extremely useful when future modifications are required to the Data Model. The reason is that the Layout model is driven by the Data model, so any changes in the Data model will cascade down to the Layout model. Using column aliases, protects the Layout model (to a certain degree), from such changes.
Summary, Formula and Placeholder columns

Apart from columns which are selected from the database, there are other types of columns which can be created within the report itself. They are SUMMARY columns, FORMULA columns, and PLACEHOLDER columns. In brief: A SUMMARY column allows you to perform aggregate functions such as SUM, AVG, COUNT, MAX, MIN etc.. A FORMULA column allows you to perform any pl/sql function that will return a value of type NUMBER, VARCHAR2, DATE or BOOLEAN. However columns referenced in the formula must be in the same group or at a higher level, due to frequency constraints which are discussed in section 1.2b. A PLACEHOLDER column is merely a container, or a place to hold a value. A formula column is used to populate a placeholder column. Where do these columns go? In which group do they belong? The answers are simple.
If you want to get the total number of employees in a department, the sum must reset at department level, so the SUMMARY column must be created in the department group. If you want to calculate the commission in dollars for each employee, that is salary times commission percentage, the FORMULA column must be created in the same group as the salary and commission percentage columns, that is the employee group. If you want to create a PLACEHOLDER column, or container into which values are assigned, place it in the same group as the formula column which is performing the assignment, or place it at a higher level. When creating these types of columns, always use the default naming convention. This can save precious hours later if and when the report needs to be modified. For example: Summary column names are prefixed by CS_ Formula column names are prefixed by CF_ Placeholder columns names are prefixed by CP_ If possible try to calculate summary functions and formulae directly in the database, this will be more efficient compared to querying all the records from the server to the client and performing the calculations on the client side.
System Parameters and User Parameters

These parameters also fall under the Data Model umbrella. They can be viewed from the Object Navigator, not from the Data Model window. Why do these parameters belong to the Data Model? Because they represent DATA that is required to run the report. For example, some of the System Parameters are DESTYPE (File, Printer, Mail etc.), DESNAME (Output filename, Printer name, Email address etc.), MODE (Character, Bitmap), ORIENTATION (Portrait, Landscape), DESFORMAT (PDF, HTMLCSS, etc.) and so on. The User Parameters are entirely custom created and can be of type VARCHAR2, NUMBER or DATE. These types of parameters are required in conjunction with the Runtime Parameter Form which will be discussed later on in this paper.
System Variables
These are default variables such as Current Date or Physical Page Number, a list of which is found in the Source property of a field.
Global Variables
These can be very useful when you need to assign values to variables in mid-flight, for example in the Between Pages Trigger or in a format trigger. To create a global variable, simply create a local PL/SQL program unit of type Package Spec, then declare a variable in it with the appropriate datatype. A Package Body is not required. To assign values to this global variable, use the following syntax: package_spec_name.variable_name. For example if the package spec is called Global and the variable declared in it is called v_Count, then in the report trigger or format trigger, we can assign a value to it as follows: global.v_count := 10;
1.2b) Layout Model
The Three-Dimensional Mountain Range Concept

The layout model is one of the most interesting, creative and visual aspects of Oracle Reports. Think of it as a Mountain Range. The largest frames at the base, the smaller frames above that, moving right up to the very smallest frames at the peak of the mountains. This type of visualization is invaluable in deciphering the many layers of objects that are present, even in a simple report. Adversely, if the layout is not visualized in this way it will merely seem like a maze of objects, layer upon layer! The Mountain Range concept is attempting to help you visualize what seems to be a two-dimensional diagram, in three-dimensions. The layout of a report, does have three dimensions. Across the page, Down the page, and Through the page. Obviously when printed on paper, the third dimension is a little difficult to see, but it is present in terms of the logical positioning of the objects, one behind the other.
Here is a diagram of a simple layout.
Visualizing this three-dimensionally, the same diagram will look like this.
Each layer is known as a frequency and is closely linked to the heirarchical structure of the groups and columns in the Data Model. This link is discussed later in this paper.
Moving and Re-sizing Layout Objects

Always save the report before attempting extensive moving or re-sizing of objects in the layout. As a last resort, the layout can always be re-defaulted, however if a lot of formatting has already been done, then a re-default may not be wise as all the customized formatting will be lost. If an object is moved or re-sized by mistake, use the Edit>Undo menu to undo the change. If the aim is merely to re-size objects, but not to move them, then ensure that Confine Mode is kept on. This is controlled by the Padlock button in the Layout Window. By default it is pressed, that is the padlock is locked, keeping the layout objects confined to their enclosing objects. This prevents you from accidentally moving an object outside of the boundaries where it belongs. If Confine Mode is turned off, an object can potentially be moved outside of the frame where it belongs, which will result in a frequency error. Move the object back to its parent frame and turn on Confine Mode, the error will disappear. As emphasized earlier, when making changes in the Layout Window, always keep in mind the Mountain Range concept. Give the frames a different fill colour each, so that it is easier to see the various layers. Use the Arrange menu, to move an object back and forth one layer at a time, or to send it right to the back or bring it right to the front. This is where the 3rd dimension comes into play! To select a frame and everything inside it at once, click the Frame Select button (white arrow on vertical button palette) and then click the frame. This can be very useful when moving groups of objects together. If a small object needs to be resized, you do not have to resize all the enclosing objects first (although this was required in the early versions of Reports). Simply click the Flex Mode button in the Layout Window and re-size the object, this will automatically resize all the enclosing frames, thereby saving a lot of time. Once the re-size has been done, turn off Flex Mode. The Arrange menu is also extremely useful for uniformally sizing and aligning objects.
The Margin Area

Having understood the Mountain Range Concept, it is easier to see where the Margin Area fits in. Although the word Margin implies a border around the page, the Margin Area in Reports is actually an entire layer that sits behind all the other layout objects, and so it is the largest and the furthest layer of all. To get to the Margin Area click the Margin button in the Layout Window. Once in the Margin Area, the other frames will still be visible, but they cannot be selected. Any object now placed on the Margin Area, will appear as the backdrop on every page of the report (apart from the header and trailer pages). The most common use of the Margin Area is for including the current Date or Page Number. However since it is an entire layer and not just a strip around the page, it can be used for templates for which we would otherwise use preprinted stationery. The size of the margins can be controlled from the layout window as well as from the Page Setup dialog during printing. The page boundaries are determined by the height and width dimensions in the report properties.
The Push Path

Layout objects displaying data such as fields and repeating frames, by default have the ability to expand down the page at runtime to accommodate all the rows which are retrieved by the queries. This is what is meant by a Vertical Sizing of Variable or Expand. In other words, it is very likely that a frame for example, has the potential to expand downwards at runtime, thereby pushing all the other objects in its path. The objects that get pushed further down are said to be in the push path of the expanding object above. This can be visualized like a train track. If you place a series of carriages on a train track, then push one, all the other carriages in its path will also get pushed down the track. However if an object has a Vertical Sizing of Fixed, it will stay the same size at runtime, regardless of the amount of data retrieved. So there is no push path. Consequently any object placed below it will not be pushed down by it. This concept is extremely important for reports that are printed on pre-printed stationery such as Cheque prints, where detail records appear in the main body of the page and the cheque information appears at the bottom of the page. However if all the detail records cannot fit on the first page, they would push the cheque on to the next page!! To prevent this, ensure that the frame above the cheque is stretched downwards and then set to a Vertical Sizing of Fixed. This keeps the cheque independent of any push path, and so the cheque will print at the same position on every page.
Physical and Logical Pages

A physical page as we all know can be an A4 sheet of paper for example. However let us say our report needs to print 100 columns of data across the page. This may not fit on one physical A4 sheet of paper, even if the report is printed with a Landscape orientation. So what do we do? We can pretend that our page is 5 times wider than a physical page. That is, the logical page size can be defined as 5x1. 5 pages wide and 1 page high. Now all the columns can be fitted in. The 100 columns will be printed on 5 physical sheets of paper and they can then be taped together. Using the same example, if during a report run, there are only 50 columns that are needed, the rest of the pages will still print as blank pages. These blank pages can be suppressed in Oracle Reports 3.0+ by setting the BLANKPAGES runtime parameter to . No
Building Character Mode reports

Here are some key points to note with respect to Character Mode reports: 1. The MODE system parameter must be set to Character. 2. Turn on Use Character Units in Designer or Design in Character Units in the report level properties. This should be done before the layout is created, otherwise objects may shrink to fit the new Character cell grid and result in having no height or width. If this error occurs either expand the objects manually or re-default the layout (although the latter involves loss of custom formatting). 3. If the output of a Character mode report is written to file, it will always be output in plain text or ASCII format. 4. ASCII printer drivers are not required for Character mode reports, you may use the usual Postscript or PCL drivers. 5. The DESFORMAT parameter will point to a .prt file under the ORACLE_HOME\reportsNN\printers directory (which can be edited with any text editor). The .prt file specifies the height and width of the report in character units, as well as enables the passing of escape sequences to the printer, to enable such things as Bold or compressed text. These escape sequences or printer codes are specific to each printer model and therefore must be obtained from the printer manual. 6. In Reports 3.0+, simply apply the Character mode template in the Wizard when creating the layout for the first time, this will set the important Character mode properties for you automatically. 7. For A4 Portrait, the page dimensions should be set to 80x66 character units, and for A4 Landscape, the page dimensions should be 132x66.
Merging Fields (variable text) with Boilerplate text (static text)

Let us look at an example where this can be used. In a Letter style report, there will be a fair amount of static text and some variable data, such as: Dear Mr Bloggs, This is regarding Invoice number 3456 for the amount of $400 The text in italics is variable, the rest is static. How do we merge these two types of fields? There will already be existing fields such as F_NAME, F_INVOICE and F_AMOUNT. These fields can be made hidden fields by setting them to Hidden or Visible=No depending on the version of Reports. Then, in the static text on the layout, type the following: Dear &F_NAME, This is regarding Invoice number &F_INVOICE for the amount of &F_AMOUNT Notice the preceding ampersand. This provides a reference to the actual field. Ensure that the font type and size is set correctly in the hidden field, but most important, ensure that the Horizontal Sizing of the hidden fields is set to Variable, so that they can shrink or expand dynamically at runtime. From Reports 3.0 and higher, the hidden fields can be omitted and the columns referenced directly without the F_. For example &NAME instead of &F_NAME.
Page Breaks
Always use the Maximum Records per Page property on the appropriate Repeating Frame, to control page breaks. For example, if every new department must begin on a new page, go to the Department repeating frame and set the Maximum Records per Page property to 1. Alternatively, if there is a requirement such as: If a new department begins half way down the page and all the employees of that department cannot fit on the same page, then move the entire department to the start of the next page. .. this is achieved by setting the Page Protect property on the department frame.
Conditional Printing
This functionality has been greatly enhanced in recent versions of Reports. The Conditional Formatting property on a layout object allows you to choose the required conditions and format styles without the need for any code. However a simple but powerful block of code to remember is: IF <CONDITION> THEN RETURN (TRUE); ELSE RETURN(FALSE); END IF; This code can be used in the format trigger of ANY layout object, which gives you endless possibilities of how it can be applied. For example, if you wish to suppress the salary field in an employee listing, unless the person running the report is a manager, and assuming p_user_type is a custom variable that stores the user information, then the following code in the format trigger of the salary field, will solve the problem: IF p_user_type <> Manager THEN RETURN (TRUE); ELSE RETURN(FALSE); END IF;
Page Numbering
The page number can be obtained simply by selecting it from the Source property of a field. However to reference a page number programmatically, use the following syntax: DECLARE x NUMBER; BEGIN srw.get_page_num(x); srw.message(0, This is the current page number ||to_char(x)); END;
1.2c) How the Data Model and Layout Model are related
The table below shows how the Data Model and Layout Model are so closely linked. Data Model Group Column Layout Model Repeating Frame Field
Therefore, every Repeating Frame must relate back to one Group. Every Field in the layout, must relate back to a Column in the Data Model. This link is established by the Source property of a Repeating Frame or Field. However every Group or Column does not necessarily have to relate to an object in the layout, so it is a one-way dependency. Once the layout is created based on say the department and employee Groups, Columns in the department group will appear as fields in the department repeating frame. Columns in the employee group, will appear as fields in the employee repeating frame. If there are 4 department records returned, the department repeating frame will repeat 4 times. Since the employee group is structured as a child of the department group, the employee repeating frame will be inside, the department repeating frame. The Repeating Frames and Fields get their names from the Groups and Columns in the Data Model. That is why it is important to use meaningful names and column aliases in the Data Model, before the Layout is created. The style of the report layout is also governed by the structure of the groups in the Data Model. For example, for a Tabular style report, one group in the Data Model is sufficient. For a Master-Detail, Group Left or Group Above style report, there must be at least two groups present in the Data Model. For a Matrix style report, there must be at least three groups as well as a cross-product group, and so on. Therefore the Data Model and Layout Model work hand in hand.
1.3 Running a report 1.3a) Basic requirements

To run a test report, all that is required is Reports Runtime, a valid connection to a Database, any layout object on the Layout, and preferably a printer driver. Everything else is optional.
1.3b) Destination types - where should the output go?

Here is a list of destination types that can be used with the system parameter DESTYPE. Screen This destination type sends the output to screen and is the only destination that does not utilize a printer driver for formatting the output. Instead it uses Screen fonts. All other destination types require at least one printer driver installed. Preview This destination type also sends the output to the screen but uses the Printer fonts of the default printer driver to format the output. While in Preview, the output can be sent to the printer if desired. File The output of a report can be stored in a file in various formats including Postscript, PCL, PDF, plain text or ASCII, RTF (rich text format), HTML or HTMLCSS (cascading style sheets). To generate a file in Postscript (or eps, encapsulated postscript format), simply set a Postscript printer driver as the default. If the output is opened in a text editor, the header information will show that it is in fact in Postscript format. To view Postscript output on screen, use a shareware Postscript viewer such as GhostView which can be downloaded off the Internet. Alternatively simply send the output file directly to a printer that understands Postscript. On UNIX you will require .ppd files and the configured uiprint.txt file. For each printer queue used, there must be one line in the uiprint.txt file. To generate a file in PCL format, use a PCL printer driver as default. If the output is opened in a text editor, the first line in the header will have a string LANGUAGE=PCL. On UNIX you will require .hpd files and .tfm files for the fonts, as well as the uiprint.txt file. To obtain plain text or ascii output, the report must be a Character mode report and run with MODE=Character. For RTF, PDF, HTML or HTMLCSS simply set the DESFORMAT parameter to any of these values. RTF output can be opened in Word Processors such as MS Word, PDF output can be viewed using the Adobe Acrobat Viewer, HTML or HTMLCSS can be viewed via a web browser such as Netscape or Internet Explorer. In Reports 6i, XML format will also be available. Mail This will connect to your email client and send an email with the report attached in eps (encapsulated postscript) format or in text format if the report is a Character mode report. Printer This sends the output directly to the default printer. Cache This is used when running Web Reports. The output is cached in a specified location and then dynamically redirected to the web browser on the client. In Oracle Reports 3.0, it is possible to send the output of a report to multiple destination types simultaneously by setting up a job in the Queue Manager. In version 6.0 this functionality is enhanced even further with the new Distribution capabilities.
1.3c) Different ways of calling a report

Below are the various means of calling a report, be it in an interactive mode or in batch mode. 1. 2. 3. The most common way of running a report is via Reports Runtime or directly from the command line. Alternatively a batch job can be scheduled via the Reports Queue Manager. If the Reports Server is installed remotely, then a client machine can schedule a report to run on the remote machine using the CLI executable (eg: r30cli32.exe), and optionally redirect the output back to the client by specifying the LOCALFILE parameter. A report can be called from a Form by using the RUN_PRODUCT command, or in Reports 3.0 and higher, the RUN_REPORT_OBJECT command. If running web forms, then WEB.SHOW_DOCUMENT( <URL can be >) used to call web reports. RUN_PRODUCT does not require a Reports Server. RUN_REPORT_OBJECT requires a Reports Server to be installed. WEB.SHOW_DOCUMENT requires Web Reports to be setup. Lastly, a report can be called via a URL in a web browser, if Web Reports has been setup (either CGI - Common Gateway Interface or OWS - Oracle Web Server).
4.
5.
1.3d) User input at runtime - the Parameter Form

To allow users to enter input variables at runtime, a report must have a Parameter Form. This is built very easily by choosing the Parameter Form Builder option in the Tools menu. Once the required system parameter and user parameters have been selected, you can specify a dynamic list of values or a static list of values, by going to the properties of the user parameters. This can also be used to restrict users to those values only. Where the user is allowed to enter their own values, a validation trigger can be created on the user parameters to check their accuracy. However where relatively complex validation is required, for example to compare a start date and end date which are both user parameters, it is best to create a Form through Form Builder, since Forms has much more extensive functionality relating to interactive user input validation. To display the parameter form when running web reports, ensure that the PARAMFORM runtime variable is set to HTML. To suppress the parameter form, use the option in the Tools>Preferences>Runtime Settings for that session only, or pass the runtime variable PARAMFORM=No. The Parameter Form can consist of more than one page, and the width and height of a page can be set in the Report level properties.
1.4 Printing from Oracle Reports

As described earlier, printer drivers are absolutely essential to run a report to any destination other than Screen The . reason for this is that Oracle Reports utilizes the printer driver when it formats the output. On Windows platforms, printer drivers are usually installed off the operating system CD. Once installed you can customize the driver name. So the same driver can be installed more than once with different names and different properties, for example one could point to a lower paper tray by default, although this functionality is now available within reports itself.. On UNIX, the common printer drivers are supplied with the Developer installation, for example some .ppd and .hpd files for Postscript and PCL printing. If there are any files unavailable for a particular Printer model, they may be obtained from the respective Printer vendor. The two printer related configuration files on UNIX are uiprint.txt and spoolcmd.sh which are both found in the ORACLE_HOME for Developer. Note that for Character mode reports, the .prt files specified in the DESFORMAT parameter, may contain information pertaining to the the physical printer, such as printer escape sequences. An ASCII printer driver is not required for Character mode reports.
When running a report to the printer, this is the path that is followed: Oracle Reports > Printer Driver > Printer Queue > Physical Printer + + + .rdf/.rep file Operating System Network So if for some reason the output is not appearing at the Printer, then follow the path one step at a time, to narrow down the location of the problem. Here are some hints: To check that Oracle Reports is using the Printer Driver correctly: 1. Run a report to file. 2. Open the output file in a text editor such as WordPad. 3. The header of the output file should be readable and have information about the Printer Driver used. To check that the Printer Driver is going to the Printer Queue: 1. Go to the properties of the Printer Driver. 2. Check that the Printer Queue is shown correctly. To check that the Printer Queue is printing to the Printer correctly: 1. Create a dummy text file. 2. Send it to the printer, directly from the operating system. eg: Right-mouse>Print in Windows Explorer, or lp -d<printerqueue> filename on UNIX. 3. If the above step works then the Report should also print.
One more point to note is that if the Report is built as a GUI or Bitmap report ie. With MODE=<default>, but is later run in a Character mode environment, and if the output is still required in Bitmap format, then: Run the report from the command line with BATCH=Yes and MODE=Bitmap.
1.5 Web Reports and the Reports Server

The three-tier architecture and Web Reports are very wide topics to cover and to discuss them in detail will digress from the scope of this paper. However here are some key concepts that may be useful in understanding the overall picture. First, what is the three-tier architecture? This is an extension to the the two-tier or more familiarly known as the client/server architecture. The three tiers are as follows: 1. Thin client - Web Browser 2. Application server - Developer Server (including Reports Server) and Web Server 3. Database server These tiers can reside on one or more physical machines. The first tier would typically be a Windows95/98 client, the middle tier typically NT 4.0 or Solaris, and the back-end tier a UNIX box running Oracle. The Jinitiator web browser plug-in, although required for Web Forms, is not required for Web Reports. There are two methodologies that can be employed for running Web Reports. CGI or OWS Cartridge. The first method is not dependent on the Oracle Application (Web) Server or any particular version thereof and can therefore run against other Web Servers. The second method must have a cartridge setup first using Oracle Application Server, and is more complex to configure compared to the CGI method. The direction which Oracle is encouraging customers to take now is to employ the CGI or non-cartridge method. The HTML online documentation that is provided with the Developer Server installation, has all the detailed steps for setting up CGI and OWS reports. Creating the Reports Server requires one entry in the tnsnames.ora file which is located under the ORACLE_HOME. On NT, the Reports Server can be installed from the command line, as either a NT service or non-service. If installed as a NT service, it is very important that the service is started as a non-system user that has access to the printer drivers. The NT service can be setup to start automatically so that a manual startup is not required every time the machine is restarted. On UNIX, simply run the reports server executable to start the Reports Server process. The file <reports_server_name>.ora in the ORACLE_HOME contains configuration settings for the Reports Server. In Reports 6i it is possible to run Reports via a WebDB listener which is light-weight and also enables a further layer of security and administration, using the WebDB security model. This is discussed further on page 21.
1.6 Using Oracle Reports with Other Products Oracle Applications

This extensive suite of products includes hundreds of reports which have been built with Oracle Reports. Sometimes these reports require customization. If the release of Oracle Applications installed, runs Character mode reports on a UNIX server, via Concurrent Manager, then here are some brief steps on the process to follow for modifying an Oracle Applications report. 1. 2. 3. 4. 5. 6. FTP the .rdf file from the UNIX machine to a PC running a similar version (the first three digits of the version number should be identical) of Reports. Make the modifications to the .rdf file. Do not run it, since the PC will not have the Oracle Applications environment for doing so. FTP the .rdf file back to the UNIX box. Run it from the command line in batch mode, if possible. Ensure the report is registered correctly in the Applications environment. Run the report from Concurrent Manager to test it.
Oracle Graphics
This is another relation to Oracle Reports. Simply create a Chart Object in the reports layout and reference a .ogd or .ogr file generated from Oracle Graphics. At runtime, the Graphics Batch process will start in the background, run the graph, and display it on the report. In Reports 3.0+, there is a Chart Wizard, which will step through the creation of a Graph from within Reports itself.
Oracle Forms
The most common integration with Forms is when the RUN_PRODUCT, RUN_REPORT_OBJECT, WEB.SHOW_DOCUMENT or HOST command is used to call a report from a form. Note that if required, an entire parameter list can be passed from Forms to Reports.
Microsoft Excel
A Character mode report that saves its output to a file with an extension of .csv, will automatically be recognizable by MS Excel. For example, a hyperlink on a Web Report can point to a .csv file, which will automatically startup MS Excel and display the text (assuming the MIME types have been setup correctly in the Web Browser).
Query Builder
Some may recall that Query Builder used to be called Browser in the past and was closely linked with Discoverer/2000. However, Query Builder is now bundled with Developer as a standalone product as well as subcomponent of Reports. A button in the Data Model Wizard starts up Query Builder and provides a graphical representation of a Query, minimizing the need for typing SELECT statements.
Oracle Designer
This suite of products is also very closely linked with Oracle Developer in that, Oracle Designer has the ability to generate Forms and Reports. Oracle Developer is then used to customize these files.
WebDB
In the next release of Reports, that is Reports 6i, it is possible to tightly integrate Web Reports with WebDB. Here is an excerpt from a paper written by Stacey London of Oracle entitled New Features in Oracle Reports 6i. Oracle WebDB is a powerful HTML-based publishing and development solution for managing and publishing dynamic content on the Web. With Oracle WebDB, you can create powerful web sites, securely organize Web content, and seamlessly publish dynamic data. All that is needed is a Web browser, making it easily accessible and manageable, from site creation to administration tasks. All WebDB content is stored in a repository in an Oracle database and utilizes the Oracle Web Developers Toolkit to display HTML in your browser. WebDB 2.2 has been tightly integrated with Oracle Reports to create a robust and secure reporting environment. New Oracle Reports security wizards have been added to WebDB, permitting an authorized administrator to control access to Report Definition Files, Reports Servers, printers, output formats, report parameters and accessibility to the reporting environment overall. The Site Building capabilities of WebDB provide an easy mechanism with which to publish Oracle Reports for end user access via the Web.
2. Troubleshooting
2.1 Debugging
When attempting to fix a problem, look for the root of the problem first, before looking for a solution. Try to narrow down the scope by eliminating as many variables as possible. It helps to be aware of the process which is followed when a report is run. The report is called from another product or the command line. If it is called from another product, eliminate that variable by calling it from the command line. The parameter form may or may not be displayed. If the problem relates to passing of runtime variables, then display the parameter form, this will show you whether the parameter values have reached the report successfully. Note that there are several Report level triggers that fire in any report. The Before Parameter Form Trigger fires Parameter Form The After Parameter Form Trigger fires Queries are parsed The Before Report Trigger fires Data is fetched and the first page is formatted If there is more than one page, the Between Pages Trigger fires between the pages The After Report Trigger fires after the report is complete. In each of these triggers, it is possible to display a message, which can be used to check how far the report is executing or what the status of a flag or variable is. The syntax for the message command in Reports is: SRW.MESSAGE(N, TEXTor VARCHAR2 variable); If there are ORA errors resulting from DML or DDL statements to the database, run a SQL*Net client side trace to find out what statements are being sent. A client side SQL*Net trace is obtained by setting TRACE_LEVEL_CLIENT, TRACE_DIRECTORY_CLIENT and TRACE_FILE_CLIENT in the sqlnet.ora file. If the report runs successfully, but does not format or print correctly see section 1.4 above on Printing issues. If it appears that the Report is corrupt, for example it cannot be opened or edited, then try the following file conversion using the Reports Convert utility. RDF (binary/executable) > REX (text) > RDF (binary/executable). This often eliminates any possible corruptions in the RDF file. During design time: If there are errors in the SQL Queries, try running the Query from SQL*Plus first. Ensure that the query returns the correct data. Then copy the query to Reports. If there are errors in the Layout Editor, then re-visit the Mountain Range principle to ensure the objects are layered correctly.
2.2 Some common errors and how to resolve them

ora-1002 Fetch out of sequence The solution is to add , null to the end of the SELECT clause. For example, SELECT col1, col2, , NULL FROM rep-1216 Illegal print condition This often occurs with the LAST or ALL BUT LAST print conditions. First, try with the print condition set to DEFAULT, ensure it still works. If LAST or ALL BUT LAST is required, then anchor the object to the frame above it. rep-1814 Infinite report detected This can be caused either by a data or layout problem. Try the query in SQL*Plus, do you get an infinite number of records? You may be missing a join. If not, then check the Layout. Ensure that there are no objects that are too close to the lower boundary of the page. If there are, then try moving them up a fraction. rep-1800 Formatter error This indicates that a valid printer driver is not installed or is not recognized by Oracle Reports. See section 1.4 above for more information relating to printing. rep-3000 Internal error starting Oracle Toolkit If attempting to run a GUI version of Reports on Motif (UNIX), ensure the DISPLAY environment variable is set to your IPaddress:0.0 . eg: $ export DISPLAY=140.83.32.99:0.0 If running in character mode, ensure the TERM environment variable is set correctly. eg: $ export TERM=vt220 rep-0001 Unable to initialize message subsystem On UNIX, ensure that the ORACLE_HOME environment variable is pointing to where Developer is installed. On Windows, check the ORACLE node in the registry for a parameter called RWnn. This should point to the ORACLE_HOME\REPORTSnn directory. eg: RW25 = c:\orant\reports25 rep-1213 Field <field name> references column <column name>at a frequency below its group. This usually happens because a field has lost its source or has been created in the incorrect frame. See section 1.2b for how to resolve this.
Conclusion
It is my hope that this paper has achieved its objective, by providing a clearer understanding of what Oracle Reports is all about and how best to work with it as a reporting tool.

Reports6i Secrets For Developers

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Reports6i Secrets For Developers

Uploaded by

Copyright:

Available Formats

Oracle Reports - Secrets for Developers October 19, 1999 by Sriyani De Silva Page 1 _____________________________________________________________________________________________________________

Oracle Reports - Secrets for Developers

1. Hints, Tips and Fundamental Concepts.

1.1b) Upgrade Path

1.2 Building or modifying a report

1.2a) Data Model

Queries, Groups and Columns

Single Query with join clauses vs Multiple Queries with Links

Summary, Formula and Placeholder columns

System Parameters and User Parameters

1.2b) Layout Model

The Three-Dimensional Mountain Range Concept

Here is a diagram of a simple layout.

Moving and Re-sizing Layout Objects

The Margin Area

The Push Path

Physical and Logical Pages

Building Character Mode reports

Merging Fields (variable text) with Boilerplate text (static text)

1.3 Running a report 1.3a) Basic requirements

1.3b) Destination types - where should the output go?

1.3c) Different ways of calling a report

1.3d) User input at runtime - the Parameter Form

1.4 Printing from Oracle Reports

1.5 Web Reports and the Reports Server

1.6 Using Oracle Reports with Other Products Oracle Applications

2.2 Some common errors and how to resolve them

You might also like