Progress Reporting

Programs that use bulk addition are frequently the types of programs where it is desirable to report the program's progress to the user. For example, a program that reformats a file would typically display its percentage complete while running. However, a single COBOL statement may represent the majority of the running time, so progress reporting is difficult to do. The file reformatting program, for example, could spend 20% of its time writing out the reformatted records and 80% of its time in the CLOSE statement while the records are having their keys written.

You can use a special declarative section to do progress reporting. This section is called directly by Vision in a periodic fashion while the keys are being added to the file. To create the declarative, use the following form of the USE statement:

USE FOR REPORTING ON file-name.

Vision executes this section at regular intervals. This reporting period is approximately once for each percentage point completed per key.

Because the declarative is called from within a file operation, the declarative section's code may not execute any file operations. In addition, the declarative may not start or stop any run units (including chaining), nor may it do an EXIT PROGRAM from the program that contains the declarative. Finally, note that the declarative runs as a locked thread - no other threads execute while the declarative runs.

To determine how far along Vision is in adding the keys, you can call the library routine C$KEYPROGRESS. You pass this routine a single parameter which has the following layout:

01  KEYPROGRESS-DATA, SYNC.
    03  KEYPROG-CUR-KEY   PIC XX COMP-N.
    03  KEYPROG-NUM-KEYS  PIC XX COMP-N.
    03  KEYPROG-CUR-REC   PIC X(4) COMP-N.
    03  KEYPROG-NUM-RECS  PIC X(4) COMP-N.

A copy of this group item can be found in the COPY library keyprog.def.

When C$KEYPROGRESS returns, the group item is filled with current data. The individual items contain the following:

KEYPROG-CUR-KEY - this is the current key being worked on by Vision. The primary key is key 1, the first alternate is key 2, and so on.
KEYPROG-NUM-KEYS - this is the total number of keys in the file.
KEYPROG-CUR-REC - this is the number of the last record written for the current key, ranging from 1 to the total number of records to write.
KEYPROG-NUM-RECS - this is the total number of records to be keyed.

You may report this information in any fashion. If you want to report the actual percentage complete, the formula is the following:

total-operations = keyprog-num-recs * keyprog-num-keys

operations-complete = 
  (keyprog-cur-key - 1) * keyprog-num-recs + keyprog-cur-rec

pct-complete = 
  (operations-complete / total-operations) * 100

That formula computes the percentage complete for just adding the keys. If you want to treat the original record writes and the adding of the keys in a single percentage scale, the formula is slightly different:

total-operations = keyprog-num-recs * (keyprog-num-keys + 1)

operations-complete = 
  keyprog-cur-key * keyprog-num-recs + keyprog-cur-rec

pct-complete = 
  (operations-complete / total-operations) * 100

Here is an example of a typical reporting declarative:

77  PROGRESS-BAR-1      HANDLE OF FRAME.

DECLARATIVES.
MYFILE-REPORTING SECTION.
   USE FOR REPORTING ON MYFILE.
MYFILE-REPORT.
   CALL "C$KEYPROGRESS" USING KEYPROGRESS-DATA
   MODIFY PROGRESS-BAR-1, FILL-PERCENT = 
          ((((KEYPROG-CUR-KEY - 1) * KEYPROG-NUM-RECS
          + KEYPROG-CUR-REC) / (KEYPROG-NUM-RECS
          * KEYPROG-NUM-KEYS)) * 100).
END DECLARATIVES.

Note: As mentioned above, the progress reporting code in the Declaratives Section tracks only the bulk addition of keys to the file. To also indicate the time spent writing records, similar code should be added to the corresponding WRITE statements in the Procedure Division.