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{ ...}}} {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.out UTIL env path= x UTIL WCS OC | UTIL PACK >LPT1: UTIL HEX CHAR 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{ ...}}} {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