1 USERS
!
  The USERS utility displays a list of the users currently on the system or
  on any nodes in the VAXcluster containing the system.

  By default, USERS shows interactive and batch users on the current node.
  For each process, it shows the username, pid, process name, mode (Inter-
  active, Batch, Subprocess, or Detached process), and current image.

  By using optional parameters and qualifiers, you can limit or extend the
  list of processes displayed, and specify the type of information shown.
!
2 Parameters
!
  The optional first parameter to USERS is the node or nodes to be inter-
  rogated.  The specified node(s) must be members of the VAXcluster which
  contains the node running USERS.  The default is the current node.  Node
  names may contain wildcards; "*" means "all nodes currently in the VAX-
  cluster".  A list of names may be specified:

        $  USERS  A*,B%%,CNODE
        $  USERS  SPOCK
        $  USERS               ! shows this node's current users

  "0", meaning "the current node"; can be used when specifying an optional
  second parameter, since this requires a non-blank first parameter.


  The optional second parameter is the username or usernames whose proces-
  ses are to be displayed.  By default ALL current users are displayed.
  These names can contain wildcards, and a list of usernames may be used:

        $  USERS  0  SYSTEM       ! show only user SYSTEM on this node
        $  USERS  *  SYSTEM,FIELD ! show SYSTEM and FIELD on all nodes
        $  USERS  0  %%KIRK       ! show users JTKIRK, etc.

  If any usernames are specified, the default for the /MODE qualifier
  changes from /MODE=IB to /MODE=IBSDV.
!
2 Qualifiers
!
/OUTPUT

  /OUTPUT=output_file_name

  By default, USERS writes its display to SYS$OUTPUT, which is normally
  the terminal screen.  If the /OUTPUT qualifier is used, the display will
  instead be written to the specified file.

/WIDTH

  /WIDTH=n

  By default, the USERS display is 80 columns wide.  The /WIDTH qualifier
  allows you to specify any other width between 66 and 132.

  The USERS output is truncated to fit the specified width.  If needed,
  the rightmost field (which is either the current image, the source, or
  the user data) is truncated.  If the image is being displayed, the
  truncation is done on the left; otherwise it is done on the right.

  USERS does not always display its fields in the same columns.  The
  username and process name fields are only made wide enough to hold the
  longest names encountered, not the longest possible names.

/MODE

  /MODE=modes

  By default, USERS displays current interactive and batch processes.
  Using the /MODE qualifier, you can specify one or more of the following
  characters to tailor the types of processes displayed.

             I - Interactive
             B - Batch
             S - Subprocesses           (see note 2)
             D - Detached processes     (see note 3)
             V - VMS Detached processes (see note 4)
  Notes:

  1. The default is /MODE=IB, unless any usernames are specified as the
     second parameter to USERS; in this case, the default is /MODE=IBS.

  2. If /MODE=S is specified, all subprocesses are shown; if any other
     mode(s) are used with S, then only subprocesses of those modes are
     shown.

  3. /MODE=D excludes detached processes in /MODE=V; see note 4.  It
     includes network processes.

  4. /MODE=V shows all detached and network processes for the users
     SYSTEM, DECNET, and AUDIT$SERVER which are running images in
     SYS$SYSTEM, and the SWAPPER process.

/IMAGE

  This is the default.  USERS by default displays the image each process
  is currently executing.  A maximum of 80 characters of the image name
  are shown; fewer characters are shown, if necessary, to fit the display
  within the display width (see the /WIDTH qualifier).  If the image name
  needs truncation, characters are dropped from the beginning of the name,
  and no indication is shown that truncation took place.

  If a process is in an "unusual" state (any state except CUR, COM, LEF,
  or HIB), the process state is displayed <in angle brackets> before the
  image.  In certain states, USERS may not be able to display the image.

  If the image is in SYS$SYSTEM, then the full pathname of the image file 
  is not shown; just the filename is displayed, and it is displayed in
  lowercase characters.

! NSWC local
  If the image is in NSWC$ROOT:[EXE], just the filename is displayed, in
  uppercase characters.

! NSWC local
  If the image is in COMM$SW, just the filename is displayed, with the
  first character capitalized and the rest lowercased.

  See also the qualifiers /DATA and /SOURCE, which are mutually exclusive
  with /IMAGE.

/DATA

  By default, USERS displays displays the image each process is currently
  executing.  If the /DATA qualifier is used, then instead of the image
  USERS will display data about each user.

! NSWC local
  The data shown includes the user's full name, branch, office, and phone
  number.

  If no data is available for a user, that user's data is blank.  When
  necessary, the data is truncated to fit in the display width (see the
  /WIDTH qualifier).

  See also the qualifiers /IMAGE and /SOURCE, which are mutually exclusive
  with /DATA.

/SOURCE

  By default, USERS displays displays the image each process is currently
  executing.  If the /DATA qualifier is used, then instead of the image
  USERS will display the "source" of each process.

  For interactive processes created via SET HOST, the source is the term-
  inal name (RTAn), and the node and username from which the SET HOST was
  done.

  For other interactive processes, the source is the terminal name and,
  for terminal server ports, the terminal server name and port name.

  For subprocesses, the source is the process name and pid of the parent
  process.

  When necessary, the source text is truncated to fit in the display width
  (see the /WIDTH qualifier).

  See also the qualifiers /IMAGE and /DATA, which are mutually exclusive
  with /SOURCE.

/TIMES

  By default, USERS displays displays the image each process is currently
  executing.  If the /TIMES qualifier is used, then instead of the image
  USERS will display for each process:

    1. Its connect time, in days, hours, and minutes; format:  dd hh:mm
       where dd is blank if days is zero, and is ** if days is over 99.

    2. Its cpu time in hours, minutes, and seconds; format:  hhh:mm:ss.ff
       where ff is hundredths of seconds; hhh is displayed as *99 if hours
       is over 999.

    3. Its I/O count (sum of direct I/O count and buffered I/O count); if
       greater than 9999999, it will display as *nnnnnn, where nnnnnn is
       the correct low-order six digits.

/VERSION

  Causes USERS to display on the SYS$OUTPUT file its current version number
  and creation date, in the format:

        NSWC USERS Rev n.nnn Created dd-mmm-yyyy hh:mm

  After this is displayed, USERS exits; it does not display the list of
  current users.

2 Examples
!
  USERS always displays processes in node order and, within each node, in
  alphabetical order by username.  It attempts to show a subprocess immed-
  iately after its parent.

  Three examples are shown, under the subtopics Ex1, Ex2, and Ex3.
!
3 Ex1
!
      $ USERS /M=IBS /WIDTH=66
 
      Node   User     Pid       Process   M  Image      NODE1   12:54:17
 
      NODE1  ALAN     20200F54  ALAN\A14  I 
             ALAN     20200F8C  ALAN_1    S  edt
             ALAN     20200E7E  ALAN      I  $1$DUS0:[ALAN.PROGS]XXX
             BARTMAN  20200D77  BARTMAN   I  tpu
             BARTMAN  20400C54  BATCH_32  B  AN.PRODUCT.PROGRAMS]KLUGE55

  In the heading, the current node and the current time of day are shown.
  The column labeled "M" shows the mode of each process:  Interactive,
  Subprocess, Batch process, or Subprocess.

  The field widths for username and process name are set to accommodate
  the longest names displayed; these widths, and the number of spaces left
  to display the image, can change for each execution of USERS.  Note that
  the image name of the batch process is truncated.
!
3 Ex2
!
      $ USERS * /M=IBS /WIDTH=66 /SOURCE
 
      Node   User     Pid       Process   M  Source     OPSGS   12:59:52
 
      NODE1  ALAN     20200F54  ALAN\A14  I  LTA576 servr1/port_6
             ALAN     20200F8C  ALAN_1    S  %20200F54 "ALAN\A14"
             ALAN     20200E7E  ALAN      I  TXA0
             BARTMAN  20200D77  BARTMAN   I  RTA1 node2::bartman
      NODE2  ALAN     20400C43  ALAN_31   B

  This example shows the output when /SOURCE is used; see the help text
  for the /SOURCE qualifier for more information.  It also shows users
  on the entire cluster (first parameter "*"); note that the nodes are
  shown in alphabetical order, and within each node the users are shown
  in alphabetical username order.
!
3 Ex3
!
      $ USERS /DATA /WIDTH=66

      Node   User     Pid      M  Data                  OPSGS   13:14:51
 
      NODE1  ALAN     20200F54 I  Zirkle, Alan  K55  B111  663-8023
             ALAN     20200E7E I  Zirkle, Alan  K55  B111  663-8023
             BARTMAN  20200D77 I  Simpson, Bartholomew  K55  B111  663-8

  This example shows the output when /DATA is used; the type of data
  displayed may be different on different systems.  Note that the data
  may be truncated.
!
2 SYSMGRs
!
  When a user with SYSPRV executes USERS, it begins a continuously-updating,
  interactive display (unless the /STATIC qualifier is used).  On a 24-line
  display, up to 20 processes are displayed.  If there are more processes
  than can fit on the screen, various keys can be used to scroll through
  the list of processes.

  By default, the display updates at 5 second intervals; this rate can be
  adjusted to values between 3 and 19 seconds.

  When a process being displayed is deleted, the process stays displayed
  for one screen update, in reverse video.  The process mode is displayed
  followed by a minus sign.  When a new process is created, and it is in
  the region which is currently on the screen, it is displayed for one
  screen update in reverse video, with a plus sign after the mode.  For
  each screen update which shows any processes in reverse video, the
  terminal bell rings once (the bell can be suppressed).
  
  Broadcast messages may jumble the screen; CONTROL-W refreshes it.  USERS
  will automatically refresh the screen when a newly-displayed process has
  a username or process name too wide to fit in the existing fields; the
  fields are displayed wider.  (USERS will not narrow these fields when
  a process with a long name leaves the screen; CONTROL-W will do this.)

  When there are more processes than can fit on the screen, at the bottom
  of the screen will be a display showing how many processes are "above"
  the screen, and how many are "below"; this display will look like:

                [1;7m   9 MORE 27   [m

  assuming there are 9 processes above and 27 below.

  USERS will ring the bell four times when the last process in the set of
  processes being displayed, other than any processes with your username,
  gets deleted.  If SYSTEM runs "USERS 0 SYSTEM,FIELD /M=IB", then USERS
  will beep when the last interactive or batch process for FIELD on this
  node goes away (the bell can be suppressed).
!
3 Qualifiers
!
/SILENT

  When /SILENT is specified, USERS will not ring the bell to signal the
  addition or deletion of processes.

/STATIC

  When /STATIC is specified, USERS run by a System Manager will not run
  the continuously-updating interactive display.  It will show the set
  of users once and exit; i.e. it will duplicate the output which non-
  System-Managers get.

/OUTPUT

  /OUTPUT=output_file_name

  When a user with SYSPRV specifies the /OUTPUT qualifier, USERS forces
  the /STATIC qualifier.

/WIDTH

  /WIDTH=n

  When the /WIDTH qualifier is used for the continuously-updating display,
  USERS uses a display width which is the MINIMUM of:

        * The value specified on the /WIDTH qualifier

        * The terminal's characteristic width, as shown on SHOW TERMINAL

  but never less that 66 or more than 132.

3 Input

  While the continuously-updating display is running, input from the
  keyboard can be used to modify the display.  Entering H invokes a
  HELP display which describes the allowed input (the help display
  will not display correctly if the screen width is below 80 or the
  screen height is below 22).

    * H or ? or F15 or PF2 all invoke the HELP display.

    * E or Q or CONTROL-Z or CONTROL-Y all cause USERS to exit.

    * CONTROL-W refreshes the screen.

    * An integer between 3 and 19 sets the display update rate to
      that value.

    * I causes images to be displayed (the default), S displays source
      information, D displays user data, and T displays times.

    * The Right Arrow key sets the display to 132 columns, and Left
      Arrow sets it to 80 columns.

    * The Up Arrow and Down Arrow keys scroll the screen one line in
      each direction.  The PREV SCREEN and NEXT SCREEN scroll the
      screen 16 lines (on a 24 line screen) in each direction.

    * The EDT keys ADVANCE, BACKUP, SECTION, GOLD/BOTTOM, GOLD/TOP,
      LINE, and GOLD/RESET perform in USERS as they do in EDT; the
      EVE keys FWD/REV and MOVE-BY-LINE function as in EVE.
!
3 SELECTing
!
USERS allows you to select a process, then run a command against that
process (for example STOP), without exiting USERS.  "Selecting" is con-
trolled by the four keys SELECT, FIND, INSERT HERE, and REMOVE, by the
up- and down-arrow keys, and by the CONTROL-DEL key combination.

The INSERT HERE key causes the process currently at the top of the screen
to be selected.  This is shown by the process' display being underlined.

The REMOVE key causes the currently-selected process to be deselected.
When the banner at the top of the screen shows an arrow after the word
USERS ( --U-S-E-R-S--> ), then no process is currently selected.

If INSERT HERE is hit when a process is already selected, then it will
change the selection to another process.  If the previous selection was
at the top of the screen, then the new selection will be the process at
the bottom of the screen.  If the previous selection was not at the top,
then the top process will be the new selection.

When a process is selected, and that selected process is on the screen,
then the up- and down-arrow keys are used to change the selected process,
and will not scroll the display normally, unless the display must be
scrolled to change the selection.

If the selected process is not currently on the screen, the FIND key will
scroll the screen until that process is visible.

The SELECT key causes a spawned subprocess to be invoked; it will not be
invoked if the selected process is not visible.  The screen will be part-
ially cleared; the selected process will be the last process shown.  The
subprocess will be passed the selected process' nodename, username and
pid; it runs a command procedure which the site may configure as desired.
The supplied procedure works as follows:

  It prompts you to enter <CR> or a command; entering <CR> causes the
  subprocess to exit and USERS to continue.  For any command you enter,
  it will append "/ID=n" where n is the pid of the selected process.
  An exception:  if you enter the command UU, it will run the command
  "USERS * x /M=IBSDV", where x is the username of the selected process;
  this will show all processes currently being run by the user.  After
  running your command, the prompt is reissued and you may enter another
  command or <CR>.

Entering CONTROL-DEL causes the selected process to be permanently deleted
from the USERS display; it will not be deleted if it is not currently vis-
ible.  This feature helps you concentrate on processes of interest by
removing other processes which may distract you.  If a new process starts
with the same pid as a deleted process, the new process will be ignored by
USERS.
!
!  Alan L. Zirkle     NSWC Code K55     Dahlgren, Virginia  22448
!
