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

/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.

/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.

/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.

/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.

/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.

/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.

/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+.

/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.

/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.

/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 '<DJDE>', 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.

