7.5.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. With a visual report, each of these divisions are referred as a Report Section. The Report Section screen is shown in the following screen:

The 10 different sections which are defined for visual reportfiles are (in order of appearance):

Page Heading

The meaning of each section will be 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 form to the Report Section screen, the Page Heading will be the first of the sections encountered. At this point you should notice that the <F2> and <F3> keys, which were unused in the Report Description form, now have functions associated with them and that the <F5> key, which was used in the former form, now has no function associated with it. The following table reflects these changes in function key assignments:

Key Function

<F2> PREVIOUS

<F3> NEXT

<F5> Unused

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 form.

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 report section list shown above, whereas pressing the NEXT key <F3> moves you down through the list.

In order to go from the Report Footing section to the Page Heading section you must 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 displays 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 form. 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 will appear, and so on.

You can switch freely between the different sections, and the cursor can be moved anywhere on the screen. Text typed in a Report Section, called background text, 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 the 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 background 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 if you enter background text and/or print fields in the Page Heading section which actually belong in the Detail section they are printed at the top of each page (they are printed once per page).

The Arrow keys move the cursor one row or one column in the direction of the arrow. The Arrow keys do not go beyond the margins of your terminal. For instance, pushing the Up Arrow key when the cursor is already on the top line has no effect.

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. If the RETURN key is pressed while the cursor is positioned on the bottom line of the Report Section screen the cursor moves to the beginning of the bottom line.

If your keyboard has Insert Line and Delete Line keys, you may use them to insert or delete lines in the current Report Section screen. Pressing the Delete Line key deletes the line containing the cursor. All lines below the cursor are shifted up one line. The Delete Line 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 outlined later in this chapter. Pressing the Insert Line 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 all be shifted down one line. (Note: If there are currently fields to be printed in the last line they must be deleted before the Insert Line key is allowed.)

If your keyboard has Insert Character and Delete Character keys, you may use them to insert or delete characters in the current line of the Report Section. Pressing the Delete Character key deletes the character at the current cursor position and shifts the rest of the line one position to the left (including background text and print fields). The Delete Character key cannot be used if the cursor is positioned on a print field. Pressing the Insert Character key inserts a blank character at the current cursor position. Background text and print fields at, and to the right of the current cursor position are all shifted one position to the right. Background text which is shifted completely off the end of a line is lost. Print fields can 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 will also erase any background text which they 'space 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 is positioned on an existing print field within the current Report Section screen allows you to change, by means of the Field Description form, information relating to that print field. (Note: More information regarding the Field Description form is provided as you progress through this chapter.)

Pressing the ADD key <F6> while the cursor is not positioned on an existing print field within the current Report Section screen allows you to enter (again via the Field Description form) information regarding a new print field.

Pressing the SWITCH key <F7> causes the Report Description form to be re-displayed. Pressing the SWITCH key <F7> while in the Report Description form re-displays the Page Heading section's screen.

As stated earlier, selecting the EXIT function (by pressing the EXIT key <F8>) when you are done designing the report writes the current visual report to the appropriate file and exits.

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:

Key Sequence Function

<F1> H access the on-line HELP facility

<F1> D DELETE the current print field

<F1> U UNDELETE the last deleted field

<F1> P display PICTURE

(i.e., all the Report Sections at once)

<F1> R REFRESH the screen

Pressing the GOLD key <F1> and then the D key while the cursor is positioned on a print field causes the field to be deleted. A copy of the last deleted print field is saved in a 'buffer' enabling you to restore the deleted field to a Report Section screen. This is done by using the UNDELETE function (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 contents of the 'buffer' are overwritten by each subsequent field deletion and are completely destroyed upon selection of the EXIT function.)

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

One of the most useful GOLD functions is the PICTURE function, which enables you to view all of the section 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. A single row of dashes immediately followed by another indicates an empty section. The various Report Section screens are displayed in the following order:

Page Heading

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 with our example, make sure that the cursor is located in the upper left-hand corner of the screen. Then enter the Page Heading background text as follows:

Press the Space Bar 16 times

Type M a g a z i n e (with a space between each letter)

Press the Space Bar 3 times

Type L i s t (with a space between each letter)

Press RETURN twice

Type Magazine

Press the Space Bar 9 times

Type Magazine Title

Press the Space Bar 23 times

Type Yearly Rate

Press the Space Bar 4 times

Type Subscribers

Press RETURN once

Press the Up Arrow key 3 times

After making the preceding entries the screen should appear as shown in the screen below, 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 new field begins at the current cursor position when the ADD key is pressed.

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 form is displayed as shown below.

Notice that the display of the function keys and their associated functions once again includes the STORE function, but does not include the PREVIOUS or NEXT (as well as the ADD, SWITCH, and EXIT) functions.

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

Key Sequence Function

<F1> H HELP

<F1> X CANCEL

<F1> D DELETE

<F1> R REFRESH Screen

<F1> 4 CLEAR Screen

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. To proceed, fill in the form as shown below.

Notice how 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 length of the field cannot be determined, you must enter a non-zero integer in the Field Length field.)

After the Field Description form has been filled in, pressing the STORE key <F5> stores its contents and redisplays the Report Section screen with the newly added print field. Unlike the C/Base data entry forms, visual reports do not use 'display attributes', so background text and print fields may be 'laid-out' contiguously (immediately adjacent to one another) with no ill effects. The screen should appear as follows:

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 is removed.

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

After storing the contents of this Field Description (by pressing the STORE key <F5>), the screen should look like the following:

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 form, which should be filled in as shown below.

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, as shown below, 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 form which should be filled as shown:

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 as shown below.

Pressing the UPDATE key <F4> while the cursor is positioned on an existing print field (e.g., the subscribers field) also causes the Field Description form to be displayed, as shown in the following 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 of this form) redisplays the original contents of the Field Description form.

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 form.

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 form (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 form, the PREVIOUS, NEXT, ADD, SWITCH, and EXIT functions are not allowed.

Print fields may be used to print any one of five possible values: a data field in the report's RMSfile, a data field in an RMSfile other than the report's RMSfile (i.e., a lookup field), the sum of a data field in the report's RMSfile (i.e., the total of all the values of a particular data field from all of the records which were selected for printing), a wtr parameter, or a shell variable.

To print the value of a data field within the report's RMSfile, you enter the data field name into the Field Name field. A default value is assigned to the Field Length field (much as it was in creating the formfiles using formdef) which may be overridden, and no value is entered in the field labeled Maximum String Length or Number of Decimal Places, as entry to this field is optional. 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 contained within the report's RMSfile, 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 wtr parameter or a shell variable, enter its name in the Field Name field. These variable names must be preceded by a dollar sign ( $ ). The predefined wtr parameters are shown in the following table:

Name Value

$TRUE Always "yes"

$FALSE Always "no"

$page The current page number

$line The current line number

$column The current column number

$todays_date The system date when a report is started

$todays_time The system time when a report is started

You can print the value of a data field in an 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 C/Base RMSfile that contains that data field, respectively. To specify the particular record you want to 'lookup', enter the name of a field in the report's RMSfile into the Field Name field. The value of this field is used to perform the field lookup.

A field lookup searches the RMSfile specified in the Lookup Data File field for a record whose primary key 'matches' the current value of the Field Name field. The result of the field lookup is printed as part of the report. The following illustration shows how field lookups are done:

In order for field lookups to work, the primary key of the file 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 data field (specified in the Field Name field) is printed instead.

The other fields of the Field Description form 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.

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, it is assumed 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 sum is printed. A value of yes means that the sum of the field is not reset to zero when the sum 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 will be used as we continue through this chapter with further examples. One thing a visual reportfile will not allow you to do 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. 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 form displayed you may return to the Report Section screen by using the CANCEL function.) The screen should appear as follows:

At this point you must 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 reportfile to the file designated when you invoked the visual report (in this case, demo~mymag) and return to the system prompt. (Note: Information and instructions regarding running reports is contained in subsequent sections of this chapter.)