**************************************
** Console utilities for Windows 95 **
**************************************

Version 1.01


=============
- Copyright -
=============

The programs, documentation files and all the remaining files in this
package are copyrighted:

Copyright  Juan M. Aguirregabiria 1987-1996. All rights reserved

Other brand and product names are trademarks or registered trademarks of
their respective holders.


============
- FreeWare -
============

These programs are FreeWare; there is no charge for using them and they
may be distributed freely so long as the files are kept together and
unaltered. You may neither sell nor profit from distributing them in any
way.


==============
-  Disclaimer
==============

In no event will the Author be liable to users for any damages,
including but not limited to any lost profits, lost savings or other
incidental or consequential damages arising out of the use or the
inability to use these programs, even if the Author has been advised of
the possibility of such damages, or for any claim by other party. 


======================================
-  Hardware and software requirements
======================================

To run the programs in this package you need Microsoft Windows 95 and
the hardware necessary to run it.

They will probably run under Windows NT, but the Author has not tested
this possibility. Reports on using the programs under NT will be greatly
acknowledged.


========================
- Suggestions and bugs -
========================

The Author would gratefully welcome information about any bug or problem
found in these programs. Suggestions to improve them in future versions 
are also welcome, but I cannot guarantee that they will be added to a 
future release of the program. 
Write to:

	Juan M. Aguirregabiria
	Fisika Teorikoa. Zientzi Fakultatea
	Euskal Herriko Unibertsitatea
	P.K. 644, 48080 Bilbo (Spain)
	Internet address: wtpagagj@lg.ehu.es
        WWW: http://lcpx07.lc.ehu.es/jma.html


================
- Introduction -
================

Microsoft has been advertising the new user interface (we could say the
Mac-like interface) in Windows 95 and every effort has been made to
suggest that Windows 95 no longer runs under DOS, but is a new operating
system on is own. Schulman and other authors have conclusively proved
that this claim is not completely correct (and also that 16-bit code has
still a central role in Windows 95).

So DOS is not gone ... BUT THIS IS VERY GOOD NEWS!

To start with, many file maintenance jobs are far easier when using
command line utilities and batch files. The "user-friendly" way to do
many simple tasks (comparing two directories or copying to the disk the
relevant modified files of you current programming task, for instance)
is boring and error prone. 

On the other hand, Unix-like filters are still very useful, but the task
to provide them a good looking user-friendly interface is probably not
worth; after all they will be used only by advanced users that are not
afraid of the command line (and even acknowledge its advantages in some
cases).

Finally, DOS is still there with Windows 95, but it's a much better DOS!
Many previous limitations are gone or lessened, because one may now
easily write the so-called "console" mode applications that

 - look like old DOS programs:
   - if they are run form the command line, their output is
     sent to the DOS box,
   - redirection and pipes are supported as usual.

 - but are true Windows 95 programs with many of the Win32 advantages:
   - long filenames
   - direct access to all available physical and virtual memory (no more
     need of those often mutually incompatible DOS extenders).
   - version information
   - threads
   - memory mapped files
   - structured exception handling
   - mouse
   - etc.

I couldn't stand being completely deprived of the command line. After
all I do know writing (well, at least in my native language, which
obviously is not English). I sometimes think that all these icons and
"user-friendly" interfaces are a step back to the caves where icons were
used because nobody knew writing. For instance, by using one of
the utilities included with this package you can simply write:

  cpy -md . a:\backup

to copy all the files in the current directory (and its subdirectories)
that are newer than the same files in the "a:\backup" directory. How
many steps are necessary to do the same thing by using the Explorer? Not
to speak about the possibility of errors.

In this package I include new compilation for Windows 95 of some DOS
utilities which I have been using from years. I hope you find some of
them useful.


*************
**  COUNT  **
*************

DESCRIPTION:    Counts characters words, etc.
        
USE:            Count file(s)

ACTION: Count bytes, characters, letters, vowels, consonants, words, lines
        sentences, words per sentence and letters per word.

EXAMPLES:
        Count *.txt *.doc
        shows the statistic of all text files in the current directory
        
NOTES:  - DOS wildcards '*' and '?' can be used
        - More than one file specification can be included
        - The statistics are sent to the standard output and may be 
          redirected to any file or device.
        - Any byte higher than the space is considered a character
        - Only the 26 characters A-Z (and a-z) are considered letters
        - Word are formed by consecutive letters
        - Sentences end with '.', '!' or '?'
        - Lines end with LF=^J=0x0A=10 or the end of file

HELP:   Count -? 
        displays some help lines.

EXIT CODES:
        0     No error
        1     No source file
        2     File not found


***********
**  CPY  **
***********

DESCRIPTION:   Copy group of files 

USE:           Cpy [options] source [target] 

ACTION: Copy the 'source' directory or files ('*' and '?' may be used)
        to the 'target' (or the current) directory. By default the copy
        continues into subdirectories and includes hidden and system
        files. 
          If the destination disk is full, the user is prompted and has
        the opportunity to change the disk (or skip a long file).
        Memory is used to copy groups of files and allow for multiple
        copies (very useful when copying from floppy to floppy).
          It is possible to select only files older than a given date, or 
        only those already exiting, or only those having being modified,
        and to be prompted for individual files.
          Directories are created as necessary.
          Include the best features of XCOPY and REPLACE and some more.
          It is especially useful in systems with a single floppy drive
        and the number of disk swaps is minimum.
          It may be used for backup copies, because it may use and set
        the 'archive' flag, which is also used by other backup utilities.
        
OPTIONS:
        Options may be grouped and appear anywhere in the command line.
        They are case insensitive and start with '-' or '/':
        -? (or any error) open this help topic 
        -1 Copy one file each time (what for?!)
        -A Copy  only files modified after the last copy with Cpy,
           XCOPY, BACKUP, etc., i.e., files with the 'archive' flag set
        -B Reset 'archive' flag after copy
        -C Prompt the user to confirm the copy of each file
        -R Overwrite read-only files with no warning. Otherwise you are
           prompted before replacing them.
        -D Only files exiting in destination
        -N Only files not existing in target
        -Y Put all files in the same directory
        -F mm-dd-yy Only files from this date on
        -E Check only if files are equal
        -K Multiple copies
        -M Only modified or missing files
        -O Only older files!
        -H Exclude hidden and system files
        -P Pause before start copying
        -S Do not follow into subdirectories
        -V Copy void directories
        -U Source and target unit are the same
        -X Delete source after copy
        -W Wait for a key before exiting
        -T directory Another way to indicate the target directory

EXAMPLES:
        - CPY -dm . a:\backup
        copies the files from the current directory that are newer 
        than files already located in a:\backup
        - CPY /TO \ a:
        copies all files and directories to drive A:. If the latter
        is the current drive, CPY will prompt you to change the 
        floppy disk when necessary.
        - CPY a:\*.sys a: -s -f 1-31-96
        copies all files which are located in the root directory of
        the a: drive (and not in any directory), have .sys extension 
        and are not older than 1-31-96.
        
NOTES:  - By default, the copy continues into the subdirectories, which
        are created in the target if they are not void in the source.
        - By default hidden and system files are copied, and read-only
        files are overwritten after a warning.
        - It is possible to check files for equality.
        - Files may be copied or moved.
        - It is optimized to minimize the disk swapping.
        - There are options to make backup copies.

HELP:   Cpy -? 
        displays some help lines.

KNOWN BUGS AND LIMITATIONS:
        - It is not possible to rename files.
        - Critical errors are ignored.
        - It cannot deal with files longer than the destination disk.

EXIT CODES:
          0 No error. Includes using /?.
          1 User break.
          2 Unknown option.
          4 No source.
          8 Not enough memory.
         16 Invalid date.
         32 Bad source.
         64 Some options are invalid because source = target.
        128 File errors: creation, opening, etc.


***********
**  CUT  **
***********

DESCRIPTION:    Extract some columns, rows, fields or bytes from a file    

USE:    Cut /{b|c|f|r}n1[-n2][,n3[-n4] ...] [/dc] [file]

ACTION: Puts in the standard output the selected 'b'ytes, 'c'olumns, 
        'f'ields or 'r'ows from the standard input (or from 'file').

OPTIONS:
        Options are case insensitive and may appear in any place and
        start by '-' or '\\'
        By default the field delimiter is the Tab character, but it may be 
        changed to the character 'c' by using '/dc' or to the space with 
        '/d" "'.

EXAMPLES:
        - Cut -c1-3,5 text.txt >new.txt
        copies columns 1,2,3 and 5 form text.txt and send then to new.txt
        - Cut -f2,5-7 -d" " < in > out
        copies the 2nd, 5th, 6th and 7th words from each line of in and 
        send them to out

HELP:   Cut -? 
        displays some help lines.

KNOWN BUGS AND LIMITATIONS:
        - If a field is lacking from some lines, additional separators
          could be sent to the output.
        - Bytes, columns, fields and rows must be between 1 and 2097152.

EXIT CODES:
          0 No error. Includes using -? or /?.
          1 User break.
          2 Unknown option.
          4 Bad syntax.
          8 Could not open the file.
         16 Invalid numeric value.

RELATED PROGRAMS: Paste, Sort.


*************
**  DETAB  **
*************

DESCRIPTION:    Substitutes spaces for Tabs   

USE:    Detab [/Dn] [/Ts] [[<]source] [[<]destination]      

ACTION: replaces tabulators with spaces.

OPTIONS:        Options are case insensitive and may start also by '-':
        '-Dn' To have tabulators at columns 1, 1+n, 1+2n, etc.
        '-Ts' To have tabulators as indicated in 's': a sequence of 
              strings separated by ',' and having the form 'n0[:ni[:nm]]': 
              tabulators at column 'n0' and, if 'ni' is used, n0+ni, 
              n0+2ni, etc. The last tabulator will not exceed column 'nm' 
              or the maximum line length: 1048576.
        If no option is used, '-D8' is assumed.
        The complete file specification of 'source' and 'destination' are
        optional and default to the standard input and the standard 
        output, respectively.

EXAMPLES:
        - Entab in out
        puts tabulators at columns 9, 17, etc., and replaces them with
        spaces.
        - Entab -t2,5,10:10 <in >out
        puts tabulators at columns 2,5,10,20,30, etc.
        
HELP:   Detab -? 
        displays some help lines.

KNOWN BUGS AND LIMITATIONS:
        - It is assumed that the file contains only ASCII text and
        special characters are ignored.
        - If the last characters is Ctrl+Z, it is not copied to
        destination.

EXIT CODES:
         0 No error. Includes using -? or /?.
         1 User break.
         2 Bad syntax.
         4 Unknown option.
         8 Could not open the file.
        16 Invalid number.

RELATED PROGRAMS: Entab, Trail.

*************
**  ENTAB  **
*************

DESCRIPTION:    Substitutes Tabs for spaces   

USE:    Entab [/Dn] [/Ts] [[<]source] [[<]destination]      

ACTION: replaces spaces with tabulators.

OPTIONS:        Options are case insensitive and may start also by '-':
        '-Dn' To have tabulators at columns 1, 1+n, 1+2n, etc.
        '-Ts' To have tabulators as indicated in 's': a sequence of 
              strings separated by ',' and having the form 'n0[:ni[:nm]]': 
              tabulators at column 'n0' and, if 'ni' is used, n0+ni, 
              n0+2ni, etc. The last tabulator will not exceed column 'nm' 
              or the maximum line length: 1048576.
        If no option is used, '-D8' is assumed.
        The complete file specification of 'source' and 'destination' are
        optional and default to the standard input and the standard 
        output, respectively.

EXAMPLES:
        - Entab in out
        puts tabulators at columns 9, 17, etc.
        - Entab -t2,5,10:10 <in >out
        puts tabulators at columns 2,5,10,20,30, etc.
        
HELP:   Entab -? 
        displays some help lines.

KNOWN BUGS AND LIMITATIONS:
        - It is assumed that the file contains only ASCII text and
        special characters are ignored.
        - If the last characters is Ctrl+Z, it is not copied to
        destination.

EXIT CODES:
         0 No error. Includes using -? or /?.
         1 User break.
         2 Bad syntax.
         4 Unknown option.
         8 Could not open the file.
        16 Invalid number.

RELATED PROGRAMS: Entab, Trail.

****************
**  FILECOMP  **
****************

DESCRIPTION:    Compares lines from files

USE:    FileComp [options] file1 file2

ACTION: compares lines from file1 with those in file2.

OPTIONS:
        Options are case insensitive, may appear anywhere and start with 
        '-' or '/':
        /B      Ignore trailing blanks.
        /C      Case insensitive compare.
        /F      Show full lines.
        /S      Ignore spaces and tabs.
        /T      Expand tabs before comparing.
        'file2' may be a drive or directory name.

EXAMPLES:
        - FileComp file a:
        compares the lines of file with those in a:file and show the
        first few characters of different lines.
        - FileComp -c -f file1 file2
        after a case insensitive compare it shows the full lines which
        do not match.

HELP:   FileComp -? 
        displays some help lines.

KNOWN BUGS AND LIMITATIONS:
        - Only the first 524,288 lines are compared.
        - Only the first 102,400 characters of each line are taken into
          account.

EXIT CODES:
        0 if files were equal,
        1 otherwise.


************
**  HEAD  **
************

DESCRIPTION:    Dumps the first few lines or characters of a file    

USE:    Head [/n] [/b] [file ...]

ACTION: dumps to the standard output the first 10 (or 'n') lines (or
        'b'ytes) from the standard input (or from file ...)

OPTIONS:        Options are case insensitive and may start also by '-':
        -number dumps the first 'number' lines or characters.
        -b      dumps the first bytes, instead of the first lines.

DELIMITER:
        's' may be any character string (it should be enclosed between
        
        
EXAMPLES:
        - Head -b -5 <in >out
        send to out the first 5 characters of in.
        - Head <in
        shows in the screen the first 10 lines of in.
                
HELP:   Head -? 
        displays some help lines.

EXIT CODES:
         0 always.

RELATED PROGRAMS: Tail.

*************
**  PASTE  **
*************

DESCRIPTION:    Merge lines from different files.

USE:    Paste [/dc] {file | -} ...

ACTION: Put in the standard output the lines from the specified files
        (or from the standard input if '-' has been used) separated by 
        a tabulator (or a space if '-d" "' is used, any character 
        string 's' with '-ds' or '-d s' and even no character if 
        '-d ""' is specified).

OPTIONS: Options are case insensitive and may start by '-? or '/':
        -d" "   paste lines with a space.
        -dc     paste lines with the character 'c'.
        -d      put lines side by side with no separator.

DELIMITER:
        's' may be any character string and it should be enclosed 
        between double quotation marks if it contain spaces, 
        tabulators or other special characters. The following
        C-like escape sequences are allowed:
        Sequence  C form  Value   Meaning
        \'n'              'n'     Explicit decimal value
        \a        \a      7       Bell character
        \b        \b      8       Backspace
        \e                27      Esc character
        \f        \f      12      Form feed
        \n        \n      10      New line (line feed)
        \r        \r      13      Carriage return
        \o'n'     \'n'    'n'     Explicit octal value
        \t        \t      9       Horizontal Tab
        \v        \v      11      Vertical Tab
        \x'n'     \x'n'  'n'      Explicit hexadecimal value
        \z                0       Null character
                 
EXAMPLES:
        - Paste file1 file2 file3 >file4
        send to line4 the lines from file1, file2 and file3 joined by
        tabs.
        - Paste file1 file2
        append to the lines of file1 those of file2 and show them on the
        screen.
        - Paste -d\z file1 file2
        append to the lines of file1 those of file2 with no delimiter 
        and show them on the screen.
        - Paste -d "\n" file1 file2     
        show on the screen each line of file1 followed by the 
        corresponding line of file2.

HELP:   Paste -? 
        displays some help lines.

KNOWN BUGS AND LIMITATIONS:
        - Not more than 25 files can be specified and the end of any of
          them stops the process.
        - The resulting line may not be longer than 1048576 characters.

EXIT CODES:
         0 No error. Includes using -? or /?.
         1 User break.
         2 Unknown option.
         4 Bad syntax.
         8 Too many files.
        16 Could not open the file.

RELATED PROGRAMS: Cut.


************
**  SORT  **
************

DESCRIPTION:    Sort and merge utility.

USE:    Sort [options] [file...]

INPUT FILE(S):
        - If no input file is indicated, Sort will read lines from
          the standard input which can be the keyboard or a redirected 
          input file. So:
                Sort
          will read lines from the keyboard. (To end entering lines, 
          press Ctrl-Z and Enter.)
        - On the other hand,
                Sort < filename
          will read the specified filename, and
                program ... | Sort 
          will read the output from another program. This allows 
          using Sort as a filter. 
        - Alternatively, one or more file names can be specified in 
          the command line. For example:
                Sort file
                Sort file1 file2 file2
                Sort *.txt read.??
          As indicated in the last example, the '?' and '*' wildcards
          can be used.

OUTPUT FILE(S):
        - By default, the Sorted/merged output will be sent to the 
          standard output which can be the screen or a redirected
          output file. So:
                Sort
          will write the output to the screen, while
                Sort > file
          will send it to file, and 
                Sort | program
          will allow program using the output of Sort. This allows 
          using Sort as a filter. 
        - You can also use the /O (or -O) option to specify the 
          output file:
                Sort -o file
          will write to 'file'.

OPTIONS: 
        Option  Meaning
        ------  -------
        /A      Pure (extended) ASCII/ANSI order.
        /B      Ignore starting blanks.
        /C      Use CombSort method instead of QuickSort.
        /D      Dictionary order (spaces are ignored).
        /E      Espaol: ch and ll are single letters.
        /F      Sort the first number by its floating point value.
        /H      Use HeapSort method instead of QuickSort.
        /I      Use insertion method (slow but stable).
        /M      Merge previously Sorted 'files'.
        /N      Sort the first number by its integer value.
        /O file Output result to 'file'.
        /Q      Use the (default) quickSort method.
        /R      Sort in reverse order.
        /S      Use Shell method.
        /X n    Maximum line length.
        /W      Use Windows' ANSI chars.
        /Z      Appends to the final file an ASCII null character.
        /n      Start Sorting by the n-th column (n = 1, 2, ...)

        Options can be grouped       : /HTZ is equivalent to /H /T /Z 
                are case-insensitive : /H   is equivalent to /h
                start by '/' or '-'  : /H   is equivalent to -H

Sort METHOD:
        By default Sort uses a sophisticated version of Hoare's 
        QuickSort, which is the faster general purpose Sorting 
        algorithm. But using one of the following options you can select 
        another method:
        Option  Method
        ------  ------
        /C      CombSort (R. Box and S. Lacey, Byte April 1991 p.315)
        /H      HeapSort
        /I      Insertion
        /Q      QuickSort
        /S      Shell

        - All methods, except Insertion, are 'unstable', i.e., they may 
        change the relative order of lines having the same 'value'. 
        This is could be a problem when performing a second Sorting on 
        an already Sorted file. For instance, if you Sort alphabetically
        a file starting at column 8, and then by the number in the 
        first column, you might end with two lines as follows: 
                3       Last 
                3       First 
        instead of the desired order (because L comes after F): 
                3       First 
                3       Last 
        To overcome this, you must use the insertion method in all Sorts
        but the first. Unfortunately, this method (which is the only one 
        used by the DOS Sort utility) is very very slow, except for very
        short files. 

MERGING FILES:
        - If you want to merge already Sorted files, use the /M option. 
        Merging will be automatically used if the program ran out of 
        memory and sent partial files to the disk.

SORTING ORDER:
        By default, files are Sorted:
         - in ascending order,
         - starting from the first character in each line,
         - using the PC extended character set (also called the OEM set),
         - as text files and using all characters in the line, but, if the 
           /A option is not used some identifications are made. 
           For instance, upper-case letters and the corresponding 
           lower-case (and accented) letters are identified.  is 
           after N and all characters that are not letters or digits are 
           equivalent to a space. 

        Option  Meaning
        ------  -------
        /A      Pure (extended) ASCII/ANSI order. Characters that are not letters.
                or digits are not equivalent to spaces; a, A, and  are different, etc. 
        /B      Ignore starting blanks. 
        /D      Dictionary order (spaces are ignored). 
        /E      Espaol: the ch and ll digrams are single letters. This option has 
                become obsolete, because of the resolution taken by the Academies of 
                all Spanish-speaking countries in May 1994.
        /F      Sort the first number by its floating point value. 
        /N      Sort the first number by its integer value. 
        /R      Sort in reverse (descending) order.
        /W      Use Windows ANSI character set, instead of the DOS set. 
        /n      Start Sorting by the n-th column (n = 1, 2, ...) The first n-1 columns 
                will be skipped.

NOTES:  You could consider using Sort because:
        - Sort is free. 
        - The Sort utility that comes with every DOS copy is very slow
          and can handle only very small files. 
        - Sort is more powerful than all other shareware/freeware Sort 
          programs I have been able to test. 
        - It is a true 32 bits program, so it runs quickly and is able 
          to use all the memory to deal with large files. After using 
          all the memory, the disk will be used as virtual memory.
        - Sort can use different Sorting algorithms ranging from the 
          fast QuickSort to the stable Insertion Sort. 
        - It can be used to Sort files using the PC or the Windows ANSI 
          character set.
        - It can be used to Sort non-English files. 

HELP:   Typing        Sort /?
                      Sort /h
        will display a help screen with the usage and options.

KNOWN BUGS AND LIMITATIONS:
        - By default, Sort will ignore the Ctrl-Z characters appearing
        at the end of some text files (some programs still adhere to 
        this old CP/M convention!). If you want such a character 
        appended at the end of the output file, use the /Z option.
        - By default, Sort may read lines whose length does not exceeds 
        10240 characters. Lines longer than this limit are split in two 
        (or more) pieces. This will produce more lines (some of them 
        shorter, of course) in the output file. Using the /X n option you 
        instruct Sort to use lines of length <= n-2 (the last two 
        characters are necessary to hold the newline and null characters), 
        with n <= 4294967295.

EXIT CODES:
        When an error happens, Sort will terminate with a non-zero exit 
        code and issue one of the following messages:
        Code Message                         Meaning
        ---- -------                         -------
          0  (none)                          Successful operation
                                             (includes using
                                             /? or -?)
          1  User break                      Break or Ctrl-C was used 
          2  Output file name missing        After the /O option a file
                                             name is required
          4  Can't open 'filename'           An input file was not present
          8  Invalid option: 'o'             An unknown option was used
         16  Can't handle more than n files  The program ran out of files
                                             to Sort a very large file
         32  Not enough free file handles    The program ran out of file 
                                             handles to 
                                             Sort a very large file 
         64  Memory exhausted                There was not enough memory
                                             to read a text line
        128  Stack overflow.                 The program ran out of stack 
                                             space when  Sorting a very 
                                             large file. 
                                             Try another sort method.

RELATED PROGRAMS: Cut, Paste.


************
**  TAIL  **
************

DESCRIPTION:    Dumps the last few lines or characters of a file    

USE:    Tail [/n] [/b] [file ...]

ACTION: dumps to the standard output the last 10 (or 'n') lines (or
        'b'ytes) from the standard input (or from file ...)

OPTIONS:        Options are case insensitive and may start also by '-':
        -number dumps the last 'number' lines or characters.
        -b      dumps the last bytes, instead of the first lines.
        
EXAMPLES:
        - Tail -b -5 <in >out
        send to out the last 5 characters of in.
        - Tail <in
        shows in the screen the last 10 lines of in.
                
HELP:   Tail -? 
        displays some help lines.

EXIT CODES:
         0 always.

RELATED PROGRAMS: Head.

*************
**  TRAIL  **
*************

DESCRIPTION:    Fixes end of lines

USE:    Trail [<input] [>output]        

ACTION: to send to output the lines from input with their trailing spaces and
        tabulators deleted. A single LF character is paired with a CR.

EXAMPLES:
        - Trail in > out
        send to out the lines from in with the trailing spaces and
        tabulators removed. End of lines are also fixed if necessary
        (for instance, if it was a Unix file).

HELP:   Trail -? 
        displays some help lines.

KNOWN BUGS AND LIMITATIONS:
        - A Ctrl+Z is not copied and ends the conversion.
        - Lines cannot be longer than 1048576 characters.

EXIT CODES:
        0 No error. Includes using -? or /?.
        1 User break.

RELATED PROGRAMS: Entab, Detab.

