TAA Tools
DLYCMD      DELAY COMMAND EXECUTION                    TAAJOBK

The DLYCMD allows you to  enter a command at a workstation  and have it
executed at  a later time.  It is  specifically intended for operations
at  the system console that  should only be run  when no other jobs are
active.  Some functions of  the system (e.g.  RCLSTG) require  that the
system be  in the  restricted state  (only a single  job is  active) in
order to execute.

Tools  now exist  for SAVSYSBCH and  RCLSTGBCH which  may preferable to
the use of DLYCMD for these functions.

As an example  of DLYCMD, assume  you want to  run RCLSTG beginning  at
3:00  AM tomorrow  morning and  then powerdown.   Just  prior to  going
home,  you would enter  the following command  at a workstation  in the
controlling subsystem (you can  prompt for the  command entered in  the
CMD parameter).

        DLYCMD    CMD(RCLSTG)
                  TIME(030000)
                  DATE(*DAY1)
                  TEXT('Reclaim Storage function')
                  RSTDSTATE(*YES)
                  POWERDOWN(*YES)

A display would appear as follows:

**********************************************************************
*                                                                    *
*               TAA Delay command in operation                       *
*                                                                    *
*    Text . . . . . . . . . . : Reclaim Storage function             *
*                                                                    *
*    Command to be executed . : RCLSTG                               *
*                                                                    *
*    Command date . . . . . . : *DAY1                                *
*    Date to execute  . . . . : 12/02/09                             *
*    Time to execute  . . . . :  3:00:00                             *
*    Maximum active job limit : *NOMAX                               *
*    Subsystem  . . . . . . . : *ALL                                 *
*    Exit pgm after timeout   : *NONE                                *
*    Restricted state . . . . : *YES                                 *
*    Power down . . . . . . . : *YES                                 *
*    Restart  . . . . . . . . : *NO                                  *
*    Signoff LOG(*LIST) . . . : *YES                                 *
*    Wait time  . . . . . . . :   900                                *
*                                                                    *
*                                                                    *
*       No break messages will appear.  No function keys are valid.  *
*       Use system request to display a Message Queue.               *
*       An -End Request- via System Request causes a Signoff.        *
*                                                                    *
**********************************************************************

You would  then go home.   At  3:00 AM, the  DLYCMD would shutdown  the
subsystems,  enter the  restricted  state, execute  the  RCLSTG command
and then powerdown.

When  the display  occurs, there  are no  input fields and  the program
will not respond to the enter  key or a function key.  You can  end the
command using  system request  option 2 (End  previous request),  but a
Signoff will occur.

While  the command is executing,  no messages will cause  a break.  You
can display a message queue using the the system request function.

If you  request  the  restricted  state, DLYCMD  ensures  that  only  a
single job is  active at the workstation as ending  the subsystems does
not cause other jobs at the same workstation to end.

Using the defaults for Day and Time and MAXJOBS
-----------------------------------------------

There are three methods of delaying the command:

             - Using a time of day
             - Using a date
             - Using the MAXJOBS parameter

If  all defaults  are taken, the  DLYCMD screen  appears with  a status
message indicating a  wait of 30  seconds.  This  is designed to  allow
the  operator  time  to  review  the   specifications  and  cancel  the
function  if  required.   The  cancel  would be  done  by using  System
Request  Option 2 (End Previous Request), but  will cause the job to be
signed off.

Triggering a command based on a MAXJOBS value
---------------------------------------------

In addition to  triggering a command  based on a time  of day, you  can
also  trigger a  command  based on  the  number of  active  jobs.   For
example,  if  you want  to trigger  a command  when  there are  only 10
active jobs (or less) on the system, you would say:

                  MAXJOBS(10)

The default is  that all  subsystems would  be checked.   You may  also
name one  or more subsystems.   For example,  if you enter  the command
from  a  device in  the controlling  subsystem  and want  to  trigger a
command when there  are no  active jobs in  SBSD1 or  SBSD2, you  would
specify:

                  MAXJOBS(0)
                  SBS(SBSD1 SBSD2)

When  using MAXJOBS,  the  subsystem monitor  (a  job that  appears  on
WRKACTJOB) does not count toward the value.

You can  specify both the TIME  and the MAXJOBS triggers  in which case
the command will not be triggered until both are satisfied.

For  example, assume  you are  using the  QBATCH subsystem and  want to
perform RCLSTG  beginning no earlier  than 11:00  PM tonight and  after
all  work  has been  completed  in the  QBATCH  subsystem.   You  would
specify:

        DLYCMD    CMD(RCLSTG)
                  TIME(230000)
                  MAXJOBS(0)
                  SBS(QBATCH)
                  TEXT('RCLSTG command')
                  POWERDOWN(*YES)
                  RESTART(*YES)

If the  number of jobs you specified is  greater or equal to the number
in the  subsystem,  the  command  waits 30  seconds  and  accesses  the
number  active again.   This  process is  repeated 3  times before  the
command  you want is  run.  This  repeated processing is  an attempt to
ensure that a 'window of  time' has not found  a condition where a  new
job is starting, but is not yet known to the subsystem.

Note  that if  you have  'never  ending' batch  jobs  in the  specified
subsystem, specifying  MAXJOBS(0) will never cause the  command to run.
There are two solutions:

  **   Determine  the number of 'never ending'  batch jobs and use this
       number instead of 0.

  **   Use the RTVSBSBCH solution described later.

If you are  using QBASE as  the controlling subsystem  for all of  your
work, there  will be additional jobs  which are active.   You will want
to review the RTVSBSBCH solution.

Triggering a command based on the TAA Tool RTVSBSBCH
----------------------------------------------------

If  QBASE is  used (it is  the system  default) rather  than a separate
subsystem for batch  work, the  system starts several  batch jobs  that
exist in QBASE that  remain active while they are  waiting for an event
to  occur.   A  similar condition  can  exist in  a  separate subsystem
devoted to batch work  where 'never ending user  jobs' are waiting  for
some event.

Because these types  of jobs are  common, the definition of  when batch
work  is completed can  be complex.   Unless  you have a  very straight
forward  batch subsystem with  none of these types  of jobs, you cannot
rely on a count of zero  batch jobs to determine that there is  no more
batch work to be performed.

Most installations  consider that  a job that  is waiting for  an event
can  be  safely terminated  when  it is  time to  reach  the restricted
state or shut down the system.

To provide a  solution for when  there is no  more 'actual batch  work'
being  performed,  the   TAA  Tool  RTVSBSBCH  should   be  considered.
*RTVSBSBCH is an option for the MAXJOBS parameter.

RTVSBSBCH  allows  you to  determine  that no  'actual  batch  work' is
being performed based on the  status values as displayed by  WRKACTJOB.
If the  only  batch jobs  still active  are in  a wait  state, you  can
decide to end the subsystem.

You should  not use MAXJOBS(*RTVSBSBCH) unless you  have understood the
RTVSBSBCH  tool documentation  and used  the PRTSBSBCH  command to help
determine your individual system  requirements.  You may describe  your
own set of status conditions that should be checked for.

If  *RTVSBSBCH  is   specified,  1  to  9  subsystems   or  all  active
subsystems  may  be  checked.    If  a  TIME  value  is  also  entered,
RTVSBSBCH is not attempted until the TIME value is met.

If all  subsystems  specified find  no  jobs  in the  RTVSBSBCH  return
variables of  RUN and OTHCNT,  the job delays  30 seconds and  does the
same test  again for all specified subsystems.   This helps ensure that
a window of  time has  not caused  a lack of  batch activity.   If  the
loop  is successful  3  consecutive times,  the  command you  specified
will be run.

If  one of  the subsystems  to be  checked  reports batch  activity, an
exception  spooled file is output and the  job waits again for the time
specified on the WAITTIME parameter.

Setting the defaults for DLYCMD
-------------------------------

You can set the defaults  for DLYCMD to your own requirements  by using
the SETDLYCMD  command.   A user with  *ALLOBJ special  authority would
enter:

             SETDLYCMD

and  press F4.  The command  prompts are the same  as for DLYCMD except
that *SAME is allowed for most  parameters.  Key over the defaults  you
want to  change and  press Enter.   The  next time  DLYCMD is  prompted
for, you will see your default.

SETDLYCMD  may also  be used without  prompting to  change one  or more
parameters.

The defaults are  stored in the  DLYCMD data area  in TAASECURE.   Both
SETDLYCMD and DLYCMD  use the same  prompt override program  to extract
the values  from the TAASECURE  data area.  The  EXITPGM parameter does
not exist on SETDLYCMD and cannot be set as a default.

The  SETDLYCMD function  may also be  invoked from the  TAA SAVE2 menu.
The same  set of  defaults is used  for any  DLYCMD operation.   If  an
'exit  before  save program'  is  specified  in  the SAVE2  Application
Value, it is used on the DLYCMD.

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

  **   If you have requested RSTDSTATE(*YES):

         --   The  command  must  be  executed  from  a  device in  the
              controlling subsystem.    The  default on  i5/OS  is  for
              QBASE to be  the controlling subsystem and  also used for
              interactive  and   batch  work.    Therefore,  any  local
              device in  QBASE  could perform  the  function.   If  the
              QINTER/QBATCH approach  is used, you  must have  a device
              in the  controlling subsystem (e.g.   QCTL) to  enter the
              command.

         --   If   the  restricted  state  cannot   be  reached  in  10
              minutes, the command fails with an escape message.

         --   If   POWERDOWN(*NO)   is   requested,   the   controlling
              subsystem  will  be  restarted   after  your  command  is
              completed.   The  current controlling subsystem  is used.
              Not the name in the  QCTLSBSD system value.  You can  use
              an auto start job to bring up other subsystems.

  **   If a  break message occurs at  a workstation which  is executing
       a  command, the  command is  interrupted  and will  not complete
       until the message  interrupt is ended.   RCLSTG assigns  QSYSOPR
       to the requesting workstation and may send break messages.

       To   prevent  this   potential   hang  condition,   the   CHGJOB
       BRKMSG(*HOLD)  function is  used while  DLYCMD is  in execution.
       However,  any  inquiry messages  caused  by the  DLYCMD command,
       will cause  the function  to hang.    For example,  if a  'mount
       media'  occurs,  the DLYCMD  command  will  hang  waiting for  a
       response.

       The   RCLSTG  command  does  not   normally  issue  any  inquiry
       messages.   The  SAVSYS  command  normally  causes  media  mount
       messages  unless the  entire  save can  be  placed  on a  single
       media.

Security considerations
-----------------------

The  intent  is that  you  will  leave the  system  unattended  and the
DLYCMD in execution.   Because of  this, there is  a security  exposure
since  the  System  Request function  can  be  used  while  the  DLYCMD
display is being displayed.

Physical security should be used.

Two functions are automatically provided by DLYCMD.

  **   No  Function key  or Enter  key can  be used  to end  the DLYCMD
       display.

  **   If  System Request  is used  for -End  Request-, a  Signoff will
       occur.

The POWERDOWN and SIGNOFF  options on DLYCMD control what  happens when
the command completes successfully.

Only  a user with  *ALLOBJ authority  can use  SETDLYCMD.   The program
which  accesses the  command defaults  for the prompt  override program
adopts the owners authority.

Tighter security
----------------

To achieve  better security,  you should  consider  a separate  profile
(e.g.    QSYSOPR2) so  that  you  can  prevent  certain actions.    The
following  user profile could be  created (CURLIB should be  set to the
library which contains the DLYCMD command):

             CRTUSRPRF    USRPRF(QSYSOPR2) PASSWORD(xxxx)
                            USRCLS(*SYSOPR) CURLIB(TAATOOL)
                            INLPGM(QSYS/QCMD) ATNPGM(*NONE)
                            TEXT('User profile intended for +
                            use with TAATOOL DLYCMD')

Note that it is  important for a  user class of *SYSOPR  to be used  so
that the user  can perform save  operations and power down  the system.

The following  commands will prevent  access to certain  System Request
functions.

             GRTOBJAUT    OBJ(QSYS/TFRSECJOB) OBJTYPE(*CMD)
                            USER(QSYSOPR2) AUT(*EXCLUDE)

             GRTOBJAUT    OBJ(QSYS/DSCJOB) OBJTYPE(*CMD)
                            USER(QSYSOPR2) AUT(*EXCLUDE)

The sequence of events would then be:

  **   Signoff the device to be used in the controlling subsystem.

  **   Signon as QSYSOPR2.

  **   Prompt for the DLYCMD.

  **   Enter the required values and press Enter.

  **   The DLYCMD display will appear (as shown earlier).

  **   Go home.

At  that point, any user gaining access to  the device could not do the
following:

  **   Use System Request to transfer to a secondary job.

  **   Use the Attention key to  access a group job or a  command entry
       menu.

  **   Use  System  Request to  -End  request-  to  access the  command
       entry display.  A signoff would occur.

  **   End  the DLYCMD function  and access command entry  by using any
       Function key or Enter key.

Any user gaining access to the device could use System Request to:

      - Display the current job.
      - Display any authorized message queue (including QSYSOPR).
      - Send a message to a message queue.
      - Signoff.

You could  prevent any  of the  remaining valid  options  by using  the
GRTOBJAUT command as was suggested for the TFRSECJOB command.

DLYCMD use within a CL program
------------------------------

It is  possible to  execute the  DLYCMD within  a CL  program, but  the
command  can only be  executed from an  interactive job.   Commands may
follow DLYCMD in a CL program,  but only if you request  POWERDOWN(*NO)
and  SIGNOFF(*NO).   For  example,  after  the command  completes,  you
could start other subsystems or submit batch jobs.

DLYCMD Command parameters                             *CMD
-------------------------

   CMD           The  command  to be  executed  when  the triggers  are
                 satisfied.     F4  may  be  used  to  prompt  for  the
                 command.     The   original  default   is  blank   (no
                 command).   The  command is  optional and  is intended
                 for  those  cases  where  you  only  want a  PWRDWNSYS
                 option to  occur.   SETDLYCMD may  be  used to  change
                 the default.

   TIME          The  time of  day  trigger.   It  must  be entered  as
                 HHMMSS.    Military  time is  used  (2:00  PM must  be
                 entered as 140000).   The original  default is  *NONE.
                 SETDLYCMD may be used to change the default.

   DATE          The date  trigger.   A  date (in  job  format) or  the
                 values  *TODAY, *DAY1 or  *DAY2 can  be entered.   The
                 original  default is  *TODAY.   SETDLYCMD may  be used
                 to change the default.

                 If *TODAY is entered,  the TIME value must be  greater
                 than the current  time.  *DAY1 means the  next day and
                 *DAY2 is the second day.

   MAXJOBS       The  maximum number of  jobs trigger.   The default is
                 *NOMAX.  The value may  be from 0 to 9999.   SETDLYCMD
                 may be used to change the default.

                 Note that  the subsystem  monitor job  can be  seen on
                 WRKACTJOB,  but  is  not  considered  a  job  for  the
                 MAXJOBS parameter.   Thus an  entry of  0 means  there
                 is no other job, but the monitor job.

                 If a value is  entered, it is used to  compare against
                 all   of  the  active   jobs  specified  in   the  SBS
                 parameter.   If the  number is met,  the command waits
                 30 seconds  and  tries the  function  twice more  with
                 another  intervening 30  seconds.   This helps  ensure
                 that no new jobs are being started.

                 The  special value  *RTVSBSBCH may  be entered  to use
                 the  RTVSBSBCH  tool  on  the  specified   subsystems.
                 This tool  is designed  to assist  you in  determining
                 if any  'actual batch work' is  being performed in the
                 subsystem.  Before  specifying *RTVSBSBCH, review  the
                 documentation  for  the RTVSBSBCH  tool  and  try  the
                 PRTSBSBCH command  to ensure that you  have the proper
                 status values checked for your system.

   SBS           The  subsystems  to check  for the  MAXJOBS parameter.
                 Up  to 9  subsystems  may  be  named.    The  original
                 default  is *ALL.   SETDLYCMD  may be  used  to change
                 the default.

                 If  MAXJOBS is other than *NOMAX  and a subsystem name
                 is entered, the subsystem must be active.

                 If  you   name  multiple   subsystems,  there   is   a
                 performance  advantage  in  naming   the  most  active
                 subsystem  first.  For  example, if you  want to delay
                 until both  QINTER  and QBATCH  are  1 and  QINTER  is
                 more likely to  have more active jobs,  specify QINTER
                 first.   If  QINTER has  multiple active  jobs, QBATCH
                 is not even checked.

                 There  is overhead  involved in  checking for MAXJOBS.
                 If you need to  check for MAXJOBS, but do not  need to
                 do so  until a specific time, you  should also specify
                 the  TIME  parameter.   No overhead  occurs  while the
                 job is waiting for the time value to expire.

   EXITPGM       The name  of  your  exit  program which  will  be  run
                 after  any time  out has  occurred  and before  ending
                 any  subsystems.  *NONE  is the  default meaning there
                 is no exit program.

                 An exit program and library  name may be specified  to
                 cause  the  program  to  be   run  after  the  timeout
                 occurs.   The intention of  the program is  to provide
                 for any cleanup before ending all subsystems.

   TEXT          The  text  that should  appear  on the  display.   The
                 original default is *NONE.   SETDLYCMD may be used  to
                 change the default.

   RSTDSTATE     Whether  the   restricted  state  should   be  entered
                 before  the  command  entered  on  the  CMD  parameter
                 should  be  executed.     The   restricted  state   is
                 required for some  commands.  The original  default is
                 *NO.  SETDLYCMD may be used to change the default.

   POWERDOWN     Whether  the system should  be powered  down after the
                 command is  executed.   The original  default is  *NO.
                 SETDLYCMD may be used to change the default.

                 If the  restricted  state is  used and  PWRDWNSYS(*NO)
                 is   specified,   STRSBS   will   be  used   for   the
                 controlling    subsystem   when    the   CMD   command
                 completes.

   RESTART       Whether to  re-start  the system  if  a powerdown  has
                 occurred.     This  value   is  passed  thru   to  the
                 PWRDWNSYS  command  RESTART parameter.    The original
                 default is *NO.  SETDLYCMD  may be used to change  the
                 default.

   SIGNOFF       Whether  to signoff  after  the  command is  executed.
                 If  the system  is  re-started without  powering down,
                 you may  choose to  signoff.   LOG(*LIST) is  used  to
                 provide a  job  log.   The original  default is  *YES.
                 SETDLYCMD may be used to change the default.

                 An entry  of *NO will  cause a return  when the DLYCMD
                 is  complete.    If you  include  the DLYCMD  in  a CL
                 program  with  commands  following  DLYCMD,  you  will
                 want to specify SIGNOFF(*NO).

   WAITTIME      The wait  time associated with  the MAXJOBS parameter.
                 The  5  digit  0 decimal  parameter  uses  an original
                 default of 600  seconds (10  minutes).  SETDLYCMD  may
                 be used to change the default.

                 This  value  controls  the   frequency  in  which  the
                 DLYCMD  will check the  number of active  jobs per the
                 MAXJOBS  and  SBS  parameters.    There  is   overhead
                 associated  with this  checking.   Thus  the  WAITTIME
                 should  not be  specified  too  low.   If  the MAXJOBS
                 value  is reached,  the DLYCMD  will not  recognize it
                 until the wait time expires.

SETDLYCMD Command parameters                          *CMD
----------------------------

The same parameters as  used on DLYCMD are supported plus  the addition
of *SAME for each parameter except CMD.

If the  CMD parameter is blank, the  current value is not  changed.  To
reset the CMD parameter to blanks, use the NOOP TAA command.

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

The following TAA Tools must be on your system:

      ADDDAT      Add date
      CHKALLOBJ   Check *ALLOBJ special authority
      CHKRSDSTE   Check restricted state
      CLCDATDIF2  Calculate date difference 2
      CLCTIMDIF   Calculate time difference
      EDTVAR      Edit variable
      EXTLST      Extract list
      EXTLST2     Extract list 2
      RTVIPLSTS   Retrieve IPL status
      RTVJOBSTS   Retrieve job status
      RTVSBSD     Retrieve subsystem description
      RTVNBRACT   Retrieve number of active jobs in a subsystem
      SNDCOMPMSG  Send completion message
      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
   ------        -----      ---------      ----------     -----------

   DLYCMD        *CMD                      TAAJOBK        QATTCMD
   SETDLYCMD     *CMD                      TAAJOBK2       QATTCMD
   TAAJOBKD      *FILE         DSPF        TAAJOBKD       QATTDDS
   TAAJOBKC      *PGM          CLP         TAAJOBKC       QATTCL
   TAAJOBKC2     *PGM          CLP         TAAJOBKC2      QATTCL
   TAAJOBKC11    *PGM          CLP         TAAJOBKC11     QATTCL
   DLYCMD        *DTAARA

The DLYCMD data area is in TAASECURE.

Structure
---------

DLYCMD     Cmd
  TAAJOBKC   CL

SETDLYCMD   Cmd
  TAAJOBKC2  CL

The  TAAJOBKC11 program is used  as a prompt override  program for each
command.
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top