1 VTL This program is used to list file(s) on a VT100 family terminal. The file(s) are displayed one screen at a time for easy viewing. Various commands can be entered to change listing parameters or to position to a particular portion of the file. Many of the commands are the same as the Digital editor EDT. Commands can be entered either by using keys on the VT100 keypad, or by entering commands to the prompt at the bottom of the screen. 2 FEATURES Some of the major features of the program are outlined below: 1. Delete the file being displayed. 2. Print the file being displayed. 3. Split screen mode to display two files. 4. CTRL/C detection for aborting searches, etc. 5. Write portions of the file being displayed. 6. Skipping to the next directory when using wildcards. 7. Displaying the file header of the file being displayed. 8. Teco compatible see-all mode. 9. Search forward/backward for a string. 10. Working message displayed when searching. Enhancments requested but not implemented yet: 1. Backing up to the previous file. 2. Swapping to auxillary file with full screen display. 3. Initialization file to define the keypad keys. 4. /FIND, /RECORD, and /PAGE options at startup. 5. Repetition count for commands. The maximum record size that can be displayed is 512 characters. All commands have a repetition count of one. Relative, indexed and stream LF files are not supported. 2 INSTALLATION There are three files used with this program. The VTL program written in Macro-11, the VTLNATIVE program written in Macro-32, and the error message file. These files must be copied to the following directorys: SYS$SYSTEM:VTL.EXE - This is the main program which can be started with either the "MCR VTL" or "RUN SYS$SYSTEM:VTL" commands. SYS$SYSTEM:VTLNATIVE.EXE - This program is used to do the VMS wildcard lookup using the run time library routine LIB$FIND_FILE. It is executed by the VTL program from compatibility (PDP-11) mode using the unsupported elephant directive. This program CAN NOT be started using the RUN command. Obviously, this program is not needed for RSX-11M/M+. If the native mode routine is not located in SYS$SYSTEM, define the logical name SYS$NORDEN pointing to the directory where it resides. If the routine is not found in either directory, an error is reported to the terminal, the user is prompted, and the program continues using the normal RSX-11M file lookup routines. LB:[1,2]RSX11M.MSG - This file contains the RSX-11M error messages. If the error message file is not located in LB:[1,2], the program attempts to lookup the file in DUA0:[MILLER]. Unfortunatly, since the error message routine uses QIO$'s to perform directory lookup, a logical name can not be used. You can edit file RSXMSG.MAC in routine GERMSG to point to any alternate directory you want. You can't specify a sub-directory. 2 GETTING_STARTED There are three methods of starting the VTL program. The sections described below presume you have the following symbol defined in your login command file on VMS, or VTL is installed on RSX-11M/M+: $ VTL :== $SYS$SYSTEM:VTL 1. The most common way of starting the program is to pass a file specification to the program on the command line. When using this method, the file(s) specified are displayed and the program exits when there are no more files to display. Example: $ VTL [ROBIN...]A%C*.DAT Multiple file specifications separated by commas can also be specified. Example: $ VTL DL0:[*]*.CMD,DL1:[*]*.CMD 2. The second method is to allow the program to prompt for the file specification. Using this method allows you to remain in the program until you type CTRL/Z to exit. After starting the program, the screen is cleared and the "File(s): " prompt is displayed at the bottom of the screen. At this point, the file specification can be entered. Example: $ VTL (The screen is cleared) File(s): 3. The last method allows you to use a command file as input to the program. The command file contains a list of all the files to be displayed. This method is useful when using a program such as "DIRECTORY" to display all files created since a particular date. The length of the command lines can be up to a maximum of 256 characters. The continuation character "-" is allowed at the end of a line to continue the command line on the next line. If the file extension isn't specified the default is .CMD on RSX-11M and .COM on VAX/VMS. When the end of the command file is reached, the program exits. Example: $ DIRECTORY/NOHEADER/NOTRAILER/SINCE/OUTPUT=TODAY.COM $ VTL @TODAY Once you've started displaying a file, typing the PF2 key on the keypad displays the keypad diagram. There is no other online help. This document will be converted to the help file format at some point so HELP at DCL level is possible. 2 STARTUP_OPTIONS There are a number of options which can be specified at startup time by specifying option on the command line. The options can be specified anywhere on the command line which allows them to be appended to the VTL symbol defined in your login command file (if desired). Options can not be specified on the command line when using command file input. When using command file input, the options must reside within the command file or before the command file line within a command procedure. All options are preceded with a slash "/" and can be negated by preceding the option with either a minus sign "-" or a "NO". All startup options can be changed after the program is started with the "SET" command. If the option is not followed by the word "(default)", then the option must be specified to enable that option. The following are the valid startup options: 3 AVO The VT100 has the advanced video option. If your VT100 doesn't have the AVO, the terminal can only display 14 lines of 132 column text. 3 BINARY When displaying a binary file, the option suppresses escape seqeuences and all control characters so the text within the binary file can be displayed properly. 3 FEXIT This controls whether the program automatically displays the next file or exits at the end of file. If enabled, the user must type either "EXIT" or "NEXT" to stop displaying the current file. 3 FF This controls whether formfeeds are passed to the VT100. This option is useful when the VT100 has a hardcopy attached to allow formfeeds to skip to the top of a new page. 3 HEADER Controls whether the file header is automatically displayed before displaying the first page (screen) of the file. The file header is displayed in a format similar to the "ANALYZE/RMS" DCL command. 3 LINES This controls the number of lines to display on the screen. The default number of lines displayed is 20 lines if the file name display is enabled or 22 or it is disabled. When operating over a dialup modem, it is often desirable to display fewer lines. The command format is "/LINES=n" where "n" can be from 5 to 20 (or 22 if the file name is disabled). 3 MARK This command is used to override how often the program marks record positions. These record positions are used to quickly reposition to records within the file. The program has 1000 entrys for saving the record positions. If this switch is not specified, the following algorithm is used to calculate the record marking count: ((blocks_used * records/block)/mark_entrys) = mark_count. The worst case records/block is based upon the maximum record size. max_record > 256 use (512/32) = 16 records/block. max_record > 100 use (512/16) = 32 records/block. max_record > 32 use (512/8) = 64 records/block. max_record > 16 use (512/4) = 128 records/block. max_record < 16 use (512/2) = 256 records/block. The mark count is limited to a maximum of 50 records unless overridden. If the file you are displaying has more than 50,000 records, you will want to specify a mark count. Otherwise, all records after 50,000 will have to be skipped to sequentially from the last record marked. The command format is "/MARK=n". 3 OUTPUT This allows you to specify an output file for subsequent write commands. The output file is not opened until the first write command is issued, thus errors are deferred until that time. The command format is "/OUTPUT=filename". The output file remains open until the CLOSE command is issued or until you exit the program. 3 NARROW This forces all files to be displayed on a narrow (80 column) screen. Normally the maximum record size within the file is used to determine whether the screen should be NARROW or WIDE. 3 NAME This controls whether the file name is displayed at the top of the screen. Disabling the file name display allows two more lines for the file display. 3 NUMBERS This controls whether the record number is displayed along the left hand margin preceeding each display line. These record numbers are useful when specifying a range for the write command. 3 PROTECT The controls whether the file protection is changed before deleting a file using the DELETE command. If protection is disabled, the file protection is changed to allow deletion before deleting the file. This is useful if you want to delete a file whose protection is set to read-only which causes a "Protection Violation" when trying to delete it. 3 QUIET This controls whether bells are appended to messages displayed. If bells are disabled, then bells within the file are also suppressed. 3 RULER This controls whether a ruler is displayed on the line following the file name line. If the file name display is disabled then the ruler is also disabled. 3 SCREEN This is used to specify the screen display width. It also controls the number of characters displayed on each line before the line is truncated. Specifying a screen width overrides the NARROW or WIDE options. The command format is "/SCREEN=n" where the range for "n" is from 1 to 512. 3 SCROLL This controls whether both files should be scrolled when in split screen mode. This is useful when you want to do a visual comparison of two files. You can only scroll in the forward direction using either the down arrow key, section, enter, or the return key. All other commands only affect the active file. 3 SEEALL This allows non-printable characters such as control characters to be displayed. Control characters are displayed as ^char and tabs, carriage return, linefeed, and formfeed are displayed by the VT100 graphics HT, CR, LF, or FF respectivly. Escapes are displayed as dollar signs ($). 3 SECTION This specifies the number of lines advanced by the SECTION command. The default section size is normally (max_lines- (max_lines/5)+1) where max_lines depends on whether you've specified the /LINES options or if the you've disabled the file name display. The command format is "/SECTION=n" where "n" can be any number. If you specify zero, the section size is calculated using the algorithm above. 3 TECO This is a sub-option to the SEEALL command. This controls whether control characters are displayed using the graphics character +/-char instead of the ^char format. 3 VERSION This displays the current version of the program. 3 WIDE This forces all files to be displayed on a wide (132 column) screen. Normally the maximum record size within the file is used to determine whether the screen should be NARROW or WIDE. 3 WAIT This controls whether the program waits for a response to the prompt "Type any character to continue: " when a file open error occurs when wildcards are specified. If this option is disabled, the program waits three seconds to give the user time to read the error message displayed and then continues to open the next file. This option is useful when doing a wildcard list of a directory which has files protected which normally results in the error "Protection Violation" being displayed. 2 COMMANDS There are a number of commands available while a file is being displayed. The command prompt is displayed on the last line of the screen and is constructed from the last record number displayed. If the file is positioned at the end of file, then the command prompt is preceeded with the string "EOF-". Commands can also be issued by using various keys on the VT100 keypad. A keypad diagram can be displayed by using the PF2 key. The keypad commands CAN NOT be modified by an initialization file such as EDT keys. The valid commands are described below: 3 ADVANCE This command sets the direction to the forward direction. 3 BOTTOM This command positions to the end of file and then displays the last part of the file on the screen. 3 BACKUP This command sets the direction to the backward direction. 3 CLOSE This command is used to close an output file which is open for the WRITE command. 3 DELETE This command is used to delete the current file being displayed. 3 EXIT This command is used to exit from the program or to exit split screen mode when the bottom file is active. You can also exit by typing CTRL/Z. 3 FIND This command is used to find a search string. The command format is "FIND search_string". If a search string is not specified, you are prompted for one. 3 FNDNXT This command is used to find the next occurance of a search string. If a search string doesn't exist, you are prompted for one. 3 LEFT This command moves the margin left if previously moved right with the RIGHT command. This command is equivalent to the EDT SHR (shift screen right) command. The command format is "LEFT n" where "n" is from 1 to 512. 3 LINE This command is used to advance or backup a single display line depending of the direction. The plus sign or minus sign is used to advance or backup overriding the current direction. 3 NDIR This command is used to display the next directory or sub- directory when wildcard directorys have been specified. 3 NEXT This command is used to display the next file (if any). If there are no further files the program exits. 3 PAGE This command is used to find the next page. The formfeed character defines the start the next page. FORTRAN formfeeds and print file formfeeds are not detected (future version). 3 PRINT This command is used to spool the current file to the line printer. On RSX-11M, the file is always spooled to LP0. On VAX/VMS, the file is spooled to SYS$PRINT which can be assigned to any line printer. The file is left open for display after the file is spooled. Thus, you must use the NEXT command to display the next file if desired. 3 RIGHT This command is used to move the margin right to display part of the text truncated due to the terminal width. This command is equivalent to the EDT SHL (shift display left) command. The command format is "RIGHT n" where "n" can be from 1 to 512. 3 REFRESH This command is used to refresh the entire screen displayed. The keypad is re-enabled (incase the terminal was reset) and the entire screen is redisplayed. If two files are displayed in split screen mode, then both files are redisplayed. This command is used for screen refresh instead of CTRL/W used in EDT since CTRL/W is not recognized by the program. 3 RESET This command is used to reset the select range selected by the SELECT command. 3 SELECT This command selects a portion of the file to be written. The lines selected are displayed in reverse video just like EDT. A "WRITE SELECT" command is then used to write the selected lines. When this command is issued the current page is automatically selected. The select point starts at the top of the current page. Because of this implementation, the minimum that can be written is a single page. To write less than a page, enable the record number display and use a "WRITE range" command. 3 SECTION This command is used to advance or backup a section depending on the current direction. 3 SET This command is used to change the listing parameters. This command is used to change any of the startup options described early plus the following commands; SET SEARCH EXACT or GENERAL (default), SET TAB n (defines the size of a tab, the default is 8). 3 SHOW This command is used to display a particular parameter. Valid keywords for SHOW are: FILE - Displays the file name. HEADER - Displays the file header. KEYPAD - Displays the keypad diagram. MARK - Displays the record marking count. SEARCH - Displays the search string and general/exact. VERSION - Displays the version number. 3 SHL Same as the RIGHT command. 3 SHR Same as the LEFT command. 3 SPLIT This command is used to enter split screen mode. If you don't enter a file name on the command line, you are prompted for one. After the file is successfully opened, the screen is redisplayed with the file specified at the bottom of the screen. The "Active" message is displayed to the right of the file name to show which file is currently active. If commands to override the screen width were not specified (such as NARROW and WIDE), then the screen width is controlled by the active file at the time the REFRESH command is executed. To exit from split screen mode, make the bottom file the "Active" file and then type EXIT or CTRL/Z. After the bottom screen is exited, the top file is then redisplayed on a full screen. 3 SWAP This command is used to swap between the two files displayed in split screen mode. The "Active" message is displayed to the right of the active file or the "SHOW FILE" command is executed if the file name display is disabled. 3 TOP This command is used to positions to the top of the file and displays the first page on the screen. 3 WRITE This command is used to write a portion of the active file to an output file. If an output file is not open or you didn't specify an output file at startup time with the "/OUTPUT=filename" option, you are prompted for a file name. The range for the WRITE command are descibed in a later section. The default range for the write command is "WRITE PAGE". If you type the carriage return or ENTER key on the keypad, the program displays the next page of the file. A page is defined as the text displayed on the screen as opposed to the text between two formfeeds as in EDT. You can also enter a record number at the command prompt. This allows you to skip quickly to a position within the file. This is useful if you don't know what to search for and don't want to repeatedly type the carriage return or section key. 2 RANGE_FORMAT The range for the WRITE command is a subset of the ranges allowed by EDT. The normal range format is: beginning_line:ending_line or beginning_line THRU ending_line The following keywords can be used for the ranges: . - The ending line number on the current page. line_number - A line number within the file. BEGIN - The beginning line number of the file (line 1). BPAGE - The beginning line number on the current page. EPAGE - The ending line number on the current page. END - The ending line number in the file. PAGE - The current page displayed. Same as BPAGE:EPAGE. WHOLE - The whole file. Same as BEGIN:END. SELECT - The lines selected by the SELECT command. 2 OUTPUT_FILE The output file is created with the file type and file attributes of the active input file. This means that if the input file is variable length with print-file-format, the output file will be the same format. This should be rememebered when writing portions of multiple input file. No checking is done to insure the current input file attributes are the same as the output file. Thus, writing a FORTRAN file to an output file created with print-file-format will not PRINT or TYPE the way you expect after closing the output file. 2 FILE_FORMATS Currently, only implied (carriage-return) and embedded carriage control files are formatted properly for output to the terminal. The first character of each record in FORTRAN files and the sequence field used for print-files for carriage control are not interpreted. This support will be added in a future version of the program. 3 EMBEDDED For files with embedded carriage control (carriage-return/line-feed in the file), scrolling backwards doesn't always backup a section or a single page. This is because a single record may be displayed on several lines on the screen. To accuratly display these files, display the file in SEEALL mode (this is what EDT actually does). Also, when scrolling backwards through embedded carriage control file, the entire screen is redisplayed since this is the only way to accuratly redisplay the previous page. 2 ABNORMAL_TERMINATION If the program aborts abnormally or by your typing CTRL/Y to stop it, a software terminal characteristic must be changed. When the program starts, the escape sequence characteristic is enabled. This tells the terminal driver to expect escape sequences. By having the terminal driver interpret the escape sequences, the program doesn't have to do single character reads which results in less system overhead (EDT does single character reads). The following DCL command disables the escape sequence characteristic: $ SET TERMINAL/NOESCAPE 2 CONTROL_Y Since this program is written in PDP-11 Macro and runs in compatibility mode, CTRL/Y detection is not possible. If you are in the habit of typing CTRL/Y to abort programs, this program should be run from a command procedure which handles CTRL/Y or disables it altogether. 2 CONTINUATION_PROMPT Whenever file open errors occur with wildcards active, after displaying the file header, or after displaying the keypad, the program prompts with the message "Type any character to continue: ". At this prompt, typing "E" or CTRL/Z will exit the program and typing "N" will display the next file. The "N"ext feature is useful if you want to display just the file header (/HEADER option) of each file when using wildcards.