(Guide to Installing and Using WATCHER) <ABSTRACT>(June, 1994) This manual describes the installation, configuration, and operation of WATCHER, an idle terminal monitor for VMS systems. <ENDABSTRACT> <REVISION_INFO>(This is a revised manual.) <REVISION_INFO>(Operating System and Version:\VAX/VMS V5.0 or later, OpenVMS AXP V1.0 or later) <REVISION_INFO>(Software Version:\WATCHER V2.9) <ENDTITLE_PAGE>(Matthew D. Madison<LINE>MadGoat Software) <COPYRIGHT_PAGE> <PRINT_DATE>(24 June 1994) Permission is granted to copy and redistribute this document for no commercial gain. The information in this document is subject to change without notice and should not be construed as a commitment by the author. The author assumes no responsibility for any errors that may appear in this document. <emphasis>(DISCLAIMER:\bold) The author, the author's employer, and MadGoat Software make no representations or warranties with respect to the contents hereof and specifically disclaim any implied warranties of merchantability or fitness for any particular purpose. The following are trademarks of Digital Equipment Corporation: <COPYRIGHT_DATE>(1993, 1994\MadGoat Software. All rights reserved.) <ENDCOPYRIGHT_PAGE> <CONTENTS_FILE> <preface>(\WATCHER_DOC_2) One of the first programs a new VMS system manager usually needs is an <quote>(idle terminal monitor) (ITM). That is, a program to monitor terminal activity and logout those users whose terminals remain inactive for an extended period of time. An ITM helps ensure that system resources are not wasted and helps reduce the possibility of intruders using unattended terminals as a means of entry into the system. Unfortunately, an ITM can also be an annoyance to system users. A simple ITM can victimize legitimate users who may need to remain logged in but idle while they are at work. This can lead to clever users devising <quote>(hacks) to evade the ITM, defeating the purpose of using the ITM in the first place. WATCHER has a high degree of flexibility, allowing system managers to decide how to accommodate users' needs while still addressing operational and security issues. WATCHER is fully configurable, providing the following features: <list>(unnumbered) <le>You can tell WATCHER which terminals to watch, and on a per-terminal basis, what measurements (CPU use, process I/O count, terminal I/O count) to use as criteria for determining idleness, and how long a terminal should be idle before the user should be forced off. <le>Users can be excluded from interference by WATCHER based on any combination of username, UIC, a held identifier, privileges, terminal device and/or port name, time-of-day/day-of-week, and name of image being run. <le>You can override or modify the watch criteria and/or idle times for any user based on any combination of username, UIC, a held identifier, privileges, terminal device and/or port name, time-of-day/day-of-week, and name of image being run. <endlist> Through the use of these features, the system manager should be able to configure WATCHER to handle most types of terminals and accommodate most users. <head1>(Intended Audience\WATCHER_DOC_3) This manual is intended for the system manager or other person responsible for installing and configuring WATCHER. <head1>(Document Structure\WATCHER_DOC_4) This document consists of two parts. The first describes the installation and use of WATCHER. The second describes all of the WATCHER Control Program (WCP) commands in detail. <head1>(Support for WATCHER\WATCHER_DOC_5) There is no formal support for WATCHER. If you have Internet connectivity, however, you may wish to subscribe to one or more of the following MadGoat Software mailing lists: <list>(simple) <le><emphasis>(Info-MadGoat@wkuvx1.wku.edu\bold) Discussion of MadGoat Software products by users and MadGoat developers. To subscribe, send a message to <emphasis>(Info-MadGoat-Request@wkuvx1.wku.edu) with the word SUBSCRIBE in the first line of the body of the message. <le><emphasis>(MadGoat-Announce@wkuvx1.wku.edu\bold) Announcements of new releases and new products from MadGoat. To subscribe, send a message to <emphasis>(MadGoat-Announce-Request@wkuvx1.wku.edu) with the word SUBSCRIBE in the first line of the body of the message. <le><emphasis>(MadGoat-Bugs@wkuvx1.wku.edu\bold) Address for reporting bugs in MadGoat Software products. Please include the name of the package and version in the subject header of the message, so the report can be more easily directed to the appropriate developer. <endlist> If you cannot send electronic mail, you can contact the author by post, facsimile, or telephone at: <table> <table_setup>(2\10) <table_row>(\Matthew Madison) <table_row>(\TGV, Incorporated) <table_row>(\101 Cooper Street) <table_row>(\Santa Cruz, CA 95060 USA) <table_row>(\) <table_row>(Fax:\+1 408 457 5208) <table_row>(Phone:\+1 408 457 5390) <endtable> <ENDPREFACE> <ENDFRONT_MATTER> <PART> <CHAPTER>(Installing WATCHER\WATCHER_DOC_6) To use WATCHER, you need the following files: <table> <table_setup>(2\25) <table_row>(WATCHER.EXE\The main WATCHER image) <table_row>(WCP.EXE\The WATCHER Control Program) <table_row>(WCP_HELPLIB.HLB\Help library for WCP) <table_row>(DECW_STARTLOGIN.COM\Part of DECwindows support) <table_row>(WATCHER_CONFIG.WCFG\You create this file with WCP) <table_row>(WATCHER_STARTUP.COM\Sample startup command procedure) <table_row>(WATCHER_SHUTDOWN.COM\Sample shutdown command procedure) <table_row>(SAMPLE_CONFIG.WCP\Sample configuration commands) <endtable> The package comes with the object code files and libraries and a command procedure called LINK.COM, for creating the two images. It is easiest to simply place all of the files in the distribution in one directory, run LINK.COM to create the images, then edit WATCHER_STARTUP.COM and the sample configuration commands in SAMPLE_CONFIG.WCP as needed for your system. Then all you need to do is to run WCP, execute the WCP command file you created from the sample, which in turn creates a WATCHER_CONFIG.WCFG file, then execute WATCHER_STARTUP.COM to start the Watcher process. <head1>(Required Logical Names\WATCHER_DOC_7) The three system-wide logical names WATCHER requires are: <table> <table_setup>(2\25) <table_row>(WATCHER_DIR\Should point to location of images and command procedures) <table_row>(WATCHER_CONFIG\Configuration file to be used) <table_row>(WATCHER_TRACE\Trace file; use NL: if debug disabled) <endtable> They should all be defined in executive mode. <head2>(Logical Name for Help Library\WATCHER_DOC_8) The help library for WCP may be placed in SYS$HELP, or, if you define the logical name WCP_HELPLIB to be the full path name of the file, anywhere else on the system. The sample WATCHER_STARTUP.COM includes the necessary DEFINE command to do this for you. <head1>(Privileges Required\WATCHER_DOC_9) The account that is used for the WATCHER process requires the following privileges: <table> <table_setup>(2\15) <table_row>(CMKRNL\Required for DECwindows support and disconnects) <table_row>(PRMMBX\For defining the command mailbox) <table_row>(PSWAPM\Required for disconnects) <table_row>(SHARE\For sending warning messages to other users' terminals) <table_row>(SYSNAM\For defining the command mailbox) <table_row>(SYSPRV\(optional) to ensure access to appropriate files) <table_row>(WORLD\For getting information about and killing processes) <endtable> SYSPRV is not needed if you make sure that WATCHER has enough access to read its configuration files and the system rightslist (if using identifiers as an exclusion criterion on pre-VMS V5.4 systems), and write its log and trace files (if used). Both CMKRNL and SYSPRV are required for DECwindows support. CMKRNL and PSWAPM are required to perform virtual terminal disconnections. <head1>(Other Requirements\WATCHER_DOC_10) The RUN command in WATCHER_STARTUP.COM should provide the WATCHER process with sufficient quotas to operate on most systems. CPU and memory requirements will vary depending on the number of rules in the WATCHER configuration, peak number of interactive users, and peak number of watched users. You may wish to refer to the following table in computing expected memory resources needed by the WATCHER process: <table> <table_setup>(2\40) <table_row>(Memory required per WATCH rule\206 bytes) <table_row>(Memory required per EXCLUDE or OVERRIDE rule\507 bytes) <table_row>(Memory required per interactive process\465 bytes) <table_row>(Memory required per watched process\531 bytes) <table_row>(Size of WATCHER code (approximate)\18K bytes) <endtable> On pre-VMS V5.4 systems, allow a small increase in CPU, memory, and I/O requirements if identifiers are used as an exclusion mechanism, since WATCHER will require access to the rightslist database for each interactive process. DECwindows support also requires additional overhead for access to the job logical name tables of all interactive and detached processes on the system. <chapter>(Configuring WATCHER\WATCHER_DOC_11) The WATCHER Control Program (WCP) is used to create WATCHER configurations. WCP is designed to be executed as a VMS foreign command. To set up the foreign command, define the symbol <interactive> <s>($ )(WCP :== $WATCHER_DIR:WCP) <endinteractive> Once the symbol is set up, you can invoke WCP with the command: <interactive> <s>($ )(WCP) <endinteractive> WCP will automatically load the contents of your defined WATCHER_CONFIG file, if it exists. <head1>(Setting up WATCH Rules\WATCHER_DOC_12) The WATCH command sets up rules that determine which terminals get watched, how to determine whether the terminals are active, and how long terminals must be inactive before a user can be forced off. For example: <interactive> <s>(WCP> )(WATCH *$RT*/MEASURE=PROCESS_IO/LOGOUT=00:15:00) <endinteractive> This command sets up a rule for watching all DECnet remote logins, using changes in total process I/O (buffered plus direct) to determine process activity, and causing logouts to occur after 15 minutes of inactivity. <note>You must have at least one WATCH command in your configuration. <endnote> <head2>(Identifying Terminals\WATCHER_DOC_13) WATCH commands take any wildcard pattern. All terminal device names that match the specified pattern are watched. The device names used by WATCHER are the physical device names of terminals; if the system is part of a VAXcluster, SCS node name is prefixed to the device name, as is normally done by VMS with cluster-accessible devices. If the terminal device driver supports remote port identification, as does the LTDRIVER for LAT terminals, the remote port information can also be used as a match criterion by using the /ACCPORNAM qualifier. The port name can be specified as a wildcard pattern. For example: <interactive> <s>(WCP> )(WATCH *$LT*/ACCPORNAM="TRMSRV/*") <endinteractive> This command would cause the terminals attached to terminal server TRMSRV to be watched. <head2>(WATCH Criteria\WATCHER_DOC_14) WATCHER gives you the choice of using one or more of the following measurements as criteria for judging whether a terminal or user is active: <table> <table_setup>(2\20) <table_row>(TERMINAL_IO\the I/O operation count on the terminal device) <table_row>(CPU\The total CPU time used by the process owning the terminal plus all of its subprocesses, in centiseconds) <table_row>(PROCESS_IO\the sum of the buffered and direct I/O counts of the process owning the terminal plus all of its subprocesses) <endtable> The TERMINAL_IO measurement is useful for conventional terminals but cannot be used for workstations (running either VWS or DECwindows) due to the nature of workstation activity. PROCESS_IO is recommended for use on workstation terminal devices. For any of these measurements you can specify a minimum threshold value. When WATCHER performs a comparison, the difference between the current measured value and the last measured value must be greater than the specified threshold to be counted as activity. The default threshold value is zero, so that any difference at all counts as activity. Several samples of WATCH commands with different criteria and threshold values are provided in SAMPLE_CONFIG.WCP. <head2>(Terminal Groupings\WATCHER_DOC_15) You can group WATCH rules together by using the /GROUP qualifier. When WATCHER applies its rules for determining terminal activity, activity on one terminal in the group counts as activity for all the terminals in the group. The main use for this feature is with multi-windowed terminals and workstations running VWS (DECwindows workstations are handled in this manner automatically). For example, the following rules handle all the workstation terminal types on a standalone VWS workstation: <interactive> <s>(WCP> )(WATCH WTA*/GROUP=VWS ! normal VT200-series windows) <s>(WCP> )(WATCH TKA*/GROUP=VWS ! Tek 4010 emulation windows) <s>(WCP> )(WATCH TJA*/GROUP=VWS ! Tek 4125 emulation windows) <endinteractive> The user can then create any number of any type of terminal window, and as long as one of them is active, they will all remain logged in. <head1>(Exclusions and Overrides\WATCHER_DOC_16) WATCHER's behaviour towards a terminal or user can be modified through the definition of exclusion and override rules. Exclusions and overrides can be based on any combination of username, terminal/port name, UIC, image being run, privileges, a held identifier, and time of day. Exclusion rules prevent WATCHER from taking any action towards a user, while override rules merely modify how the terminal is watched (i.e., the activity criteria and inactivity periods). For example (taken from a VAXcluster system): <interactive> <s>(WCP> )(EXCLUDE SYSTEM/TERMINAL=*$OPA0:) <S>(WCP> )(OVERRIDE JONES/TERMINAL=NODE1$TXA3:/DURING=(PRIMARY:8-16)-) <S>(_WCP> )( /LOGOUT=02:00:00) <ENDINTERACTIVE> The first command prevents WATCHER from taking any action against the SYSTEM account while it is logged into the system console. The second command extends the logout inactivity period to two hours for user JONES weekdays from 8 am to 4:59 pm, while JONES is logged into the terminal in her office, which is on port TXA3 on system NODE1. <head1>(Saving Configurations\WATCHER_DOC_17) Once you have established the rules you need for your configuration, you should create the configuration file with the SAVE command: <interactive> <s>(WCP> )(SAVE WATCHER_CONFIG) <endinteractive> If WATCHER is currently running, you can have the new configuration take effect immediately with the RESET command, which will cause the WATCHER process to reload its configuration information from the file. <head2>(VAXcluster Environments\WATCHER_DOC_18) For mainly homogeneous VAXcluster environments, you should be able to use one configuration file for all nodes in the cluster. If you have a mix of nodes, however, it may be easier to create multiple configuration files and define the WATCHER_CONFIG logical name differently depending on the system. <head2>(Editing Configurations\WATCHER_DOC_19) The WATCH, EXCLUDE, and OVERRIDE commands all have a /DELETE to allow you to remove rules from the database, and you can add rules as well. However, you cannot control the order of the new rules (order is important because WATCHER searches the rule lists in the order you enter them until one matches). To assist in making complex changes to the configuration, the SHOW command has a /COMMAND qualifier that causes the configuration information to be displayed as commands you would enter to build the configuration: <interactive> <s>(WCP> )(SHOW/COMMAND/OUTPUT=CONFIG.WCP ALL) <ENDINTERACTIVE> Once you dump the commands to the command file, you can edit the command file as needed and create a new configuration with the commands: <interactive> <s>($ )(WCP/NOFILE) <S>(WCP> )(@CONFIG) <s>(WCP> )(SAVE WATCHER_CONFIG) <endinteractive> Instead of editing the configuration, it may be easier just to maintain a WCP command file with the necessary commands in it and build a new configuration each time you need to make a change. <head1>(DECwindows Support\dwses) The VMS DECwindows implementation makes it difficult for a WATCHER-type program to properly identify, warn, and logout DECwindows sessions. However, WATCHER does provide limited support for watching DECwindows sessions, enabled with the following commands: <interactive> <s>(WCP> )(SET DECWINDOWS) <S>(WCP> )(WATCH *WSA*/MEASURE=PROCESS_IO/NOWARNING) <ENDINTERACTIVE> Note that you cannot use TERMINAL_IO as a measurement when watching DECwindows sessions, nor can WATCHER give warnings to idle DECwindows sessions. WATCHER identifies DECwindows sessions by searching the job logical name table for each interactive process for the logical name DECW$DISPLAY, defined in executive mode. Each interactive job related to a single DECwindows session will have the same value for DECW$DISPLAY. WATCHER immediately changes the terminal device name it uses to the WSA device name (even for DECterm sessions) and also sets the group name to the WSA device name. In this way, activity in any of the DECwindows jobs will be counted as activity for all jobs related to that session. The DECwindows window manager and DECterm controller processes are detached processes that are also needed by WATCHER (when forcing off a DECwindows session). To identify these processes, WATCHER searches for detached processes with DECW$DISPLAY defined in user mode. WATCHER tracks these processes, but does not use them in activity determination (it calls them <quote>(fake) processes in debug/trace logs). When WATCHER identifies a DECwindows session to be forced off, it looks for all processes (including the detached processes, which are important) with a matching WSA device name and forces them off. This should destroy all the windows on the workstation and return it to a blank, background screen. It then creates a detached process that executes the DECW_STARTLOGIN command procedure (which must be located in WATCHER_DIR:), which, after waiting a few seconds for other activity to die down, restarts the login process on the affected WSA device. WATCHER cannot be used to watch DECwindows jobs that are started on remote systems, with the local workstation being used only as a display. There must be at least some jobs running on the workstation with some activity to prevent WATCHER from logging out the DECwindows session. This technique should be effective for VMS DECwindows V2 (VMS V5.1 through V5.5) and V3 (also known as DECwindows/Motif V1.0), and should even work with X terminals. It may not work with future DECwindows implementations. <Chapter>(Troubleshooting WATCHER\WATCHER_DOC_20) If WATCHER is not behaving as expected, there may be a problem with your WATCHER configuration. There is debug/trace code built into WATCHER to allow you to monitor five categories of activities: the mainline WATCHER code, the exclusion-checking code, the override-checking code, measurement checks, and process information collection. Through the use of the SET DEBUG command, you can turn on tracing for any or all of these debugging categories. If WATCHER is already running, the best way to set up a test configuration is with the following command sequence: <interactive> <S>($ )(SET PROCESS/PRIVILEGE=(SYSNAM,SYSPRV)) <s>($ )(WCP) <S>(WCP> )(SET DEBUG=n) <S>(WCP> )(SET NOACTION) <S>(WCP> )(SAVE WATCHER_DIR:TEST_CONFIG) <S>(WCP> )(EXIT) <S>($ )(DEFINE/SYSTEM/EXEC WATCHER_CONFIG WATCHER_DIR:TEST_CONFIG) <S>($ )(DEFINE/SYSTEM/EXEC WATCHER_TRACE trace-file-spec) <S>($ )(WCP RESET) <endinteractive> The debug level <emphasis>(n) is described in the SET DEBUG command description, but usually will be 1 (just mainline) or 31 (full). You can direct the trace information to any file accessible to WATCHER, or to an unowned terminal. The SET NOACTION command will prevent WATCHER from actually logging anyone out or sending warning messages to terminals. Subsequent WCP RESET commands will cause the trace file to be closed and a new version created, so you can easily view past trace information. To go back to <quote>(production) mode, just redefine WATCHER_CONFIG back to the name of the real configuration file, define WATCHER_TRACE to be NL:, and issue another WCP RESET command. <head1>(Forcing Wakeups\WATCHER_DOC_21) To assist in debugging, you may want to have WATCHER wake up more often than normal. You can do this by setting a shorter wakeup interval in the test configuration, or you can force a wakeup to occur by writing to the WATCHER control mailbox. From a suitably privileged account (SYSPRV), you can use the commands: <interactive> <s>($ )(OPEN/WRITE WMBOX WATCHER_MBOX:) <S>($ )(WRITE WMBOX "") <S>($ )(CLOSE WMBOX) <ENDINTERACTIVE> Each WRITE command will trigger a wakeup, and WATCHER will go through its processing sequence. <part> <part_page> <title>(Part II\Command Descriptions) <endpart_page>(RENUMBER) <COMMAND_SECTION>(Command Descriptions\CMD) <SET_TEMPLATE_COMMAND>(COMMAND\DOUBLERUNNINGHEADS) <COMMAND>(WCP\\WATCHER_DOC_22) <x>(WATCHER Control Program) <OVERVIEW> Executes the WATCHER Control Program. <ENDOVERVIEW> <FORMAT> <FCMD>(WCP) <FPARMS>([command]) <QUAL_LIST> <QPAIR>(/FILE=file-spec\See description.) <ENDQUAL_LIST> <ENDFORMAT> <PARAMDEFLIST> <PARAMITEM>([command]) <PARAMDEF> Any WCP command except the input redirection operator (@). The specified command is executed and control is returned to DCL immediately thereafter. <ENDPARAMDEFLIST> <DESCRIPTION> WCP is intended to be used as a DCL <quote>(foreign) command. To use it as a foreign command, you must define a symbol as follows: <interactive> <s>($ )(WCP :== $WATCHER_EXE:WCP) <endinteractive> Defining the symbol in this way allows you to use the /FILE qualifier and specify <quote>(one-shot) commands on the command line. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/[NO]FILE=file-spec) <QUALDEF> Loads the specified WATCHER configuration file for editing. If not specified, the configuration file pointed to by the logical name WATCHER_CONFIG is loaded. The default file type is WCFG. If /NOFILE is specified, no configuration file is loaded. <ENDQUALDEFLIST> <COMMAND>(@ (Redirect Command Input)\\WATCHER_DOC_23) <x>(WCP commands<xs>@) <OVERVIEW> Executes WCP commands read from a file. <ENDOVERVIEW> <FORMAT> <FCMD>(@) <FPARMS>(file-spec) <ENDFORMAT> <PARAMDEFLIST> <PARAMITEM>(file-spec) <PARAMDEF> Name of the file containing WCP commands. If omitted, the default file type is WCP. <ENDPARAMDEFLIST> <DESCRIPTION> Use this command to have WCP take further command input from the specified file. There is no built-in limit on the number of levels of nesting of command files, so be careful when using input redirection from within a command file. Commands read from command files are not displayed unless you SET VERIFY. Command redirection can only be used at the WCP command prompt, not as a <quote>(one-shot) WCP command. To have a file be used for input for an entire WCP session, use the following sequence of DCL commands. <interactive> <s>($ )(DEFINE/USER SYS$INPUT file-spec) <s>($ )(WCP) <endinteractive> <ENDDESCRIPTION> <COMMAND>(EXCLUDE\\WATCHER_DOC_24) <OVERVIEW> Defines an exclusion rule. <ENDOVERVIEW> <FORMAT> <FCMD>(EXCLUDE) <FPARMS>(username-pat) <ENDFORMAT> <QUAL_LIST> <QPAIR>(/ACCPORNAM=port-pat\/ACCPORNAM=*) <QPAIR>(/DELETE\) <QPAIR>(/DURING=daytim-list\(all the time)) <QPAIR>(/HOLDING=identifier\(ignored)) <QPAIR>(/IMAGE=fspec-pat\/IMAGE=*) <QPAIR>(/PRIVILEGES=priv-list\(ignored)) <QPAIR>(/TERMINAL=dev-pat\/TERMINAL=*) <QPAIR>(/UIC=uic\/UIC=[*,*]) <ENDQUAL_LIST> <PARAMDEFLIST> <PARAMITEM>(username-pat) <PARAMDEF> A VMS username or pattern containing wildcards, identifying the user to be excluded. <ENDPARAMDEFLIST> <DESCRIPTION> This command is used to add or remove (with /DELETE) an exclusion rule to the WATCHER configuration. When WATCHER is running, any process that matches all of the specified criteria is not watched. Omitted criteria are not used or always match. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/ACCPORNAM=port-pat) <QUALDEF> Port name or pattern containing wildcards, identifying the terminal port (for terminal servers and other devices using port names) on which the user must be logged in to be excluded. The default is any port. <QUALITEM>(/DELETE) <QUALDEF> Specifies that the rule should be deleted from the configuration. All criteria must match exactly for the rule to be deleted. <QUALITEM>(/DURING=daytim-list) <QUALDEF> Specifies a list of days and times during which the user is to be excluded from watching. The day/time specifications are of the form <syntax> day:(hour-range[,...]) <endsyntax> where <emphasis>(day) is a day of the week or the word PRIMARY or SECONDARY, identifying the primary and secondary days set with SET DAYS, and <emphasis>(hour-range) is either a single hour number (0 through 23) or two hour numbers separated by a hyphen. Multiple hour ranges may be specified per day. <QUALITEM>(/HOLDING=identifier) <QUALDEF> Specifies that the user should be excluded if holding the specified identifier. The identifier is converted to binary format before being stored in the configuration, so you must create the configuration file on the target system, or on a node with the same RIGHTSLIST database as the target system, to prevent misinterpretation of the identifier. If you are running VMS V5.4 or later, WATCHER obtains the identifiers held by the process directly (using $GETJPI), and thus can check identifiers that are granted dynamically. Prior to V5.4, WATCHER uses the $FIND_HELD system service to scan the system rightslist for identifiers held by the user that owns each process; dynamically granted identifiers cannot be checked in this case. Note that if you do not use /HOLDING on any EXCLUDE or OVERRIDE command, the rights identifier information is not collected by WATCHER, resulting in some savings in processing time (especially on pre-V5.4 systems). <QUALITEM>(/IMAGE=fspec-pat) <QUALDEF> Specifies that the user should be excluded if running an executable image whose name (as returned by the JPI$_IMAGNAME item from $GETJPI) matches the specified wildcard pattern. For a job with subprocesses, the image name that WATCHER uses for matching against the wildcard pattern is the image currently being run by the master process in the job, or, if the master process is not running an image, an image being run by one of the subprocesses (randomly selected if there are two or more such subuprocesses). <QUALITEM>(/PRIVILEGES=priv-list) <QUALDEF> Specifies that the user is to be excluded only when holding the specified privilege or privileges. If omitted, privileges are not used as a criterion. <QUALITEM>(/TERMINAL=dev-pat) <QUALDEF> Specifies a terminal device name or pattern containing wildcards. The user must be logged into a matching terminal to be excluded. <QUALITEM>(/UIC=uic) <QUALDEF> Specifies a UIC or UIC pattern. A process is excluded only when owned by a matching UIC. You may use an asterisk for the member part of the UIC to have all UIC's in a group match. If omitted, any UIC will match. <ENDQUALDEFLIST> <COMMAND>(EXIT\\WATCHER_DOC_25) <OVERVIEW> Ends a WCP session. <ENDOVERVIEW> <FORMAT> <FCMD>(EXIT) <FPARMS>() <ENDFORMAT> <DESCRIPTION> Ends the current WCP session and returns control to DCL. If you have modified the configuration, EXIT will ask for a file name for saving the configuration before exiting. <ENDDESCRIPTION> <COMMAND>(HELP\\WATCHER_DOC_26) <OVERVIEW> Displays help information. <ENDOVERVIEW> <FORMAT> <FCMD>(HELP) <FPARMS>([topic...]) <ENDFORMAT> <PARAMDEFLIST> <PARAMITEM>(topic) <PARAMDEF> The name of a topic in the help library. If omitted, a list of topics is displayed. <ENDPARAMDEFLIST> <DESCRIPTION> This command is pretty straightforward. <ENDDESCRIPTION> <COMMAND>(OVERRIDE\\WATCHER_DOC_27) <OVERVIEW> Defines an override rule. <ENDOVERVIEW> <FORMAT> <FCMD>(OVERRIDE) <FPARMS>(username-pat) <ENDFORMAT> <QUAL_LIST> <QPAIR>(/ACCPORNAM=port-pat\/ACCPORNAM=*) <QPAIR>(/DELETE\) <QPAIR>(/DURING=daytim-list\(all the time)) <QPAIR>(/HOLDING=identifier\(ignored)) <QPAIR>(/IMAGE=fspec-pat\/IMAGE=*) <QPAIR>(/PRIVILEGES=priv-list\(ignored)) <QPAIR>(/TERMINAL=dev-pat\/TERMINAL=*) <QPAIR>(/UIC=uic\/UIC=[*,*]) <QPAIR>(/[NO]DISCONNECT[=deltatime]) <QPAIR>(/[NO]FORCE_EXIT[=deltatime]) <QPAIR>(/[NO]LOGOUT[=deltatime]) <QPAIR>(/MEASURE=(measurement[,...])) <QPAIR>(/[NO]WARNING[=deltatime]) <ENDQUAL_LIST> <PARAMDEFLIST> <PARAMITEM>(username-pat) <PARAMDEF> A VMS username or pattern containing wildcards, identifying the user for which the override is to take effect. <ENDPARAMDEFLIST> <DESCRIPTION> This command is used to add or remove (with /DELETE) an override rule to the WATCHER configuration. When WATCHER is running, any process that matches all of the specified criteria will have the warning, logout, and measurement information, if specified, taken from the override rule instead of the WATCH rule. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/ACCPORNAM=port-pat) <QUALDEF> Port name or pattern containing wildcards, identifying the terminal port (for terminal servers and other devices using port names) on which the user must be logged in to have the override apply. The default is any port. <QUALITEM>(/DELETE) <QUALDEF> Specifies that the rule should be deleted from the configuration. All criteria must match exactly for the rule to be deleted. <QUALITEM>(/DURING=daytim-list) <QUALDEF> Specifies a list of days and times during which the override is to apply. The day/time specifications are of the form <syntax> day:(hour-range[,...]) <endsyntax> where <emphasis>(day) is a day of the week or the word PRIMARY or SECONDARY, identifying the primary and secondary days set with SET DAYS, and <emphasis>(hour-range) is either a single hour number (0 through 23) or two hour numbers separated by a hyphen. Multiple hour ranges may be specified per day. <QUALITEM>(/HOLDING=identifier) <QUALDEF> Specifies that the override should apply only if the user is holding the specified identifier. The identifier is converted to binary format before being stored in the configuration, so you must create the configuration file on the target system, or on a node with the same RIGHTSLIST database as the target system, to prevent misinterpretation of the identifier. If you are running VMS V5.4 or later, WATCHER obtains the identifiers held by the process directly (using $GETJPI), and thus can check identifiers that are granted dynamically. Prior to V5.4, WATCHER uses the $FIND_HELD system service to scan the system rightslist for identifiers held by the user that owns each process; dynamically granted identifiers cannot be checked in this case. Note that if you do not use /HOLDING on any EXCLUDE or OVERRIDE command, the rights identifier information is not collected by WATCHER, resulting in some savings in processing time (especially on pre-VMS V5.4 systems). <QUALITEM>(/IMAGE=fspec-pat) <QUALDEF> Specifies that the override should apply only if the user is running an executable image whose name (as returned by the JPI$_IMAGNAME item from $GETJPI) matches the specified wildcard pattern. For a job with subprocesses, the image name that WATCHER uses for matching against the wildcard pattern is the image currently being run by the master process in the job, or, if the master process is not running an image, an image being run by one of the subprocesses (randomly selected if there are two or more such subuprocesses). <QUALITEM>(/PRIVILEGES=priv-list) <QUALDEF> Specifies that the override should apply only when the user is holding the specified privilege or privileges. If omitted, privileges are not used as a criterion. <QUALITEM>(/TERMINAL=dev-pat) <QUALDEF> Specifies a terminal device name or pattern containing wildcards. The user must be logged into a matching terminal to have the override apply. <QUALITEM>(/UIC=uic) <QUALDEF> Specifies a UIC or UIC pattern. The override applies only to processes owned by a matching UIC. You may use an asterisk for the member part of the UIC to have all UIC's in a group match. If omitted, any UIC will match. <QUALITEM>(/[NO]DISCONNECT[=deltatime]) <QUALDEF> Specifies that the logout/disconnect information should be overridden, performing a virtual terminal disconnection instead of deleting the user process. The inactivity interval can be overridden by specifying a <emphasis>(deltatime), or logouts/disconnects can be prevented altogether by specifying /NODISCONNECT (although it is more efficient to use EXCLUDE for this). <QUALITEM>(/[NO]FORCE_EXIT[=deltatime]) <QUALDEF> Specifies that the logout/disconnect information should be overridden, performing a forced image exit instead of deleting the process or disconnecting the terminal. Only user-mode images are forced; if the user is at DCL command level, the forced exit is skipped. The inactivity interval can be overridden by specifying a <emphasis>(deltatime), or exits/logouts/disconnects can be prevented altogether by specifying /NOFORCE_EXIT (although it is more efficient to use EXCLUDE for this). <QUALITEM>(/[NO]LOGOUT[=deltatime]) <QUALDEF> Specifies that the logout/disconnect information should be overridden, performing a process deletion instead of a virtual terminal disconnection. The inactivity interval can be overridden by specifying a <emphasis>(deltatime), or logouts can be prevented by specifying /NOLOGOUT (although it is more efficient to use EXCLUDE for this). <qualitem>(/MEASURE=(measurement[,...])) <qualdef> Specifies that the activity measurements should be overridden. For <emphasis>(measurement), specify one of the following: <table> <table_setup>(2\25) <table_row>(CPU[:<emphasis>(threshold)]\CPU time (the sum of the CPU time used by the process and all its subprocesses, in centiseconds) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in CPU time between passes must exceed the specified threshold for a process to be considered active.) <table_row>(PROCESS_IO[:<emphasis>(threshold)]\Process I/O (the sum of the buffered and direct I/O counts for the process and all its subprocesses) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <table_row>(TERMINAL_IO[:<emphasis>(threshold)]\Terminal I/O (the operation count on the terminal device) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <endtable> Any combination of PROCESS_IO, CPU, and TERMINAL_IO is permitted. If omitted, <emphasis>(threshold) values default to zero. Note that threshold values should be chosen as a function of the wakeup interval (defined with SET INTERVAL). <qualitem>(/[NO]WARNING[=deltatime]) <qualdef> Specifies that the warning information should be overridden. The warning inactivity interval can be overridden by specifying a <emphasis>(deltatime), or warnings can be prevented by specifying /NOWARNING. <ENDQUALDEFLIST> <COMMAND>(QUIT\\WATCHER_DOC_28) <OVERVIEW> Quits WCP without saving configuration changes. <ENDOVERVIEW> <FORMAT> <FCMD>(QUIT) <FPARMS>() <ENDFORMAT> <DESCRIPTION> If changes to the configuration have been made, you are asked for confirmation before quitting. <ENDDESCRIPTION> <COMMAND>(RESET\\WATCHER_DOC_29) <OVERVIEW> Sends a reset command to the WATCHER process. <ENDOVERVIEW> <FORMAT> <FCMD>(RESET) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> This command sends a reset command to the WATCHER process, which causes WATCHER to flush all process and configuration information, close its log and trace files, and read in the configuration again. OPER and SYSPRV privileges are required for this command. <ENDDESCRIPTION> <COMMAND>(SAVE\\WATCHER_DOC_30) <OVERVIEW> Saves a WATCHER configuration. <ENDOVERVIEW> <FORMAT> <FCMD>(SAVE) <FPARMS>([file-spec]) <ENDFORMAT> <PARAMDEFLIST> <PARAMITEM>(file-spec) <PARAMDEF> Name of the file to which the configuration should be written. If omitted, it defaults to the name of the file read in with the WCP/FILE qualifier (if any). If specified, the default file type is WCFG and the default location is the current default directory. <ENDPARAMDEFLIST> <COMMAND>(SET ACTION\\Command_Set_Action) <OVERVIEW> Controls whether WATCHER performs warning and logout actions. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]ACTION) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> To test out a WATCHER installation or configuration change, you may want to SET NOACTION to prevent WATCHER from actually notifying any terminals or logging any users out. The SET NOACTION setting allows you to test your configuration safely, and use the DEBUG and trace facilities to see how WATCHER would have performed. When you are through testing, return the setting back to the default, SET ACTION, to have WATCHER actually perform warnings, disconnections, logouts, etc. <ENDDESCRIPTION> <COMMAND>(SET BELL\\WATCHER_DOC_31) <OVERVIEW> Enables or disables the ringing of the terminal bell on warnings and logouts. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]BELL) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> By default, the terminal bell is not rung when WATCHER displays a warning or logout message on a terminal. SET BELL will cause WATCHER to send a BEL character with the message to cause the terminal bell to ring. <ENDDESCRIPTION> <COMMAND>(SET DAYS\\WATCHER_DOC_32) <OVERVIEW> Establishes the primary and secondary day settings for subsequent commands. <ENDOVERVIEW> <FORMAT> <FCMD>(SET DAYS) <FPARMS>() <ENDFORMAT> <QUAL_LIST> <QPAIR>(/PRIMARY=(day-list)) <QPAIR>(/SECONDARY=(day-list)) <ENDQUAL_LIST> <DESCRIPTION> This command is used to move one or more days from the primary day list to the secondary day list or vice-versa. These lists are used as shorthand by other commands when you specify PRIMARY or SECONDARY on a /DURING qualifier. <ENDDESCRIPTION> <COMMAND>(SET DEBUG\\WATCHER_DOC_33) <OVERVIEW> Enables or disables debug tracing and sets the level of debug information. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]DEBUG[=mask]) <FPARMS>() <ENDFORMAT> <DESCRIPTION> SET DEBUG turns on debug tracing. WATCHER will send debug output to the file or device identified by the WATCHER_TRACE logical name. For <emphasis>(mask), specify a decimal number representing a bitmask indicating which kinds of debugging information you want logged. <table> <table_setup>(3\8\8) <table_heads>(Value\Bit no.\Description) <table_row>(<align_number>(##1)\<align_number>(##0)\main line code) <table_row>(<align_number>(##2)\<align_number>(##1)\exclusion checks) <table_row>(<align_number>(##4)\<align_number>(##2)\override checks) <table_row>(<align_number>(##8)\<align_number>(##3)\measurement checks) <table_row>(<align_number>(#16)\<align_number>(##4)\process info collection) <endtable> The <emphasis>(mask) value can be any one of the above, or a sum of any of the above values. Use SET NODEBUG to disable debug tracing. <ENDDESCRIPTION> <COMMAND>(SET DECWINDOWS\\WATCHER_DOC_34) <OVERVIEW> Enables or disables extra processing required for DECwindows support. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]DECWINDOWS) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> Since the DECwindows support requires additional processing beyond that used for watching normal terminals, it is by default turned off. You should only SET DECWINDOWS when you will be running WATCHER on a DECwindows workstation (or a system with DECwindows terminals). You will also need to include a WATCH rule for WSA terminal devices to watch DECwindows sessions (as described in <reference>(dwses)). <ENDDESCRIPTION> <COMMAND>(SET EVENT_LOG\\WATCHER_DOC_35) <OVERVIEW> Establishes how normal WATCHER events are recorded. <endoverview> <format> <fcmd>(SET [NO]EVENT_LOG) <FPARMS>() <ENDFORMAT> <QUAL_LIST> <QPAIR>(/FILE=file-spec\) <QPAIR>(/OPERATOR=oper-list\) <ENDQUAL_LIST> <DESCRIPTION> This command specifies how normal WATCHER events (startup, shutdown, reset, and logout events) are recorded. By default, WATCHER events are logged to the CENTRAL operator class. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/FILE=file-spec) <QUALDEF>Directs event logging to the specified file. <QUALITEM>(/OPERATOR=oper-list) <QUALDEF>Specifies a list of one or more operator classes to which WATCHER events should be logged. If more than one operator class name is specified, the list should be comma-separated and surrounded by parentheses. <ENDQUALDEFLIST> <COMMAND>(SET INSWAP\\Command_Set_INSWAP) <OVERVIEW> Sets the $GETJPI NOINSWAP control flag used by WATCHER. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]INSWAP) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> Under VAX/VMS V5.2 and later (and all versions of OpenVMS AXP), the $GETJPI system service supports a control flag that prevents it from taking any action that would result in the swapping in of a process that is currently swapped out. SET NOINSWAP enables the use of this control flag in WATCHER, causing WATCHER to ignore any swapped-out processes. The default setting is INSWAP. Using SET NOINSWAP may result in inactive processes not being logged out by WATCHER, or in some cases may result in processes getting logged out prematurely, because activity of swapped-out processes cannot be determined when NOINSWAP is set. <ENDDESCRIPTION> <COMMAND>(SET INTERVAL\\WATCHER_DOC_36) <OVERVIEW> Sets the hibernation interval between processing passes. <ENDOVERVIEW> <FORMAT> <FCMD>(SET INTERVAL=delta-time) <FPARMS>() <ENDFORMAT> <DESCRIPTION> This command sets the length of time WATCHER hibernates between processing passes. The default is 5 minutes. The value you should use should be smaller than the warning and logout intervals for all terminals and smaller than the difference between the logout and warning intervals for any single terminal. Too small a value, however, will cause WATCHER to waste CPU time. <ENDDESCRIPTION> <COMMAND>(SET MULTIWARN\\WATCHER_DOC_37) <OVERVIEW> Enables or disables multiple warnings. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]MULTIWARN) <FPARMS>( ) <QUAL_LIST> <QPAIR>(/INTERVAL=delta-time\/INTERVAL="0 00:05:00") <ENDQUAL_LIST> <ENDFORMAT> <DESCRIPTION> By default, WATCHER displays only one warning on terminals, at the time specified on the /WARNING qualifier. SET MULTIWARN enables multiple warnings; one at the /WARNING time and again every five minutes (or whatever interval you specify) until the /LOGOUT or /DISCONNECT time is reached. This is a system-wide setting. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/INTERVAL=delta-time) <QUALDEF> Specifies the interval of time that should occur between warnings. If omitted, defaults to five minutes. This value should equal or exceed the wakeup interval value (specified by SET INTERVAL). The actual interval between warnings may be longer than the specified time, since checks are made only at each processing pass (the interval between which is controlled by the wakeup interval value). <ENDQUALDEFLIST> <COMMAND>(SET VERIFY\\WATCHER_DOC_38) <OVERVIEW> Enables or disables echoing of commands in command files. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]VERIFY) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> The SET VERIFY command turns on command verification, so that commands read from WCP command files are echoed to the terminal. SET NOVERIFY turns off verification, which is the default. <ENDDESCRIPTION> <COMMAND>(SET WATCH_DEFAULT\\WATCHER_DOC_39) <OVERVIEW> Establishes defaults for subsequent WATCH commands. <ENDOVERVIEW> <FORMAT> <FCMD>(SET WATCH_DEFAULT) <FPARMS>( ) <ENDFORMAT> <QUAL_LIST> <QPAIR>(/[NO]DISCONNECT[=deltatime]) <QPAIR>(/[NO]FORCE_EXIT[=deltatime]) <QPAIR>(/[NO]LOGOUT[=deltatime]\) <QPAIR>(/MEASURE=(measurement[,...])\) <QPAIR>(/[NO]WARNING[=deltatime]\) <ENDQUAL_LIST> <DESCRIPTION> The SET WATCH_DEFAULT command is used to set logout, warning, and measurement defaults for subsequent WATCH commands. The defaults set by this command are saved between WCP sessions. <ENDDESCRIPTION> <qualdeflist> <QUALITEM>(/[NO]DISCONNECT[=deltatime]) <QUALDEF> Sets the default for disconnects, to be used if not specified on subsequent WATCH commands. /DISCONNECT, /FORCE_EXIT, and /LOGOUT are mutually exclusive. <QUALITEM>(/[NO]FORCE_EXIT[=deltatime]) <QUALDEF> Sets the default for forced image exits to be used on subsequent WATCH commands. /DISCONNECT, /FORCE_EXIT, and /LOGOUT are mutually exclusive. <QUALITEM>(/[NO]LOGOUT[=deltatime]) <QUALDEF> Sets the default for logouts, to be used if not specified on subsequent WATCH commands. /DISCONNECT, /FORCE_EXIT, and /LOGOUT are mutually exclusive. <qualitem>(/MEASURE=(measurement[,...])) <qualdef> Sets the default measurements to be used for activity determination if not specified on subsequent WATCH commands. For <emphasis>(measurement), specify one of the following: <table> <table_setup>(2\25) <table_row>(CPU[:<emphasis>(threshold)]\CPU time (the sum of the CPU time used by the process and all its subprocesses, in centiseconds) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in CPU time between passes must exceed the specified threshold for a process to be considered active.) <table_row>(PROCESS_IO[:<emphasis>(threshold)]\Process I/O (the sum of the buffered and direct I/O counts for the process and all its subprocesses) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <table_row>(TERMINAL_IO[:<emphasis>(threshold)]\Terminal I/O (the operation count on the terminal device) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <endtable> Any combination of PROCESS_IO, CPU, and TERMINAL_IO is permitted. If omitted, <emphasis>(threshold) values default to zero. Note that threshold values should be chosen as a function of the wakeup interval (defined with SET INTERVAL). <qualitem>(/[NO]WARNING[=deltatime]) <qualdef> Sets the defaults for warnings, to be used if not specified on subsequent WATCH commands. <ENDQUALDEFLIST> <COMMAND>(SHOW\\WATCHER_DOC_40) <OVERVIEW> Displays all or part of the current configuration. <ENDOVERVIEW> <FORMAT> <FCMD>(SHOW) <FPARMS>(<list>(stacked\braces) <LE>ACTION <LE>ALL <le>BELL <LE>DAYS <LE>DEBUG <LE>DEFAULTS <LE>EVENT_LOG <LE>EXCLUDE <LE>FILE <LE>GLOBALS <LE>INSWAP <LE>INTERVAL <LE>MULTIWARN <LE>OVERRIDE <LE>WATCH <endlist>) <QUAL_LIST> <QPAIR>(/[NO]COMMAND\/NOCOMMAND) <QPAIR>(/OUTPUT=file-spec\/OUTPUT=SYS$OUTPUT:) <ENDQUAL_LIST> <ENDFORMAT> <DESCRIPTION> The SHOW command displays information about the current configuration and the WCP default settings. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/[NO]COMMAND) <QUALDEF> The /COMMAND qualifier indicates that the display should be formatted as the commands that would be entered to create the specified records. Use /COMMAND with the /OUTPUT qualifier to create an MCP command file that can be altered with your favorite editor, then read back into MCP to create a new configuration. <QUALITEM>(/OUTPUT=file-spec) <QUALDEF> The /OUTPUT qualifier is used to direct the SHOW result to a file or other device. By default, the result is displayed on the current output device, SYS$OUTPUT. <ENDQUALDEFLIST> <COMMAND>(SHUTDOWN\\WATCHER_DOC_41) <OVERVIEW> Sends a shutdown command to the WATCHER process. <ENDOVERVIEW> <FORMAT> <FCMD>(SHUTDOWN) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> This command sends a shutdown command to the WATCHER process, which causes WATCHER to close its log files and exit. OPER and SYSPRV privileges are required for this command. <ENDDESCRIPTION> <COMMAND>(WATCH\\WATCHER_DOC_42) <OVERVIEW> Defines a watch rule. <ENDOVERVIEW> <FORMAT> <FCMD>(WATCH) <FPARMS>(device-pat) <ENDFORMAT> <QUAL_LIST> <QPAIR>(/ACCPORNAM=port-pat\/ACCPORNAM=*) <QPAIR>(/DELETE\) <QPAIR>(/[NO]DISCONNECT[=deltatime]) <QPAIR>(/[NO]FORCE_EXIT[=deltatime]) <QPAIR>(/[NO]LOGOUT[=deltatime]) <QPAIR>(/MEASURE=(measurement[,...])) <QPAIR>(/[NO]WARNING[=deltatime]) <ENDQUAL_LIST> <PARAMDEFLIST> <PARAMITEM>(device-pat) <PARAMDEF> A terminal device name or pattern containing wildcards, to identify the terminal(s) to be watched. <ENDPARAMDEFLIST> <DESCRIPTION> This command is used to add or remove (with /DELETE) a watch rule to the WATCHER configuration. When WATCHER is running, a process running on any terminal matching the specified criteria will be watched for inactivity, using the specified parameters. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/ACCPORNAM=port-pat) <QUALDEF> Port name or pattern containing wildcards, identifying the terminal port(s) (for terminal servers and other devices using port names) to be watched. The default is any port. <QUALITEM>(/DELETE) <QUALDEF> Specifies that the rule should be deleted from the configuration. All criteria must match exactly for the rule to be deleted. <QUALITEM>(/[NO]DISCONNECT[=deltatime]) <QUALDEF> For systems with virtual terminals enabled, this qualifier specifies whether the terminal should be disconnected from the system, and if so, how long the terminal should be inactive before the disconnection occurs. If virtual terminals are not enabled, or the terminal to be forced off is not connected through a virtual terminal, the process is logged out (the same effect as for the /LOGOUT qualifier). If both this qualifier and /LOGOUT are omitted, the disconnect/logout default is taken from the current SET WATCH_DEFAULT setting. The /DISCONNECT, /FORCE_EXIT, and /LOGOUT qualifiers are mutually exclusive. <NOTE> The terminal-disconnection code used by WATCHER runs in kernel mode, at elevated IPL, and hence may result in a system crash if the VMS terminal UCB extensions or terminal class driver changes. As with all code that uses undocumented VMS internals, exercise caution when using /DISCONNECT for the first time and when you upgrade to a new version of VMS. The disconnect code is the only part of WATCHER that uses kernel mode. <ENDNOTE> <QUALITEM>(/[NO]FORCE_EXIT[=deltatime]) <QUALDEF> Specifies that any user-mode image currently running at the terminal should be forced to exit, without actually logging the user off. The /DISCONNECT, /FORCE_EXIT, and /LOGOUT qualifiers are mutually exclusive. <QUALITEM>(/[NO]LOGOUT[=deltatime]) <QUALDEF> Specifies whether the terminal should be logged out, and if so, how long the terminal should be inactive before logout occurs. If this qualifier and /DISCONNECT are omitted, the logout/disconnect default is taken from the current SET WATCH_DEFAULT setting. The /DISCONNECT, /FORCE_EXIT, and /LOGOUT qualifiers are mutually exclusive. <qualitem>(/MEASURE=(measurement[,...])) <qualdef> Specifies the measurements that should be used for activity determination. For <emphasis>(measurement), specify one of the following: <table> <table_setup>(2\25) <table_row>(CPU[:<emphasis>(threshold)]\CPU time (the sum of the CPU time used by the process and all its subprocesses, in centiseconds) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in CPU time between passes must exceed the specified threshold for a process to be considered active.) <table_row>(PROCESS_IO[:<emphasis>(threshold)]\Process I/O (the sum of the buffered and direct I/O counts for the process and all its subprocesses) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <table_row>(TERMINAL_IO[:<emphasis>(threshold)]\Terminal I/O (the operation count on the terminal device) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <endtable> Any combination of PROCESS_IO, CPU, and TERMINAL_IO is permitted. If omitted, <emphasis>(threshold) values default to zero. Note that threshold values should be chosen as a function of the wakeup interval (defined with SET INTERVAL). If no /MEASUREMENT qualifier is specified, the measurement settings are taken from the SET WATCH_DEFAULT settings. <qualitem>(/[NO]WARNING[=deltatime]) <qualdef> Specifies whether the terminal should be warned about inactivity, and if so, how long the terminal should be inactive before warning is sent. The warning interval should be less than the logout interval. If omitted, the default is taken from the current SET WATCH_DEFAULT setting. <ENDQUALDEFLIST> <ENDCOMMAND

(WATCHER_DOC_1) (Guide to Installing and Using WATCHER) <ABSTRACT>(June, 1994) This manual describes the installation, configuration, and operation of WATCHER, an idle terminal monitor for VMS systems. <ENDABSTRACT> <REVISION_INFO>(This is a revised manual.) <REVISION_INFO>(Operating System and Version:\VAX/VMS V5.0 or later, OpenVMS AXP V1.0 or later) <REVISION_INFO>(Software Version:\WATCHER V2.9) <ENDTITLE_PAGE>(Matthew D. Madison<LINE>MadGoat Software) <COPYRIGHT_PAGE> <PRINT_DATE>(24 June 1994) Permission is granted to copy and redistribute this document for no commercial gain. The information in this document is subject to change without notice and should not be construed as a commitment by the author. The author assumes no responsibility for any errors that may appear in this document. <emphasis>(DISCLAIMER:\bold) The author, the author's employer, and MadGoat Software make no representations or warranties with respect to the contents hereof and specifically disclaim any implied warranties of merchantability or fitness for any particular purpose. The following are trademarks of Digital Equipment Corporation: <COPYRIGHT_DATE>(1993, 1994\MadGoat Software. All rights reserved.) <ENDCOPYRIGHT_PAGE> <CONTENTS_FILE> <preface>(\WATCHER_DOC_2) One of the first programs a new VMS system manager usually needs is an <quote>(idle terminal monitor) (ITM). That is, a program to monitor terminal activity and logout those users whose terminals remain inactive for an extended period of time. An ITM helps ensure that system resources are not wasted and helps reduce the possibility of intruders using unattended terminals as a means of entry into the system. Unfortunately, an ITM can also be an annoyance to system users. A simple ITM can victimize legitimate users who may need to remain logged in but idle while they are at work. This can lead to clever users devising <quote>(hacks) to evade the ITM, defeating the purpose of using the ITM in the first place. WATCHER has a high degree of flexibility, allowing system managers to decide how to accommodate users' needs while still addressing operational and security issues. WATCHER is fully configurable, providing the following features: <list>(unnumbered) <le>You can tell WATCHER which terminals to watch, and on a per-terminal basis, what measurements (CPU use, process I/O count, terminal I/O count) to use as criteria for determining idleness, and how long a terminal should be idle before the user should be forced off. <le>Users can be excluded from interference by WATCHER based on any combination of username, UIC, a held identifier, privileges, terminal device and/or port name, time-of-day/day-of-week, and name of image being run. <le>You can override or modify the watch criteria and/or idle times for any user based on any combination of username, UIC, a held identifier, privileges, terminal device and/or port name, time-of-day/day-of-week, and name of image being run. <endlist> Through the use of these features, the system manager should be able to configure WATCHER to handle most types of terminals and accommodate most users. <head1>(Intended Audience\WATCHER_DOC_3) This manual is intended for the system manager or other person responsible for installing and configuring WATCHER. <head1>(Document Structure\WATCHER_DOC_4) This document consists of two parts. The first describes the installation and use of WATCHER. The second describes all of the WATCHER Control Program (WCP) commands in detail. <head1>(Support for WATCHER\WATCHER_DOC_5) There is no formal support for WATCHER. If you have Internet connectivity, however, you may wish to subscribe to one or more of the following MadGoat Software mailing lists: <list>(simple) <le><emphasis>(Info-MadGoat@wkuvx1.wku.edu\bold) Discussion of MadGoat Software products by users and MadGoat developers. To subscribe, send a message to <emphasis>(Info-MadGoat-Request@wkuvx1.wku.edu) with the word SUBSCRIBE in the first line of the body of the message. <le><emphasis>(MadGoat-Announce@wkuvx1.wku.edu\bold) Announcements of new releases and new products from MadGoat. To subscribe, send a message to <emphasis>(MadGoat-Announce-Request@wkuvx1.wku.edu) with the word SUBSCRIBE in the first line of the body of the message. <le><emphasis>(MadGoat-Bugs@wkuvx1.wku.edu\bold) Address for reporting bugs in MadGoat Software products. Please include the name of the package and version in the subject header of the message, so the report can be more easily directed to the appropriate developer. <endlist> If you cannot send electronic mail, you can contact the author by post, facsimile, or telephone at: <table> <table_setup>(2\10) <table_row>(\Matthew Madison) <table_row>(\TGV, Incorporated) <table_row>(\101 Cooper Street) <table_row>(\Santa Cruz, CA 95060 USA) <table_row>(\) <table_row>(Fax:\+1 408 457 5208) <table_row>(Phone:\+1 408 457 5390) <endtable> <ENDPREFACE> <ENDFRONT_MATTER> <PART> <CHAPTER>(Installing WATCHER\WATCHER_DOC_6) To use WATCHER, you need the following files: <table> <table_setup>(2\25) <table_row>(WATCHER.EXE\The main WATCHER image) <table_row>(WCP.EXE\The WATCHER Control Program) <table_row>(WCP_HELPLIB.HLB\Help library for WCP) <table_row>(DECW_STARTLOGIN.COM\Part of DECwindows support) <table_row>(WATCHER_CONFIG.WCFG\You create this file with WCP) <table_row>(WATCHER_STARTUP.COM\Sample startup command procedure) <table_row>(WATCHER_SHUTDOWN.COM\Sample shutdown command procedure) <table_row>(SAMPLE_CONFIG.WCP\Sample configuration commands) <endtable> The package comes with the object code files and libraries and a command procedure called LINK.COM, for creating the two images. It is easiest to simply place all of the files in the distribution in one directory, run LINK.COM to create the images, then edit WATCHER_STARTUP.COM and the sample configuration commands in SAMPLE_CONFIG.WCP as needed for your system. Then all you need to do is to run WCP, execute the WCP command file you created from the sample, which in turn creates a WATCHER_CONFIG.WCFG file, then execute WATCHER_STARTUP.COM to start the Watcher process. <head1>(Required Logical Names\WATCHER_DOC_7) The three system-wide logical names WATCHER requires are: <table> <table_setup>(2\25) <table_row>(WATCHER_DIR\Should point to location of images and command procedures) <table_row>(WATCHER_CONFIG\Configuration file to be used) <table_row>(WATCHER_TRACE\Trace file; use NL: if debug disabled) <endtable> They should all be defined in executive mode. <head2>(Logical Name for Help Library\WATCHER_DOC_8) The help library for WCP may be placed in SYS$HELP, or, if you define the logical name WCP_HELPLIB to be the full path name of the file, anywhere else on the system. The sample WATCHER_STARTUP.COM includes the necessary DEFINE command to do this for you. <head1>(Privileges Required\WATCHER_DOC_9) The account that is used for the WATCHER process requires the following privileges: <table> <table_setup>(2\15) <table_row>(CMKRNL\Required for DECwindows support and disconnects) <table_row>(PRMMBX\For defining the command mailbox) <table_row>(PSWAPM\Required for disconnects) <table_row>(SHARE\For sending warning messages to other users' terminals) <table_row>(SYSNAM\For defining the command mailbox) <table_row>(SYSPRV\(optional) to ensure access to appropriate files) <table_row>(WORLD\For getting information about and killing processes) <endtable> SYSPRV is not needed if you make sure that WATCHER has enough access to read its configuration files and the system rightslist (if using identifiers as an exclusion criterion on pre-VMS V5.4 systems), and write its log and trace files (if used). Both CMKRNL and SYSPRV are required for DECwindows support. CMKRNL and PSWAPM are required to perform virtual terminal disconnections. <head1>(Other Requirements\WATCHER_DOC_10) The RUN command in WATCHER_STARTUP.COM should provide the WATCHER process with sufficient quotas to operate on most systems. CPU and memory requirements will vary depending on the number of rules in the WATCHER configuration, peak number of interactive users, and peak number of watched users. You may wish to refer to the following table in computing expected memory resources needed by the WATCHER process: <table> <table_setup>(2\40) <table_row>(Memory required per WATCH rule\206 bytes) <table_row>(Memory required per EXCLUDE or OVERRIDE rule\507 bytes) <table_row>(Memory required per interactive process\465 bytes) <table_row>(Memory required per watched process\531 bytes) <table_row>(Size of WATCHER code (approximate)\18K bytes) <endtable> On pre-VMS V5.4 systems, allow a small increase in CPU, memory, and I/O requirements if identifiers are used as an exclusion mechanism, since WATCHER will require access to the rightslist database for each interactive process. DECwindows support also requires additional overhead for access to the job logical name tables of all interactive and detached processes on the system. <chapter>(Configuring WATCHER\WATCHER_DOC_11) The WATCHER Control Program (WCP) is used to create WATCHER configurations. WCP is designed to be executed as a VMS foreign command. To set up the foreign command, define the symbol <interactive> <s>($ )(WCP :== $WATCHER_DIR:WCP) <endinteractive> Once the symbol is set up, you can invoke WCP with the command: <interactive> <s>($ )(WCP) <endinteractive> WCP will automatically load the contents of your defined WATCHER_CONFIG file, if it exists. <head1>(Setting up WATCH Rules\WATCHER_DOC_12) The WATCH command sets up rules that determine which terminals get watched, how to determine whether the terminals are active, and how long terminals must be inactive before a user can be forced off. For example: <interactive> <s>(WCP> )(WATCH *$RT*/MEASURE=PROCESS_IO/LOGOUT=00:15:00) <endinteractive> This command sets up a rule for watching all DECnet remote logins, using changes in total process I/O (buffered plus direct) to determine process activity, and causing logouts to occur after 15 minutes of inactivity. <note>You must have at least one WATCH command in your configuration. <endnote> <head2>(Identifying Terminals\WATCHER_DOC_13) WATCH commands take any wildcard pattern. All terminal device names that match the specified pattern are watched. The device names used by WATCHER are the physical device names of terminals; if the system is part of a VAXcluster, SCS node name is prefixed to the device name, as is normally done by VMS with cluster-accessible devices. If the terminal device driver supports remote port identification, as does the LTDRIVER for LAT terminals, the remote port information can also be used as a match criterion by using the /ACCPORNAM qualifier. The port name can be specified as a wildcard pattern. For example: <interactive> <s>(WCP> )(WATCH *$LT*/ACCPORNAM="TRMSRV/*") <endinteractive> This command would cause the terminals attached to terminal server TRMSRV to be watched. <head2>(WATCH Criteria\WATCHER_DOC_14) WATCHER gives you the choice of using one or more of the following measurements as criteria for judging whether a terminal or user is active: <table> <table_setup>(2\20) <table_row>(TERMINAL_IO\the I/O operation count on the terminal device) <table_row>(CPU\The total CPU time used by the process owning the terminal plus all of its subprocesses, in centiseconds) <table_row>(PROCESS_IO\the sum of the buffered and direct I/O counts of the process owning the terminal plus all of its subprocesses) <endtable> The TERMINAL_IO measurement is useful for conventional terminals but cannot be used for workstations (running either VWS or DECwindows) due to the nature of workstation activity. PROCESS_IO is recommended for use on workstation terminal devices. For any of these measurements you can specify a minimum threshold value. When WATCHER performs a comparison, the difference between the current measured value and the last measured value must be greater than the specified threshold to be counted as activity. The default threshold value is zero, so that any difference at all counts as activity. Several samples of WATCH commands with different criteria and threshold values are provided in SAMPLE_CONFIG.WCP. <head2>(Terminal Groupings\WATCHER_DOC_15) You can group WATCH rules together by using the /GROUP qualifier. When WATCHER applies its rules for determining terminal activity, activity on one terminal in the group counts as activity for all the terminals in the group. The main use for this feature is with multi-windowed terminals and workstations running VWS (DECwindows workstations are handled in this manner automatically). For example, the following rules handle all the workstation terminal types on a standalone VWS workstation: <interactive> <s>(WCP> )(WATCH WTA*/GROUP=VWS ! normal VT200-series windows) <s>(WCP> )(WATCH TKA*/GROUP=VWS ! Tek 4010 emulation windows) <s>(WCP> )(WATCH TJA*/GROUP=VWS ! Tek 4125 emulation windows) <endinteractive> The user can then create any number of any type of terminal window, and as long as one of them is active, they will all remain logged in. <head1>(Exclusions and Overrides\WATCHER_DOC_16) WATCHER's behaviour towards a terminal or user can be modified through the definition of exclusion and override rules. Exclusions and overrides can be based on any combination of username, terminal/port name, UIC, image being run, privileges, a held identifier, and time of day. Exclusion rules prevent WATCHER from taking any action towards a user, while override rules merely modify how the terminal is watched (i.e., the activity criteria and inactivity periods). For example (taken from a VAXcluster system): <interactive> <s>(WCP> )(EXCLUDE SYSTEM/TERMINAL=*$OPA0:) <S>(WCP> )(OVERRIDE JONES/TERMINAL=NODE1$TXA3:/DURING=(PRIMARY:8-16)-) <S>(_WCP> )( /LOGOUT=02:00:00) <ENDINTERACTIVE> The first command prevents WATCHER from taking any action against the SYSTEM account while it is logged into the system console. The second command extends the logout inactivity period to two hours for user JONES weekdays from 8 am to 4:59 pm, while JONES is logged into the terminal in her office, which is on port TXA3 on system NODE1. <head1>(Saving Configurations\WATCHER_DOC_17) Once you have established the rules you need for your configuration, you should create the configuration file with the SAVE command: <interactive> <s>(WCP> )(SAVE WATCHER_CONFIG) <endinteractive> If WATCHER is currently running, you can have the new configuration take effect immediately with the RESET command, which will cause the WATCHER process to reload its configuration information from the file. <head2>(VAXcluster Environments\WATCHER_DOC_18) For mainly homogeneous VAXcluster environments, you should be able to use one configuration file for all nodes in the cluster. If you have a mix of nodes, however, it may be easier to create multiple configuration files and define the WATCHER_CONFIG logical name differently depending on the system. <head2>(Editing Configurations\WATCHER_DOC_19) The WATCH, EXCLUDE, and OVERRIDE commands all have a /DELETE to allow you to remove rules from the database, and you can add rules as well. However, you cannot control the order of the new rules (order is important because WATCHER searches the rule lists in the order you enter them until one matches). To assist in making complex changes to the configuration, the SHOW command has a /COMMAND qualifier that causes the configuration information to be displayed as commands you would enter to build the configuration: <interactive> <s>(WCP> )(SHOW/COMMAND/OUTPUT=CONFIG.WCP ALL) <ENDINTERACTIVE> Once you dump the commands to the command file, you can edit the command file as needed and create a new configuration with the commands: <interactive> <s>($ )(WCP/NOFILE) <S>(WCP> )(@CONFIG) <s>(WCP> )(SAVE WATCHER_CONFIG) <endinteractive> Instead of editing the configuration, it may be easier just to maintain a WCP command file with the necessary commands in it and build a new configuration each time you need to make a change. <head1>(DECwindows Support\dwses) The VMS DECwindows implementation makes it difficult for a WATCHER-type program to properly identify, warn, and logout DECwindows sessions. However, WATCHER does provide limited support for watching DECwindows sessions, enabled with the following commands: <interactive> <s>(WCP> )(SET DECWINDOWS) <S>(WCP> )(WATCH *WSA*/MEASURE=PROCESS_IO/NOWARNING) <ENDINTERACTIVE> Note that you cannot use TERMINAL_IO as a measurement when watching DECwindows sessions, nor can WATCHER give warnings to idle DECwindows sessions. WATCHER identifies DECwindows sessions by searching the job logical name table for each interactive process for the logical name DECW$DISPLAY, defined in executive mode. Each interactive job related to a single DECwindows session will have the same value for DECW$DISPLAY. WATCHER immediately changes the terminal device name it uses to the WSA device name (even for DECterm sessions) and also sets the group name to the WSA device name. In this way, activity in any of the DECwindows jobs will be counted as activity for all jobs related to that session. The DECwindows window manager and DECterm controller processes are detached processes that are also needed by WATCHER (when forcing off a DECwindows session). To identify these processes, WATCHER searches for detached processes with DECW$DISPLAY defined in user mode. WATCHER tracks these processes, but does not use them in activity determination (it calls them <quote>(fake) processes in debug/trace logs). When WATCHER identifies a DECwindows session to be forced off, it looks for all processes (including the detached processes, which are important) with a matching WSA device name and forces them off. This should destroy all the windows on the workstation and return it to a blank, background screen. It then creates a detached process that executes the DECW_STARTLOGIN command procedure (which must be located in WATCHER_DIR:), which, after waiting a few seconds for other activity to die down, restarts the login process on the affected WSA device. WATCHER cannot be used to watch DECwindows jobs that are started on remote systems, with the local workstation being used only as a display. There must be at least some jobs running on the workstation with some activity to prevent WATCHER from logging out the DECwindows session. This technique should be effective for VMS DECwindows V2 (VMS V5.1 through V5.5) and V3 (also known as DECwindows/Motif V1.0), and should even work with X terminals. It may not work with future DECwindows implementations. <Chapter>(Troubleshooting WATCHER\WATCHER_DOC_20) If WATCHER is not behaving as expected, there may be a problem with your WATCHER configuration. There is debug/trace code built into WATCHER to allow you to monitor five categories of activities: the mainline WATCHER code, the exclusion-checking code, the override-checking code, measurement checks, and process information collection. Through the use of the SET DEBUG command, you can turn on tracing for any or all of these debugging categories. If WATCHER is already running, the best way to set up a test configuration is with the following command sequence: <interactive> <S>($ )(SET PROCESS/PRIVILEGE=(SYSNAM,SYSPRV)) <s>($ )(WCP) <S>(WCP> )(SET DEBUG=n) <S>(WCP> )(SET NOACTION) <S>(WCP> )(SAVE WATCHER_DIR:TEST_CONFIG) <S>(WCP> )(EXIT) <S>($ )(DEFINE/SYSTEM/EXEC WATCHER_CONFIG WATCHER_DIR:TEST_CONFIG) <S>($ )(DEFINE/SYSTEM/EXEC WATCHER_TRACE trace-file-spec) <S>($ )(WCP RESET) <endinteractive> The debug level <emphasis>(n) is described in the SET DEBUG command description, but usually will be 1 (just mainline) or 31 (full). You can direct the trace information to any file accessible to WATCHER, or to an unowned terminal. The SET NOACTION command will prevent WATCHER from actually logging anyone out or sending warning messages to terminals. Subsequent WCP RESET commands will cause the trace file to be closed and a new version created, so you can easily view past trace information. To go back to <quote>(production) mode, just redefine WATCHER_CONFIG back to the name of the real configuration file, define WATCHER_TRACE to be NL:, and issue another WCP RESET command. <head1>(Forcing Wakeups\WATCHER_DOC_21) To assist in debugging, you may want to have WATCHER wake up more often than normal. You can do this by setting a shorter wakeup interval in the test configuration, or you can force a wakeup to occur by writing to the WATCHER control mailbox. From a suitably privileged account (SYSPRV), you can use the commands: <interactive> <s>($ )(OPEN/WRITE WMBOX WATCHER_MBOX:) <S>($ )(WRITE WMBOX "") <S>($ )(CLOSE WMBOX) <ENDINTERACTIVE> Each WRITE command will trigger a wakeup, and WATCHER will go through its processing sequence. <part> <part_page> <title>(Part II\Command Descriptions) <endpart_page>(RENUMBER) <COMMAND_SECTION>(Command Descriptions\CMD) <SET_TEMPLATE_COMMAND>(COMMAND\DOUBLERUNNINGHEADS) <COMMAND>(WCP\\WATCHER_DOC_22) <x>(WATCHER Control Program) <OVERVIEW> Executes the WATCHER Control Program. <ENDOVERVIEW> <FORMAT> <FCMD>(WCP) <FPARMS>([command]) <QUAL_LIST> <QPAIR>(/FILE=file-spec\See description.) <ENDQUAL_LIST> <ENDFORMAT> <PARAMDEFLIST> <PARAMITEM>([command]) <PARAMDEF> Any WCP command except the input redirection operator (@). The specified command is executed and control is returned to DCL immediately thereafter. <ENDPARAMDEFLIST> <DESCRIPTION> WCP is intended to be used as a DCL <quote>(foreign) command. To use it as a foreign command, you must define a symbol as follows: <interactive> <s>($ )(WCP :== $WATCHER_EXE:WCP) <endinteractive> Defining the symbol in this way allows you to use the /FILE qualifier and specify <quote>(one-shot) commands on the command line. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/[NO]FILE=file-spec) <QUALDEF> Loads the specified WATCHER configuration file for editing. If not specified, the configuration file pointed to by the logical name WATCHER_CONFIG is loaded. The default file type is WCFG. If /NOFILE is specified, no configuration file is loaded. <ENDQUALDEFLIST> <COMMAND>(@ (Redirect Command Input)\\WATCHER_DOC_23) <x>(WCP commands<xs>@) <OVERVIEW> Executes WCP commands read from a file. <ENDOVERVIEW> <FORMAT> <FCMD>(@) <FPARMS>(file-spec) <ENDFORMAT> <PARAMDEFLIST> <PARAMITEM>(file-spec) <PARAMDEF> Name of the file containing WCP commands. If omitted, the default file type is WCP. <ENDPARAMDEFLIST> <DESCRIPTION> Use this command to have WCP take further command input from the specified file. There is no built-in limit on the number of levels of nesting of command files, so be careful when using input redirection from within a command file. Commands read from command files are not displayed unless you SET VERIFY. Command redirection can only be used at the WCP command prompt, not as a <quote>(one-shot) WCP command. To have a file be used for input for an entire WCP session, use the following sequence of DCL commands. <interactive> <s>($ )(DEFINE/USER SYS$INPUT file-spec) <s>($ )(WCP) <endinteractive> <ENDDESCRIPTION> <COMMAND>(EXCLUDE\\WATCHER_DOC_24) <OVERVIEW> Defines an exclusion rule. <ENDOVERVIEW> <FORMAT> <FCMD>(EXCLUDE) <FPARMS>(username-pat) <ENDFORMAT> <QUAL_LIST> <QPAIR>(/ACCPORNAM=port-pat\/ACCPORNAM=*) <QPAIR>(/DELETE\) <QPAIR>(/DURING=daytim-list\(all the time)) <QPAIR>(/HOLDING=identifier\(ignored)) <QPAIR>(/IMAGE=fspec-pat\/IMAGE=*) <QPAIR>(/PRIVILEGES=priv-list\(ignored)) <QPAIR>(/TERMINAL=dev-pat\/TERMINAL=*) <QPAIR>(/UIC=uic\/UIC=[*,*]) <ENDQUAL_LIST> <PARAMDEFLIST> <PARAMITEM>(username-pat) <PARAMDEF> A VMS username or pattern containing wildcards, identifying the user to be excluded. <ENDPARAMDEFLIST> <DESCRIPTION> This command is used to add or remove (with /DELETE) an exclusion rule to the WATCHER configuration. When WATCHER is running, any process that matches all of the specified criteria is not watched. Omitted criteria are not used or always match. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/ACCPORNAM=port-pat) <QUALDEF> Port name or pattern containing wildcards, identifying the terminal port (for terminal servers and other devices using port names) on which the user must be logged in to be excluded. The default is any port. <QUALITEM>(/DELETE) <QUALDEF> Specifies that the rule should be deleted from the configuration. All criteria must match exactly for the rule to be deleted. <QUALITEM>(/DURING=daytim-list) <QUALDEF> Specifies a list of days and times during which the user is to be excluded from watching. The day/time specifications are of the form <syntax> day:(hour-range[,...]) <endsyntax> where <emphasis>(day) is a day of the week or the word PRIMARY or SECONDARY, identifying the primary and secondary days set with SET DAYS, and <emphasis>(hour-range) is either a single hour number (0 through 23) or two hour numbers separated by a hyphen. Multiple hour ranges may be specified per day. <QUALITEM>(/HOLDING=identifier) <QUALDEF> Specifies that the user should be excluded if holding the specified identifier. The identifier is converted to binary format before being stored in the configuration, so you must create the configuration file on the target system, or on a node with the same RIGHTSLIST database as the target system, to prevent misinterpretation of the identifier. If you are running VMS V5.4 or later, WATCHER obtains the identifiers held by the process directly (using $GETJPI), and thus can check identifiers that are granted dynamically. Prior to V5.4, WATCHER uses the $FIND_HELD system service to scan the system rightslist for identifiers held by the user that owns each process; dynamically granted identifiers cannot be checked in this case. Note that if you do not use /HOLDING on any EXCLUDE or OVERRIDE command, the rights identifier information is not collected by WATCHER, resulting in some savings in processing time (especially on pre-V5.4 systems). <QUALITEM>(/IMAGE=fspec-pat) <QUALDEF> Specifies that the user should be excluded if running an executable image whose name (as returned by the JPI$_IMAGNAME item from $GETJPI) matches the specified wildcard pattern. For a job with subprocesses, the image name that WATCHER uses for matching against the wildcard pattern is the image currently being run by the master process in the job, or, if the master process is not running an image, an image being run by one of the subprocesses (randomly selected if there are two or more such subuprocesses). <QUALITEM>(/PRIVILEGES=priv-list) <QUALDEF> Specifies that the user is to be excluded only when holding the specified privilege or privileges. If omitted, privileges are not used as a criterion. <QUALITEM>(/TERMINAL=dev-pat) <QUALDEF> Specifies a terminal device name or pattern containing wildcards. The user must be logged into a matching terminal to be excluded. <QUALITEM>(/UIC=uic) <QUALDEF> Specifies a UIC or UIC pattern. A process is excluded only when owned by a matching UIC. You may use an asterisk for the member part of the UIC to have all UIC's in a group match. If omitted, any UIC will match. <ENDQUALDEFLIST> <COMMAND>(EXIT\\WATCHER_DOC_25) <OVERVIEW> Ends a WCP session. <ENDOVERVIEW> <FORMAT> <FCMD>(EXIT) <FPARMS>() <ENDFORMAT> <DESCRIPTION> Ends the current WCP session and returns control to DCL. If you have modified the configuration, EXIT will ask for a file name for saving the configuration before exiting. <ENDDESCRIPTION> <COMMAND>(HELP\\WATCHER_DOC_26) <OVERVIEW> Displays help information. <ENDOVERVIEW> <FORMAT> <FCMD>(HELP) <FPARMS>([topic...]) <ENDFORMAT> <PARAMDEFLIST> <PARAMITEM>(topic) <PARAMDEF> The name of a topic in the help library. If omitted, a list of topics is displayed. <ENDPARAMDEFLIST> <DESCRIPTION> This command is pretty straightforward. <ENDDESCRIPTION> <COMMAND>(OVERRIDE\\WATCHER_DOC_27) <OVERVIEW> Defines an override rule. <ENDOVERVIEW> <FORMAT> <FCMD>(OVERRIDE) <FPARMS>(username-pat) <ENDFORMAT> <QUAL_LIST> <QPAIR>(/ACCPORNAM=port-pat\/ACCPORNAM=*) <QPAIR>(/DELETE\) <QPAIR>(/DURING=daytim-list\(all the time)) <QPAIR>(/HOLDING=identifier\(ignored)) <QPAIR>(/IMAGE=fspec-pat\/IMAGE=*) <QPAIR>(/PRIVILEGES=priv-list\(ignored)) <QPAIR>(/TERMINAL=dev-pat\/TERMINAL=*) <QPAIR>(/UIC=uic\/UIC=[*,*]) <QPAIR>(/[NO]DISCONNECT[=deltatime]) <QPAIR>(/[NO]FORCE_EXIT[=deltatime]) <QPAIR>(/[NO]LOGOUT[=deltatime]) <QPAIR>(/MEASURE=(measurement[,...])) <QPAIR>(/[NO]WARNING[=deltatime]) <ENDQUAL_LIST> <PARAMDEFLIST> <PARAMITEM>(username-pat) <PARAMDEF> A VMS username or pattern containing wildcards, identifying the user for which the override is to take effect. <ENDPARAMDEFLIST> <DESCRIPTION> This command is used to add or remove (with /DELETE) an override rule to the WATCHER configuration. When WATCHER is running, any process that matches all of the specified criteria will have the warning, logout, and measurement information, if specified, taken from the override rule instead of the WATCH rule. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/ACCPORNAM=port-pat) <QUALDEF> Port name or pattern containing wildcards, identifying the terminal port (for terminal servers and other devices using port names) on which the user must be logged in to have the override apply. The default is any port. <QUALITEM>(/DELETE) <QUALDEF> Specifies that the rule should be deleted from the configuration. All criteria must match exactly for the rule to be deleted. <QUALITEM>(/DURING=daytim-list) <QUALDEF> Specifies a list of days and times during which the override is to apply. The day/time specifications are of the form <syntax> day:(hour-range[,...]) <endsyntax> where <emphasis>(day) is a day of the week or the word PRIMARY or SECONDARY, identifying the primary and secondary days set with SET DAYS, and <emphasis>(hour-range) is either a single hour number (0 through 23) or two hour numbers separated by a hyphen. Multiple hour ranges may be specified per day. <QUALITEM>(/HOLDING=identifier) <QUALDEF> Specifies that the override should apply only if the user is holding the specified identifier. The identifier is converted to binary format before being stored in the configuration, so you must create the configuration file on the target system, or on a node with the same RIGHTSLIST database as the target system, to prevent misinterpretation of the identifier. If you are running VMS V5.4 or later, WATCHER obtains the identifiers held by the process directly (using $GETJPI), and thus can check identifiers that are granted dynamically. Prior to V5.4, WATCHER uses the $FIND_HELD system service to scan the system rightslist for identifiers held by the user that owns each process; dynamically granted identifiers cannot be checked in this case. Note that if you do not use /HOLDING on any EXCLUDE or OVERRIDE command, the rights identifier information is not collected by WATCHER, resulting in some savings in processing time (especially on pre-VMS V5.4 systems). <QUALITEM>(/IMAGE=fspec-pat) <QUALDEF> Specifies that the override should apply only if the user is running an executable image whose name (as returned by the JPI$_IMAGNAME item from $GETJPI) matches the specified wildcard pattern. For a job with subprocesses, the image name that WATCHER uses for matching against the wildcard pattern is the image currently being run by the master process in the job, or, if the master process is not running an image, an image being run by one of the subprocesses (randomly selected if there are two or more such subuprocesses). <QUALITEM>(/PRIVILEGES=priv-list) <QUALDEF> Specifies that the override should apply only when the user is holding the specified privilege or privileges. If omitted, privileges are not used as a criterion. <QUALITEM>(/TERMINAL=dev-pat) <QUALDEF> Specifies a terminal device name or pattern containing wildcards. The user must be logged into a matching terminal to have the override apply. <QUALITEM>(/UIC=uic) <QUALDEF> Specifies a UIC or UIC pattern. The override applies only to processes owned by a matching UIC. You may use an asterisk for the member part of the UIC to have all UIC's in a group match. If omitted, any UIC will match. <QUALITEM>(/[NO]DISCONNECT[=deltatime]) <QUALDEF> Specifies that the logout/disconnect information should be overridden, performing a virtual terminal disconnection instead of deleting the user process. The inactivity interval can be overridden by specifying a <emphasis>(deltatime), or logouts/disconnects can be prevented altogether by specifying /NODISCONNECT (although it is more efficient to use EXCLUDE for this). <QUALITEM>(/[NO]FORCE_EXIT[=deltatime]) <QUALDEF> Specifies that the logout/disconnect information should be overridden, performing a forced image exit instead of deleting the process or disconnecting the terminal. Only user-mode images are forced; if the user is at DCL command level, the forced exit is skipped. The inactivity interval can be overridden by specifying a <emphasis>(deltatime), or exits/logouts/disconnects can be prevented altogether by specifying /NOFORCE_EXIT (although it is more efficient to use EXCLUDE for this). <QUALITEM>(/[NO]LOGOUT[=deltatime]) <QUALDEF> Specifies that the logout/disconnect information should be overridden, performing a process deletion instead of a virtual terminal disconnection. The inactivity interval can be overridden by specifying a <emphasis>(deltatime), or logouts can be prevented by specifying /NOLOGOUT (although it is more efficient to use EXCLUDE for this). <qualitem>(/MEASURE=(measurement[,...])) <qualdef> Specifies that the activity measurements should be overridden. For <emphasis>(measurement), specify one of the following: <table> <table_setup>(2\25) <table_row>(CPU[:<emphasis>(threshold)]\CPU time (the sum of the CPU time used by the process and all its subprocesses, in centiseconds) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in CPU time between passes must exceed the specified threshold for a process to be considered active.) <table_row>(PROCESS_IO[:<emphasis>(threshold)]\Process I/O (the sum of the buffered and direct I/O counts for the process and all its subprocesses) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <table_row>(TERMINAL_IO[:<emphasis>(threshold)]\Terminal I/O (the operation count on the terminal device) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <endtable> Any combination of PROCESS_IO, CPU, and TERMINAL_IO is permitted. If omitted, <emphasis>(threshold) values default to zero. Note that threshold values should be chosen as a function of the wakeup interval (defined with SET INTERVAL). <qualitem>(/[NO]WARNING[=deltatime]) <qualdef> Specifies that the warning information should be overridden. The warning inactivity interval can be overridden by specifying a <emphasis>(deltatime), or warnings can be prevented by specifying /NOWARNING. <ENDQUALDEFLIST> <COMMAND>(QUIT\\WATCHER_DOC_28) <OVERVIEW> Quits WCP without saving configuration changes. <ENDOVERVIEW> <FORMAT> <FCMD>(QUIT) <FPARMS>() <ENDFORMAT> <DESCRIPTION> If changes to the configuration have been made, you are asked for confirmation before quitting. <ENDDESCRIPTION> <COMMAND>(RESET\\WATCHER_DOC_29) <OVERVIEW> Sends a reset command to the WATCHER process. <ENDOVERVIEW> <FORMAT> <FCMD>(RESET) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> This command sends a reset command to the WATCHER process, which causes WATCHER to flush all process and configuration information, close its log and trace files, and read in the configuration again. OPER and SYSPRV privileges are required for this command. <ENDDESCRIPTION> <COMMAND>(SAVE\\WATCHER_DOC_30) <OVERVIEW> Saves a WATCHER configuration. <ENDOVERVIEW> <FORMAT> <FCMD>(SAVE) <FPARMS>([file-spec]) <ENDFORMAT> <PARAMDEFLIST> <PARAMITEM>(file-spec) <PARAMDEF> Name of the file to which the configuration should be written. If omitted, it defaults to the name of the file read in with the WCP/FILE qualifier (if any). If specified, the default file type is WCFG and the default location is the current default directory. <ENDPARAMDEFLIST> <COMMAND>(SET ACTION\\Command_Set_Action) <OVERVIEW> Controls whether WATCHER performs warning and logout actions. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]ACTION) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> To test out a WATCHER installation or configuration change, you may want to SET NOACTION to prevent WATCHER from actually notifying any terminals or logging any users out. The SET NOACTION setting allows you to test your configuration safely, and use the DEBUG and trace facilities to see how WATCHER would have performed. When you are through testing, return the setting back to the default, SET ACTION, to have WATCHER actually perform warnings, disconnections, logouts, etc. <ENDDESCRIPTION> <COMMAND>(SET BELL\\WATCHER_DOC_31) <OVERVIEW> Enables or disables the ringing of the terminal bell on warnings and logouts. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]BELL) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> By default, the terminal bell is not rung when WATCHER displays a warning or logout message on a terminal. SET BELL will cause WATCHER to send a BEL character with the message to cause the terminal bell to ring. <ENDDESCRIPTION> <COMMAND>(SET DAYS\\WATCHER_DOC_32) <OVERVIEW> Establishes the primary and secondary day settings for subsequent commands. <ENDOVERVIEW> <FORMAT> <FCMD>(SET DAYS) <FPARMS>() <ENDFORMAT> <QUAL_LIST> <QPAIR>(/PRIMARY=(day-list)) <QPAIR>(/SECONDARY=(day-list)) <ENDQUAL_LIST> <DESCRIPTION> This command is used to move one or more days from the primary day list to the secondary day list or vice-versa. These lists are used as shorthand by other commands when you specify PRIMARY or SECONDARY on a /DURING qualifier. <ENDDESCRIPTION> <COMMAND>(SET DEBUG\\WATCHER_DOC_33) <OVERVIEW> Enables or disables debug tracing and sets the level of debug information. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]DEBUG[=mask]) <FPARMS>() <ENDFORMAT> <DESCRIPTION> SET DEBUG turns on debug tracing. WATCHER will send debug output to the file or device identified by the WATCHER_TRACE logical name. For <emphasis>(mask), specify a decimal number representing a bitmask indicating which kinds of debugging information you want logged. <table> <table_setup>(3\8\8) <table_heads>(Value\Bit no.\Description) <table_row>(<align_number>(##1)\<align_number>(##0)\main line code) <table_row>(<align_number>(##2)\<align_number>(##1)\exclusion checks) <table_row>(<align_number>(##4)\<align_number>(##2)\override checks) <table_row>(<align_number>(##8)\<align_number>(##3)\measurement checks) <table_row>(<align_number>(#16)\<align_number>(##4)\process info collection) <endtable> The <emphasis>(mask) value can be any one of the above, or a sum of any of the above values. Use SET NODEBUG to disable debug tracing. <ENDDESCRIPTION> <COMMAND>(SET DECWINDOWS\\WATCHER_DOC_34) <OVERVIEW> Enables or disables extra processing required for DECwindows support. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]DECWINDOWS) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> Since the DECwindows support requires additional processing beyond that used for watching normal terminals, it is by default turned off. You should only SET DECWINDOWS when you will be running WATCHER on a DECwindows workstation (or a system with DECwindows terminals). You will also need to include a WATCH rule for WSA terminal devices to watch DECwindows sessions (as described in <reference>(dwses)). <ENDDESCRIPTION> <COMMAND>(SET EVENT_LOG\\WATCHER_DOC_35) <OVERVIEW> Establishes how normal WATCHER events are recorded. <endoverview> <format> <fcmd>(SET [NO]EVENT_LOG) <FPARMS>() <ENDFORMAT> <QUAL_LIST> <QPAIR>(/FILE=file-spec\) <QPAIR>(/OPERATOR=oper-list\) <ENDQUAL_LIST> <DESCRIPTION> This command specifies how normal WATCHER events (startup, shutdown, reset, and logout events) are recorded. By default, WATCHER events are logged to the CENTRAL operator class. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/FILE=file-spec) <QUALDEF>Directs event logging to the specified file. <QUALITEM>(/OPERATOR=oper-list) <QUALDEF>Specifies a list of one or more operator classes to which WATCHER events should be logged. If more than one operator class name is specified, the list should be comma-separated and surrounded by parentheses. <ENDQUALDEFLIST> <COMMAND>(SET INSWAP\\Command_Set_INSWAP) <OVERVIEW> Sets the $GETJPI NOINSWAP control flag used by WATCHER. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]INSWAP) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> Under VAX/VMS V5.2 and later (and all versions of OpenVMS AXP), the $GETJPI system service supports a control flag that prevents it from taking any action that would result in the swapping in of a process that is currently swapped out. SET NOINSWAP enables the use of this control flag in WATCHER, causing WATCHER to ignore any swapped-out processes. The default setting is INSWAP. Using SET NOINSWAP may result in inactive processes not being logged out by WATCHER, or in some cases may result in processes getting logged out prematurely, because activity of swapped-out processes cannot be determined when NOINSWAP is set. <ENDDESCRIPTION> <COMMAND>(SET INTERVAL\\WATCHER_DOC_36) <OVERVIEW> Sets the hibernation interval between processing passes. <ENDOVERVIEW> <FORMAT> <FCMD>(SET INTERVAL=delta-time) <FPARMS>() <ENDFORMAT> <DESCRIPTION> This command sets the length of time WATCHER hibernates between processing passes. The default is 5 minutes. The value you should use should be smaller than the warning and logout intervals for all terminals and smaller than the difference between the logout and warning intervals for any single terminal. Too small a value, however, will cause WATCHER to waste CPU time. <ENDDESCRIPTION> <COMMAND>(SET MULTIWARN\\WATCHER_DOC_37) <OVERVIEW> Enables or disables multiple warnings. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]MULTIWARN) <FPARMS>( ) <QUAL_LIST> <QPAIR>(/INTERVAL=delta-time\/INTERVAL="0 00:05:00") <ENDQUAL_LIST> <ENDFORMAT> <DESCRIPTION> By default, WATCHER displays only one warning on terminals, at the time specified on the /WARNING qualifier. SET MULTIWARN enables multiple warnings; one at the /WARNING time and again every five minutes (or whatever interval you specify) until the /LOGOUT or /DISCONNECT time is reached. This is a system-wide setting. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/INTERVAL=delta-time) <QUALDEF> Specifies the interval of time that should occur between warnings. If omitted, defaults to five minutes. This value should equal or exceed the wakeup interval value (specified by SET INTERVAL). The actual interval between warnings may be longer than the specified time, since checks are made only at each processing pass (the interval between which is controlled by the wakeup interval value). <ENDQUALDEFLIST> <COMMAND>(SET VERIFY\\WATCHER_DOC_38) <OVERVIEW> Enables or disables echoing of commands in command files. <ENDOVERVIEW> <FORMAT> <FCMD>(SET [NO]VERIFY) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> The SET VERIFY command turns on command verification, so that commands read from WCP command files are echoed to the terminal. SET NOVERIFY turns off verification, which is the default. <ENDDESCRIPTION> <COMMAND>(SET WATCH_DEFAULT\\WATCHER_DOC_39) <OVERVIEW> Establishes defaults for subsequent WATCH commands. <ENDOVERVIEW> <FORMAT> <FCMD>(SET WATCH_DEFAULT) <FPARMS>( ) <ENDFORMAT> <QUAL_LIST> <QPAIR>(/[NO]DISCONNECT[=deltatime]) <QPAIR>(/[NO]FORCE_EXIT[=deltatime]) <QPAIR>(/[NO]LOGOUT[=deltatime]\) <QPAIR>(/MEASURE=(measurement[,...])\) <QPAIR>(/[NO]WARNING[=deltatime]\) <ENDQUAL_LIST> <DESCRIPTION> The SET WATCH_DEFAULT command is used to set logout, warning, and measurement defaults for subsequent WATCH commands. The defaults set by this command are saved between WCP sessions. <ENDDESCRIPTION> <qualdeflist> <QUALITEM>(/[NO]DISCONNECT[=deltatime]) <QUALDEF> Sets the default for disconnects, to be used if not specified on subsequent WATCH commands. /DISCONNECT, /FORCE_EXIT, and /LOGOUT are mutually exclusive. <QUALITEM>(/[NO]FORCE_EXIT[=deltatime]) <QUALDEF> Sets the default for forced image exits to be used on subsequent WATCH commands. /DISCONNECT, /FORCE_EXIT, and /LOGOUT are mutually exclusive. <QUALITEM>(/[NO]LOGOUT[=deltatime]) <QUALDEF> Sets the default for logouts, to be used if not specified on subsequent WATCH commands. /DISCONNECT, /FORCE_EXIT, and /LOGOUT are mutually exclusive. <qualitem>(/MEASURE=(measurement[,...])) <qualdef> Sets the default measurements to be used for activity determination if not specified on subsequent WATCH commands. For <emphasis>(measurement), specify one of the following: <table> <table_setup>(2\25) <table_row>(CPU[:<emphasis>(threshold)]\CPU time (the sum of the CPU time used by the process and all its subprocesses, in centiseconds) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in CPU time between passes must exceed the specified threshold for a process to be considered active.) <table_row>(PROCESS_IO[:<emphasis>(threshold)]\Process I/O (the sum of the buffered and direct I/O counts for the process and all its subprocesses) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <table_row>(TERMINAL_IO[:<emphasis>(threshold)]\Terminal I/O (the operation count on the terminal device) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <endtable> Any combination of PROCESS_IO, CPU, and TERMINAL_IO is permitted. If omitted, <emphasis>(threshold) values default to zero. Note that threshold values should be chosen as a function of the wakeup interval (defined with SET INTERVAL). <qualitem>(/[NO]WARNING[=deltatime]) <qualdef> Sets the defaults for warnings, to be used if not specified on subsequent WATCH commands. <ENDQUALDEFLIST> <COMMAND>(SHOW\\WATCHER_DOC_40) <OVERVIEW> Displays all or part of the current configuration. <ENDOVERVIEW> <FORMAT> <FCMD>(SHOW) <FPARMS>(<list>(stacked\braces) <LE>ACTION <LE>ALL <le>BELL <LE>DAYS <LE>DEBUG <LE>DEFAULTS <LE>EVENT_LOG <LE>EXCLUDE <LE>FILE <LE>GLOBALS <LE>INSWAP <LE>INTERVAL <LE>MULTIWARN <LE>OVERRIDE <LE>WATCH <endlist>) <QUAL_LIST> <QPAIR>(/[NO]COMMAND\/NOCOMMAND) <QPAIR>(/OUTPUT=file-spec\/OUTPUT=SYS$OUTPUT:) <ENDQUAL_LIST> <ENDFORMAT> <DESCRIPTION> The SHOW command displays information about the current configuration and the WCP default settings. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/[NO]COMMAND) <QUALDEF> The /COMMAND qualifier indicates that the display should be formatted as the commands that would be entered to create the specified records. Use /COMMAND with the /OUTPUT qualifier to create an MCP command file that can be altered with your favorite editor, then read back into MCP to create a new configuration. <QUALITEM>(/OUTPUT=file-spec) <QUALDEF> The /OUTPUT qualifier is used to direct the SHOW result to a file or other device. By default, the result is displayed on the current output device, SYS$OUTPUT. <ENDQUALDEFLIST> <COMMAND>(SHUTDOWN\\WATCHER_DOC_41) <OVERVIEW> Sends a shutdown command to the WATCHER process. <ENDOVERVIEW> <FORMAT> <FCMD>(SHUTDOWN) <FPARMS>( ) <ENDFORMAT> <DESCRIPTION> This command sends a shutdown command to the WATCHER process, which causes WATCHER to close its log files and exit. OPER and SYSPRV privileges are required for this command. <ENDDESCRIPTION> <COMMAND>(WATCH\\WATCHER_DOC_42) <OVERVIEW> Defines a watch rule. <ENDOVERVIEW> <FORMAT> <FCMD>(WATCH) <FPARMS>(device-pat) <ENDFORMAT> <QUAL_LIST> <QPAIR>(/ACCPORNAM=port-pat\/ACCPORNAM=*) <QPAIR>(/DELETE\) <QPAIR>(/[NO]DISCONNECT[=deltatime]) <QPAIR>(/[NO]FORCE_EXIT[=deltatime]) <QPAIR>(/[NO]LOGOUT[=deltatime]) <QPAIR>(/MEASURE=(measurement[,...])) <QPAIR>(/[NO]WARNING[=deltatime]) <ENDQUAL_LIST> <PARAMDEFLIST> <PARAMITEM>(device-pat) <PARAMDEF> A terminal device name or pattern containing wildcards, to identify the terminal(s) to be watched. <ENDPARAMDEFLIST> <DESCRIPTION> This command is used to add or remove (with /DELETE) a watch rule to the WATCHER configuration. When WATCHER is running, a process running on any terminal matching the specified criteria will be watched for inactivity, using the specified parameters. <ENDDESCRIPTION> <QUALDEFLIST> <QUALITEM>(/ACCPORNAM=port-pat) <QUALDEF> Port name or pattern containing wildcards, identifying the terminal port(s) (for terminal servers and other devices using port names) to be watched. The default is any port. <QUALITEM>(/DELETE) <QUALDEF> Specifies that the rule should be deleted from the configuration. All criteria must match exactly for the rule to be deleted. <QUALITEM>(/[NO]DISCONNECT[=deltatime]) <QUALDEF> For systems with virtual terminals enabled, this qualifier specifies whether the terminal should be disconnected from the system, and if so, how long the terminal should be inactive before the disconnection occurs. If virtual terminals are not enabled, or the terminal to be forced off is not connected through a virtual terminal, the process is logged out (the same effect as for the /LOGOUT qualifier). If both this qualifier and /LOGOUT are omitted, the disconnect/logout default is taken from the current SET WATCH_DEFAULT setting. The /DISCONNECT, /FORCE_EXIT, and /LOGOUT qualifiers are mutually exclusive. <NOTE> The terminal-disconnection code used by WATCHER runs in kernel mode, at elevated IPL, and hence may result in a system crash if the VMS terminal UCB extensions or terminal class driver changes. As with all code that uses undocumented VMS internals, exercise caution when using /DISCONNECT for the first time and when you upgrade to a new version of VMS. The disconnect code is the only part of WATCHER that uses kernel mode. <ENDNOTE> <QUALITEM>(/[NO]FORCE_EXIT[=deltatime]) <QUALDEF> Specifies that any user-mode image currently running at the terminal should be forced to exit, without actually logging the user off. The /DISCONNECT, /FORCE_EXIT, and /LOGOUT qualifiers are mutually exclusive. <QUALITEM>(/[NO]LOGOUT[=deltatime]) <QUALDEF> Specifies whether the terminal should be logged out, and if so, how long the terminal should be inactive before logout occurs. If this qualifier and /DISCONNECT are omitted, the logout/disconnect default is taken from the current SET WATCH_DEFAULT setting. The /DISCONNECT, /FORCE_EXIT, and /LOGOUT qualifiers are mutually exclusive. <qualitem>(/MEASURE=(measurement[,...])) <qualdef> Specifies the measurements that should be used for activity determination. For <emphasis>(measurement), specify one of the following: <table> <table_setup>(2\25) <table_row>(CPU[:<emphasis>(threshold)]\CPU time (the sum of the CPU time used by the process and all its subprocesses, in centiseconds) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in CPU time between passes must exceed the specified threshold for a process to be considered active.) <table_row>(PROCESS_IO[:<emphasis>(threshold)]\Process I/O (the sum of the buffered and direct I/O counts for the process and all its subprocesses) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <table_row>(TERMINAL_IO[:<emphasis>(threshold)]\Terminal I/O (the operation count on the terminal device) should be used as a criterion. If <emphasis>(threshold) is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active.) <endtable> Any combination of PROCESS_IO, CPU, and TERMINAL_IO is permitted. If omitted, <emphasis>(threshold) values default to zero. Note that threshold values should be chosen as a function of the wakeup interval (defined with SET INTERVAL). If no /MEASUREMENT qualifier is specified, the measurement settings are taken from the SET WATCH_DEFAULT settings. <qualitem>(/[NO]WARNING[=deltatime]) <qualdef> Specifies whether the terminal should be warned about inactivity, and if so, how long the terminal should be inactive before warning is sent. The warning interval should be less than the logout interval. If omitted, the default is taken from the current SET WATCH_DEFAULT setting. <ENDQUALDEFLIST> <ENDCOMMAND_SECTION>