9.17 The Final Frontier

We have just about covered all of the features of the Report Writer. There are many condition and expression operators that we have not covered. You will just have to try a little experimenting to see how they work. They are described in Chapter 10, Report Writer Programming Reference along with a sample of how they work. All of the statements have been covered; however, there are some statements that have some unusual features which we have not needed yet.

The first of these is the break statement. When checking an input file, it is possible to watch two or more fields simultaneously and perform the break action if any of the fields change. The need for this feature usually arises when the key of a file is composed of multiple fields, or when a file has been sorted by more than one field. To specify more than one field in a break statement, you separate the fields by the OR keyword as in:

CHECK subscriptions, AT END OF started OR magazine

After this statement has executed, each time started or magazine (or both) change, the procedure new_cycle is called. Of course, this could be extended to more than two fields, but the demo system is not that complex.

Another point to be made about the break statement is that there are synonyms for some of the key words. These are listed in the table below:

Key Word Synonym

START TOP

END BOTTOM

CHECK WATCH

The example described above could also be written:

WATCH subscriptions, AT THE BOTTOM OF started OR magazine

The break statement can also be used with a REPORT event. The TOP (or START) of a report event occurs just before the first character is about to be printed. At the time of the break, all initializations have been done. The END (or BOTTOM) of a report event occurs after the end of the special MAIN procedure is reached. At the time of the break, all totals have been accumulated, all end of field events have been processed, but the last end of page event has not been processed yet and is done after the end of report event. The report event can be used to print summary information as follows:

AT END OF REPORT

The other statement that needs more discussion is PRINT. This statement is the real work horse of the Report Writer. It probably has more built-in options than any other statement. First, there are the different types of print items. So far, we have seen BP, NL, expression, and expression : expression. There are two more print items that we have not looked at yet. These are

expression : expression : expression

and

expression: :expression.

The first of these is used to print out real numbers (those that have decimal places). It can also be used to restrict the length of printed strings. The last argument (called precision by the Report Writer) controls how many digits following the decimal point are printed. It also controls the maximum number of string characters printed if the first expression is a string. The example below helps to clarify things. The following statements:

message := "hello, world" /* 12 characters */

produce the following output:

3.14116

As you can see, even though the length is specified, if the actual data is larger than the length more characters are printed unless the precision is specified. This is probably another area you need to do some experimenting, but the rules are as follows:

If the length is specified, print at least that many characters (blank fill).

If the precision is specified, print at most that many characters (truncate).

If the value being printed is a real number, then the precision starts counting after the decimal point.

There are a few additional attributes to be discussed that have not been used in the examples: SKIPPAGES, MAXPAGES, and NOOUTPUT. These attributes are used to suppress the printing of report output.

The SKIPPAGES attribute controls the number of pages of output that must be generated before Report Writer starts printing output. Until this page number is reached, the Report Writer suppresses the output of the report program. For example, if you wanted to start printing a report on page 11 you would use the following statement:

SET SKIPPAGES := 10;

The default value for SKIPPAGES is zero so that if SKIPPAGES is not set the report prints output starting with page 1.

The next attribute, MAXPAGES, controls the maximum page number that is output. If it is greater than zero, after this page number is reached, all output is suppressed. The Report Writer does not stop execution when this limit is reached, it merely stops printing anything. To print just the first 10 pages of a report Set MAXPAGES as shown below:

SET MAXPAGES := 10;

The last attribute, NOOUTPUT, suppresses output when it is set to 1 or $TRUE. The default for NOOUTPUT is 0 or $FALSE. If the NOOUTPUT attribute is not set (or is set to 0 or $FALSE) and no output is generated by a report, the message:

No data printed for this report

is printed on the printer or displayed on the screen. If NOOUTPUT is set to $TRUE or 1, this message is suppressed. A case where you would have a report that did not generate output would be a report to update records as was described in section 9.12. To suppress the message telling you no data was printed, set NOOUTPUT as follows:

SET NOOUTPUT := $TRUE;

You can set this attribute to $TRUE and $FALSE as many times as you wish throughout your report.

As you can see, the Report Writer has a lot of complex features built into it. The only reliable way to completely discover how these work is to do some experimenting. We have presented most of the obvious ways of using the Report Writer. There will be times you will be confronted with a problem not covered in this chapter. Don't give up hope. We tried very hard not to put limitations into the Report Writer. If you think something might work, try it! The worst that could happen is the computer won't do what you wanted.