 
               UTIL version 1.1   5/25/83  by John R. Hind
 
  UTIL provides a number of utility filter functions for IBM PC-DOS V2 which
  allows an experienced user to easily manipulate ASCII data files. Programmers
  can use these functions to provide a great degree of function and flexibility
  in command lists processed by the batch command processor.
 
*******************************************************************************
*                                                                             *
* DISTRIBUTION and USE RESTRICTIONS:                                          *
*                                                                             *
* This program is provided "AS IS" without warranty of any kind. It is        *
* not warranted for merchantability or fitness for any perpose.               *
*                                                                             *
* This program must be used only on an IBM PERSONAL COMPUTER.                 *
*                                                                             *
* This program may be copied and distributed for non-commercial use when      *
* accompanied by a copy of this help file. If the user finds it to be of      *
* value then he is requested to forward $3.00 to the author to help defray    *
* development costs. Please enclose a self addressed stamped envelope with    *
* payment indicating the version number so that it will be posible to         *
* provide information on bugs/fixes to the program:                           *
*                                                                             *
*                     John R. Hind                                            *
*                     4100 Pickwick Dr.                                       *
*                     Raleigh, NC. 27612                                      *
*                                                                             *
* Copies of this program may be included in distributions of software packages*
* or used for commercial perposes provided that the author is paid $3.00 per  *
* copy for the first 10 copies and $1.00 per copy thereafter.                 *
*                                                                             *
* The author will provide a limmited number of full distribution disks (      *
* including demonstration batch files) for a copying fee of $30.00 each.      *
* Requests for the above should be made by computer clubs and other groups    *
* who can provide local distribution as the author has no means of mass       *
* production.                                                                 *
*                                                                             *
*******************************************************************************
 
 
Command Syntax:
 
UTIL {prefix} subcommand { operand{ operand{ ...}}} {<infile} {>outfile}
 
Where:
   prefix => EOF if end of file character is to be added to end of
             standard output (outfile above).
             EXP if tabs are to be removed from the input.
             TAB if tabs are to be removed from the input and then added
             to the resulting output.
   subcommand :
      => HELP or ? - Writes this help file to standard output
      => COPY or CPY  - Moves ASCII text standard input to standard
             output selectively, see description below.
      => WCS or OUTC or SAY  - Writes each operand value to standard
             output as an ASCII text line.
      => DIR or FILES - Writes a batch file image to standard output
             which contains a line for each file found when a directory
             lookup is performed for each of the operand values. If the
             value specified contains a device and/or subdirectory part
             then it is included in each corresponding output line.
      => SYSDIR - as above except only system and hidden files are included.
      => CHGDIR - only normal files which have been flagged as changed are
            included in dir output.
      => ENV - Writes SET commands to standard output which represent
             the current DOS environment. If operands are provided then
             they are used to select specific SET NAMES to be output in
             a generic fashion ( ie "X" selects all names starting with
             an X , "X=" selects only the name X).
      => HEX or UNPACK - Converts a standard input file to an ASCII text
             standard output containing printable hex representation of
             each input byte (suitable for transmission over an ASCII net).
             If the option CHAR or /C is specified then the output is in
             a standard memory dump format including the relative offset of
             each dump line from the beginning of the input file, blanks
             between the hex byte representation and printable characters
             representation.
      => PACK - Converts a standard input file of ASCII text lines which
             contain only printable hex characters into a standard output
             where each pair of input characters is packed into an output
             byte. This function may be used to receive a file over an ASCII
             net which was UNPACKED by the above function or to create special
             output character sequences for device control (ie to setup a
             printer or intelligent modem).
      => PASTE - Lines from a paste file (required operand) are added to
             the end of lines read from standard input starting at input
             line FROM=nnn (optional). The addition continues FOR=nnn
             (optional) lines. If CS=nn is specified then the addition
             begins at column nn and if "FILL=string" is specified then
             string is repeated and used to pad short input lines to the
             starting column.
      => PASTE PAGE=nn - converts standard input to a two column page format
             of nn lines per page. If FROM=nnn (optional) is specified then
             the column generation begins at the nnn'th line. The width of
             a column is 39 unless overridden by CS=nn and the page width is
             twice the column width plus one delimited character between the
             columns. FILL=string defines the delimiter character and is
             repeated as required to pad the leftmost lines forming the
             first column. If option "HDR=string" is given then each page
             will start with a header line containing a page number and the
             string value. The second and following pages will also contain
             a top of forms character with this option.
   operands :
             Command operands may be any sequence of nonblank characters
             which will be converted to upper case or a quoted string.
             Operands are delimited by one or more blanks, by a comma, or
             by a slash.
   examples :
             UTIL DIR A:\BILLS\*.DAT  A:\ALPHA\BETA ABC.*
             UTIL WCS "this is line one"  "LINE 2" "" | MYPROG
             UTIL EOF COPY FROM=13 TO=45 =ABC "=abc" <test.in >test.out
             UTIL env path=  x
             UTIL WCS OC | UTIL PACK >LPT1:
             UTIL HEX CHAR <TEST.DAT  >LPT1:
             UTIL PASTE <\FIGS\X.A FROM=28 CS=40 \FIGS\X.B FOR=33 >LPT1:
             DIR | SORT | UTIL PAGE=23 "HDR=Sorted Directory"
 
COPY filter subcommand
 
 COPY moves selected ASCII text lines or portions thereof from standard
 input to standard output.
 
Command Syntax:
 
UTIL {EOF} [COPY] { operand{ operand{ ...}}} {<infile} {>outfile}
           [CPY ]
 
Where:
   Operand:
      => FROM=nnn or F=nnn - The copy operation starts on or after line
             nnn or at line one if operand not specified.
      => START=string or S=string - If specified then the copy starts on
             the first line which contains string and is or follows the
             from specification.
      => END=string or E=string - If specified then the copy ends on
             the first line which contains string and is or follows the
             from or start specification.
      => TO=nnn or T=nnn - If specified then the copy ends on line nnn
             of the standard input.
      => /C - If specified then lines which would have been output
             are counted and this count is output in there place
      => /N - If specified then the relative input line number is
             given at the begining of each selected output line
      => /U - If specified then each selected output line is forced
             to upper case.
      => /L - If specified then each selected output line is forced
             to lower case.
      => TRIGER=string or =string  - Used to specify from one to five
             strings which limit lines output to those which contain
             one or more of the string values.
      => NOT=string or !=string  - Used to specify from one to five
             strings which limit lines output to those which do not
             contain one or more of the string values
      => CS=nnn - If specified then the output line starts at the column
             nnn of the standard input line.
      => BS=string - If specified then the output line starts after the
             location of string in the standard input line or at column
             1 (overrides specification of CS option).
      => TB=string - Equivalent to requesting both TRIGGER=string and
             BS=string.
      => CE=nnn - If specified then the output line ends at the column
             nnn of the standard input line.
      => ES=string - If specified then the output line ends at the
             location of string in the standard input line or at the
             end of the input line (overrides specification of CE option).
      => OP=string - If specified then string is a prefix which is
             output in front of each output line.
      => OS=string - If specified then string is a suffix which is
             output at the end of each output line.
 
 ***************************************************************************
                 U T I L   P R O G R A M   N O T E S
 ***************************************************************************
 
VERSION 1.1 CHANGES
* BUGS FIXED
   - Input EOF character properly handled after LF.
   - Help files sent to ERROR DOS HANDLE after syntax error message.
 
* NEW FUNCTION
   - Short on-line help files to reduce main storage use.
   - COPY /C option added to count selected lines.
   - PASTE subcommand added to allow lines from two files to be appended
     to each other.
   - PASTE PAGE=nn added to provide creation of dual column pages from
     single column input.
 
DEMO DISK:
 
   The demo disk contains eight batch files which demonstrate each of
   the subcommands of the program. It should be installed on the A drive
   which should be set as the default drive and a path command issued
   such that access is gained to the DOS 2 utility commands SORT and
   TREE. It is assumed that a graphics printer is defined as LPT1: .
   When this setup is done then the operator may input the command
   requests DEMO1 ... DEMO8 to execute the respective batch files.
 
GENERAL COMMENTS:
 
1) ASCII TEXT FILE FORMAT:
   A record may contain up to 255 characters followed by an ASCII CR control
   character. If an ASCII LF control character is the first character in the
   record data then it is ignored. If a NULL character is found in the data
   then it and all characters which follow it in the record are ignored.
   If an End Of File character (26) is found as the first character of a
   record the it is discarded and any characters following it are not
   used.
 
2) RESTRICTIONS:
   a) Line (record) numbers are in the range of 1 to 32000.
   b) String specifications must be of length 1 to 80.
   c) The standard input file for the HEX CHAR function must be less
      than 65768 bytes in length.
   d) The DOS environment block formatted by the ENV function must be
      less than 4095 bytes in length.
   e) PASTE PAGE size limited to 70 lines of 250 characters each.
 
3) ERROR MESSAGES:
   a) All error messages are output to the standard DOS 2 error message
      device ( file handle #2).
   b) List of possible error messages:
 
     **ERROR - No Subcommand Specified
     Indicates that no UTIL function was requested, is followed by a listing
     of the Command Syntax HELP file on the standard output device.
 
     **ERROR - Subcommand `xxxxx' is not supported
     Indicates that an invalid value xxxxx was specified in the command
     line where a UTIL function subcommand name should have been given.
 
     **ERROR - UTIL Return code is nn
     Processing was abnormally terminated due to an error indicated by DOS,
     the DOS error code nn is displayed and is returned to the operating
     system so that it may be tested by the invoking BATCH file (if any).
 
     **ERROR - `xxxx' exceeds trigger limit of 5 strings
     Too many trigger operands have been requested in the COPY function.
 
     **ERROR - `xxxx' exceeds exclude limit of 5 strings
     Too many excluded operands have been requested in the COPY function.
 
     **ERROR - `xxxx' is not a valid COPY parameter
 
     **ERROR - `xxxx' is not a valid HEX (UNPACK) option
 
     **ERROR - `xxxx' exceeds trigger limit of 6 strings
     Too many trigger operands have been requested in the ENV function.
 
     **ERROR - can't open file xxxxx
     PASTE file specification could not be accessed, DOS error code will
     appear as return code in the following message.
 
     **ERROR - xxxx is a duplicate file name or invalid option
 
