Oracle Reports - Secrets for Developers

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

Oracle Reports - Secrets for Developers

Sriyani De SilvaPrincipal Support Analyst

Oracle Asia Pacific Global Support CentreMelbourne - Australia


ContentsORACLE REPORTS - SECRETS FOR DEVELOPERS........................................................................................1

INTRODUCTION...................................................................................................................................3

AUDIENCE..............................................................................................................................................3OBJECTIVES ...........................................................................................................................................3ACKNOWLEDGMENTS .............................................................................................................................3

1. HINTS, TIPS AND FUNDAMENTAL CONCEPTS. ........................................................................4

1.1 UPGRADING FROM A PREVIOUS RELEASE.............................................................................................41.1a) History of releases....................................................................................................................41.1b) Upgrade Path ...........................................................................................................................5

1.2 BUILDING OR MODIFYING A REPORT...................................................................................................61.2a) Data Model ..............................................................................................................................61.2b) Layout Model .........................................................................................................................101.2c) How the Data Model and Layout Model are related................................................................15

1.3 RUNNING A REPORT ........................................................................................................................161.3a) Basic requirements .................................................................................................................161.3b) Destination types - where should the output go? .....................................................................161.3c) Different ways of calling a report ...........................................................................................171.3d) User input at runtime - the Parameter Form...........................................................................17

1.4 PRINTING FROM ORACLE REPORTS ..................................................................................................181.5 WEB REPORTS AND THE REPORTS SERVER .......................................................................................191.6 USING ORACLE REPORTS WITH OTHER PRODUCTS............................................................................20

2. TROUBLESHOOTING....................................................................................................................22

2.1 DEBUGGING ...................................................................................................................................222.2 SOME COMMON ERRORS AND HOW TO RESOLVE THEM.......................................................................23

CONCLUSION......................................................................................................................................24


Introduction

AudienceThis paper is written for application developers who have had some basic technical experience with Oracle Reports as areporting tool.

ObjectivesThe aim is to share with you, in a concise and simple format, fundamental concepts about the various aspects of OracleReports, starting from building or modifying a report, through to troubleshooting methods for quick resolution oferrors.

AcknowledgmentsI extend my appreciation and thanks to the staff at Oracle, both in Melbourne and Auckland, whom I have worked withsince 1994. The many customers I have worked with, for their technical input and diversity of thought. To the OracleEducation 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 releasesIn the beginning, there was RPT. This was a character mode reporting tool that was based on SQL statements. This toolcan 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 becopied 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 waspart 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. CDE2later 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 Reports Version Forms VersionOracle V6 Tools SQL*ReportWriter 1.1 SQL*Forms 3.0CDE1 Oracle Reports 2.0 Oracle Forms 4.0CDE2 Oracle Reports 2.5 (early versions) Oracle Forms 4.5 (early versions)Developer/2000 1.x Oracle Reports 2.5 Oracle Forms 4.5Developer/2000 2.x Oracle Reports 3.0 Oracle Forms 5.0Oracle Developer 6.0 Oracle Reports 6.0 Oracle Forms 6.0Oracle Developer 6i Beta Oracle Reports 6i 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 particularrelease. 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 > 6iSQL*ReportWriter 1.1 > Oracle Reports 2.5 > 6iOracle Reports 2.5 > 6.0 or 6iOracle 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 beupgraded 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 mostinstallations 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 selectedfrom the database. The Layout Model is where the appearance of the report output is decided. These two sections of areport are discussed in more detail below.

1.2a) Data Model

Queries, Groups and ColumnsThe Data Model is used to define all the Queries that select the required data for the report. The query Columns arethen structured into Groups. So a report can have one or more queries, a query can have one or more groups, and agroup can have one or more columns. In what sequence the groups are structured, is extremely important indetermining 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 theemployees in another query, and then link the two queries using their primary and foreign keys.

Single Query with join clauses vs Multiple Queries with LinksFrom 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 DataModel. 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 SELECTclause, 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. Forexample:WHERE DEPT.DEPTNO = EMP.DEPTNO(+)Using this syntax, you achieve two things: One - the number of queries are minimized thereby reducing network trafficand improving performance; Two - an outer join is created, thereby ensuring the listing of all parent records, regardlessof whether they have any child records or not.

Sort OrderThe group heirarchy also determines the sort order of the data. The ORDER BY clause in the SELECT statement canonly 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 thecolumns 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 Modelwindow, not in the Object Navigator.

Column AliasingWhen writing queries in Oracle Reports, always specify column aliases to keep column names clear and readable. Thisis extremely useful when future modifications are required to the Data Model. The reason is that the Layout model isdriven by the Data model, so any changes in the Data model will cascade down to the Layout model. Using columnaliases, protects the Layout model (to a certain degree), from such changes.

Summary, Formula and Placeholder columnsApart from columns which are selected from the database, there are other types of columns which can be created withinthe 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 ahigher 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 populatea 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 theSUMMARY 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, theFORMULA column must be created in the same group as the salary and commission percentage columns, that is theemployee group.If you want to create a PLACEHOLDER column, or container into which values are assigned, place it in the samegroup 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 ifand 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 efficientcompared to querying all the records from the server to the client and performing the calculations on the client side.

System Parameters and User ParametersThese parameters also fall under the Data Model umbrella. They can be viewed from the Object Navigator, not from theData Model window. Why do these parameters belong to the Data Model? Because they represent DATA that isrequired 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 ofparameters are required in conjunction with the Runtime Parameter Form which will be discussed later on in thispaper.


System VariablesThese are default variables such as Current Date or Physical Page Number, a list of which is found in the Sourceproperty of a field.

Global VariablesThese can be very useful when you need to assign values to variables in “mid-flight”, for example in the Between PagesTrigger or in a format trigger. To create a global variable, simply create a local PL/SQL program unit of type PackageSpec, 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 reporttrigger 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” ConceptThe layout model is one of the most interesting, creative and visual aspects of Oracle Reports. Think of it as aMountain Range. The largest frames at the base, the smaller frames above that, moving right up to the very smallestframes at the peak of the mountains. This type of visualization is invaluable in deciphering the many layers of objectsthat are present, even in a simple report. Adversely, if the layout is not visualized in this way it will merely seem like amaze of objects, layer upon layer!

The “Mountain Range” concept is attempting to help you visualize what seems to be a two-dimensional diagram, inthree-dimensions. The layout of a report, does have three dimensions. Across the page, Down the page, and Throughthe page. Obviously when printed on paper, the third dimension is a little difficult to see, but it is present in terms ofthe 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 theData Model. This link is discussed later in this paper.


Moving and Re-sizing Layout ObjectsAlways save the report before attempting extensive moving or re-sizing of objects in the layout. As a last resort, thelayout can always be re-defaulted, however if a lot of formatting has already been done, then a re-default may not bewise as all the customized formatting will be lost. If an object is moved or re-sized by mistake, use the Edit>Undomenu 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 iscontrolled by the Padlock button in the Layout Window. By default it is pressed, that is the padlock is locked, keepingthe layout objects confined to their enclosing objects. This prevents you from accidentally moving an object outside ofthe boundaries where it belongs.If Confine Mode is turned off, an object can potentially be moved outside of the frame where it belongs, which willresult in a frequency error. Move the object back to its parent frame and turn on Confine Mode, the error willdisappear.

As emphasized earlier, when making changes in the Layout Window, always keep in mind the Mountain Rangeconcept. 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 itright 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 buttonpalette) 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 requiredin 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, turnoff Flex Mode.

The Arrange menu is also extremely useful for uniformally sizing and aligning objects.

The Margin AreaHaving 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 allthe 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 frameswill still be visible, but they cannot be selected. Any object now placed on the Margin Area, will appear as the backdropon 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 anentire layer and not just a strip around the page, it can be used for templates for which we would otherwise use pre-printed stationery.

The size of the margins can be controlled from the layout window as well as from the Page Setup dialog duringprinting. The page boundaries are determined by the height and width dimensions in the report properties.


The Push PathLayout objects displaying data such as fields and repeating frames, by default have the ability to expand down the pageat runtime to accommodate all the rows which are retrieved by the queries. This is what is meant by a Vertical Sizing ofVariable 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 othercarriages 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 ofdata 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, wheredetail 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!! Toprevent 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 PagesA physical page as we all know can be an A4 sheet of paper for example. However let us say our report needs to print100 columns of data across the page. This may not fit on one physical A4 sheet of paper, even if the report is printedwith 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 fittedin. 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 willstill print as blank pages. These blank pages can be suppressed in Oracle Reports 3.0+ by setting the BLANKPAGESruntime parameter to ‘No’.


Building Character Mode reportsHere 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 andresult 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 characterunits, as well as enables the passing of escape sequences to the printer, to enable such things as Bold orcompressed text. These escape sequences or printer codes are specific to each printer model and therefore must beobtained from the printer manual.

6. In Reports 3.0+, simply apply the Character mode template in the Wizard when creating the layout for the firsttime, 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 pagedimensions 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 andsome 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 madehidden 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 setcorrectly in the hidden field, but most important, ensure that the Horizontal Sizing of the hidden fields is set toVariable, 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 BreaksAlways 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 theMaximum 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 samepage, 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 PrintingThis functionality has been greatly enhanced in recent versions of Reports. The “Conditional Formatting” property on alayout 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 beapplied. For example, if you wish to suppress the salary field in an employee listing, unless the person running thereport is a manager, and assuming p_user_type is a custom variable that stores the user information, then the followingcode 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 Layout ModelGroup Repeating FrameColumn Field

Therefore, every Repeating Frame must relate back to one Group. Every Field in the layout, must relate back to aColumn in the Data Model. This link is established by the Source property of a Repeating Frame or Field. Howeverevery 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 willappear as fields in the department repeating frame. Columns in the employee group, will appear as fields in theemployee repeating frame. If there are 4 department records returned, the department repeating frame will repeat 4times. Since the employee group is structured as a child of the department group, the employee repeating frame will beinside, 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 isimportant 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 aTabular style report, one group in the Data Model is sufficient. For a Master-Detail, Group Left or Group Above stylereport, there must be at least two groups present in the Data Model. For a Matrix style report, there must be at leastthree 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 requirementsTo run a test report, all that is required is Reports Runtime, a valid connection to a Database, any layout object on theLayout, 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 driverfor formatting the output. Instead it uses Screen fonts. All other destination types require at least one printer driverinstalled.

Preview This destination type also sends the output to the screen but uses the Printer fonts of the default printer driverto 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 orASCII, 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 thedefault. 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 downloadedoff the Internet. Alternatively simply send the output file directly to a printer that understands Postscript. On UNIX youwill require .ppd files and the configured uiprint.txt file. For each printer queue used, there must be one line in theuiprint.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 firstline in the header will have a string “LANGUAGE=PCL”. On UNIX you will require .hpd files and .tfm files for thefonts, 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 AcrobatViewer, 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 (encapsulatedpostscript) 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 dynamicallyredirected 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 settingup a job in the Queue Manager. In version 6.0 this functionality is enhanced even further with the new Distributioncapabilities.


1.3c) Different ways of calling a reportBelow are the various means of calling a report, be it in an interactive mode or in batch mode.

1. The most common way of running a report is via Reports Runtime or directly from the command line.2. Alternatively a batch job can be scheduled via the Reports Queue Manager.3. 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 byspecifying the LOCALFILE parameter.

4. A report can be called from a Form by using the RUN_PRODUCT command, or in Reports 3.0 and higher, theRUN_REPORT_OBJECT command. If running web forms, then WEB.SHOW_DOCUMENT(‘<URL’>) can beused to call web reports.

RUN_PRODUCT does not require a Reports Server. RUN_REPORT_OBJECT requires a Reports Server to beinstalled. WEB.SHOW_DOCUMENT requires Web Reports to be setup.

5. Lastly, a report can be called via a URL in a web browser, if Web Reports has been setup (either CGI - CommonGateway Interface or OWS - Oracle Web Server).

1.3d) User input at runtime - the Parameter FormTo allow users to enter input variables at runtime, a report must have a Parameter Form. This is built very easily bychoosing 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 ora static list of values, by going to the properties of the user parameters. This can also be used to restrict users to thosevalues only.

Where the user is allowed to enter their own values, a validation trigger can be created on the user parameters to checktheir accuracy. However where relatively complex validation is required, for example to compare a start date and enddate which are both user parameters, it is best to create a Form through Form Builder, since Forms has much moreextensive functionality relating to interactive user input validation.

To display the parameter form when running web reports, ensure that the PARAMFORM runtime variable is set toHTML.

To suppress the parameter form, use the option in the Tools>Preferences>Runtime Settings for that session only, orpass 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 Reportlevel properties.


1.4 Printing from Oracle ReportsAs described earlier, printer drivers are absolutely essential to run a report to any destination other than ‘Screen’. Thereason 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 cancustomize the driver name. So the same driver can be installed more than once with different names and differentproperties, for example one could point to a lower paper tray by default, although this functionality is now availablewithin reports itself..

On UNIX, the common printer drivers are supplied with the Developer installation, for example some .ppd and .hpdfiles for Postscript and PCL printing. If there are any files unavailable for a particular Printer model, they may beobtained from the respective Printer vendor.The two printer related configuration files on UNIX are uiprint.txt and spoolcmd.sh which are both found in theORACLE_HOME for Developer.

Note that for Character mode reports, the .prt files specified in the DESFORMAT parameter, may contain informationpertaining to the the physical printer, such as printer escape sequences. An ASCII printer driver is not required forCharacter 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 downthe 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 laterrun 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 ServerThe three-tier architecture and Web Reports are very wide topics to cover and to discuss them in detail will digressfrom the scope of this paper. However here are some key concepts that may be useful in understanding the overallpicture.

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 Browser2. Application server - Developer Server (including Reports Server) and Web Server3. 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-endtier 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 cantherefore run against other Web Servers. The second method must have a cartridge setup first using Oracle ApplicationServer, 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 forsetting 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 installedas a NT service, it is very important that the service is started as a non-system user that has access to the printerdrivers.The NT service can be setup to start automatically so that a manual startup is not required every time the machine isrestarted.

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 ofsecurity and administration, using the WebDB security model. This is discussed further on page 21.


1.6 Using Oracle Reports with Other Products

Oracle ApplicationsThis extensive suite of products includes hundreds of reports which have been built with Oracle Reports. Sometimesthese reports require customization.If the release of Oracle Applications installed, runs Character mode reports on a UNIX server, via ConcurrentManager, then here are some brief steps on the process to follow for modifying an Oracle Applications report.

1. FTP the .rdf file from the UNIX machine to a PC running a similar version (the first three digits of the versionnumber should be identical) of Reports.

2. Make the modifications to the .rdf file. Do not run it, since the PC will not have the Oracle Applicationsenvironment for doing so.

3. FTP the .rdf file back to the UNIX box.4. Run it from the command line in batch mode, if possible.5. Ensure the report is registered correctly in the Applications environment.6. Run the report from Concurrent Manager to test it.

Oracle GraphicsThis 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 thegraph, 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 FormsThe 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 entireparameter list can be passed from Forms to Reports.

Microsoft ExcelA Character mode report that saves its output to a file with an extension of .csv, will automatically be recognizable byMS Excel.For example, a hyperlink on a Web Report can point to a .csv file, which will automatically startup MS Excel anddisplay the text (assuming the MIME types have been setup correctly in the Web Browser).

Query BuilderSome 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. Abutton 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 DesignerThis suite of products is also very closely linked with Oracle Developer in that, Oracle Designer has the ability togenerate Forms and Reports. Oracle Developer is then used to customize these files.


WebDBIn the next release of Reports, that is Reports 6i, it is possible to tightly integrate Web Reports with WebDB. Here is anexcerpt 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 publishingdynamic 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 andutilizes 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. NewOracle Reports security wizards have been added to WebDB, permitting an authorized administrator to control accessto Report Definition Files, Reports Servers, printers, output formats, report parameters and accessibility to the reportingenvironment overall. The Site Building capabilities of WebDB provide an easy mechanism with which to publishOracle 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 narrowdown 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 isexecuting or what the status of a flag or variable is. The syntax for the message command in Reports is:

SRW.MESSAGE(N,’TEXT’ or 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 thecorrect 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 layeredcorrectly.


2.2 Some common errors and how to resolve themora-1002 Fetch out of sequenceThe solution is to add “, null” to the end of the SELECT clause.For example, SELECT col1, col2,… , NULL FROM …

rep-1216 Illegal print conditionThis often occurs with the LAST or ALL BUT LAST print conditions. First, try with the print condition set toDEFAULT, 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 detectedThis can be caused either by a data or layout problem. Try the query in SQL*Plus, do you get an infinite number ofrecords? You may be missing a join. If not, then check the Layout. Ensure that there are no objects that are too close tothe lower boundary of the page. If there are, then try moving them up a fraction.

rep-1800 Formatter errorThis 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 ToolkitIf attempting to run a GUI version of Reports on Motif (UNIX), ensure the DISPLAY environment variable is set toyour IPaddress:0.0 .eg: $ export DISPLAY=140.83.32.99:0.0If running in character mode, ensure the TERM environment variable is set correctly.eg: $ export TERM=vt220

rep-0001 Unable to initialize message subsystemOn 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 theORACLE_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.


ConclusionIt is my hope that this paper has achieved its objective, by providing a clearer understanding of what Oracle Reports isall about and how best to work with it as a reporting tool.

Documents

Oracle Reports - Secrets for Developers