1 REFORMAT ! Copies a file, changing its format. Can also be used to create an empty file in a given format. Usage: $ REFORMAT input_file output_file {qualifier(s)} At least one qualifier must be used to specify the format of the output file. No more than one of the three qualifiers /FORTRAN, /LIST, and /NONE may be used. If none of these are used, the output file is given the same type of carriage control as the input file. ! 2 Parameters The first parameter is the name of the input file to be used. The second parameter is the name of the output file to be created. No wild cards are allowed on either file name. If either name is omitted, it is prompted for. If it is desired to create an empty file with attributes controlled by the supplied qualifiers, specify NL: as the input file. The input file must not have records longer than 256 characters. The file must be a file that can be printed; using an .OBJ or .EXE file, for in- stance, will cause REFORMAT to abort. 2 Carriage_Control_Qualifiers /FORTRAN The output file is given 'Fortran' carriage control. Column 1 of each record is assumed to contain a carriage control character, and is not dis- played when the file is PRINTed or TYPEd. If the /CONVERT qualifier is not used, or if the input file has Fortran carriage control, column 1 of each input record becomes the carriage con- trol character; the contents of the records are not modified. If the /CONVERT qualifier is used, and the input file does not have For- tran carriage control, then each record is restructured and a proper car- riage control character is added in column 1 of each output record. /LIST The output file is given 'List' carriage control. Each record is termin- ated by an ASSUMED Carriage Return/Line Feed. Other spacing may be con- trolled by placing ASCII control characters (such as Form Feed, Vertical Tab, Carriage Return, Line Feed) in the record. Files created by EDT have this type of carriage control. If the /CONVERT qualifier is not used, or if the input file has List car- riage control, the contents of the records are not modified. If the /CONVERT qualifier is used, and the input file does not have List carriage control, then each record is restructured and, if necessary, pro- per ASCII control characters are added in the record. For example, if the input file has Fortran carriage control, column 1 of each record is remov- ed. /NONE The output file is given 'None' carraige control. Each record must contain ASCII control characters (Form Feed, Vertical Tab, Carriage Return, Line Feed) to control spacing. Normally, each record must have a Carriage Return/Line Feed pair as its last two characters. The .DOC files produced by RNO have this type of carriage control. ! The .MEM files produced by RUNOFF have this type of carriage control. If the /CONVERT qualifier is not used, or if the input file has None car- riage control, the contents of the records are not modified. (Note that the file may look strange when PRINTed or TYPEd.) If the /CONVERT qualifier is used, and the input file does not have None carriage control, then each record is restructured and proper ASCII con- trol characters are added in the record. For example, if the input file has Fortran carriage control, column 1 of each record is removed, and a Carriage Return/Line Feed pair is added to the end of the record. /CONVERT This qualifier is used with the /FORTRAN, /LIST, or /NONE qualifiers to cause the records in the file to be restructured into the new carriage control format. If this qualifier is not used, the records are copied without modification. For more information, see the /FORTRAN, /LIST, and /NONE qualifiers. 2 Other_Qualifiers ! /APPEND This qualifier causes REFORMAT to append the contents of the input file to the end of the output file. If the output file does not exist, it is created without comment. If the output file does already exist, then REFORMAT will abort if its carriage control format is not correct: * If the /FORTRAN, /LIST, or /NONE qualifier is used, then the existing file must have this format. * Otherwise, the existing file must have the same format as the input file. [One way to determine the format of a file is to use the lexical function F$FILE_ATTRIBUTES(file,"RAT"), which returns either "", "CR", or "FTN".] The two qualifiers /APPEND and /KEY cannot both be used. /BLANK_LINES=option This qualifier causes REFORMAT to treat blank lines specially. | If the input file has FORTRAN carriage control, the | | entire line (including the carriage control character) | | must be blank for the line to be considered blank. | One of the following four options must be specified: REMOVE_ALL - All blank lines are discarded. REMOVE_NULLS - All lines which are null are discarded. REMOVE_NON_NULLS - All lines which are blank but not null are discarded. REMOVE_ADJACENT - When more than one blank line appears in a row, all but one are discarded. For each input line, this qualifier is processed last; if /TRUNCATE is also used, for example, there will be no non-null blank lines to remove. For files with FORTRAN carriage control, a null line will be one column long, consisting only of a blank carriage control character. For LIST files, a null line will be zero columns long. For NONE files, a null line will be two columns long, consisting of a carriage-return character fol- lowed by a line-feed character. /COLUMNS=([m,]n) If /COLUMNS=(m,n) is used, where m and n are integers and m < n, then only those columns of each input record are copied to the output file. If /COLUMNS=n is used, then only columns 1 through n are copied. If the /COLUMNS qualifier is not used, all columns are copied. Note that if one or more of the columns before column 'm' contains a Tab character, and /UNTAB is not used, then each Tab removed may shorten the line by up to eight spaces. /DJDE This qualifier was added for use with VMS RUNOFF files; it it unnecessary and should not be used with RNO files. If /DJDE is used, occurrences in the input file of Xerox 9700 Laser Print- er commands, which begin with the string '', are shifted so that the command begins in the first printable column. This allows, for instance, VMS RUNOFF files with a non-zero left margin setting to be correctly pro- cessed on the 9700, which requires that Laser Printer commands not be in- dented. Also, a blank line is inserted after each Laser Printer command. Since these lines do not actually get printed, the pages on which they occur would otherwise end up one line short, causing, for instance, page numbers to be printed one line too high. /DUPLICATES This qualifier must only be used when the /KEY qualifier is used. It al- lows duplicate keys in the indexed sequential output file. The default is that duplicate keys will cause REFORMAT to abort. This qualifier should be used only when duplicate keys are necessary. It should not be used just to prevent inadvertant duplicate key errors, since subsequent users of the indexed sequential file may be depending on the fact that no duplicate keys are present. /EBCDIC When this qualifier is used, each character in the input file is translat- ed from EBCDIC to ASCII; EBCDIC is commonly used on IBM mainframe systems. /FAO="format" When this qualifier is used, the specified FAO format string is used to construct the output lines from the input lines. The format string must contain exactly one occurrence of "!AS", which tells where to insert the contents of the input lines. One example of this is: $ DIRECTORY /OUTPUT=ZZZ.ZZZ /NOHEADING /NOTRAILING ... $ REFORMAT ZZZ.ZZZ ZZZ.COM /FAO="$ @PROC !AS XX" This reformats a directory listing (ZZZ.ZZZ) into a command file (ZZZ.COM) which calls procedure PROC.COM iteratively. Successive names from the directory listing are used as the first parameter of each call, and "XX" is used as the second parameter of each call. The FAO format string can also be used to include line numbers in the out- put lines. This is done by including either "!UL" or "!ZL" exactly once in the format string, at the point where line numbers are to be inserted. These are equivalent. A field width can also be used (as in "!6UL" or "!5ZL"), and the line numbers will be padded with blanks (for UL) or zeros (for ZL). Modifying the example above, we can do: $ REFORMAT ZZZ.ZZZ ZZZ.COM /FAO="$ @PROC !AS !UL" and the line number (of ZZZ.COM) will become the second parameter to pro- cedure PROC.COM. Other FAO format items can be used, as long as they don't require param- eters. See the DCL Dictionary (under Lexical Functions -- F$FAO) to learn more about FAO usage. To experiment with FAO, commands like the following can be executed: $ WRITE SYS$OUTPUT F$FAO("$ @PROC !AS !6ZL" , "text of line" , 999) When the output file has 'Fortran' carriage control, column 1 is never af- fected by the use of the /FAO qualifier; it acts only on columns 2+. /FIXED=n When this qualifier is used, the output file is created with fixed-length records, of length 'n'. When this option is not used, the file is created with variable-length records. REFORMAT does not truncate the input records to this length; records which are too long will cause REFORMAT to abort. The /COLUMNS qualifier may be used to guarantee that the records are short enough. /KEY=([m,]n) If /KEY=(m,n) is used, where m and n are integers, the output file is cre- ated as an indexed sequential file with a character string key starting in column m and ending in column n. Unless the /DUPLICATES qualifier is also specified, the key must be unique in each record; by default, duplicate keys are not allowed. If /KEY=n is used, the output file is created as indexed sequential, with a character string key starting in column 1 and ending on column n. If the /KEY qualifier is not used, the output file is created as a sequen- tial file. /SHIFT=n The output records are shifted to the right 'n' columns by adding 'n' blanks at the beginning of each line. (If the output file has Fortran carriage control, the blanks are added after column 1.) Note that the presence of Tabs on the line will affect the final spacing. If this qualifier is not used, the records are not shifted. /SPLIT="string" RESTRICTION: The /SPLIT qualifier can only be used when the output file has 'List' carriage control, either by default or by use of the /LIST qualifier. When this qualifier is used, and the specified string occurs in a record of the file, then the record is split into multiple records, at the point where the string occurs. The string is then removed. If the string appears N times in a record, then that record is split into N+1 records. If the string appears at the very beginning or very end of a record, or twice in a row, then a zero-length record is created. The string must be between 1 and 15 characters long. /SYMBOLS When this qualifier is used, substitutions are made for any DCL symbol names occurring in the input file. The names must be surrounded by apos- trophes (single quotes). Wherever the input file contains a valid symbol name, the output file will contain that symbol's value. Undefined names are not considered errors; the name is copied verbatim to the output file. REFORMAT may abort if symbol substitution causes a line on the output file to become too long. When it is not convenient to use apostrophes to surround symbol names, any two single characters may be chosen as opening and closing delimiters. On the command line, specify /SYMBOLS=("o","c") where "o" is the chosen open- ing delimiter and "c" is the chosen closing delimiter. They can be the same character, but you still need to specify it twice. /TRUNCATE When this qualifier is used, rightmost Tabs and Blanks are removed from each input record before the record is written to the output file. In certain cases, this can result in a significant savings in the disk space used by a file. /UNTAB When this qualifier is used, Tab characters in the input file are convert- ed to blanks, with the standard eight-column tab spacing used. Note that this will cause the output file to use more disk space. /VERSION This qualifier causes REFORMAT to display on the SYS$OUTPUT file its cur- rent version number and date, in the format: NSWC REFORMAT Rev n.nnn Created dd-mmm-yyyy hh:mm If /VERSION is used, REFORMAT does not prompt for input and output file specifications; if both are not included, REFORMAT exits after displaying the version. If both are included, REFORMAT displays the version AND does its normal processing as specified. 2 VFC_Carriage_Control ! Files with VFC carriage control are created the following ways: * Using the OPEN /WRITE command in DCL * Running batch jobs; batch logs have VFC carriage control * Explictly creating the file with RMS and specifying VFC * Copying some files from PDP systems You can tell if the file has VFC carriage control by examining the output from DIR /FULL. The record format will be "VFC, 2 Byte header". VFC files have carriage control information for each record embedded in a two-byte header which is appended to the beginning of each record. This header is not considered part of the record; i.e. you will not see it if you edit the file or do a DUMP /RECORD. The only convenient way to see it is to do a DUMP /NORECORD. The format of the header is defined in the RMS Reference manual. REFORMAT cannot create a VFC output file. It handles most VFC input files correctly. It does the following for each line: If the carriage control information in the header for the line is the VFC equivalent of the Fortran characters '0', '1', '+', '$', or NUL, then the output line is given the correct translation of this. If the information is the equivalent of Fortran blank (i.e. a normal line), or does not match any Fortran code, then the line is treated as if it had LIST carriage con- trol (i.e. the first character in the line is examined to see if it is a Form Feed, etc.). !