The Calculate Delay tool is used to determine the number of seconds
to delay a job to begin the next iteration of a repeating activity.
Activities like this can occur within limited time during the day.
We call this range the "activity block".  The number of seconds
returned is meant to be used with the IBM i DLYJOB command.

For example, suppose we require an activity to take place at 10
minutes past each hour, but it needs to occur only during business
hours from 8:00 am to 5:00 pm.  The following command can be used to
determine the number of seconds to be used with DLYJOB.

  CLCDLY STRTIME(081000) ENDTIME(170000) ITV(010000) DLY(&DLY)

If the current time was 09:45:30 then the above command would return
a &DLY of 1470 seconds to the next activity time of 10:10:00.

The CLCDLY command understands overnight conditions.  If the ENDTIME
parameter is less than the STRTIME parameter then the activities are
assume to take place overnight.  For example, one could specify the
following to schedule an activity that occurs every 30 minutes
beginning at 5:00 pm and continuing to 8:00 am.

  CLCDLY STRTIME(1700) ENDTIME(0800) ITV(0030) DLY(&DLY)

The start and end times are inclusive.  If the current time is
07:59:58 and you used the above command it would return a delay of 2
seconds and the last activity would take place at the end time of
08:00.  Likewise, if the current time was 16:00:00 the next activity
would be at the start time of 17:00 and the &DLY would be 3600 or
one hour.

There are two additional parameters on the command.  One to return
the time of the next activity (RSMTIME), and one to simulate a
specific clock time (TIME) for testing purposes.  The DLY and
RSMTIME values correspond to the same keywords on the DLYJOB
command.

Care should be used when specifying a RSMTIME with DLYJOB.  It is
possible to have the system clock be a few milliseconds past a
specified RSMTIME which results in a DLYJOB of almost 24 hours.

Times and durations can be entered in either HHMM or HHMMSS format
with 00 is used for seconds if the HHMM format is used.


CLCDLY escape messages you can monitor for
------------------------------------------

CPF9898 This is sent if the parameters passed to the command do not
pass the validation checks.

CLCDLY command parameters                             *CMD
-------------------------

   STRTIME       This specifies the beginning of the activity block.
                 This is a 24 hour time that can be specified as
                 HHMM or HHMMSS.  If STRTIME is greater than the
                 ENDTIME then the activity block extends overnight.
                 STRTIME and ENDTIME may not be the same.  Values
                 can be 000000 through 235959.  This keyword is
                 optional and defaults to 000000.

   ENDTIME       This specifies the end of the activity block.  This
                 is a 24 hour time that can be specified as HHMM or
                 HHMMSS.  If STRTIME is greater than the ENDTIME
                 then the activity block extends overnight.  STRTIME
                 and ENDTIME may not be the same.  Values can be
                 000000 through 235959.  This keyword is optional
                 and defaults to 235959.

   ITV           This is the duration between activities in the
                 activity block.  This can be specified as HHMM or
                 HHMMSS.  It can be in the range of 000001 to 235959
                 inclusive.  This keyword is optional and defaults
                 to 010000 or one hour.

   DLY           This is a *DEC (5 0) variable that holds the return
                 value for the number of seconds until the next
                 activity.  It is meant to be used with DLYJOB.

   RSMTIME       This is a *CHAR (6) variable that holds the return
                 value for the time at which the next activity is to
                 occur.  It can be used with DLYJOB but care should
                 be taken.  It is possible to have the system clock
                 be a few milliseconds past a specified RSMTIME
                 which results in a DLYJOB of almost 24 hours.

   TIME          This specifies the time from which the DLY and
                 RSMTIME should be calculated.  This can be
                 specified as HHMM or HHMMSS.  It can be in the
                 range of 000000 to 235959 inclusive.  This keyword
                 is optional and defaults to *CURRENT.  Unless you
                 are testing this function the default value of
                 *CURRENT should be used.


Restrictions
------------

None.

Prerequisites
-------------

The following TAA Tools must be on your system:

     SNDESCINF       Send escape information
     SNDESCMSG       Send escape message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   CLCDLY        *CMD                   TAADLYS       QATTCMD
   TAADLYSC      *PGM       CLLE        TAALIBZC      QATTCL
   TAADLYSB      *PGM       CLLE        TAALIBZC      QATTCL

Structure
---------

CLCDLY      Cmd
   TAADLYSC    CL pgm