Parameters are values that are constant to a particular run of a report, but may be different between runs of a report. We have already seen one use of parameters in the $todays_date parameter. The Report Writer provides several pre-defined parameters, which are:
$todays_date - Date report was started
$todays_time - Time (24 hour clock) report was started
$page - Current page number
$line - Current line number
$col - Current column number
$TRUE - A value that is always true
$FALSE - A value that is always false
In addition, you may add other parameters to your report. For instance, if you had 3 different sized labels and wanted to use the same report to print on any of them, you could create two parameters. $LABELLENGTH and $LABELWIDTH, that the report could use to set up attributes for printing on any size label.
Parameters are created within a report program by using their name in the program. To size the label with the parameters $LABELLENGTH and $LABELWIDTH, we would need the following statement in our MAIN procedure:
SET PAGELENGTH := $LABELLENGTH,
FIRSTLINE := 1,
LASTLINE := $LABELLENGTH,
PAGEWIDTH := $LABELWIDTH;
This use of parameters tells the Report Writer that it needs to get the values of the shell variables LABELLENGTH and LABELWIDTH before execution of the report can begin. (See the section at the end of this chapter for passing shell variables to the Report Writer.) The complete program to print on different sized labels might look like:
/* print mailing labels for subscribers */
FILE labels IS "sub"
FIELD IN labels ARE
subscriber, name, address,
city, state, zip;
MAIN
BEGIN
SET PAGELENGTH := $LABELLENGTH,
PAGEWIDTH := $LABELWIDTH,
FIRSTLINE := 1,
LASTLINE := $LABELLENGTH;
SELECT FROM labels
SORTED BY zip;
FOR EACH labels
DO details;
END
PROCEDURE details /* print one label */
BEGIN
PRINT name, NL;
address [1], NL;
IF address [2] NE "" THEN
PRINT address [2], NL;
PRINT city, ", ", state, " ", zip, BP;
END
Another common use of parameters is to specify which records to select. For instance, you might want to print out all subscribers from a certain state, or all subscribers within a range of zip codes. These types of reports can be done by adding parameters to the SELECT statement that sorts the subscribers. The two examples mentioned could be handled respectively by the following statements:
/* select subscribers from particular state */
SELECT FROM labels
WHERE state EQ $SUBSTATE
SORTED BY subscriber;
/* select subscribers from range of zip codes */
SELECT FROM labels
WHERE zip GE $LOZIP AND zip LE $HIZIP
SORTED BY subscriber;
A clever enhancement of this idea is to make the parameters optional. This entails using the parameter if it has a value, or selecting everything if it does not. This could print all subscriptions or just the subscriptions for one subscriber. The following SELECT statement uses the $SUBSCRIBER parameter to do this:
/* select all subscribers or just 1 if SUBSCRIBER specified */
SELECT FROM script
WHERE $SUBSCRIBER EQ ""OR
$SUBSCRIBER EQ subscriber
SORTED BY subscriber;
Parameters may also be used as the file name given in the FILE declaration. In this case the declaration would look like:
FILE labels IS $MASTER;
While this might not have much use in our current set of examples, suppose you are working in an accounting system that has two files that have the same basic format: name, address, city, state, zip, and key (as in customer master, vendor master, employee master, etc.). By declaring the file name as $MASTER, you can print labels for either file merely by changing the value of the parameter passed in $MASTER.
PROBLEM 5:
Modify the report program from problem 4 so that it prints labels from the file $MASTER. The label sizes are also to be passed to the program as $LABELLENGTH and $LABELWIDTH. In addition, you should only print labels for the magazine $MAGAZINE.