1 ADD
  Adds new items to the ETHERMON utility's internal databases.

  The command format is

      ADD item-name [additional parameters]

  where the item-names are specified below.

2 FILTER
  Adds a new entry to the message filter database. The filter can be
  initially enabled or disabled, and can specify protocol type, source
  address, destination address, or a combination thereof for filtering.

  The command format is

      ADD FILTER /qualifier [/qualifier...]
3 Command_Qualifiers
/DISABLE
 Specifies that the filter should initially be disabled; it may be
 enabled later with the SET FILTER command. The default for a new
 filter definition is enabled.

/ENABLE
 Specifies that the filter should initially be enabled; it may be
 enabled later with the SET FILTER command. The default for a new
 filter definition is enabled.

/EXCLUDE=(field=value[,field=value])
 Specifies that messages that match the specified fields should be
 filtered out and not used in the analysis. The fields that can be
 used are:
      DESTINATION=address
      PROTOCOL=aa-bb   (where aa-bb is the hexadecimal protocol type)
      SOURCE=address

/ONLY=(field=value[,field=value])
 Specifies that messages that do not match the specified fields 
 should be filtered out and not used in the analysis. The fields
 that can be used are:
      DESTINATION=address
      PROTOCOL=aa-bb   (where aa-bb is the hexadecimal protocol type)
      SOURCE=address

1 address
2 assignment_conventions
  The conventions for Ethernet addresses are that the least significant 
  bit of the first byte is clear for a physical address, and set for a 
  multicast address. The first two to four bytes describe a block of 
  addresses allocated to a particular manufacturer, and the remaining 
  bytes make up an individual ID code for a single node. A short, very
  incomplete list of known physical address ranges are:

    Digital Equipment Corp.: AA-00-03-00-xx-yy (hardware default for
                                                network adapters)
                             AA-00-04-00-xx-yy (DECnet logical addresses)
                             08-00-2B-xx-yy-zz (initial hardware addresses
                                                for LANCE-based interfaces,
                                                used for DECservers and
                                                DECbridges)
    Sun Microsystems:        08-00-20-02-xx-yy (hardware default for 
                                                386i workstations; last
                                                2 bytes +1 are host ID)
                             08-00-20-00-xx-yy (hardware default for
                                                Ethernet interfaces on other
                                                Sun workstations)
    Xyplex Corp.:            08-00-87-00-xx-yy (Ethernet CC's, HIU's, etc.;
                                                yyxx is unit serial #)
    Ungermann-Bass:          00-DD-00-xx-yy-zz (old-style NET-ONE terminal
                                                network controllers,
                                                where xxyy is box #, zz is
                                                board #)
                             00-DD-01-xx-yy-zz (new terminal network boxes,
                                                xxyyzz is 24-bit box #)
                             00-DD-0F-xx-yy-zz (Token Ring terminal network
                                                boxes, xxyyzz is box #)
    CMC:                     02-CF-1F-04-xx-yy (UNIBUS Ethernet interfaces)
                             02-CF-1F-09-xx-yy (UNIBUS Ethernet interfaces)
                             02-CF-1F-70-xx-yy (MULTIBUS II Ethernet
                                                interfaces)

2 formats
  Addresses on the Ethernet can be specified to ETHERMON in four
  different formats. The standard Xerox physical address display format
  is the one always used by ETHERMON on output, and may be used for
  input wherever an Ethernet address is required. It is of the form
  aa-bb-cc-dd-ee-ff, where each pair of letters is a one- or two-digit
  hexadecimal number, and the numbers are separated by hyphens.
  Alternately, Ethernet addresses can be specified as:
     a) DECnet node number, i.e. area.node, where area is a decimal number
        in the range 1 to 63 and node is a decimal number in the range
        1 to 1023;
     b) Internet physical address, i.e. a.b.c.d, where each letter is
        a decimal number in the range 0 to 255, and the total address
        must correspond to an entry in the address table;
     c) DECnet node name, i.e. a 1- to 6-character alphanumeric string
        (starting with a letter) which must match the DECnet name of 
        an entry in the address table.

1 CLEAR
  Removes item definitions from the ETHERMON utility's internal
  databases.

  The command format is

      CLEAR item-name [additional parameters]

  where the item-names are specified below.

2 FILTER
  Removes entries from the Ethernet message filter database, or clears
  the entire filter list (/ALL).

  If only a single filter is to be removed, the number of the desired
  filter must be specified.

  The command format is

      CLEAR FILTER filter-number
         or
      CLEAR FILTER/ALL

1 DISPLAY
  Generates a dynamically updating status display, similar to the VMS
  MONITOR utility. The display updates continuously at the specified
  update interval (see SET INTERVAL for more details) until any key is
  struck on the user terminal; at this time, the display will terminate
  and control will return to the ETHERMON prompt.

  The command format is

      DISPLAY displaytype

  where displaytype is one of the types specified below.

2 DESTINATIONS
  Displays the top (up to 15) destination addresses being specified in
  the Ethernet traffic. For addresses with known meanings, their symbolic
  names will also be displayed.

2 PROTOCOLS
  Displays the top (up to 8) protocol types being specified in the
  Ethernet traffic. For protocol types with known functions, their
  symbolic names will also be displayed.

2 SIZES
  Displays the size distribution of messages being transferred on the
  Ethernet for message size groupings from 1-100 to 1401-1500 bytes.

2 SOURCES
  Displays the top (up to 15) source addresses being specified in the 
  Ethernet traffic. For addresses with known meanings, their symbolic
  names will also be displayed.

2 STATISTICS
  Displays the current counter statistics from the Ethernet port
  (averages, minimums, and maximums not yet implemented).

1 Ethernet_port
  When the ETHERMON program is started, it must be informed as to what
  VAX/VMS device it will use as its interface to the Ethernet. Any DEC
  standard Ethernet port (DEUNA, DEQNA, DEBNT, etc.) may be specified
  by its VMS device name as a command line parameter at DCL level; if
  the name is not specified (or ETHERMON is not invoked as a foreign
  command), Ethermon will prompt for the device name. The unit number
  is not required, as it will be discarded anyway.

  Note that the user must have PHY_IO and NETMBX (or SETPRV) privileges
  to run this utility.

1 EXIT
  Terminates the ETHERMON utility and returns control to the command
  interpreter. Control-Z may also be used for this purpose.

1 HELP
  The ETHERMON utility provides the ability to dynamically monitor
  the state of an Ethernet network connected to a VAX system. It can
  generate dynamic displays of the current state of the cable, or can
  record events occurring on the cable for analysis by another
  program.

  For more information on any command, type

      HELP command [/qualifiers] [parameters]

  at the ETHERMON prompt.

1 LOAD
  Loads files of equivalence name definitions into the address, filter,
  or protocol name tables.

  The command format is:

      LOAD [/tabletype] [loadfilespec]

2 loadfilespec
  The name of the data file to be loaded into the ETHERMON run-time
  database. If the file specification is missing or incomplete, the
  specification SYS$DISK:[]ETHERMON.ETH_tabletype is used to supply missing
  components. The format of the files is that used by the SAVE command.

2 tabletypes
/ADDRESSES
  Specifies that the file should be merged into the addresses table;
  this is the default if no table type is specified.

/FILTERS
  Specifies that the file should be appended to the filters table;
  note that all filters loaded from a file are initially disabled, 
  and must be enabled with the SET FILTER command to be used.

/PROTOCOLS
  Specifies that the file should be merged into the protocols table.

1 MONITOR
  Generates a dynamically updating status display, similar to the VMS
  MONITOR utility. The display updates continuously at the specified
  update interval (see SET INTERVAL for more details) until any key is
  struck on the user terminal; at this time, the display will terminate
  and control will return to the ETHERMON prompt.

  The command format is

      MONITOR displaytype

  This command is a synonym for the DISPLAY command; use HELP DISPLAY
  for more information.

1 SAVE
  Saves files of equivalence name definitions from the address, filter,
  or protocol name tables.

  The command format is:

      SAVE [/tabletype] [savefilespec]

2 savefilespec
  The name of the data file to be written from the ETHERMON run-time
  database. If the file specification is missing or incomplete, the
  specification SYS$DISK:[]tabletype.ETH is used to supply missing
  components. The output files are ASCII data, in a format suitable
  for use by the LOAD command; the files may be edited, but the format
  should remain the same to ensure that the LOAD command works.

2 tabletypes
/ADDRESSES
  Specifies that the addresses table should be saved; this is the
  default if no table type is specified.

/FILTERS
  Specifies that the filters table should be saved.

/PROTOCOLS
  Specifies that the protocols table should be saved.

1 SET
  Modifies the attributes of internal data items in the ETHERMON
  utility.

  The command format is

      SET item-name value
        or
      SET item-name /qualifier

  where the item-names are specified below.

2 ADDRESS_NAME
  Adds new entries or modifies existing ones in the Ethernet address/
  node name table. An Ethernet address (physical or multicast) may be
  entered with an arbitrary text string (if the string contains blanks,
  lowercase letters, or punctuation marks, it should be enclosed in
  double quotes {"}). Note that, when enabled, additional address names
  may be entered automatically as ETHERMON analyzes received Internet
  ARP messages and similar node identification messages.

  The command format is

      SET ADDRESS_NAME physical_etheraddr name_symbol
            or
      SET ADDRESS_NAME physical_etheraddr"quoted string"
            or
      SET ADDRESS_NAME /[NO]AUTOMATIC
3 physical_etheraddr
  A standard 48-bit Ethernet address in Xerox standard display format,
  i.e., of six 1- or 2-digit hexadecimal numbers, low byte first, 
  with the bytes separated by hyphens. For example: 12-34-56-87-AB-DD.

3 name_symbol
  A name of up to 23 characters, containing only letters, numbers, 
  dollar sign ($), and/or underscore (_). For example: VAX_10.

3 quoted_string
  A string of text, begun and ended with double quote marks ("); the
  quote marks are not included in the string itself, and quote marks
  may not be used as part of the string. Only the first 23 characters
  specified will actually be stored. For example: "My MicroVAX on TCP/IP".

/AUTOMATIC
  Specifies that automatic address/name recognition be enabled; /NOAUTOMATIC
  disables automatic recognition. Initially, automatic recognition is
  disabled to reduce the quantity of messages being lost due to processing
  delays (the proportion being lost is displayed in the upper left corner
  of DISPLAY command screens). To reduce loss-generating overhead, automatic
  recognition is temporarily disabled (if enabled) while a DISPLAY command
  is in progress.

2 FILTER
  Modifies an existing entry in the message filter database. The filter 
  can be enabled or disabled, and can change the protocol type, source
  address, destination address, or a combination thereof for filtering.

  The command format is

      SET FILTER filter_num/qualifier [/qualifier...]
           or
      SET FILTER/SIZE=(sizeoption[,sizeoption...])
3 filter_num
  The identification number the filter was assigned when it was created
  with the ADD FILTER command.

3 Command_Qualifiers
/DISABLE
 Specifies that the filter should be disabled; it may be enabled 
 later with the SET FILTER/ENABLE command. The default for a new
 filter definition is enabled.

/ENABLE
 Specifies that the filter should be enabled; it may be disabled
 later with the SET FILTER/DISABLE command. The default for a new
 filter definition is enabled.

/EXCLUDE=(field=value[,field=value])
 Specifies that messages that match the specified fields should be
 filtered out and not used in the analysis. Any existing EXCLUDE's
 that are not specified here will not be changed. The fields that 
 can be used are:
      DESTINATION=address
      PROTOCOL=aa-bb   (where aa-bb is the hexadecimal protocol type)
      SOURCE=address

/NODESTINATION
 Clears any previously defined destination address filtering for the
 filter (whether it was EXCLUDE or ONLY filtering).

/NOPROTOCOL
 Clears any previously defined protocol type filtering for the
 filter (whether it was EXCLUDE or ONLY filtering).

/NOSOURCE
 Clears any previously defined source address filtering for the
 filter (whether it was EXCLUDE or ONLY filtering).

/ONLY=(field=value[,field=value])
 Specifies that messages that do not match the specified fields 
 should be filtered out and not used in the analysis. Any existing
 ONLY's that are not specified here will not be changed. The fields
 that can be used are:
      DESTINATION=address
      PROTOCOL=aa-bb   (where aa-bb is the hexadecimal protocol type)
      SOURCE=address

/SIZE=(sizeoption[,sizeoption...])
 Specifies the new characteristics of the message size filter. The
 message size filter is independent of the set of message address and
 protocol filters, and its effects are logically AND'ed with the other
 enabled filters. The size options are:

      DISABLE             disables use of message size filter

      ENABLE              enables use of message size filter

      MAXIMUM=number      sets new maximum message size (must be
                          in the range 46 to 1500)

      MINIMUM=number      sets new minimum message size (must be
                          in the range 46 to 1500)

2 INTERVAL
  Sets the update rate for the DISPLAY command. The command value is
  the number of seconds between updates (initially defaulting to 4
  seconds). The value must be in the range of 2 to 60 seconds.

  The command format is

      SET INTERVAL number-of-seconds

2 PROTOCOL_NAME
  Adds new entries or modifies existing ones in the Ethernet protocol
  type/node name table. An Ethernet protocol type may be entered 
  with an arbitrary text string (if the string contains blanks,
  lowercase letters, or punctuation marks, it should be enclosed in
  double quotes {"}).

  The command format is

      SET PROTOCOL_NAME ethernet_protocol name_symbol
            or
      SET PROTOCOL_NAME ethernet_protocol "quoted string"
3 ethernet_protocol
  A standard 16-bit Ethernet protocol number of two 1- or 2-digit
  hexadecimal numbers, low byte first, with the bytes separated by
  hyphens. For example: 80-5B.

3 name_symbol
  A name of up to 24 characters, containing only letters, numbers, 
  dollar sign ($), and/or underscore (_). For example: STANFORD.

3 quoted_string
  A string of text, begun and ended with double quote marks ("); the
  quote marks are not included in the string itself, and quote marks
  may not be used as part of the string. Only the first 24 characters
  specified will actually be stored.
  For example: "Stanford V Kernel experiment".

1 SHOW
  Displays status of various internal databases used by the ETHERMON
  utility.

  The format of the command is

      SHOW data-item

  where data-item is one of the names specified below.

2 ADDRESS_NAMES
  Displays the Ethernet address and name association table. This table
  is used to find symbolic meanings of source and destination addresses
  specified in Ethernet messages.

2 FILTERS
  Displays the currently defined Ethernet message filters; the filter
  number (used for SET FILTER and CLEAR FILTER), enable/disable status,
  and the protocol type/source address/destination address (if used) and
  associated matching state(s) are displayed for each filter.

2 PORT_STATUS
  Displays the current status of ETHERMON's connection to the Ethernet
  interface.
3 Command_qualifiers
/ZERO
  Specifies that, after the port counters are read, they should be
  zeroed.

2 PROTOCOL_NAMES
  Displays the Ethernet protocol type and name association table. This
  table is used to find symbolic meanings of protocol types specified
  in Ethernet messages. Protocol types specified with a preceding '*'
  are permanently defined and may not be removed.

1 SUMMARIZE
  Tallies up the total number of messages found on the network for each
  address, protocol type, or whatever is being sorted for, over the
  specified sampling interval. Samples are taken for the interval set by
  the SET INTERVAL command (unless the /INTERVAL qualifier is used here
  to override), and then a report is generated, displaying the messages
  counts and associated identifiers sorted in decreasing message count
  order.

  The command format is

      SUMMARIZE group-type [/qualifier]

2 DESTINATIONS
  Specifies that the summary should be over destination addresses.

2 INTERNET
  Specifies that the summary should be over 2nd level protocols used in
  Internet IP (DOD) [06-00] protocol type messages.

2 PROTOCOLS
  Specifies that the summary should be over protocol types.

2 SOURCES
  Specifies that the summary should be over source addresses.

2 Command_qualifiers
/INTERVAL=delta-time
 Specifies the period of time the trace will runs before it stops and the
 collection file is closed. Days may not be specified; only hours, minutes,
 seconds, and hundredths of seconds may be specified.

1 TRACE
  Collects messages received from the Ethernet into a file, as restricted
  by the currently enabled filter set. The TRACE command runs for the 
  period of time specified by the SET INTERVAL command, unless the /INTERVAL
  qualifier is specified with a different period. The file can be 
  recorded in either binary or printable ASCII format.

  The command format is

      TRACE [/qualifier[/qualifier]]

2 Command_Qualifiers
/ASCII
 Specifies that the output file will be in ASCII format. If not specified,
 the default is binary format.

/BINARY
 Specifies that the output file will be in binary format. If not specified,
 the default is binary format.

/INTERVAL=delta-time
 Specifies the period of time the trace will runs before it stops and the
 collection file is closed. Days may not be specified; only hours, minutes,
 seconds, and hundredths of seconds may be specified.

/OUTPUT=filespec
 Specifies the name of the output file; if not specified, the filename will
 be ETHERMON.DAT for binary format, and ETHERMON.LIS for ASCII format.

2 File_formats
3 ASCII
 The ASCII file contains three lines for each received and filter-passed
 Ethernet message. The first line contains the VMS timestamp when the
 message was received, the source and destination addresses in standard
 ASCII-hexadecimal format, the protocol type (also ASCII-hex), and the
 message body's length in bytes. The second line is a hexadecimal dump of
 the first 40 bytes of the received message; the third line is the same
 40 bytes dumped in ASCII (with a space before each actual character, such
 that the ASCII characters line up under their hexadecimal bytes; periods
 are displayed for unprintable characters).

 Preceding the dump lines is a single line reporting when the dump began.

 Following the dump lines are three lines reporting when the dump was
 completed, and the quantity of data bytes and messages processed from
 the Ethernet before and after filtering.

 The file has carriage-return carriage control and variable-length records.

3 Binary
 The binary file contains one variable-length record per received and
 filter-passed Ethernet message. A set of structure definitions for various
 languages are listed below.
4 FORTRAN

    STRUCTURE /BIN_REC/
      INTEGER*4 VMS_DATETIME(2) ! quadword system timestamp
      BYTE      DESTADDR(0:5)   ! beginning of XEDRIVER P5 buffer: dest addr
      BYTE      SRCADDR(0:5)    ! source Ethernet address
      UNION
       MAP
        BYTE    PROTOCOL(0:1)   ! Ethernet protocol type
       END MAP
       MAP
        BYTE    DSAP            ! IEEE 802 destination SAP
        BYTE    SSAP            ! IEEE 802 source SAP
        UNION
         MAP
          BYTE  CTL(0:1)        ! IEEE 802 CTL byte(s)
         END MAP
         MAP
          BYTE  ECTL            ! IEEE extended 802 CTL byte
          BYTE  PID(0:4)        ! IEEE extended 802 Protocol IDentification
         END MAP
        END UNION
       END MAP
      END UNION                 ! end of XEDRIVER P5 buffer (20 bytes)
      INTEGER*2 LENGTH          ! length of message body
      BYTE      BODY(1500)      ! not all of this array may be sent; only
                                ! part actually used is written to file
    END STRUCTURE ! /BIN_REC/

4 MACRO

            $DEFINI REC
    $EQU    REC$Q_TIME       0     ; VAX/VMS binary timestamp
    $EQU    REC$B_DESTADDR   8     ; 6-byte destination address
    $EQU    REC$B_SRCADDR    14    ; 6-byte source address
    $EQU    REC$B_PROTOCOL   20    ; 2-byte Ethernet protocol type
    $EQU    REC$B_DSAP       20    ; 1-byte IEEE 802 DSAP
    $EQU    REC$B_SSAP       21    ; 1-byte IEEE 802 SSAP
    $EQU    REC$B_CTL        22    ; 1- or 2-byte IEEE 802 CTL field
    $EQU    REC$B_ECTL       22    ; 1-byte IEEE extended 802 CTL field
    $EQU    REC$B_PID        23    ; 5-byte IEEE extended 802 protocol ID
    $EQU    REC$W_LENGTH     28    ; word length of message body
    $EQU    REC$T_BODY       30    ; body of message
    $EQU    REC$K_MAXLEN     1530  ; maximum length of file record
            $DEFEND REC
