Conference share::zap

31.0. "Zap V3.6 Documentation" by MRMFG1::K_MACONI (The Doctor) Fri Nov 07 1986 14:14

 ZAP
                 Help file for Zap version 3.6

   Zap is an idle process deletion utility which runs under VAX/VMS
version 4.2 or greater.  This program uses an initialization file to
determine its run characteristics.  Once the initialization file has
been read, Zap will run indefinitely with very little disk i/o.
 Errors
   If Zap should ever fail, an error file will be created which will
contain why the process failed.  This file (ZAP$DIR:ZAP.ERR) should
be checked to see if there is any obvious cause for the error (which
could be caused by system problems).  If the error is not obvious,
send the error file to Zap support.

   Zap support is available through the VMS Notes file MRMFG1::ZAP.
Please direct all support related questions through this notes file.
 Initialization
   The Zap initialization command file (ZAP$DIR:ZAP.DAT) is used to
inform Zap on how to scan the system.  There are three types of commands
within the initialization file.  The first is a run parameter, the
second is an exception record, and the third is an image exit record.

   The file is a standard ascii text file which can be edited with any
text editor.  Comments may be contained within the file by placing an
exclamation point as the first character in the line.  No blank lines
are allowed within the initialization file.
 
 
Exception_records
   Exception records are command lines which describe to Zap how to
handle various processes running on the system.  These command lines
contain a description of a process, and an appropriate action.

   Each exception record contains several fields, below is a brief
explanation of each of those fields.

    Uic        - Any valid uic specification with wild cards, ex. [1,4]
                 or [*,*].

    Image name - Any valid image name up to 39 characters.  Standard
                 Vax/VMS filename wildcards are allowed.  Ex. aut%ori*

    Terminal   - Legal terminal specifications are:
                    all, batch, console, detach, dialup,
                    lat, local, network, remote, and virtual
                 A physical device may be specified by preceeding the
                 device name with an underscore.  For example:
                    _TXC3: or _LTA3521:

    Time limit - Integer time limits greater than zero or * for no limit
                 or zero for immediate zap.

    Messages   - yes or message to send the two minute warning messages
                 and a logout message, or no or nomessage to send no
                 warning or logout messages.

   Zap exception records are read sequentially and the first record that
applies to a specific process will be used.  This records are read into
memory so that Zap must be reinitialized to change these records.
 
 
Examples
   Below are several examples of exception lines that are included in
the default Zap initialization file.  Each record is in the form:

     Uic       Image           Terminal        Time limit     Message

   This command insures that no user who is logged in at the console
device will ever be Zapped.

     [*,*]     *               console         *              nomessage

   This command is used to limit the length of time any SYSTEM remote
user may be idle, no matter what image is being run.

     [001,004] *               remote          15             message

   This command is used to limit the amount of idle time that a user
may remain idle in the MAIL program.  This might be used to extend the
default idle limit for this specific image.

     [*,*]     MAIL            all             30             message

   This command is used to make all programs which begin with AVR and
end with E to be immune from Zap when run from the [1500,2020] uic.

     [1500,1]  avr*e           all             *              nomessage

   This command would exclude any user within the 240 uic group from
being zapped if they were logged into terminal TXA3:.

     [240,*]   *               _txa3:          *              nomessage

   This command would be used to specify a default Zap idle limit for
all users who are not included in a previous exception record.

     [*,*]     *               all             20             message
 
 
Run_parameters
   Run parameters are used to indicate how the zap process should run.
They describe what characteristics the monitor should take on.  Currently
there are only three run parameters supported.
 
 
/debug
   This parameter tells Zap to write detailed information about
the work that it is doing to the zap log file (ZAP$DIR:ZAP.LOG).
This parameter is included for Zap support only.  Its use for
other purposes is not supported.

   If this parameter is turned on, extremely large zap log files
will be created.  Unattended, these logs could easily reach into
the tens of thousands of blocks if left to run for a day or more.

/DEBUG=TRUE or /DEBUG=FALSE
 
 
/inswap
   This parameter is used to indicate how Zap should handle a
process which is swapped out at the time that the system is
scanned for idle processes.

   If a process is swapped during the scan and this parameter
is set to true, then it will be swapped in and checked for idle
time.  If this parameter is set to false, the process will be
ignored for this pass and remain at its previous level of idle
time.

/INSWAP=TRUE or /INSWAP=FALSE
 
 
/send
   This parameter tells Zap when to send warning messages to the
users terminal.  Up to five different times may be specified, in
descending order.  All times must be greater than zero.

/SEND=time_1[,time_2][,time_3][,time_4][,time_5]
 
 
/sensitivity
   This parameter tells Zap how much work a process must perform
in order to be considered active.  Below is the formula which is
used by Zap to calculate how much work a given process has
performed within the last minute.  If a process meets or exceeds
the sensitivity level, then the process is considered active.

   ( cpu_time in hundredths of second ) +
   ( 2 * buffered_io ) +
   ( 3 * direct_io )

/SENSITIVITY=sensitivity_factor
 
 
/traceback
   This parameter tells Zap how to handle subprocesses.  This
parameter can either be enabled or disabled.  By default, it
is disabled.

   If traceback is disabled, then only a process which does not
have any active subprocesses is checked for idle time.  This
means that if a user has many levels of inactive subprocesses,
then they will be zapped from the lowest level on up (as they
accumulate sufficient idle time).

   If traceback is enabled, then only the main processes on the
system are checked for idle time.  This is done by billing the
parent process for all of the time that its subprocesses use.
If this total is not enough to keep the parent process active,
then the parent process is killed and the subprocesses are left
to die on their own.

/TRACEBACK=TRUE or /TRACEBACK=FALSE
 
 
Examples
   The send command is expressed as a parameter list in the form:

     !
     /send=10,8,6,4,2
     !

   which tells Zap to send a warning message to the users terminal
when the user has 10, 8, 6, 4, or 2 minutes of idle time remaining.

   The sensitivity level is expressed as an equation of the form:

     !
     /sensitivity = 5
     !

   where 5 is the number of units of work that must be done.  No spaces
are allowed in front of the command.

   The traceback parameter is specified in the form:

     !
     /traceback=true
     !

   or to disable traceback, it is specified in the form:

     !
     /traceback=false
     !

   Always include the debug command to insure that it is
not turned on:

     !
     /debug=false
     !

   If you have a system which has a lot of swapping on it,
it would aid your performance to turn off process inswapping
in Zap.

     !
     /inswap=false
     !
 Log
   When Zap is running, a log file (ZAP$DIR:ZAP.LOG) is generated which
details what the Zap utility has done during its run.  This log file
should be purged periodically by shutting down Zap and then restarting
it with another log file.  Reinitializing Zap by setting the run status
logical to START will not perform this function.
 Messages
   When Zap determines that a user has been idle for a long period of
time, it will send warning messages to the users terminal before it
stops the users process.  These messages are sent 10 minutes, 8 minutes,
6 minutes, 4 minutes and 2 minutes before the user is killed.

   Zap allows the format of these messages to be specified in the
Zap message file (ZAP$DIR:ZAP.MSG).  If this message file does not
exist, a default message is created.
 
 
Format
   The format of the message file is an ascii representation of how
the Zap warning message will appear on the users terminal.  On video
terminals, this message is always displayed at the top of the screen.

   This file may contain comments at the beginning of the file.  To
enter comments, place an exclamation point in the first position of
the line.  Comments must be contiguous and at the front of the file.

   After the comments, the actual warning message text can be inserted.
No special characters are allowed.  However, symbols have been provided
to allow the insertion of various types of information.
 
 
Symbols
   The following symbols may be inserted within the message text
and will be replaced with the appropriate information when the
message is sent.

   Formatting characters available:

       Symbol  Meaning                 Display format

         %a    Accumulated idle time   ZZZ9
         %b    Bell                    None
         %d    Device name             XXXXXXX
         %l    Line mode               None
         %r    Remaining idle time     ZZZ9
         %t    Time of day             DD-MMM-YYYY HH:MM:SS.CC
         %u    Username                XXXXXXXXXXXX

   When line mode is selected, the message is displayed after the
current cursor position on the terminal.  When line mode is not
selected, the message is displayed at the top of the screen.
 
 
Example
   The following message file produces a brief one line
message for the user.  Although this is the default message
if no file is found, a file should always exist.

   !
   ! Default message if no message file is found
   !
   %b[Zap: Idle time remaining %r]

   The following message file produces a detailed message
for the user.  This is the default message file that comes
with the kit.

   !
   ! Formatting characters available:
   !
   !	Symbol	Meaning			Display format
   !
   !	  %a	Accumulated idle time	ZZZ9
   !	  %b	Bell			None
   !	  %d	Device name		XXXXXXX
   !     %l    Line mode               None
   !	  %r	Remaining idle time	ZZZ9
   !	  %t	Time of day		DD-MMM-YYYY HH:MM:SS.CC
   !	  %u	Username		XXXXXXXXXXXX
   !
   ! Message must be continuous, without comments
   !
   %bZap idle process status at %t

    Device: %d

    Username: %u

    Minutes of idle time accumulated: %a

    Minutes of idle time remaining:   %r
 Monitor
   While Zap is running, the system logical name ZAP$MONITOR will contain
information about how Zap is running.  The information will include how
many passes Zap has made, the number of processes in the stack, how many
processes have been stopped, and the number of errors it has encountered.

   If the error count is greater than zero, then it is advisable to
check the Zap log file to determine why the error occurred.  Normally,
errors that occur infrequently are not a cause for concern unless they
are affecting a function that you require.
 Privileges
   Zap requires certain privileges in order to operate correctly.  Since
this utility is designed to interfere with other user processes, it is
suggested that this utility never be installed with privileges so that
non-privileged users could run Zap.

   The following privileges are required for Zap:

      Exquota - Required in case the uic that the job is running under
                should run out of disk space and cause the Zap system
                to crash.  This privilege is not required if no disk
                quotas are enabled on Zaps log device.

      Oper    - Required to send messages to users.  This privilege is
                not required if no messages are to be sent, this is not
                recommended.

      Sysnam  - Required to redefine the system wide zap status logical
                ZAP$RUN_STATUS.

      Tmpmbx  - Required for basic system communications.

      World   - Required for Zap to be able to scan the entire system
                and delete idle processes.  Although GROUP privilege
                may be substituted so that it will only run in one uic
                group, it is not recommended.
 Run_status
   While Zap is running, the system logical name ZAP$RUN_STATUS describes
the current state of Zap.  It can also be used to modify Zap without just
killing the process.  Any user who has SYSNAM privilege may change this
logical name.  All changes must be made in EXEC mode, using the command:

   ASSIGN/SYSTEM/EXEC "zap run status" ZAP$RUN_STATUS
 
 
Values
   There are several values that can be assigned to the run status
logical name.  Below are the currently supported values:

      Continue - This is the normal value of the Zap run status logical
                 name.  This value is set by Zap.

      Exit     - Setting this value will cause Zap to exit at the end of
                 the next system scan that it performs.

      Start    - Setting this value will cause Zap to reinitialize itself
                 by flushing all processes status records and reading the
                 Zap initialization file.  This value should always be
                 set when Zap is first started.
 Start_up
   Two command files are provided to start up Zap.  The first is the
Zap system startup command procedure (SYS$MANAGER:ZAPSTART.COM) which
is referenced in the system startup command procedure when the system
boots (SYS$MANAGER:SYSTARTUP.COM).  This command procedure is used to
start Zap each time the system reloads.

   The second command procedure, which is referenced by the Zap system
startup command procedure, is the Zap startup command procedure
(ZAP$DIR:ZAP.COM).  This procedure is used to start Zap at any time by
a privileged user (requires SETPRV and DETACH).

   Although both of the command procedures may be modified to suit your
particular sites applications, it is recommended that the Zap startup
command procedure (ZAP$DIR:ZAP.COM) not be modified except for process
parameters.  The modification of the code which sets up the logical
names should not be changed.