!
1 VLOG
!
  The VLOG utility efficiently displays the most recent lines of a batch
  log file, whether the job is still running or not.  VLOG also monitors
  a running log file, displaying new lines as they are written.

  Format:	$ VLOG [job_or_file] [ optional qualifiers ]

  VLOG (View Log) was developed by NSWCDD K55.
!
2 Parameter
!
job_or_file

  If the parameter is a number, it is assumed to be the entry number of
  a currently-executing batch job.  VLOG will find the log file, if
  any, and view it.  See the warning below.

  If the parameter is not a number, then it is the name of the log file
  or text file to be viewed.  The default file type is .LOG.

  If the parameter is omitted, then DCL Symbol $ENTRY will be examined
  to get the entry number of the batch job most recently submitted.  If
  $ENTRY is defined, and if it refers to a currently-executing batch job,
  then VLOG will view that job's log file, if any.

  WARNING -- If you have run more than one batch job with the same log
             file name and location, then when VLOG uses an entry number
             to find the log file, it will display the HIGHEST VERSION
             of this file, which may not be the log for the specified
             job.
!
2 Qualifiers
!
/FIRST

  By default, VLOG displays the final 4 blocks of the file.  If
  /FIRST is specified, VLOG also displays the first blocks of the
  file.  If /FIRST=n is specified, where n is an integer greater
  than zero, then this many initial blocks are displayed.  If
  /FIRST is specified with no value, 4 initial blocks are
  displayed.

  The number of records displayed depends on the lengths of the
  records.

/LAST

  By default, VLOG displays the final 4 blocks of the file.  The
  number of records displayed depends on the lengths of the records.
  More or fewer blocks can be displayed by specifying /LAST=n, where
  n is an integer greater than zero.

/INTERVAL

  If the file being viewed is currently open in another process,
  VLOG first displays the final blocks of the file, then monitors
  the file, displaying any new lines that the other process has
  written to the file.  By default, VLOG hibernates for 20 seconds
  between each interrogation of the file.  A different interval can
  be used by specifying /INTERVAL=n, where n is an integer 5 or
  greater.

  Longer intervals use less system resources.

  By default, batch logs are updated only once per minute.  A batch job
  can change the update interval by using the SET OUTPUT_RATE command.
  The following command, which should be placed at the beginning of a
  batch job's command file, changes the update interval to 20 seconds,
  matching VLOG's default monitor interval:

                $ SET OUTPUT_RATE=0:0:20

  If the file to be viewed is not a log file, and is currently open in
  another process, the other process must have opened the file to allow
  sharing by another reader.  Also, the other process will probably need
  to flush the buffer periodically.  In Fortran:

                integer*4 rab_addr, status, sys$flush
                 . . .
                open (2 , .... , SHARED)
                rab_addr = for$rab(2)
                 . . .
                status = sys$flush( %val(rab_addr) )
                if (.not.status) call lib$stop( %val(status) )
		
  Note that flushing the buffer is a relatively inefficient operation.
  You have to balance your need for near-real-time viewing against the
  cost of implementing it.

/BEEP

  If the file being viewed is currently open in another process, VLOG
  monitors the file, displaying any new lines that the other process
  has written to the file.  If /BEEP is specified, the terminal bell
  rings once whenever any new lines are displayed.

/SIGNAL

  /SIGNAL="string"
  /SIGNAL=("string",BEEP)

  If this qualifier is used, VLOG highlights, in reverse video, all lines
  containing the specified string.  The string must be specified exactly
  as it will appear in the file (e.g. uppercase, lowercase, etc.).  If
  the BEEP keyword is used, the terminal bell will ring twice whenever
  a matching line is displayed.

2 Operation
!
  VLOG first opens the specified file.  In doing so, it detects whether
  somebody else has the file open for writing; VLOG displays a message
  indicating whether this is the case.

  If the file is open by somebody else, VLOG computes and displays the
  age of the file in days, hours, and minutes.  This gives an indication
  of how long the batch job has been running.

  Next, VLOG displays the size of the file, in blocks, and a message
  indicating that the following lines are the contents of the final N
  blocks of the file.  Then, these contents are displayed.

  If the file is not open by somebody else, VLOG then exits.  Other-
  wise, the following is done in a loop which executes once during each
  time interval (default every 20 seconds):

      The file is interrogated to see if its end-of-file has moved.  If
      so, VLOG closes and re-opens the file (which is required) and
      the updated blocks are read and displayed.

  The loop can be exited by entering E, Q, or CONTROL-Y.
!
3 Technical_details
!
  When VLOG opens the file, using direct calls to RMS, it uses a
  File Header Characteristic XAB to return the size of the file in
  blocks, and the last byte used in the last block.

  Then, an RMS block-mode $READ (not a $GET) is done, using RAB$L_BKT
  to specify the first block to read.  This is used to read the last
  N blocks in the file without having to read or skip the bulk of the
  file.  Reading the last 4 blocks of a 10000 block log file is thus
  done very fast and efficiently.

  Once the blocks are read, VLOG needs to find the start of the
  first record in the block, which is not straightforward because
  records can span blocks.  It does this by scanning for an aligned
  16-bit word having a value between 0 and 511 (hex 0000 and 01FF).

  When we find this, we assume fairly certainly that we have the header
  word for a variable-length record.  We can assume this because the
  ASCII characters NUL and SOH seldom appear in text files (i.e. the
  hex sequences 00nn and 01nn are rare).

  Once we find the first record, locating subsequent records in the
  block, and in subsequent blocks, is trivial.
!
2 Restrictions
!
  VLOG can view a batch log file, or any sequential ASCII file with
  variable-length records shorter than 512 bytes.  It cannot view a file
  with fixed-length or stream records, or with records longer than 511
  bytes.

  Any carriage-control information in the records is ignored.  Any non-
  printable ASCII characters are displayed as periods (".").

  If any record contains NUL characters (ASCII value 0) or SOH characters
  (ASCII value 1), VLOG may not be able to view the file in some situations.

  If VLOG finds a record longer than 511 bytes, or gets confused by
  a NUL or SOH character, it will abort with the error message:

        %VLOG-F-LOST, record location failure
!
