5: Creating the Demonstration System Reports

5.3.2 Entering Report Sections and Field Descriptions

Every report has divisions of some nature. These divisions make the report more readable and, therefore, more understandable. Even the simplest of reports will usually have a heading at the top of each page followed by the body of the report. Reports also frequently have footings at the bottom of each page and a summary at the end of the report. The Report Generator calls each of these divisions a Report Section.

The 10 different sections which are defined by the Report Generator are (in order of appearance):

The meaning of each section is defined as we progress through this chapter. For now, we will concern ourselves only with the order of the sections.

After the display has been switched from the Report Description to the Report Section screen, the Page Heading is the first section encountered. You should notice that the <F2> and <F3> keys, which were unused in the Report Description screen, now have functions associated with them and that the <F5> key, which was used in the former screen, now has no function associated with it. The following table reflects these changes in function key assignments:

These added functions are used to ‘step through’ the various Report Section screens while the other function keys retain the same function they held in the Report Description screen.

You may now select another section by pressing either the PREVIOUS key <F2> or the NEXT key <F3>. Pressing the PREVIOUS key <F2> moves you up through the list, whereas pressing the NEXT key <F3> moves you down through the list.

For example, to go from the Report Footing section to the Page Heading section, press the NEXT key <F3> twice. Pressing it the first time brings up a blank screen and the message No more report sections. Pressing the NEXT key <F3> a second time brings up the Page Heading section.

In the same manner, you may go from the Page Heading section to the Report Footing section by pressing the PREVIOUS key <F2> twice after the Page Heading section has been reached (i.e., displayed).

The Level n Heading and Level n Footing sections appear only when you specify sort fields on the Report Description screen. If no sort fields are specified, pressing the NEXT key <F3> at the Page Heading section moves you immediately to the Detail section (i.e., no Heading or Footing sections appear). If you specify just one sort field, only the Level 1 Heading and Footing sections appear, and so on.

The various sections that make up the report perform the same purpose as your blank piece of paper described earlier. You can switch freely between the different sections, and the cursor can be moved anywhere on the screen. Text typed in a Report Section is entered beginning at the location of the cursor. You can also add, change, delete, or move print fields quite easily. (Note: A print field may be defined as a portion of the printed report which is either the value of a specified data field or the result of a field lookup or total computation.)

When a Report Section screen is displayed, the abbreviated name of the section which is currently active is displayed in the lower left-hand corner of your screen.

It is important to place your text and/or print fields in the correct section. For example, anything entered in the Page Heading section is printed at the top of every page of the report. This means that if you enter text and/or print fields in the Page Heading section which actually belong in the Detail section they are printed only once per page at the top of the page.

The Arrow keys move the cursor one row or one column in the direction of the arrow. The Arrow keys will not, however, go beyond the margins of your screen. For instance, pushing the Up Arrow key when the cursor is already on the top line has no effect. (Note: Be sure not to confuse the Arrow keys on your keyboard with other keys which may be labeled with one or more ‘arrows’ and yet which serve a totally different purpose.)

Pressing the Tab key <Tab> moves the cursor to the next tab stop. (Note: Tab stops are set every eight characters.)

The Return key <RETURN> moves the cursor to the first character of the next line down. Like the Down Arrow key, this key has no effect if it is pressed while the cursor is in the bottom line of the Report Section screen.

If your keyboard has <Pg Up> and <Pg Dn> keys, you may use them to insert or delete lines in the current Report Section screen. (Note: These keys, like the Arrow keys, should not be confused with other keys on your keyboard which may be labeled ‘Delete’, ‘Del’, ‘Insert’, ‘Ins’, etc. and yet which serve a totally different purpose.) Pressing the <Pg Dn> key deletes the line containing the cursor. All lines below the cursor are shifted up one line. The <Pg Dn> key will not delete a line that contains any print fields. In order to delete such a line the print fields must first be deleted one at a time by a procedure described later in this chapter. Pressing the <Pg Up> key adds a blank line above the row containing the cursor, causing the last line of the screen to be deleted and the lines at and below the cursor to be shifted down one line. (Note: If there are print fields in the last line they must be deleted prior to pressing the <Pg Up> key or the line insertion will fail.)

If your keyboard has Ins and Del keys, you may use them to insert or delete characters in the current line of the Report Section. Pressing the Del key deletes the character at the current cursor position and shifts the rest of the line one position to the left (including text and print fields). The Del key cannot be used if the cursor is positioned on a print field. Pressing the Ins key inserts a blank character at the current cursor position. Text and print fields at, and to the right of, the current cursor position are all shifted one position to the right for each blank inserted. Text which is shifted completely off the end of a line is lost. Print fields may not be ‘shifted off’ the end of a line.

In addition, the Space bar and Backspace key of your keyboard may be used to move the cursor to the right and left, respectively. However, they also erase any text which they ‘space over’. (Note also that on some keyboards the Backspace key is labeled with a ‘back-arrow’ much like the Left Arrow key, which may also be used to move the cursor to the left but will not erase any of the text which it ‘spaces over’.)

As described earlier, the PREVIOUS and NEXT keys, <F2> and <F3> respectively, change the current Report Section.

Pressing the UPDATE key <F4> while the cursor in an existing print field allows you to change, by means of the Field Description screen, information relating to that print field. (Note: More information regarding the Field Description screen is provided as you progress through this chapter.)

Pressing the ADD key <F6> while the cursor is not positioned in an existing print field allows you to enter (again via the Field Description screen) information for a new print field.

Pressing the SWITCH key <F7> redisplays the Report Description screen. Pressing the SWITCH key <F7> in the Report Description screen redisplays the Page Heading section’s screen.

As stated earlier, pressing the EXIT key <F8> when you are done designing the report saves the reportfile and returns you to the Report Generator Menu.

The GOLD key <F1> serves the same purpose in all of the screens. There are, however, some differences in the second keys and the functions associated with them. The available GOLD functions in the various Report Section screens are:

Pressing the GOLD key <F1> and then the D key while the cursor is positioned on a print field deletes the field. A copy of the last deleted print field is saved by the Report Generator, enabling you to restore the deleted field to a Report Section screen. This is done with the UNDELETE function (i.e., pressing the GOLD key <F1> and then the U key). The ‘restored’ print field is then displayed on the Report Section screen beginning at the current cursor position. (Note: The saved print field is overwritten by each subsequent field deletion, and is completely destroyed when you press the EXIT <F8> key.)

By combining the DELETE function, cursor movement, and the UNDELETE function, print fields may be moved about with ease on the screen.

One of the most useful GOLD functions is the PICTURE function, which enables you to view all of the sections of the report simultaneously . Upon pressing the GOLD key <F1> and then the P key, each Report Section is displayed, separated by a row of dashes. Two adjacent rows of dashes indicates an empty section. The Report Section screens are displayed in the following order:

After ‘painting’ the picture, the message Press any key to continue is displayed at the bottom of the screen. Pressing any key in response to this message re-displays the Report Section that was displayed at the time the PICTURE function was invoked.

Before continuing on with our example, make sure that the cursor is located in the upper left-hand corner of the screen. Then enter the Page Heading text as follows:

After making the preceding entries the screen should appear with the cursor in the upper left-hand corner of the screen.

Pressing the NEXT key <F3> once switches the picture screen to the Detail section. This section is printed once for each record in the report’s RMSfile. In this initial example, all of the fields to be printed from the report’s RMSfile should be placed in this section.

Pressing the ADD key <F6> allows you to add a new print field to the current Report Section. The location of the field begins at the column which is the current cursor position when the ADD function is invoked.

With the cursor in the upper left-hand corner of the screen, press the ADD key <F6> to add a field to print the magazine code (i.e., the magazine field). After pressing the ADD key <F6>, a blank Field Description screen is displayed.

Notice that the display of the function keys and their associated functions once again includes the STORE function, but does not include the PREVIOUS, NEXT, ADD, SWITCH, or EXIT functions, as these are accessed from the various Report Section screens.

The available GOLD functions for this form are identical to those used in the Report Description screen. They are:

Notice that although the DELETE function may be used in this form to delete the contents of a Field Description, a much more convenient method is to simply delete them from within the Report Section screen itself.

Notice that the Field Length field is automatically filled in after you leave the Field Name field. This is done by looking in the dictionary for the RMSfile, mag, and finding the length of the field. (Note: If the Report Generator is unable to determine the length of the field, you must enter a non-zero integer in the Field Length field.)

After you have filled in the Field Description screen, press the STORE key <F5> store its contents and redisplay the Report Section screen with the newly added print field. Unlike the C/Base forms, the reports created using toolkit do not use ‘display attributes’, so text and print fields may be placed next one another with no ill effects.

Notice that when the cursor is positioned on a print field the name and type of the field is displayed at the bottom of the screen. However, when the cursor is moved off of the print field this display at the bottom of the screen is removed.

To continue with our example, move the cursor so that it is 3 columns past the magazine field (i.e., there should be 2 spaces between the magazine field and the next print field). Press the ADD key <F6> to enter information in a new Field Description screen for the title field. The information for this field is similar to the one just completed.

Store the contents of the Field Description field (by pressing the STORE key <F5>).

We are now ready to add a description for the annual subscription rate (i.e., the year_rate field). Move the cursor so that there are six blank columns after the title field. Press the ADD key <F6> once again to display the Field Description screen.

The Data Type of this field is money. Since most magazines cost less than $1,000.00 per year, a Field Length of 6 (999.99) should be sufficient.

After pressing the STORE key <F5>, the Report Section screen is redisplayed with the newly added print field.

The last print field to be added is the total number of subscriptions for each magazine, (i.e., the subscribers field). Move the cursor so that there are seven blank columns after the year_rate field. Pressing the ADD key <F6> once more displays the Field Description screen.

The Data Type of this field is integer and, since we know that all of the magazines in our system have less than 100,000 subscriptions, we can use the default Field Length of 5 columns (99999) for this field. After storing the contents of this Field Description (by pressing the STORE key <F5>), the Report Section screen is redisplayed.

Pressing the UPDATE key <F4> while the cursor is in an existing print field (e.g., the subscribers field) displays the Field Description screen.

In this case, however, the current values of the print field’s Field Description are displayed, and changes to this information are allowed.

Pressing the UPDATE key <F4> prior to pressing the STORE key <F5> (while in the UPDATE mode) redisplays the original contents of the Field Description screen.

Selecting the CANCEL function (by pressing the GOLD key <F1> followed by the X key) cancels an ADD or UPDATE operation and redisplays the Report Section screen exactly as it appeared prior to selecting the ADD or UPDATE function.

Selecting the CLEAR function (by pressing the GOLD key <F1> followed by the 4 key) clears all of the entry fields of the Field Description screen.

The REFRESH function (selected by pressing the GOLD key <F1> followed by the R key) simply ‘refreshes’, or ‘re-paints’, the screen by redisplaying the Field Description screen (including any entries which have already been made to any of its fields).

After any necessary changes have been made, pressing the STORE key <F5> records the changes and redisplays the Report Section screen.

When adding or updating the contents of a Field Description screen, the PREVIOUS, NEXT, ADD, SWITCH, and EXIT functions are not allowed.

Print fields may be used to print values from any one of five possible sources:

To print the value of a data field from the report’s RMSfile, you simply fill in the Field Name field on the Field Description form with the name of the data field whose value is to be printed. A default value is assigned to the Field Length field (much as it was in creating the data entry forms using toolkit) which may be overridden, and no default value is assigned to the field labeled Maximum String Length or Number of Decimal Places, as entry to this field is optional. (Note: Read on for more information regarding these two fields.) In this case the Sum of, Running Total?, Lookup Field Name, and Lookup Data File fields would be left blank.

To print the sum of a data field which is contained within the report’s RMSfile, you simply leave the Field Name field blank and enter the name of the data field you want to total into the field labeled Sum of. (Note: Information in the preceding paragraph regarding the Field Length and Maximum String Length or Number of Decimal Places fields apply here as well.) In this case, the Running Total?, Lookup Field Name, and Lookup Data File fields would also be left blank.

To print the value of either a Report Generator variable or an environment string name, you simply enter a dollar sign ($) followed by its name in the Field Name field. The following are the predefined Report Generator variables:

You can print the value of a RMSfield in a RMSfile other than the report’s RMSfile by performing a field lookup. To perform a field lookup, you must fill in the fields labeled Lookup Field Name and Lookup Data File with the name of the data field you want to print and the name of the RMSfile that contains that data field, respectively. To specify the particular record you want to ‘lookup’, you must also fill in the Field Name field with the name of a data field from in the report’s RMSfile which performs the field lookup.

A field lookup searches the Lookup Data File RMSfile for a record whose primary key ‘matches’ the lookup value. The lookup value is the value of the Field Name field in the current (active) record from the report’s RMSfile. The result of the field lookup is then printed as part of the report.

For field lookups to work within the Report Generator, the primary key of the RMSfile specified in the Lookup Data File field must be composed of a single field. The records in the file specified in the Lookup Data File field should also have unique keys. If no ‘matching’ record can be found, the value of the current record’s (i.e., the active record from the report’s RMSfile) data field (specified in the Field Name field) is printed instead.

The other fields of the Field Description screen control options for printing a field. The value assigned to the Field Length field controls the minimum number of columns to use when printing a field. If the value to be printed is longer than the length specified, the extra characters are still printed. Values that are shorter than the specified length are ‘padded’ with blanks to fill the remainder of the field. String, character, boolean, date, and time values are padded to the right. Real, money, and integer values are padded to the left.

To the right of the Field Length field is a field labeled Maximum String Length or Number of Decimal Places which is used in one of two ways. For string values, you may enter a number that specifies the maximum number of characters to be printed. If a string field is 40 characters in length, and you only want to see the first 20, you would enter 20 in this field. For money or real values, you may enter a value that determines the number of decimal places that are to be printed to the right of the decimal point. If this field is blank, the Report Generator assumes that only two decimal places are to be printed for money values and that only the significant digits of real values are to be printed (e.g., 1.01 is printed as 1.01, 1.10 as 1.1, 3.1415 as 3.1415, etc.).

The value assigned to the field labeled Running Total? controls when the sum of the field is reset to zero. A value of no in this field means that the sum of the field acts like the total key of a calculator in that the sum is reset to zero each time the field is printed. A value of yes, however, means that the sum of the field will not be reset to zero until the sum of the field is printed (much like the sub-total key of a calculator).

Many of the features which we’ve mentioned but haven’t implemented in this ‘simple’ report is used as we continue through this chapter with further examples. One thing the Report Generator will not do, however, is modify the records of any RMSfile. Therefore, you may experiment with its various features without being concerned that your experimentation will affect, or corrupt, your data.

This completes the rough draft of this report. All that remains now is to double-check that the print fields line up under their associated headings. This can be done quickly by using the PICTURE function. Simply press the GOLD key <F1> and then the P key from within any Report Section screen to display all of the sections of the report simultaneously. (Note: If you currently have the Field Description screen displayed you may return to the Report Section screen by using the CANCEL function.)

Press a key (i.e., any key) to redisplay the current Report Section. Once this has been done you may press the EXIT key <F8> to write the report program to the logical file designated when you selected choice D1 - Create Report Program from the Report Generator Menu (in this case, mymag). The Report Generator reports the progress of this as it proceeds. The output should appear as in the following display:

The first two lines tell you about the compilation of the report you created. The second two describe the addition of that report to the logical report catalog. After this point you are able to access this report by its logical name. When you press the RETURN key you will return to the Report Generator Menu.

The report can now be run (i.e., printed or displayed) by selecting choice D3 - Test Report Execution from this menu. After choosing this item the system presents you with a parameter form. The first field on the parameter form is the logical name of the report you wish to run. Enter mymag into this field. The second asks if you wish to print this report on the printer. Since you are only looking at the results of your design just leave the default value of no. If you wish to see a printed version of a report then just enter yes in this field. The third field asks for the number of copies. If nothing is entered then toolkit assumes that you only want one report. You can enter into this field any integer valid for your system and that many copies of that report are printed. If nothing is entered or the Output to Printer field is no then toolkit uses the default of one.

As the report is displayed on your screen, you can ‘page through’ it by pressing the Down Arrow key, ‘page back’ by pressing the Up Arrow key, or terminate the output by pressing the Q key. Once the display of the report has finished, or has been terminated, the Report Generator Menu is redisplayed. (Note: This selection may be used throughout the course of this chapter if you wish to view the output of any of your reports.)

You may also list the names of the reports you have created by selecting choice L1 - List Logical Reports from this menu. After choosing this item, the system displays a parameter form asking where you want to send the output of this report. If you send this report to the screen, you will see the following display:

Once the names and descriptions have been listed you may redisplay the Report Generator Menu by simply pressing <RETURN>. (Note: This selection may be used throughout the course of this chapter if you wish to view a list of the reports you have created.)