Defining the Page Layout [ HP Business BASIC Programmer's Guide ]
HP Business BASIC Programmer's Guide
Defining the Page Layout
The BASIC Report Writer allows you to define what a report page should
look like, including the page length, margins, and output at the top and
bottom of each page. Except for the right margin, these are all defined
in the report description. By changing the page layout, you can achieve
the best looking output.
Defining the Page Length
The Report Writer expects to know how many lines are on a page of output.
This allows the Report Writer to do automatic page breaks when needed;
the program may also trigger page breaks manually if needed. The length
of the page is set with the PAGE LENGTH statement:
Syntax:
PAGE LENGTH page-len [,top-margin [,bottom-margin] ]
This statement is a Report Writer block statement and must occur within a
report definition. All three values are numeric expressions and are
evaluated by the BEGIN REPORT statement.
Page-len must evaluate to a non-negative short integer value (0-32767).
The page length defines the total number of lines that can be written on
a page. This includes the top and bottom margins, page headers and
trailers, and all other report output. An error occurs if the report
attempts to write more lines on a page than the page can contain. The
default page length, in case no PAGE LENGTH statement is given, is sixty
lines.
To help make a report look better, you may wish to have some blank space
at the top and bottom of each page. These margins are specified in the
PAGE LENGTH statement (see syntax, above). The top and bottom margins
are specified separately and need not be the same size. By default, the
top and bottom margins have no lines in them.
The margin expressions must be non-negative short integer values. In
addition, the two margins added together must be shorter than the given
page length. If not, BEGIN REPORT fails and the report is not activated.
The top and bottom margins are always printed as blank lines on each page
of the report. This reduces the number of lines available for actual
report output. For instance, if the following occurs in a report:
300 PAGE LENGTH 66,2,4
the page can contain 66 lines; however, two blank lines are printed at
the top of each page, and four blank lines are left at the bottom. This
leaves only 60 lines for the actual report output.
Setting the Left Margin
A report normally prints starting in the first column of the output
device. In order to center a report on some paper, however, output needs
to start further out on the page. The Report Writer accommodates this
situation by letting you define the first column on which output will
appear. This is done with the LEFT MARGIN statement:
Syntax:
LEFT MARGIN first-output-column
This statement is a Report Writer block statement and must occur in the
report description. The column is a numeric expression evaluated by
BEGIN REPORT.
The LEFT MARGIN statement defines the first column where report output
will occur. The first column must be between 1 and 132; however, there
must be at least 20 characters between the left and right margins.
Blanks are added to each line before output. Thus, the print functions
such as TAB and SPA do not count the left margin as part of the line.
NOTE A word of caution is necessary for the LEFT MARGIN statement. The
left margin is used only for non-terminal devices. On a terminal,
the left margin is always one, even if it is otherwise specified in
the report. Thus, report output on a terminal will be different
from output on a printer or in a file. This can lead to a very
subtle problem.
If a report prints very long lines (close to the right margin), it
may work fine on the terminal. When redirected to a file or
printer, however, the left margin can cause the output to go past
the right margin, causing an extra line of output. Now the Report
Writer may suddenly report that too many lines have been printed on
the page.
To illustrate the situation described above, the PAGE LENGTH and LEFT
MARGIN statements have been added to the example below. PAGE LENGTH has
been set to 10 with a top and bottom margin of 3 lines each. Thus, only
4 lines are available per page for the report.
100 File_list_report:
110 REPORT HEADER
112 PAGE LENGTH 10,3,3
114 LEFT MARGIN 50
120 PRINT "Listing of files ";Fileset$;Group_acct$
130 PRINT
140 REPORT TRAILER
150 PRINT
160 PRINT "Number of files printed:";File_count
170 REPORT EXIT Status <> 0
180 PRINT
190 PRINT "File error occurred, status=";Status
200 PRINT "File listing stopped."
210 END REPORT DESCRIPTION
220 BEGIN REPORT File_list_report
230 END REPORT
240 END
If the above example is run on a terminal, the page of output looks like
this:
/////////////////////////////////////////////////////////////////////
[This is the end of the top margin]
Listing of files @.my.files
Number of files printed: 0
[This is the start of the bottom margin]
/////////////////////////////////////////////////////////////////////
If output is sent to a file of 70 characters, the following occurs:
/////////////////////////////////////////////////////////////////////
[This is the end of the top margin]
Listing of files @.my
.files
Error 260 in line 160
Insufficient space for printed output within the current page.
/////////////////////////////////////////////////////////////////////
Notice how the output of the REPORT HEADER is split when sent to the
file. This is because the output does not fit on one line. Then, during
the REPORT TRAILER, we attempted to print a fifth line on the page, but
only four lines are available, as defined by the PAGE LENGTH statement.
In order to remedy the situation, the PAGE LENGTH must be increased or
the LEFT MARGIN should be less than 43.
Setting the Right Margin
The right margin of a report can be set using the MARGIN statement. This
statement is not a Report Writer statement, and may be executed at any
time. The right margin must be at least 20 columns larger than the left
margin, and it must be less than or equal to the maximum right margin of
the output device. Refer to the MARGIN statement description for more
information.
The Infinite Page
The majority of reports define a page of a specific length, often related
to the final output device. This allows the Report Writer to control the
paging and the amount of information appearing on the page, giving the
output a uniform look.
On occasion, the report output is unpredictable, making a page definition
difficult or even clumsy. This is especially true when the output varies
in length such that a single page length is inappropriate. For these
cases, the Report Writer allows you to specify an infinite page length.
This is done by setting the page length to zero lines. For example,
PAGE LENGTH 0,3,4
defines an infinite page. Top and bottom margins may still be defined.
Triggering Page Breaks. All page breaks must be triggered manually for
the infinite page report. That is, the TRIGGER PAGE BREAK statement must
be used to start a new page. No WITH clause can start a page, as there
is always room for the output.
As with a finite page, the REPORT HEADER prints on the first page of the
report, followed by the page header. The last page of the report still
has a PAGE TRAILER after the REPORT TRAILER.
Effects on Output. An important effect of the infinite page is that
error 260, indicating a full page, never occurs. Any number of lines may
be written on the page.
The top margin prints on every page if any lines are requested. This is
followed by the page header and then the report output.
When a page break is triggered, the page trailer is printed immediately.
As there is no page length, no blank lines can be printed to position the
page trailer. The bottom margin is printed after the page trailer.
A page break in the Report Writer does not necessarily correspond to a
physical page eject on the output device. This is particularly
noticeable with the infinite page. In order to accomplish a physical
page eject, the user must print a string or use the PAGE or CTL function
of the PRINT statement.
Infinite Page Example. In order to illustrate the effects of the
infinite page, the example below has been enhanced. The program GETs a
filename (code not shown) and then display the file on the standard
output device. As each file is a different length, no PAGE LENGTH
command would be sufficient for this program. Thus a page break is
triggered between each file.
...
100 File_list_report: !
110 REPORT HEADER
120 PAGE LENGTH 0,0,0
130 LEFT MARGIN 10
140 PRINT "Listing of files ";Fileset$;Group_acct$
150 PRINT PAGE;
160 SET PAGENUM TO 0
170 PAGE HEADER WITH 3 LINES
180 PRINT
190 IF PAGENUM > 0 THEN PRINT USING Ph_image;Filename$,Group_acct$
200 Ph_image: IMAGE 30XK,K,2/
210 PAGE TRAILER WITH 3 LINES
220 IF PAGENUM > 0 THEN
230 PRINT
240 IF PAGENUM MOD 2 THEN PRINT TAB(10); PAGENUM ELSE PRINT TAB(60);PAGE&
NUM
250 PRINT PAGE;
260 ENDIF
270 REPORT TRAILER WITH 5 LINES
280 PRINT
290 PRINT "Number of files printed:";File_count
300 REPORT EXIT Status<>0
310 PRINT
320 PRINT "File error occurred, status=";Status
330 PRINT "File listing stopped."
340 END REPORT DESCRIPTION
350 Fileset$="SLCB@";Group_acct$=".DSOURCE.TEST2"
360 File_count=0
370 SEND OUTPUT TO PRINTER
380 BEGIN REPORT File_list_report
390 LOOP
400 CALL Get_file_name(Filename$)
410 EXIT IF Filename$=""
420 IF File_count=0 THEN TRIGGER PAGE BREAK ! start report output
430 File_count=File_count+1
440 COPYFILE Filename$+Group_acct$
450 TRIGGER PAGE BREAK
460 ENDLOOP
470 END REPORT
480 SEND OUTPUT TO DISPLAY
490 END
...
The output from the above program run is on the next page.
Listing of files SLCB@.MY.FILES
[Blank lines on rest of page]
//////////////////////////////////////////////////////////////////////
SLCB001E.MY.FILES
10 ! This is test program number 1.
...
1000 LOOP
//////////////////////////////////////////////////////////////////////
...
9990 PRINT "End of test."
1
//////////////////////////////////////////////////////////////////////
SLCB001E.MY.FILES
10 ! This is test program number 2.
...
490 PRINT "Start of test: SLCB002B"
//////////////////////////////////////////////////////////////////////
...
9990 PRINT "End of test."
2
//////////////////////////////////////////////////////////////////////
SLCB002B.MY.FILES
10 ! This is test program number 3.
...
600 FOR J=1 TO 3 ! for length, top, bottom
//////////////////////////////////////////////////////////////////////
...
9990 PRINT "End of test."
3
//////////////////////////////////////////////////////////////////////
SLCB003D.MY.FILES
Number of files printed: 3
4
//////////////////////////////////////////////////////////////////////
In the above example, the PAGE function is used to produce physical page
ejects for the printer. The REPORT sections all use the PAGE function to
make sure they occur on different pages from the file listings. The page
eject could also have been done by an IMAGE statement using the "@"
specifier.
The PAGE HEADER and PAGE TRAILER sections do not produce any output for
page number zero, which is set up by the REPORT HEADER section. This is
so that the initial TRIGGER PAGE BREAK used to start the report does not
print any output for the PAGE HEADER and PAGE TRAILER sections.
The COPYFILE statement writes the file onto the standard output, that is,
in the report. Several physical pages may be printed by each file. The
report page, however, changes only between files. This avoids error 260
and prints the file as quickly as possible.
The new report page is started with a TRIGGER PAGE BREAK after the file
is copied. The PAGE TRAILER performs the physical page eject to ensure
that each file starts on a new page.