Creating Paginated Reports

Introducing the paging options

You can use a number of options to produce report output in separate pages and control the format of the pages.

The paging facility is controlled by the PAGING option. When you want to produce your report in separate pages, set the PAGING option to YES in the initialization section of your report program. When PAGING is set to YES:

• Output from commands such as ROW, HEADING, and REPORT is produced in separate pages.

• You can use other OLAP DML paging options to change page features such as the size of the page, the size of the margins, and the headings that are used on each page.

Summary of the paging options

The paging options are summarized in the following table.

Option	Description
BMARGIN	Specifies the number of blank lines for the bottom margin of output pages. Default: 1.
LINENUM	Holds the current line number for the current page of output. It is adjusted automatically as output lines are produced. You should generally set LINENUM to 1 when you want to produce a report starting on page 1.
LINESLEFT	Holds the number of lines left on the current page. It is adjusted automatically as output lines are produced.
LSIZE	Specifies the width of the line within which the STDHDR program centers the standard header. Default: 80.
PAGENUM	Holds the current page number of the output. It is adjusted automatically as lines of output are produced. You should generally set PAGENUM to 1 when you want to produce a report starting on page 1.
PAGEPRG	Holds the text of a command or the name of a program to be executed at the beginning of each page of output. The default, 'STDHDR', specifies the standard header program. For no headings, specify 'NONE'.
PAGESIZE	Specifies the number of lines in a page of output, including the top margin and bottom margin. Default: 66.
PAGING	Controls the paging facility. Default: NO.
TMARGIN	Specifies the number of blank lines for the top margin of output pages. Default: 2.

How the line number is calculated

When a new page is used to store data, LINENUM is set to 1 and PAGENUM is incremented. However, the first line of output is produced after the number of lines used by TMARGIN and the lines produced by the PAGEPRG program. By the second line of actual output, LINENUM is set to the actual line number on the page.

For example, if you are using the default page layout, and you show the value of LINENUM on the first line of the body of the page, then its value is 1. However, if you show LINENUM on the second line, then its value is 6 because the 2 lines for TMARGIN and the 2 lines produced by STDHDR have been added to the line count.

Using the PAGE command to start a new page

If the PAGING option is set to YES, then you can use the PAGE command to force a page break in a report. For example, you might want to start each section of data on a new page of the report.

Example: Showing data for each product on a separate page

For example, if your report shows regional sales data for each product, then you can start the data for each product on a separate page. Your report program might include the following lines.

for product
   do
   page
   row under '-' valonly product
   for region                                   
      row indent 3 region, across month: units 
   doend

The PAGE command forces a new page at the beginning of the FOR loop for each value of the PRODUCT dimension.

Example: Resetting the page number for each product

Suppose you want to restart the page numbering of your report at 1 for each new product. You can use the following code to reset the PAGENUM option to 0 before executing a PAGE command.

for product
   do
   pagenum = 0
   page
   row under '-' valonly product
   for region                                   
      row indent 3 region, across month: units 
   doend

Starting a new page based on the lines left

Your decision to start a new page might depend on the space available on the current page. For example, you might want to start a block of data on a new page when there is not enough room on the current page for the entire block.

To start a new page when fewer than a specific number of lines remain on the current page, test the value in the LINESLEFT option.

For example, to start a new page when fewer than 12 lines are left on the current page, use these commands in your program.

if linesleft lt 12
   then page

Sending output to different outfiles

You can use the OUTFILE command to specify a file as the target outfile or to direct output to the default outfile.

The following command sends output to a file named repfile.txt.

outfile 'repfile.txt'

The following command redirects output to the default outfile.

outfile eof

Unless you use the OUTFILE command to send output to a file, your default outfile is used.

Using paging options with different outfiles

The paging options can have different values for the default outfile and for a different file. When you use the OUTFILE command to direct output to a file, the values of the paging options that are currently in use for the default outfile are saved automatically, and reinstates them when you redirect output back to the default outfile.

When you direct output to a file, the paging options are reset automatically to their default values for output to the file. After executing the OUTFILE command, you can set the paging options as desired for the file. However, the values of the paging options for the file remain in effect only as long as you continue sending output to the same file. If you use another OUTFILE command to direct output to a different outfile, then the current values for the file are not saved.

Therefore, if you want the paging options to have a particular value for a particular file, then you must set the options each time you use the OUTFILE command for that file. This is true even when you are appending output to an existing file.

Initializing the page number

The value of the PAGENUM option is reset to 1 when you execute an OUTFILE command to send output to a file. However, if you redirect output to the default outfile, then PAGENUM will contain the value it last held for the default outfile. To be sure your report starts with Page 1, you should set PAGENUM to 1 in the initialization section of your report program.

Pausing during report output

You can make your program pause while producing report output when the PAGING option is set to YES in your Express session.

Using the PAGEPAUSE option and the PAUSE command

The following table shows how to pause during the execution of a report program.

IF you want your program to pause . . .	THEN . . .
after producing each page of output,	set the PAGEPAUSE option to YES.
at other times during the execution of the program,	use the PAUSE command.

When a pause occurs as a result of the PAGEPAUSE option or the PAUSE command, program execution is suspended, and a message is displayed in the prompt area at the bottom of the screen. The default message is as follows.

Press <Enter> to continue.

Execution of commands continues when the user presses a key.

Customizing the message for a pause

You can replace the default pause message with a message of your own, as shown in the following table.

IF you want to customize the message . . .	THEN . . .
for the PAGEPAUSE option,	set the PAGEPROMPT option to the desired text.
for the PAUSE command,	supply the message as an argument to the PAUSE command.