Introduction to Utilities I
AR.COM
CMP.COM
GREP.COM
PG.COM
PRINT.COM
RM.COM
SORT.COM
SUM.COM
WC.COM
TOKEN.COM and WORD.COM
UNIQ.COM
XDIR.COM
:                 SuperSoft Utility Pack #1 

     Commands in the utility pack for the most part  have  a
consistent command syntax.    Each  command  consists  of  a
command name followed  by  arguments.    The  arguments  are
separated by spaces (not tabs).  If spaces are desired in an
argument, they  must  be  placed  in  double  quotes.    The
arguments tend to be  options,  filenames,  or  input/output
redirections.  The options are preceded by a dash  ("-")  in
all cases except for  XDIR  and  PRINT  in  which  case  the
options are preceded by slashes ("/").   Filenames  must  be
unambiguous  ("?"  and  "*"  are  not  treated   specially).
     These command make use of  a  `standard  input'  and  a
`standard output.'  Normally,  the  standard  input  is  the
console keyboard and the standard output  is  equivelent  to
console output.  However, these assignments can  be  changed
(in all  commands  except  XDIR  and  PRINT)  by  adding  an
input/output redirection argument to the command line.    If
an argument of the form >filen is added to the command line,
the standard output is changed to filen.  If an argument  of
the form <filen is added to the command line,  the  standard
input is  changed  to  filen.    (These  arguments  must  be
preceded by a space).  
     Ambiguous file specifications are not (as yet) accepted
by any utility commands except for XDIR.  Also there  is  no
provision for redirection the  standard  input/output  to  a
device such as PRN:  .  
     Each command in the utility pack is  described  in  the
following pages.  Each command is given  in  synopsis  form,
with square  brackets  ("["  and  "]")  indicating  optional
forms.  Upper case forms in the synopses are  typed  by  the
user exactly as they appear.  Lower case  forms  are  to  be
replace by some item such as a filename.  

:        AR -- file archiver 
 
 
Synopsis: 
         
 
        AR [ T D R X ] libr [ filen ] 
 
 
     AR manipulates library files.  
     A library file acts as sort of  a  sub-directory:    it
contain copies of  the  contents  of  any  number  of  files
(essentially limited only by the maximum file size).   These
file copies are  manipulated  through  the  use  of  the  AR
command with one of the options T, D, R, or X.  The  options
have the following function:  
 
        T               list the contents of libr 
        D               delete filen from libr 
        R               replace (or add) filen to libr 
        X               extract filen from libr 

 
     Only one option (and one filen) may be specified  at  a
time.  The T option will echo  filen  if  filen  is  in  the
library.  If no filen is specified with the T  option,  then
every file entry in the library is listed.  If no  filen  is
specified with the X option, then all  files  are  extracted
from the library.  With all other options, a filen  must  be
specified.  
     When  performing  the  D  and  R  functions,  libr   is
modified.  The modified copy is put in a temporary file with
the name AR.$$$ .  AR does not actually  replace  libr  with
the contents of the temporary file;  this  is  left  to  the
user.  This allows the user to determine if the new  library
is correct before deleting the  old  one.    Since  the  $$$
extension specifies a temporary file, and the name AR.$$$ is
not changed from from one invocation of AR to the next,  the
temporary is likely to be overwritten or  deleted.    It  is
thus important to rename  the  temporary  file  as  soon  as
possible.  


     The following procedure is recomended for updating  the
library file after AR has been involked:  
 
        AR T AR.$$$ 
 
        ((Check to see if AR.$$$ contains the correct filenames.)) 
 
        ERA libr 
 
        REN libr=AR.$$$ 

Discussion of use:  


     AR is valuable in keeping more files on a disk than the
operating system allows.  AR can be used in situations where
it is easier to specify a single file rather than  a  group,
such as in PIP'ing files  from  place  to  place,  or  using
Intercomputer  Communication  (Networking)  programs.     On
single floppy disk systems, a library file can  be  used  in
conjuction with DDT to transfer multiple files in  one  disk
switch.  
     


Features:  


     AR does not allow multiple filen's on a single  command
line.  AR should also rename the libr for the user.   Future
versions will correct these features.    Also  the  internal
file format may be changed to speed  up  processing  and  to
remove the following feature:  AR  will  not  archive  files
which contain sectors that resemble archive directory header
sectors.  See below.  

File formats:  


        Sector format: 
 
                <header sector> 
                <file sector> 
                <file sector> 
                        . 
                        . 
                        . 
                <header sector> 
                <file sector> 
                <file sector> 
                        . 
                        . 
                        . 
 
 

File formats:

        Header format: 
 
                A1h     byte 
                A1h     byte 
                ...     filename string 
                00h     byte 
                20h     byte 
                20h     byte 
                 . 
                 . 
                 . 
                20h     byte 
                0Dh     byte 
                0Ah     byte 

:        CMP -- file comparator 
 
 
Synopsis: 
 
 
        CMP [ -L ] [ - file ] file 
 
 
     CMP compares two  files,  indicating  the  first  place
where the files differ.  The place  is  given  by  its  byte
position, its line, and  the  buffer  in  which  it  occurs.
     If -L  is  specified,  CMP  continues  comparing  until
end-of-file (EOF).    The  two  different  byte  values  are
printed in hexidecimal, preceded by their byte  position  in
decimal.  
     The first file may be specified by  a  dash  ("-"),  in
which case it is taken from the standard input.  



Features:  


     CMP keeps positional counts in 16-bit two's  complement
form.  This means of course, that values  greater  than  32k
will not be correct.  
:        GREP -- search files for a pattern 
 
 
Synopsis: 
 
 
        GREP pattern [ file ... ] 
 
 
     GREP  searches  the  specified  files  for  the   given
pattern.  The lines  that  are  found  are  printed  on  the
standard output.  If more than one file  is  specified,  the
lines found are preceded a colon and by the filename (of the
file in which the line was found).    GREP  matches  strings
regardeless of the case of the alphabetics.  

Features:  

     Future  releases  will  be  able  to   handle   regular
expression patterns.  
:        PG -- browse a page at a time 
 
 
Synopsis: 
 
 
        PG [ file ... ] 
 
 
     PG prints the specified files on the  standard  output,
pausing every 24 lines for input from  the  standard  input.
If PG receives a "n" or "N" at this point, it quits.  If  it
receives a control-z it continues printing,  but  no  longer
pauses.  If PG receives anything else, it continues printing
and pausing.  Of course, control-c will cause  an  abort  at
any time.  

Features:  


     PG, as yet, has no option for changing  the  number  of
lines per page.  
:        PRINT -- Send files to the printer device 
 
 
Synopsis: 
 
 
        PRINT file [ /H delim header delim /S number /N /P /? ] 
 
 
     PRINT prints the specified file on the  printer  device
(PRN:).  The options are:  
 
        /H delim heading delim  specify the page heading within 
                                the arbitrary delimiter: delim 
        /S number               skip to specified page 
        /N                      number each source line 
        /P                      turn off page numbering 
:        RM -- remove a list of files 
 
 
Synopsis: 
 
 
        RM file [ file ... ] 
 
 
     RM removes the specified files.  

Discussion of use:  


     ERA duplicates  the  function  of  RM.    ERA  has  the
advantage of being faster if only  one  file  is  specified.
Also ERA is always  available,  since  it  is  part  of  the
operating system.  However, RM accepts a list of files,  but
ERA does not.  This makes RM faster if a list is used.  Also
RM allows the specification of some filenames (such as  ones
with punctuation and spaces  in  them)  that  ERA  does  not
allow.  This last feature is useful used in conjuction  with
the /X option of XDIR.  
:        SORT -- sort utility 
 
 
Synopsis: 
 
 
        SORT [ -R ] [ file ... ] 
 
 
     SORT sorts variable length  records  (terminated  by  a
new-line (line-feed)).  It prints the  sorted  list  on  the
standard output.  SORT uses ASCII collating sequence.    The
-R option reverses the order of the sort.  

Features:  


     SORT is limited to 10000  characters  and  1000  lines.
There is no provision for dictionary order (ASCII order does
not place "A" next to "a").    There  is  no  provision  for
sorting on fields within the line.  There  is  no  provision
for merges yet.  
:        SUM -- checksum a list of files 
 
 
Synopsis: 
 
 
        SUM [ file ... ] 
 
 
     SUM checksums the specified files.  The checksum  is  a
sixteen bit accumulation, with each pair of bytes taken as a
sixteen bit number.  Each filename is printed along with the
number of bytes (modulus 65536) and the  checksum,  both  in
:        WC -- word count 
 
 
Synopsis: 
 
 
        WC [ file ... ] 
 
 
     WC prints each specified filename followed by the count
of the number of lines and words in the file.  
     


Features:  


     Wc counts using 16-bit two's complement numbers,  which
:        TOKEN -- find `tokens' 
        WORD  -- find `words' 
 
 
Synopsis: 
 
 
        TOKEN [ file ... ] 
        WORD  [ file ... ] 
 
 
     These commands search the specified files for groups of
characters (strings).  They put these groups on the standard
output, one string  per  line.    TOKEN  finds  all  strings
surrounded  by  `white  space'  (tabs,   newlines,   spaces,
beginning-of-file,  and  end-of-file).    WORD   finds   all
alphanumeric strings prefixed by  an  alphabetic  character.
     


Discussion of use:  


     WORD and TOKEN are useful when used in conjunction with
SORT and UNIQ.  WORD can be run over a document, the  output
can then be SORTED, and then UNIQ can be run over the sorted
output.  The result is a sorted list of words  used  in  the
document.  Such a list would be useful to  find  mispellings
or inconsistent spellings.  
:        UNIQ -- remove duplicate lines 
 
 
Synopsis: 
 
 
        UNIQ [ file ... ] 
 
 
UNIQ copies the  specified  files  to  the  standard  output
removing any adjacent duplicate lines.  
     


Discussion of use:  


     UNIQ is useful as a post pass to SORT.  
:        XDIR -- sorted directory listing 
 
 
Synopsis: 
 
 
        XDIR [ /X /P file ... ] 
 
 
     XDIR outputs a formated  listing  of  the  files  in  a
directory.  The list is in  alphabetic  order.    XDIR  also
prints some statistics about the amount of free resources in
the directory.  The  /X  option  prints  detail  about  each
directory entry including  the  numeric  representation  for
each  character  in  the  filename.  The  /P  option  allows
redirection of the standard output to  the  printer  (PRN:).


Discussion of use:

     XDIR  can  be  used  to  determine  the exact character
sequence in a strange filename, allowing  the  file  to  be
removed with RM.
