1 LIST LIST is a utility for examining the contents of files. It's simplest use is to display records at the terminal a screen at a time, however it can also search for character strings and write portions of files to other files. Any record in a file may be accessed directly by line number or by a search. The LIST command line has the following syntax. (Optional parts of the command line are enclosed in square brackets): LIST[/qualifiers] input_file[,...] [commands][>[>]output_file] 2 Input_file Each "input_file" may be a simple file name, an indirect command file name preceded by @, or a file name containing standard RMS wild card characters. More than one "input_file" may be entered by separating them by commas. If "input_file" is a simple file name, LIST lists the file. The default file extension is ".lis". For example, $ list abc.dat lists the file abc.dat. If "input_file" is an indirect file name, LIST lists the named files in the indirect file one at a time. Each file name must appear on a line by itself and may not have wild card characters in it. The default extension for indirect file names is ".com". For example, $ list/noprompt @files lists each file specified in files.com . If "input_file" contains wild card characters LIST lists the files which match the wild cards. The wild card character matching works identically to the way it works in the TYPE command, ie. the initial default file type is ".lis" and only the most recent version of the file is selected unless ;* is specified. When more than one "input_file" is specified or when "input_file" contains wild cards or is an indirect file name, LIST prompts with each of the selected file names to see if you want them listed, unless /NOPROMPT was specified (see HELP LIST QUALIFIERS) . Responses to the prompt are: Y List the file. or N Don't list the file. G (GO) List this and remaining files with no prompting. ^Z Don't list this file and remaining files. When commands are given on LIST's command line, they are executed once for each file selected by the input file specifications. When output is redirected by the command line, it remains redirected for each file selected (see HELP LIST OUTPUT_FILE) . For example, $ list * 1,$px >all.lis prints *.lis into the file all.lis . 3 Defaults More than one file may be listed during the same LIST session by typing LIST and then a carriage-return. LIST then prompts with the "File? " prompt for one or more file name(s). After the file(s) have been listed, LIST prompts for a new file name. Whenever LIST encounters an input file name, the node, device, uic, name, and extension fields are remembered and become the defaults, even if the field has wild card characters in it. The defaults are used to replace missing fields of subsequent file names entered for listing. For example: $ list File? icr$document:list.doc When you are finished listing icr$document:list.doc, then to see icr$document:vg3.doc you would only have to type: File? vg3 and LIST would supply the missing fields of the file name. If LIST can't find a file after supplying the defaults, it tries the file name as entered. Initially, the defaults are "sys$disk:" for the device and ".lis" for the extension. 2 Searching LIST can search backwards and forwards in the input file for lines which match a specified search pattern. A search pattern is a string of characters bracketed by slashes (/) or backwards slashes (\): /string/ causes LIST to search forward from the current line for a line which matches "string". \string\ causes LIST to search backwards from the current line - 1 for a line which matches "string". Case is not significant in search patterns, eg. /X/ and /x/ match the same lines, unless the characters are inside double quotes (see below). Once specified, a pattern becomes the default pattern and may be invoked by // or \\. For example, /john doe/ searches forwards for a line with "john doe" in it in upper or lower case. There are several characters which have a special meaning when they appear inside a search pattern: 3 " All characters within enclosing double quotes are treated literally, not as special characters. The case of a character is significant when it appears within double quotes. Two double quote characters in a row within enclosing double quotes are interpreted as one literal double quote. For example, /"John Doe"/ matches only lines which contain literally John Doe . 3 ~ negation. Causes a match if the pattern does not match the line. ~ must appear at the beginning of a pattern (unless a column range is specified (see HELP LIST SEARCHING COLUMN_RANGE) ), otherwise it has no special meaning. For example, /~abc/ matches lines which don't contain abc. 3 % specifies that the match must occur at the beginning of the line only. % itself must appear at the beginning of the pattern, otherwise it has no special meaning, unless a column range (see HELP LIST SEARCHING COLUMN_RANGE) or negation (~) is desired; in this case the column range and/or the negation character must appear before %. For example, /%10/ matches only lines with a 10 in the first two columns, and /~%10/ matches lines without a 10 in the first two columns. 3 $ specifies that the match must occur at the end of the line only. $ itself must appear at the end of the pattern, otherwise it has no special meaning. For example, /%$/ matches only empty lines. 3 * is a wild card character that matches any sequence of characters, including the empty sequence. For example, /john*doe/ matches lines containing johndoe or john doe or johnabcdoe etc. 3 ? is a wild card character that matches any single character. For example, /a?c/ matches lines containing abc or acc or a c etc. 3 @ matches any one alphabetic (a-z or A-Z) character. For example, /a@c/ matches lines containing abc or acc but not a c. 3 # matches any one numeric (0-9) character. For example, /%#/ matches lines with a number in column 1. 3 ` accent matches a break character. Break characters are: beginning of line, end of line, and any non-alphanumeric character. For example, the ? command can be used with the following search pattern to display lines which contain the variable I: /`i`/? 3 ^ causes the next character to be interpreted as a control character. For example, /^z$/ matches lines containing control Z at the end of the line. 3 | logical OR. Causes a match if the sub-pattern before it or the sub-pattern after it match the line. For example, /abc|xyz|%#/ matches lines containing abc or xyz or a number in the first column. The negation character (~) may be used at the beginning of a sub-pattern; for example, /~x|~y/ matches lines which don't contain an x or don't contain a y. 3 & logical AND. Causes a match if the sub-pattern before it and the sub-pattern after it match the line. For example, /x|y&abc/ matches lines containing abc and an x or a y. The negation character (~) may be used at the beginning of a sub-pattern; for example, /~x&~y/ matches lines which don't contain an x and don't contain a y. 3 Column_range Search patterns can restrict the range of columns in the input record in which the search is to take place. A column range is specified by placing the special character "<" at the beginning of a pattern or subpattern, followed by two column numbers separated by a comma, followed by a ">" character. The rest of the search pattern follows the column range specification. For example, /<11,15>123/ searches for 123 in columns 11 through 15. Subpatterns can also specify a column range, for example: /<30,31>10&<40,41>20/ searches for a record with 10 in columns 30 and 31 and 20 in columns 40 and 41. The special characters ~ (negation) and % (match at beginning) should appear after a column range specification. For example, /<10,20>~abc/ searches for lines which don't contain abc in columns 10 through 20. When % or $ is used with a column range, the match must occur at the beginning or end, respectively, of the column range. For example, /<10,50>%abc*xyz$/ matches lines with abc starting at column 10 and xyz ending at column 50 (or the end of the record, whichever is shorter). The characters "<" and ">" and the other characters in a column range specification are only special at the beginning of a pattern, and may be used freely elsewhere in a pattern, for example: /~<10,20>/ matches lines which don't contain <10,20>. 2 Numbers Numbers are used to position LIST in the file and as arguments to commands. Numbers always precede the command they affect. A number may be a simple integer, one of several special line number variables (see HELP LIST NUMBERS VARIABLES) , or a search pattern. The numeric value of a search pattern is the number of the line that matches the pattern. LIST scans the command line from left to right. Whenever it encounters a number, the current line number, dot, is set to that number. When multiple line numbers appear next to each other, LIST positions to each in turn, for example: 1/abc/ searches for abc at or after line 1. Some commands optionally take two numbers as arguments; when specifying more than one number, separate the two numbers by a comma. For example, the P command may be used to print lines 1-45: 1,45p Numbers may be added and subtracted from one another, for example: /x/-1,+2p prints three lines around the next line which contains an x. 3 Variables Following is a description of each line number variable: . Dot is the current line number. Whenever LIST encounters a line number, the value of dot is reset to that line number. For example, /x/,.p prints the next line containing an x. $ Dollar is the last line of the file. For example, 1,$p prints the whole input file. # Sharp is the line number displayed by the most recent prompt. For example, if LIST was positioned at line 10 as indicated by the prompt "10>" then 10>1,#/x/p would print from line 1 to the next line containing an x at or after line 10. @ At-sign is the line number of the top of the last screen displayed by LIST. For example, @+1//p searches for the next line matching the current pattern after the top of the last displayed screen, and prints a screen from there. * Star is set by the "=" command and is equal to the value of dot when the "=" command was last issued. * marks a line of interest for future reference. For example, =\subroutine\,*/end/p marks the current line, then searches backwards for subroutine, then returns to the marked line, searches forwards for end, and finally prints the lines between the two matched lines. 2 Commands LIST accepts commands on it's initial command line or when it prompts with the current line number, for example: 24> Commands are single characters and are preceded by zero, one, or two numbers which are arguments to the command. More than one command may be entered on a command line; LIST scans the command line from left to right, positioning to line numbers and executing commands. There are two types of commands; those that print and those that affect LIST's state without printing. Commands that print usually print from dot (the current line number) unless two line numbers were specified, in which case printing occurs from the first line number to the second. Other commands "eat up" the number(s) that are their arguments; in other words, dot retains the value it had before the command, with its numeric argument(s), was executed. If a line number appears at the end of the command line with no command after it, the default command (P) is executed. For example, /abc/ at the end of a line of commands is equivalent to /abc/p since both cause a screen to be displayed from the next line containing abc. Note: LIST usually changes most control characters to nulls before writing out a line, however when two line numbers are specified or when the G command is executed, (for example the commands "1,$P" or "100G") all characters are written out unchanged. Thus it is possible to write out portions of a file without losing any characters. 3 P Displays lines from the file. Dot is left at the last line printed plus 1. P is the default command, and is optional at the end of the command line. P Print as many lines as will fit within the current screen size (initially 23), starting at the current line (dot). nP Print as many lines as will fit within the current screen size starting at line n. n1,n2P Print lines n1-n2. Example: 1,10p prints lines 1 through 10. 3 G Like "P", "G" displays lines from the file, however with zero or one arguments G only prints one line, and dot is left at the first line printed. G Print the current line. The current line is not changed. nG Position to and print line n. Dot is left at line n. n1,n2G Print lines n1-n2. Dot is left at n1. Example: /subroutine/g prints the next line with the string "subroutine" in it. 3 ? Displays lines matching the current search pattern, and their line numbers (unless /NONUMBERS is specified on LIST's command line). ? Display a screen-full of lines matching the current pattern. If the end of the file is reached, dot is left at line 1, else dot is left at the next line matching the current pattern. n? Display a screen-full of lines matching the current pattern, starting at line n. If the end of the file is reached, dot is left at line 1, else dot is left at the next line matching the current pattern. n1,n2? Display all lines matching the current pattern between lines n1 and n2. Dot is left at n1. Example: 1/xyz/,$? displays all occurrences of xyz in the input file. 3 L The L command causes the last line of commands to be reexecuted. 3 = The = command sets the line number variable, *, to dot. = marks a line for later reference. = Set * to dot. n= Set * to n. Dot is left at line n. Example: /x/= marks the next line containing an x. 3 S Sets the screen size. The value of dot is unchanged. S Reset the screen size to 23. The screen size and width help determine how many lines LIST prints per screen. nS Set the screen size to n. n1,n2S Set the screen size to (n2-n1)+1. Example: 7s sets the screen size to 7. 3 C Sets the column range which will be read from each input record. Initially the column range is 1-513. LIST can only read up to the first 512 characters in a record, however when the column range is set to be greater than 512, then LIST reports an error when an input record is more than 512 characters long. If the column range is restricted to 512 or less then LIST does not report record too long errors. The value of dot is unchanged. C Reset the column range to 1-513. nC Set the column range to 1-n. n1,n2C Set the column range to n1-n2. Example: 1,10c causes LIST to read and display only columns 1-10 of each record. 3 F Creates a "virtual file" by restricting LIST to a contiguous subrange of the lines in the file. Dot is left at line 1. F Reset the virtual file to correspond to the actual file. nF Make a virtual file between dot and dot+n-1. Dot becomes the new line 1 of the virtual file. n1,n2F Make a virtual file between n1 and n2. N1 becomes the new line 1 of the virtual file. Example: /subroutine/,/end/f creates a "virtual file" which contains a subroutine. Line 1 of the virtual file is the first line of the subroutine, and $ is the last line of the subroutine. 3 N Turn prompt mode on/off. When prompt mode is off, LIST does not prompt with the current line number, but leaves the cursor after the last line printed. The value of dot is unchanged. Example: 1sn sets the screen size to 1 and prompt mode off, placing LIST in line-by-line mode, in which one record is printed per carriage-return. 3 R Resets dot to 1, the screen size to 23, the screen width to it's original value, the column range to 1-513, the virtual file to the full, actual file, and prompt mode to on. The value of dot is unchanged. 3 X Finish listing the file. X is identical to ^Z (EOF). 3 ' ' Space (blank) is the null command, and does nothing. It may be used to position to a line without printing and to separate commands on a line for readability. If a line number is given before the space command, dot is left at that line number, else dot is unchanged. Example: 1,10f p creates a "virtual file" between lines 1 and 10 and prints starting at line 1. 3 W Sets the screen width. The screen size and width help determine how many lines LIST prints per screen. The value of dot is unchanged. W Reset the screen width to it's original value, read from the host operating system when LIST was started. nW Set the screen width to n. Example: 132w sets the screen width to 132 columns. 3 V Routes all the following output from the command line to the printer port of the DT80 (a VT100 look-alike). The value of dot is unchanged. Example: v 1,100p turns on the printer port, prints lines 1-100 on the printer, then turns the printer port off. 3 Looping A sequence of commands may be repeated in a loop by placing the commands within parentheses with a repetition count in front of the left parenthesis. The commands are then executed as many times as indicated by the repetition count or until a search within the commands fails. In either case, after exiting the loop execution continues with the next statement after the loop. If no repetition count is specified, the loop is executed forever or until a search failure occurs within the loop. For example, (/`i`/+1\subroutine|function|program\,.p /end$/) loops finding all Fortran modules which contain the variable I and prints the line containing each module's name. Loops may be nested up to four levels. 3 Macro LIST has a simple text replacement macro facility. A macro is a remembered set of commands. The macro is defined by enclosing the commands in square brackets ([]). When M is specified on the command line, the M is replaced by the macro text. For example, [@+1//P] defines a macro to search for the current pattern starting from the top of the last screen + 1, and print from there. To invoke the macro, type M on the command line. The text of the macro is not executed when it is defined. It is not executed until an M is typed. M may appear with other commands and line numbers on the command line; first the macro text replaces the M, then the command line is executed. M may be used more than once on a command line. Initially, the macro is defined as 1SNP; this puts LIST in line-by-line mode and prints one line (see HELP LIST COMMANDS N) . 2 Output_file The output from a line of LIST commands, which normally goes to the terminal, may be redirected to a file. To write a new file, put >output_file at the end of the commands; to append to an existing file, put >>output_file at the end of the commands. If "output_file" doesn't exist during an append, it will be created. The default file name for "output_file" is "list", and the default extension is ".lis". If "output_file" contains asterisks in it, then each field of "output_file" with an asterisk in it is replaced by the corresponding field in the input file name. When output is redirected by the initial command line which selected the file(s) to be listed, it remains redirected as long as the file(s) are being listed. For example, $ list/noprompt/header *.dat /xyz/,$?x >xyz lists all occurrences of the string xyz in *.dat to the file xyz.lis . However if the output file specification contains asterisks, a new output file is created for each input file listed, with the fields with asterisks in them replaced by the corresponding fields from the input file name. For example, $ list/noprompt/trim [murphy.proj...]*.for 1,72c 1,$px >[*]*.for trims the sequence numbers and trailing blanks from [murphy.proj...]*.for and rewrites each file with a higher version number in its original UIC. When output is redirected from a command line while listing a file, redirection is only in effect while that command line is being processed. For example, 24>1,10p>t.tmp writes lines 1-10 to the file t.tmp and then closes it. The carriagecontrol type of newly created files is identical to the carriagecontrol type of the file being listed (except for print file format files, which are written with carriage return (list) carriagecontrol), while that of appended files is the same as that of the file being appended to. Once an output file name has been specified using >output_file or >>output_file, that file name becomes the default file name for file redirection only, and need not be specified again, i.e. > or >> alone is all that is needed to redirect output to that file. The name of the file is remembered as it was typed in, so that asterisk fields are replaced with the fields from the current input file. 2 Bugs 1. Logical names must have a colon after them to be translated properly in input and output file specifications. For example: $ assign file.dat data $ list data: 2. When output is appended to a file with print file format carriagecontrol, the proper carriage control information is not written to the file. 2 Examples Hitting return prints the next screen. 45 Start printing at line 45. -5 Print from 5 lines back. - Print starting half a screen back. --- Print starting one and one-half screens back. Hitting escape prints from 2 screens back. $ Print the last line in the file. /xyz/ Locate the string xyz and print from there. // Locate the current pattern and print from there. 1/xyz/ Locate xyz at or after line 1 and print from there. /abc/-5 Print starting 5 lines before abc. 1,10 Print lines 1-10. /subr/,/end$/ Print the next subroutine. /subr/? Display lines containing subr. ? Display lines containing the current pattern. 1/`i`/,$? Print all occurences of the variable "i". 10,$>t.tmp Write lines 10 through the end of the file to t.tmp $ list *.for /`n`/,$?x prints all occurrences of the variable N in *.for 2 Keys VAX RMS indexed and relative files may be listed by key and the starting record may be based on a key match. For example, to list an indexed file by key 2 starting at the first record where key 2 is greater than or equal to " 10": $ list/key=2/keyge=" 10" indexed.dat The defaults for indexed and relative files are to list by primary key (key number 0) starting at the first record in the file. In the key qualifier descriptions, "n" stands for an integer and "key" stands for a key value, where a key value may be an integer or a character string enclosed by double quotes. A double quote within a key value may be specified by placing two double quotes in a row. If the length, N, of a character key value is less than the source file's defined key length then the match is made based on the first N characters of the key. Key matches on unsigned binary and packed decimal keys are not supported at this time. 2 Qualifiers /PROMPT /NOPROMPT Prompt with each file name selected by the command line to see if the file should be listed. By default, LIST prompts when more than one file is selected by the command line or when an indirect file is specified. (see HELP LIST INPUT_FILE) . /HEADER /NOHEADER (D) Write a header record containing each file's name and the date before listing each source file. /NUMBERS (D) /NONUMBERS Display the line number of each line selected by the "?" command. (see HELP LIST COMMANDS ?) /TRIM /NOTRIM (D) Trim trailing blanks and tabs from the source file. By selecting /Trim and restricting the column range of the file to columns 1-72, Fortran files can be stripped of sequence numbers. (see HELP LIST COMMANDS C) /DELETE /NODELETE (D) Allows the user to delete a file after listing it. When /DELETE is specified, LIST prompts with Delete? after each file selected by the command line has been listed. If Y is entered, then the file is deleted. /KEY=n List an indexed source file by key number n. By default, LIST lists the file by the primary key (key 0). /KEYEQ=key List an indexed or relative source file starting at the first record whose key equals the specified key. /KEYGE=key List an indexed or relative source file starting at the first record whose key is greater than or equal to the specified key. /KEYGT=key List an indexed or relative source file starting at the first record whose key is greater than the specified key.