! 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 !