Reports


Chapter 9 . Running Reports

While you are developing a report, you can preview its output at any time. You can either view reports at your terminal through the editor's viewer; or you can send output to a file or printer. In graphical environments such as Windows, the viewer accurately shows the output you can expect from printed output. Because the viewer is integrated within the editor, you can make changes immediately based on the viewer output, then output the report in the viewer again to see how your changes look. You can also use the Panther debugger to test reports that are run in the editor.

When a report is complete, you can run it from the command line or from a Panther application. You can view a report onscreen or in a web browser, print it, or save it to a file. You can also set up a report so that users can control report output.

In a three-tier environment with JetNet/Oracle Tuxedo, you can request that the report be run on the server and then have the results returned to the client after processing is complete.


Running Reports from the Report Menu

The editor's Report menu lets you generate output for any report currently displayed in the editor. This menu is also available in a Panther application that uses the default Panther menu bar.

Note: In the three-tier environment, the Report menu lets you generate reports on the client only; to process reports on the application server, run the report from the command line or from within the application, using JPL or C functions (refer to "Running Reports Outside the Editor").

You can send output to the report viewer, an available printer, or a file:

  1. If necessary, open the database required by the report: from the File menu, choose OpenDatabase and select the desired database. For more information on connecting to a database, refer to "Connecting to a Database."
  2. From the Report menu, choose Preview Report (from the editor) or Run Report (from a Panther application). The Run Report dialog box opens.

    Figure 9-1 The Run Report dialog box lets you view reports onscreen or send reports to a printer or file.

  3. Select the report as follows:
  4. To prevent display of warning messages, select Suppress Warnings.
  5. Choose Arguments to enter argument values for predefined report parameters. For more information about supplying arguments to reports, refer to "Supplying Arguments."
  6. Choose Page Setup to change page size, orientation, and margins. The next section describes page setup options.
  7. Direct output by selecting from the Output To box one of these options: Viewer, Printer, or File.
  8. When you select Printer or File for report output, the Print Setup push button becomes active so you can change printing options. The Print Setup dialog is different for each platform; for more information, refer to "Windows Print Setup" or "UNIX Print Setup".
  9. Choose OK to start report output.

Page Setup

The Page Setup dialog specifies page size, orientation, and margins. On Windows, Panther gets paper size and orientation settings from the system. On UNIX, initial settings for the Page Setup dialog box are read from the rwviewpr.ini file, if available.

Note: Settings in this dialog are not saved and are overruled by the report's Page Format node (see "Setting Page Format"). Use this node to set page layout properties permanently.

Figure 9-2 On the Page Setup dialog box, set additional margins, change the page size, and change the page orientation.

Paper Size
Specify the dimensions of the output area on report pages. You can select one of the predefined page sizes from the drop-down list, or specify your own page size in this format:
width x height [unit-spec]

Refer to "Page Size" for valid units of measurement.

Orientation
Select Portrait to use the shorter page measurement as the width of the report. Select Landscape to use the longer page measurement as the width.

Margins
Add space to the report's margins by editing these fields. Specify the amount of space in this format:
margin-space [unit-spec]

Refer to "Page Size" for valid units of measurement.

Duplex
Select one of the duplex printing options:

Windows Print Setup

In Windows, choosing Print Setup from the editor invokes the print dialog for that platform. For example, Windows displays this dialog:

For more information about changing print setup options, refer to your system documentation.

UNIX Print Setup

On UNIX systems, choosing Print Setup displays a dialog box that lets you control the print driver, the spool command, and the device file for the report:

Select Driver
Choose the output driver to use for the file:

Spool File
Enter the name of the file to hold the report output before it is sent to the printer. This option is accessible only when Pipe Output is inactive.

Spool Command
Enter the print command used in your operating system. If Pipe output is selected, the report is piped directly to this command. Otherwise, the report is stored in the spool file and the command should include the spool file name.

Pipe output
Selection of this option automatically sends the report output to the printer using the command in Spool Command.

Device File
This text field is visible only if you specify Generic Printer as the output driver. Enter the name of the device file to use in printing an ASCII report with the Generic Printer driver. Each device file is a binary file, compiled from ASCII, that enables printing options. For information on device files, refer to Appendix C, "Report Device Configuration Files."

Save on exit
If selected, Page Setup and Print Setup dialog settings on UNIX platforms are saved to rwviewpr.ini in the current directory when the application exits.

Running Reports Outside the Editor

You can run a report outside the editor in several ways:

Report invocations specify a report and its arguments and options with this format:

filename[!reportname ] [ (arg[, ... ] )] [ option ]...

This invocation string can also be used for subreports. For more information on subreports, refer to "Invoking Subreports."

Note: Invocation strings for URL-invoked reports conform to URL syntax rules; refer to "How to Invoke a Report From a URL" for variations in URL report invocation.

filename[!reportname]
filename is the name of a binary report file. Panther looks for the specified file in the application's memory-resident list, then in all open libraries. For remote report processing, the report file must be a library that is open to the server. You can optionally specify reportname to invoke a specific report definition in filename. If you omit reportname, Panther uses the first report definition in the file.

arg
Supply one or more arguments. Refer to "Supplying Arguments" for more information.

option
Specify one or more options to specify the output file or report format specifications. For available options and descriptions, refer to "Setting Invocation Options."

How to Invoke a Report From the Command Line

Use the rwrun utility to run reports from the command line or in a batch file. rwrun has this syntax:

rwrun filename[!reportname ] [ (arg[, ... ] )] [ option ]...

For example, the following UNIX invocation runs the custinfo.rpt report and writes the report to the file custinfo.txt. The invocation string passes a customer ID number as a parameter to the report.

rwrun custinfo.rpt \(1001\) output=custinfo.txt

Note: Any punctuation that has special usage in the operating system, such as parentheses (), must be prefixed with an escape character (\).

How to Invoke a Report From a JPL Procedure

runreport filename[!reportname ] [(arg[,...] )] [option]...

The following JPL procedure runs the custinfo.rpt report for the value in the cust_num variable and writes the report to the file custinfo.txt.

proc make_report( cust_num )
runreport custinfo.rpt (cust_num) output=custinfo.txt
return

How to Invoke a Report From a C Function

sm_rw_runreport (char *invocation-string)

For example:

int make_report( int cust_num );
{
char invocation[128];
sprintf (invocation,
"custinfo.rpt (%d) output=custinfo.txt", cust_num);
return sm_rw_runreport( invocation );
}

How to Invoke a Report From a URL

protocol://domain/filepath[?[!reportname] [(arg[,...])] 
[option]...]

Specify the desired report and, optionally, any arguments and invocation options.

For example, this URL invokes report custinfo.rpt in the web_vb application:

http://myhost.com/cgi-bin/web_vb/custinfo.rpt

You can add arguments and invocation options as parameters to the URL by appending a question mark ? to the report file specification, followed by the desired report name, arguments and options. For example, you can modify the previous report invocation by adding an argument of 11, which is mapped to report parameter cust_id when you invoke the report:

http://myhost.com/cgi-bin/web_vb/custinfo.rpt?(11)

Spaces within a URL are illegal. For more about URL syntax rules, refer to "Specifying a URL" in the Web Development Guide.

Note: Reports that are invoked by a URL do not share global data with the screens or reports that call them. Pass any needed data as parameters in the URL.

Setting Invocation Options

A report invocation string can contain one or more of the following options:

Remote Processing

remote [service=service-name] [async]
In a three-tier environment with JetNet/Oracle Tuxedo, a client's report invocation can run a report locally, or specify to run it remotely on an application server. If you omit the keyword remote, Panther runs the report locally on the client. The remote option can be specified for any report that is in a library open to the application server, such as common.lib or server.lib. The server calls the specified report service (service=service-name), or, if none is specified, uses the default report service sm_run_report.

Note: The default report service and the included unload handler process the report on the server and then send the results (in metafile format) back to the client where they can be viewed, printed or saved to a file for later output via sm_rw_play_metafile. Refer to "Default Report Service and Unload Handler" for a detailed description of how the default service and the unload handler process the report.

If you specify a custom report service with service=, the service must be defined in the JIF; the service routine must also receive and return service messages as defined for the default report service.

By default, report service requests are synchronous—that is, all client processing ceases until the service request returns, either with report output or an error. Use the async option to continue client processing while the report service executes. When the service returns, the report is saved or printed in the background.

Note: rwrun and URL invocations ignore the async option. All remote processing options are invalid for sm_rw_play_metafile.

For more information about report services, report service messages and remote processing requirements, refer to "Calling Report Services in JetNet/Oracle Tuxedo."

Initialization Options

In Windows, rwrun32.exe and rwrun64.exe support the -ini option to use a specific initialization file. The user may specify SMBASE, SMPATH, SMVARS, SMUSER, SMFLIBS, SMRBCONFIG, SMRBHOST, SMRBPORT, and SMTPJIF in the initialization file.

Note: If the -ini option is not specified, prol5w32.ini or prol5w64.ini in the Windows directory will be used.

Driver Options

If the report invocation string omits driver specification and report processing is local, Panther determines the default driver according to the local machine's platform: windows for reports processed on Windows and text for all other platforms.

When the invocation string omits driver specification and report processing is handled by a server—either a Web application server or an application server—Panther determines the default driver as follows:

On Windows systems, you can usually omit driver specification and rely on defaults to yield the desired output. Explicitly name the driver only if you need to redirect the output to a file. This can be desirable on UNIX systems, where usage of scalable fonts and graphics requires PostScript or PDF output. For example, this invocation string outputs a report to PostScript and spools the output to a printer:

runreport custinfo.rpt (cust_num) driver=postscript \
spool="lpr -Pljet"

To specify an output driver, use this option in the invocation string:

driver=driver-name

driver-name can have one of these values:

html
Generates the report in HTML format. For more information about outputting a report to HTML and viewing it in a Web browser, refer to "Running Reports in a Web Browser." HTML reports can also be saved in files.

pdf
Generates a PDF (portable document format) report (Panther 5.20 and later).

postscript
Generates the report in Adobe PostScript format.

rwmetafile
Generates the report in metafile format. The contents of a metafile can be viewed in the report viewer (refer to "Viewing Reports Onscreen"); you can also output a metafile's contents using another driver by calling sm_rw_play_metafile.

text [ device=device-file ]
Generates the report in ASCII text. The device option lets you use the capabilities of the named device configuration file to control report output. For more information about device files, refer to Appendix C, "Report Device Configuration Files."

For example, the following command-line invocation uses the device file printfile to generate the output of custhist.rpt:

rwrun custhist.rpt driver=text device=printfile spool=lp

windows
Generates the report in the format needed to output the report on Windows.

xml
Generates the report in XML format (Panther 5.40 and later).

Output Destination

You can direct output to one of several destinations: to an output file, printer, spool file, or to the report viewer. If no output destination is specified, the following defaults obtain:

To direct report output, use one of these options:

output=output-file [ overwrite | append ]
The output option directs the finished report to the named file. If output-file already exists, the overwrite option suppresses the confirmation message and allows report output to overwrite the file's contents; the append option appends report output to the file.

For example, the following command-line invocation outputs custhist.rpt in PostScript and saves the output to c.ps even if the file already exists:

rwrun custhist.rpt driver=postscript output=c.ps overwrite

printer=printer-name
(Windows only) Directs the finished output to an installed printer.

print
(Windows only) Prints the report to the system's default printer.

printtofile
(Windows only) Saves printer output to a file using the system's default printer settings. A dialog asks for the name of the print file.

spool=spool-command
(UNIX only) Spools the output according to the specified command. For example:
rwrun custhist.rpt spool="lpr -Pljet"

view
(Client only) This option invokes the viewer and directs the output to it. You can use this option only for client invocations in an interactive Panther application. In Web applications, this option is ignored.

For more information about using the viewer, refer to "Viewing Reports Onscreen."

Note: If you invoke a report for remote processing, do not use the view and async options together; otherwise, the viewer invocation might interrupt another operation that is in progress on the client. To show report output in the viewer when an asynchronous service returns, use a custom unload handler that calls sm_rw_play_metafile with the view option.

nocancel
(Client only) Specify this option with any output specifiers in order to suppress the progress dialog that otherwise appears. In a report that is processed remotely, do not use this option together with async; otherwise, the progress dialog might interrupt another operation that is in progress on the client.

This option is invalid in URL invocations and sm_rw_play_metafile.

Warnings

showwarnings | nowarnings
showwarnings specifies to display warning messages on the screen or sends them to the standard destination for error messages in your configuration. nowarnings specifies to suppress warning messages.

In Web applications, both options are ignored; in three-tier applications, they are ignored by the application server. These options are invalid for sm_rw_play_metafile.

If neither option is specified, the default depends on whether the report is invoked as a primary report or as a subreport:

Format

The following options are applied to report format; they are invalid for sm_rw_play_metafile, which outputs a report that is already formatted.

paper_size=dimensions
Generate the report using the paper size specified in the following format:
width x height [unit-spec]

Refer to "Page Size" for valid units of measurement.

Even though this option replaces the lines and columns option which specfied the length and width of the printing area in previous releases, those options can still be specified.

margin-type=margin-amt [unit-spec]
You can specify four margins for the page, where margin-type can be one of the following:
leftmargin
rightmargin
topmargin
bottommargin

For example, this string specifies a left margin of 1 inch:

leftmargin=1in

Note: There must not be any space between the margin amount and the unit of measurement.

The default value for margins is 0 for the HTML and text drivers and .25 inch for the metafile, PDF, PostScript and Windows drivers. Refer to "Page Size" for valid units of measurement.

portrait | landscape
The portrait or landscape keyword tells the output device how to orient the report to the page dimensions. portrait (the default) specifies to orient the report page to the specified paper height; landscape specifies to orient the report page according to the paper width.

When the text driver is in use, Panther seeks the capabilities landscapeon and landscapeoff in the device file in use. It outputs the control string given by landscapeon at the beginning of each page printed in landscape mode, and follows each such page with the string given by landscapeoff. Refer to information on "landscapeon/landscapeoff" for details.

lines=nlines
For text output, nlines specifies the length of the printing area on the report page.

columns=ncols
For text output, ncols specifies the width of the printing area on the report page.

Range

Range options are valid only with sm_rw_play_metafile. Because the distribution's unload handler calls this function, you can also supply these options in a report invocation that uses the remote option.

The invocation string can specify to print a range of pages in the report with one or both options:

frompage=startpage
Produces output from the specified page. If the topage= option is omitted, output includes all pages from startpage to the end.

topage=endpage
Produces output up to and including the specified page. If the frompage= option is omitted, output includes all pages from the first page through endpage.

Windows Printer Driver Options

The following options apply to the Windows printer driver only:

[simplex | duplex_horizontal | duplex_vertical]
Allows duplex printing (new in Panther 5.20). With horizontal duplex printing, the top of the page is the same on both sides of a sheet and you can read by flipping the pages horizontally. With vertical duplex printing, the top of the page is flipped on the two sides of a sheet and you can read by flipping the pages vertically. The default is to use the printer setting.

Also, each page format node has the Duplex option. Using this option, different sections of a report can be printed with different settings.

copies=ncopies
Allows printing more than one copy of a report (new in Panther 5.40).

paper_source=source
Selects the tray or other paper source (such as an envelope feed) to use for the report (new in Panther 5.40). The will vary among printer drivers. The values to use usually can be found by starting the "Printing Preferences" dialog for the printer and looking at the "Paper source" option menu drop-down. The paper source value should be copied exactly, for example,

paper_source="Tray 2"

Supplying Arguments

Reports can be invoked with arguments. This is commonly done in order to change the data that is fetched for a given report, or to set format variables. Each argument must be a valid JPL expression—either a string within quotation marks, a number, or the name of a Panther variable to evaluate when the report is run. Typically, arguments contain data that define the scope of the report. In order to process these arguments, the following conditions must be true:


Viewing Reports Onscreen

You can direct output to the viewer either from the Report menu or with the view invocation option, or you can view output that has been saved in metafile format. The report viewer displays the report one page at a time. Output is initially scaled to fit the entire page in the viewer window (ViewFull Page). To view the report scaled to 100 percent, choose ViewActual Size or the corresponding toolbar button. This option can be controlled at runtime using the application property view_full_page.

Note: The report must use scalable fonts in order for the report viewer to display it correctly in full page mode.

Figure 9-3 The report viewer lets you examine report output online.

The report viewer has its own menu and toolbar. The View menu lets you navigate through the report and determine the size of the report display. The Edit menu allows you to copy the report to the clipboard. The File menu lets you print the current output; save the output to a metafile for later viewing, save the report as a PDF file, and open an existing metafile.

How to Save Report Output to a Metafile

  1. In the viewer, choose FileSave.
  2. Enter a filename and choose OK.

The report is saved to a file with a default .rwm extension in metafile format. The output saved to this file can be displayed at any time through the report viewer or by calling sm_rw_play_metafile.

How to View Report Output Saved in a Metafile
  1. From the Report menu, choose Output Viewer.
  2. In the viewer, choose FileOpen. The file browser displays available files.
  3. Select or enter the name of the desired metafile and choose OK. The viewer displays the output saved to this file.
  4. To exit the viewer and return to the editor, choose FileExit.

Creating Dynamic Reports

You can design a report so its users have control over the content or format of its output. For example, a report can accept user input to determine report composition, such as which layout areas to use. The following example shows an application screen that asks the user to enter information that determines which data to fetch for a report. In Figure 9-4, a user enters the customer code for which they want data:

Figure 9-4 Query screen asks for the customer ID number, which the application supplies to the report as an invocation argument.

After the code is entered in the cust_num widget, the JPL Validation property for the widget is used to generate a report with the customer data. In this example, the database name and the customer code are passed as arguments—the database name as a string and the customer code as a JPL variable:

runreport custinfo.rpt \
('vbizplus', cust_num) \
remote async \
output=cust.out overwrite

The report has two parameters defined in its report node's Parameters property, db_name and cust_id, which are dynamic output widgets:

Figure 9-5 Argument values are passed to widgets that are named in the Parameters property.

The first parameter db_name receives the first invocation argument, the database name. The report uses this database name in a call node to connect to the database.

The second parameter cust_id receives the second invocation argument, cust_num. A call node executes this JPL procedure to declare the cursor:

proc make_cursor
DBMS DECLARE sel_cursor CURSOR FOR \
SELECT cust_id, first_name, last_name, \
address1, address2, city, state_prov, postal_code, \
phone, cc_code, cc_number, cc_exp_month, cc_exp_year, \
member_date, member_status, num_rentals, rent_amount \
FROM customers \
WHERE cust_id = ::cust_id

The detail node has its Data Source property set to Predefined Cursor and executes the following entry in the Cursor and Using property to fetch data for the report:

sel_cursor cust_id

Calling Report Services in JetNet/Oracle Tuxedo

In a three-tier environment with JetNet/Oracle Tuxedo, clients can request that reports be run on an application server. You can specify to run a report on the server by using the remote invocation option, or by calling a report service directly with the service_call command. If you use the remote option and omit naming a report service, Panther uses the default report service. The default service will be advertised under the name sm_run_report if that option has been chosen during the server configuration.

Report invocations that include an unqualified remote option use the distribution's unload handler for producing report output on the client. The default unload handler returns the report in metafile format to the client so that you can view, print or save it locally. You can specify your own report unload handler by directly calling a report service with service_call. The remote option is described under "Remote Processing."

In order to run reports on a server, these conditions must be true:

The JPL procedure shown in Figure 9-6 runs the report orders.rpt—which is in the server library server.lib—on the server and then returns the output to the client's screen.

Caution: When you run the utility rwrun with the remote option, Panther attempts to connect to the application middleware through a call to client_init. Because this call supplies no arguments, special provisions are required to enable client authentication. Refer to "Remote Processing and Client Authentication" for more information.

Default Report Service and Unload Handler

The default report service processes the report as follows:

  1. Receives report invocation arguments.
  2. Calls sm_rw_runreport, which outputs the report to a temporary metafile on the server.
  3. Gets the ID of the file access server that is running on the same machine. The service gets the server ID from the devserv_id property.
  4. Returns these arguments to the client:

After the report service returns to the client, a report unload handler accesses the metafile and determines how to handle it. The unload handler that is provided in the distribution performs these tasks:

  1. Unloads the reply message data that is returned by the report service.
  2. Checks the reply data to determine whether the report service succeeded and if so, the path to the metafile.
  3. Moves the metafile from the server to the client.
  4. Calls sm_rw_play_metafile, which outputs the metafile contents according to the client's original invocation.

If the service fails, the handler reports the failure to the client with a message.

Custom Report Services

The default report service saves report output to a metafile on the server and returns the metafile's name and location to the client. In order to process reports differently, you can write your own report service. As with other service routines, you must store it in a library and define it in the JIF. A standard application server must be configured to advertise this service.

Note: The JIF definition of a custom report service should not specify an unload handler; report services that are called in a report invocation string always use the distribution's unload handler. To specify a custom unload handler, call the report service directly with the service_call command. Refer to "Handling Client Output" for more information and an example.

For more information on defining services, refer to Chapter 5, "Defining Services in JetNet and Oracle Tuxedo Applications," in JetNet/Oracle Tuxedo Guide.

Report Service Tasks

At a minimum, a report service performs these tasks:

Report Service Messages

Three-tier report processing in JetNet/Oracle Tuxedo relies on service messages of datatype JAMFLEX or FML in order to pass data between client and server. The request message for all report services that are called through a report invocation string, including the default report service, contains three fields with this data:

The reply message also contains three fields with this data:

For more about service messages, refer to "Service Messages and Data Types" in JetNet/Oracle Tuxedo Guide.

Example

The following code shows a report service that spools report output to a server printer instead of saving it to a metafile:

proc sm_rw_print_report()
vars sm_rw_report_invocation,\
> sm_rw_server_options,\
> sm_rw_client_options

receive ARGUMENTS( {...} )
// run the report; spool output to printer
rval = sm_rw_runreport ( sm_rw_report_invocation\
##" "##sm_rw_server_options##" spool=lp" )
if rval == SM_RW_OK
sm_rw_message = "Report spooled to printer"
else
sm_rw_message = "Unable to print report."
// return with report output status
service_return \
({sm_rw_message, sm_rw_pathname="", sm_rw_client_options})

Handling Client Output

In order to make report output available to the invoking client, a report service must output the report to a metafile and return the file path to the client. The default report service's unload handler sm_rw_unload_hdl moves the metafile to the client and processes it with sm_rw_play_metafile. This function takes as its argument an invocation string that contains the options originally specified by the client; these direct the report output—for example, to a printer or PostScript file.

In order to specify a custom unload handler, the application must call a report service directly with service_call and supply the name of an unload handler.

For example, an application that allows report service calls to be invoked asynchronously for concurrent processing can also keep track of each service's return status. The following code obtains the call ID for each service call and stores it in a grid widget. The unload handler report_status uses this call ID to update the grid with each service call's return data:

/**********************************************
call report service
***********************************************/
proc invoke_report( cust_num )
vars sm_rw_report_invocation="custinfo.rpt("##cust_num##")"
vars new_grid_occ

// call default report service with custom unload handler
service_call "sm_run_report"( \
{ sm_rw_report_invocation, \
sm_rw_server_options="", \
sm_rw_client_options=""}, \
{ sm_rw_message, \
sm_rw_pathname, \
sm_rw_client_options}), \
ASYNC, \
UNLOAD_HANDLER "report_status", \
NOTIMEOUT
// populate new occurrence of report status grid with new ID
new_grid_occ = call_id->num_occurrences + 1
call_id[new_grid_occ] = @app()->tp_return
report_info[new_grid_occ] = \
"custinfo.rpt for customer "##cust_num
ret_status[new_grid_occ] = "Processing..."
/**********************************************
report status unload handler
***********************************************/
proc report_status( callid, msg_source, method )
vars local_file, ct, tmp_status
vars sm_rw_client_options, sm_rw_message, sm_rw_pathname

// get the service reply message data
unload_data

// report service success
if sm_rw_message == ""
{
//create local file name
local_file = sm_tmpnam()

// move report metafile to client
call sm_file_move( sm_rw_pathname, local_file )
tmp_status = "Report output complete"
}
// report service failure
else
tmp_status = "Error occurred; no report generated"

// update grid occurrence with report output status
for ct = 1 while call_id[ct] != callid
{}
ret_status[ct] = tmp_status
rpt_file[ct] = local_file

Running Reports in a Web Browser

The default driver for all reports invoked from a Web application is html. If a browser-invoked report specifies a non-HTML driver such as text and omits an output destination, Panther returns the specified output to the browser. The browser's own capabilities determine how it handles this output. If you specify an output destination along with the driver specification, Panther saves the report output on the Web application server.

The browser user can invoke a report directly through a URL. Reports that are incorporated in a Web application can be invoked in two ways:

If you invoke a report with a URL, the browser receives the HTML document with its original URL; this ensures that all internal links are interpreted correctly. If you invoke the report with runreport or sm_rw_runreport, the browser receives the HTML document without a URL. Consequently, some browsers are liable to confuse this document with the one that invoked it and thereby misinterpret internal links.

For information on including report parameters in the URL, refer to "How to Invoke a Report From a URL."

Viewing Reports

When a report is displayed in a browser, a series of navigational controls appear at the top of each page. These controls allow the user to go to the previous page, to the next page, to the top of the report, and to a page index. The up arrow goes to the screen or report that starts the application, as denoted by the URL displayed in the web browser. Like other Panther web applications, the first URL you enter remains in the URL field until the application calls sm_web_invoke_url. This prevents users from entering the application except at the start point.

Figure 9-7 This final page of the Distributors report shows the totals for the entire report.

At the end of each report is the index of page numbers. Click on the index icon of any page to reach the index. Click on a number in the index to jump to that page of the report.

Figure 9-8 The page index of the Distributors report allows you to easily go to any page in the report.

The default browser page size for reports is 25 lines. A set of navigational controls appears at the top of each Web page. To turn the navigational controls off, set the page length to 0, either in the report's Page Size property (described under "Page Format Properties") or with the report invocation's paper_size option (described under "Paper Size"). For example:

paper_size=8.5x0

If the report definition or invocation string contains page dimensions that are appropriate to printed output—for example, the report's page format node has its Paper Size property set to 8.5 x 11in—the browser approximates that page size when it calculates page breaks. If no page size is specified, Panther attempts to fill a full screen between page breaks. In both cases, Panther also uses other properties that control page breaks (refer to "Controlling Pagination").


Debugging Reports

The Panther debugger is just as useful in debugging reports as in analyzing Panther applications. The debugger's Data Watch window, for instance, can display the current value of any widget in your report layout window, as well as JPL variables and LDB entries.

When a report is running, the debugger's Source Code window lists the report structure with the current node highlighted. You can step through execution of the report, set breakpoints, and animate the display exactly as in a JPL program. JPL appears in the Source Code window if you are tracing it, whether it is called directly by your application—say, from a control string—or from within a report.

Report events are displayed in the debugger's Status window. These events include node execution, area output, subreport invocation, and page processing. Because they might cause other report events and non-report events such as execution of a JPL procedure, each report event remains displayed in the debugger's Event Stack window until it completes.

Refer to Chapter 39, "Using the Debugger," in Application Development Guide for information about Panther's debugger.