The Send Status Count command provides a simple interface for sending
a status message describing progress after the processing of n items.
This allows the user to be informed of progress by a long running
user written function that is processing items such as members or
objects. Either a count, a percentage, or a 'progress bar' of the
completed items may be sent.
The command may only be used in a CL program, but the CPP may be call
directly (see section on 'Calling the CPP')
If the function is entered in batch, no status messages are sent.
A typical series of commands to produce a 'count message' would be:
DCL &STSCNT *DEC LEN(10 0)
DCL &RUNCNT *DEC LEN(10 0)
.
LOOP: SNDSTSCNT STRMSG('Processing objects.') OPTION(*CNT) +
STSFRQ(25) STSCNT(&STSCNT) RUNCNT(&RUNCNT)
/* */
/* Your processing */
/* */
GOTO LOOP
Note that the STSCNT and RUNCNT variables must be declared as *DEC
LEN(10 0). These variables are passed to the SNDSTSCNT command and
are updated in the SNDSTSCNT command processing program. You should
not change the values of these variables for normal use.
The STSFRQ field determines how frequently a status message would be
sent (default is 25).
On the first use of SNDSTSCNT, a status message would be sent saying:
Processing objects.
The second and third messages would appear as:
Processing objects. 25 processed.
Processing objects. 50 processed.
Enhancing the status message
----------------------------
A better status message informs the user of how many items are to be
processed such as:
Processing 300 objects.
You may already know the total in your program. If not, you may be
able to determine the total. For example if you are processing a
file of records you could use the RTVMBRD command to access the
number of records to be processed.
In the following example, an outfile is created by DSPOBJD and the
object records are processed.
The following would be typical coding:
DCLF QADSPOBJ /* DSPOBJD outfile */
DCL &STSCNT *DEC LEN(10 0)
DCL &RUNCNT *DEC LEN(10 0)
DCL &CURRCD *DEC LEN(10 0)
DCL &CURRCDA *CHAR LEN(22)
DCL &STRMSG *CHAR LEN(60)
.
DSPOBJD ... OUTIFLE(QTEMP/OBJECTS)
/* Get total number of records to process */
RTVMBRD FILE(QTEMP/OBJECTS) NBRCURRCD(&CURRCD)
EDTVAR CHROUT(&CURRCDA) NUMINP(&CURRCD)
CHGVAR &STRMSG ('Processing ' *CAT &CURRCDA +
*TCAT ' objects.')
OVRDBF FILE(QADSPOBJ) TOFILE(QTEMP/OBJECTS) +
SECURE(*YES)
LOOP: RCVF
MONMSG MSGID(CPF0864) EXEC(GOTO EOF)
/* */
/* Your processing */
/* */
SNDSTSCNT STRMSG(&STRMSG) OPTION(*CNT) STSFRQ(25) +
STSCNT(&STSCNT) RUNCNT(&RUNCNT)
GOTO LOOP
Using a percentage
------------------
You may prefer to send a status message of the percent completed.
You must know the total number of items to be processed and pass this
value in the TOTCNT parameter.
The first message would appear with your text of the STRMSG parameter
such as:
Processing objects.
The second and third messages might appear as:
Processing objects. %10 processed.
Processing objects. %20 processed.
The following would be typical coding.
DCL &STSCNT *DEC LEN(10 0)
DCL &RUNCNT *DEC LEN(10 0)
DCL &TOTCNT *DEC LEN(10 0)
CHGVAR &TOTCNT nnn /* Total to be processed */
.
LOOP: /* */
/* Your processing */
/* */
SNDSTSCNT STRMSG('Processing objects.') OPTION(*PCT) +
STSFRQ(25) STSCNT(&STSCNT) RUNCNT(&RUNCNT) +
TOTCNT(&TOTCNT)
GOTO LOOP
Using a progress bar
--------------------
You may prefer to send a status message of a 'progress bar' to
provide a picture of how much of the total has been completed. You
must know the total amount of items to be processed and pass this
value in the TOTCNT parameter.
The first message would appear with your text of the STRMSG parameter
such as:
Processing objects.
The second and third and last messages might appear as:
Processing objects. Progress - >>> End
Processing objects. Progress - >>>>>>> End
Processing objects. Progress - >>>>>>>>>>>>>>>>>>>> End
The following would be typical coding.
DCL &STSCNT *DEC LEN(10 0)
DCL &RUNCNT *DEC LEN(10 0)
DCL &TOTCNT *DEC LEN(10 0)
CHGVAR &TOTCNT nnn /* Total to be processed */
.
LOOP: /* */
/* Your processing */
/* */
SNDSTSCNT STRMSG('Processing objects.') OPTION(*BAR) +
STSFRQ(25) STSCNT(&STSCNT) RUNCNT(&RUNCNT) +
TOTCNT(&TOTCNT)
GOTO LOOP
Bypassing the SNDSTSCNT command until it is time to send
--------------------------------------------------------
The normal use for SNDSTSCNT is to run the command within the loop
being processed. It would be more efficient to only invoke the
command when it needs to send a message.
The following code is a revision of the previous example to use the
*BAR function. The code updates the RUNCNT and STSCNT variables if
the STSCNT is not equal to one less than the requested STSFRQ value.
When the 'one less count' is met, SNDSTSCNT runs and updates both
variables which causes the appropriate message.
DCL &STSCNT *DEC LEN(10 0)
DCL &RUNCNT *DEC LEN(10 0)
DCL &TOTCNT *DEC LEN(10 0)
DCL &STSFRQ *DEC LEN(5 0) VALUE(25)
DCL &STSFRQ2 *DEC LEN(5 0)
CHGVAR &STSFRQ2 (&STSFRQ - 1)
.
LOOP: /* */
/* Your processing */
/* */
IF (&STSCNT *NE &STSFRQ2) /* Not one less */
CHGVAR &STSCNT (&STSCNT + 1)
CHGVAR &RUNCNT (&RUNCNT + 1)
ENDDO /* Not one less */
IF (&STSCNT *EQ &STSFRQ2) DO /* One less */
SNDSTSCNT STRMSG('Processing objects.') OPTION(*BAR) +
STSFRQ(25) STSCNT(&STSCNT) RUNCNT(&RUNCNT) +
TOTCNT(&TOTCNT)
ENDDO /* One less than STSFRQ */
GOTO LOOP
Message text length
-------------------
The maximum length of the STRMSG parameter is 60 bytes.
You may also specify the ending ending text for the ENDMSG parameter.
The default is 'processed.'. The maximum length is 60 bytes.
The length of the number of processed items in the status message
will vary. At a maximum it will be x,xxx,xxx,xxx or 13 bytes. Two
blanks will appear before the number and one blank after.
The total maximum of text that can be sent on a status message is 80
bytes. For OPTION(*CNT) or OPTION(*PCT) the combination of:
STRMSG (length of the value)
Number processed or percent
Inserted blanks
ENDMSG (length of the value)
cannot exceed 80 bytes. You must specify the STRMSG and ENDMSG
values accordingly or an escape message will occur.
For OPTION(*BAR), the ENDMSG parameter is ignored. The length of the
progress bar is 80 minus the length of the STRMSG value plus spaces
and the words 'Progress - ' and 'End'.
SNDSTSCNT escape messages you can monitor for
---------------------------------------------
None. Escape messages from based on functions will be re-sent.
Command parameters *CMD
------------------
STRMSG The beginning message text. Up to 60 bytes may be
specified. You must ensure that the total amount of
status text will not exceed 80 bytes or an escape
message will occur.
For OPTION(*CNT) or OPTION(*PCT), the length of the
total message is a combination of the length of the
STRMSG value, the length of ENDMSG value, the count
or percentage to be shown, plus a few spaces.
For OPTION(*BAR) the ENDMSG parameter is ignored.
The length of the bar is determined based on the
length of the STRMSG value plus spaces and constants
('Progress - ' and 'End'. The length of the message
will never exceed 80, but you should minimize the
value of STRMSG to ensure a meaningful length of the
'progress bar'.
OPTION The type of status message to be sent.
*CNT is the default meaning a count of the number of
processed items will be included in the message
text.
*PCT may be specified to mean a percentage of the
the total items processed is placed in the message
text. To use *PCT, you must specify the TOTCNT
parameter and pass the total number of items that
exist to be processed.
*BAR may be specified to mean a 'progress bar' is
shown in the message text. To use *BAR, you must
specify the TOTCNT parameter and pass the total
number of items that exist to be processed. When
*BAR is specified, the ENDMSG parameter is ignored.
ENDMSG The ending message text. Up to 60 bytes may be
specified. The default is 'processed.'.
The text is added to the STRMSG value plus other
values. See the discussion with the STRMSG
parameter.
The ENDMSG value is ignored for OPTION(*BAR).
STSFRQ The status frequency. The frequency in which to
send a status message. The default is 25, meaning
every 25 times the command is run, a status message
will be sent.
STSCNT The count of items between status messages. This is
a return variable that must be defined as *DEC
LEN(10 0). In normal use you would not change the
value of the variable. It is updated by the
SNDSTSCNT command processing program and reset to 0
when the STSFRQ value is met.
It is possible to bypass the running of SNDSTSCNT
until the STSFRQ value is met. See the previous
section on 'Bypassing the SNDSTSCNT command until it
is time to send' section.
RUNCNT The running count of how many times SNDSTSCNT has
been used. This is a return variable that must be
defined as *DEC LEN(10 0). In normal use you would
not change the value of the variable. It is updated
by the SNDSTSCNT command processing program.
You can change the value of this variable to cause
the status message to appear at different intervals,
but the normal use would be to just declare the
variable and let the SNDSTSCNT command processing
program control the value.
If the value passed is 0, the status message sent
will be the STRMSG value.
If you are processing multiple sets of items within
the same program, you should change the value of
RUNCNT to 0 for the first use of SNDSTSCNT when
processing a new set of items.
TOTCNT If OPTION(*PCT) or OPTION(*BAR) is specified, you
must pass the total count of items to be processed.
This allows the command processing program to divide
the RUNCNT value by the TOTCNT value to determine
the percentage processed.
You must ensure a proper value for TOTCNT to make
the *PCT or *BAR function meaningful. If *PCT is
used, the value will never exceed 100%. If *BAR is
used, the string of >'s will never exceed the length
of the Bar area.
Calling the CPP
---------------
The SNDSTSCNT CPP may be called directly from a HLL program. If you
want the STRMSG value to contain the total number of entries, you
must concatenate the value into a string of text. The following
sample RPG statements could be used:
I* Sub program for the SNDSTSCNT tool
I 'TAATOOL/TAAMSIOC' C STSCNT
C****************************************************************
C* *
C* Initialize for SNDSTSCNT (run only once) *
C* - Do not place any values in FRQCNT or RUNCNT *
C* - STRMSG is required and should be left adjusted *
C* - OPTION must be *CNT, *PCT, or *BAR *
C* - If *CNT, TOTCNT is ignored (can be 0) and *
C* ENDMSG is required. *
C* - If *PCT, a TOTCNT value is required and *
C* ENDMSG is required. *
C* - If *BAR, a TOTCNT value is required and *
C* ENDMSG is ignored (may be blank). *
C* *
C****************************************************************
C MOVEL'Progress'STRMSG Start msg
C 'processe'CAT 'd.' ENDMSG End message
C MOVE '*BAR' OPTION Set option
C Z-ADD25 STSFRQ Status freq
C Z-ADDnnn TOTCNT Total count
C****************************************************************
C* *
C* Call program for TAA SNDSTSCNT *
C* *
C****************************************************************
C CALL STSCNT SNDSTSCNT
C PARM STRMSG 60 Start msg
C PARM OPTION 4 Option
C PARM ENDMSG 60 End message
C PARM STSFRQ 100 Status freq
C PARM FRQCNT 100 Freq count
C PARM RUNCNT 100 Run count
C PARM TOTCNT 100 Total count
Restrictions
------------
Because the command requires return variables, it may only be used in
a CL program.
Prerequisites
-------------
The following TAA Tools must be on your system:
EDTVAR Edit variable
SNDESCINF Send escape information
SNDESCMSG Send escape message
SNDSTSMSG Send status message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
SNDSTSCNT *CMD TAAMSIO QATTCMD
TAAMSIOC *PGM CLP TAAMSIOC QATTCL
|
