Note that this prototype member contains constant definitions for colors to be used to define the color of the progress bar itself. This source also defines the procedure prototype for the following three subprocedures:

• createProgressBar--This routine simply creates a pointer for a new progress bar object.
• displayProgressBar--This procedure is used to display or update the display of our progress bar object.
• destroyProgressBar--This procedure removes the progress bar from memory. If no active progress bars remain, this procedure also closes the screen containing the progress bar window.

Because of the way that the progress bar objects are defined, it's actually possible to have multiple progress bars active within the same program; for example, you may want to have one bar that indicates progress for subtasks within a larger process and another that indicates progress for the entire process. The prgBars data structure is used to define the attributes of our progress bar. These attributes are listed in the table below.

The data structure containing these values can be associated with multiple program variables, effectively giving you the ability to display multiple progress bars from within a single program. Some of these values, like the Color and ShowPercent values, will be set when the bar is initially created. Others, such as the Percent and StatusMessage values, can be changed each time the status bar is displayed. Note that the Color attribute is defined using one of the five color constant values shown in the table below:

The source for the PROGBAR service program is shown below:

     P                 e

The functionality performed by this service program is fairly straightforward. We use a 75-byte field as the progress display. That field is manipulated using the hex codes for specific reverse-image color attributes. The hex display attribute value used to turn off reverse-image is then used to end the progress bar. The result is that we end up with a portion of the 75-byte field displayed in reverse-image to indicate percent of completeness.

To utilize this functionality, we must first initialize our new progress bar using the createProgressBar subprocedure. The subprocedure accepts no parameters, but returns a pointer to the newly created progress bar object. Next, we define the values for our progress bar using a data structure defined like the prgBars data structure. Note that this data structure is what the pointer created by the createProgressBar subprocedure points to. Each time we want to display (or update) our progress bar, we use the displayProgressBar subprocedure. This subprocedure accepts a single parameter, which is the resulting pointer returned by the createProgressBar subprocedure. Once a given progress bar is no longer needed, use the destroyProgressBar subprocedure to deactivate the progress bar itself and perform any additional cleanup task, including closing the display file and setting on LR when all progress bars have been destroyed.

Putting It to Use

To better illustrate how to utilize the PROGBAR service program, I've included the sample program shown below:

        Return;

Note that this example actually creates multiple progress bars concurrently. We define both a pointer and a data structure associated with that pointer for each progress bar created.

As described earlier, we first create the bar using createProgressBar and then identify the associated attributes for that bar, including the color, title, and top position along with the indicator identifying whether or not to show the percentage. Next, we simulate the data processing using a for/endfor loop and incrementing the percent value for each bar along with the status message for each prior to executing the displayProgressBar subprocedure to display each progress bar window. Once all processing is complete, destroy each bar using destroyProgressBar. Upon execution of the final destroyProgressBar, the application will automatically close the display file and set on *INLR. Our sample application then does an exfmt to output its own display file simply to wait for the user to press Enter before exiting. Figure 1 below illustrates what the final screen looks like prior to pressing the Enter key.

Note that each bar is updated independent of the other two. The application can support a maximum of 10 active progress bars at any given time. Also note that in this example I've associated the PROGBAR service program with a binding directory by the same name to simplify compiles of any programs utilizing this functionality. To compile the service program, use the following two commands:

Once you've added this service program to the PROGBAR binding directory (or the appropriate binding directory of your choice), the sample program (TESTPRGBAR) can be compiled using the standard CRTBNDRPG command shown below:

Note that the binding directory containing the PROGBAR service program should be in your library list at compile time.

Are We There Yet?

Using a routine like this can help to curb user frustration during long-running interactive jobs by giving them feedback that indicates how much longer it should take. So maybe you won't have to feel like the tortured parent with the kids in the back seat repeatedly asking, "Are we there yet? Are we there yet?"