+-----------------------------------------------------------------------------+
|                                                                             |
|                                                                             |
|                                 XSORT 3.01                                  |
|                                  SORT 3.01                                  |
|                                                                             |
|                                                                             |
|              A program (and filter) to quickly sort and merge               |
|                  ASCII / Extended ASCII / ANSI text files                   |
|               (even in non-English languages) of any length                 |
|                                                                             |
|                                                                             |
|                           Juan M. Aguirregabiria                            |
|                                                                             |
|                     Fisika Teorikoa. Zientzi Fakultatea                     |
|                        Euskal Herriko Unibertsitatea                        |
|                        P.K. 644, 48080 Bilbo (Spain)                        |
|                        Internet: wtpagagj@lg.ehu.es                         |
|                                                                             |
|                                                                             |
|                                  May 1994                                   |
|                                                                             |
+-----------------------------------------------------------------------------+

=========
Copyright
=========
The programs XSORT.EXE and SORT.EXE and this documentation file XSORT.TXT are 
copyrighted: 

                Copyright (c) Juan M. Aguirregabiria 1992-1994
                              All rights reserved

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


========
FreeWare
========
Sort is FreeWare; there is no charge for using it and it may be distributed 
freely so long as the files are kept together and unaltered. You may neither 
sell nor profit from distribution of Sort in any way, without the written 
permission from the Author. 


==========
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 this 
program, 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 XSORT you need a 386/486/Pentium compatible computer.
To run  SORT any compatible computer can be used.


=========
File list
=========
XSORT 3.01 is composed by the following four files:

XSORT.TXT       This documentation file
SORT.EXE        The 16 bits executable
XSORT.EXE       The 32 bits executable
DOS4GW.EXE      The DOS extender for XSORT.EXE


============
Introduction
============
XSORT (and its 16 bits version SORT) is a yet another sort/merge utility!
You could consider using it because:

1. XSORT is free. 
2. The SORT utility that comes with every DOS copy is very slow and can handle
   only very small files. 
3. XSORT is more powerful than all other shareware/freeware sort programs I 
   have been able to test. 
4. It is a true 32 bits program, so it runs quickly and is able to use all the 
   conventional/expanded/extended memory to deal with large files. After using 
   all the memory, the disk will be used as virtual memory. Even the 16 bits 
   SORT, which can be used in any compatible computer, will use the disk to 
   handle large files. 
5. XSORT can use different sorting algorithms ranging from the fast Quicksort 
   to the stable Insertion sort. 
6. It can be used to sort files using the PC or the Windows ANSI character set.
7. It can be used to sort non-English files. 


============ 
Installation 
============ 
If your computer is a 8086, 80186 or 80286, you can only use the SORT.EXE 16 
bits program. If you use an 386/484/Pentium computer, you may want to install 
SORT.EXE, which can be faster for small files, and/or XSORT.EXE, which is far 
more efficient for large files. 

To install the 16 bits version:
1. Copy SORT.EXE to some directory in your path.
2. To make sure that SORT.EXE is used instead of the SORT.EXE utility provided
   with your DOS copy you should:
   - Delete the DOS SORT.EXE (you will not miss it!), or
   - Rename the DOS SORT.EXE (to, say, DOSSORT.EXE), or
   - Rename this SORT.EXE
   - Make sure that the directory of this SORT.EXE appears in your path
     before the DOS utility.

To install the 32 bits version:
1. Copy XSORT.EXE to some directory in your path.
2. If you do not have in your disk a more recent copy of DOS4GW.EXE (which 
   comes with some programs), copy it to some directory in your path. 


===========
Using XSORT
===========
        Use:    XSORT [/options] [file...]
         or:     SORT [/options] [file...] 


============
Getting help
============
Typing        XSORT /?
              XSORT /h
               SORT /?
               SORT /h
will display a help screen with the usage and options.


=============
Input file(s)
=============
If no input file is indicated, XSORT will read lines from stdin which can 
be the keyboard or a redirected input file. So:
        XSORT
will read lines from the keyboard. 
(To end entering lines, press Ctrl-Z and Enter.)
On the other hand,
        XSORT < filename
will read the specified filename, and
        program ... | XSORT 
will read the output from another program. This allows using XSORT as a filter. 

Alternatively, one or more file names can be specified in the command line.
For example:
        XSORT file
        XSORT file1 file2 file2
        XSORT *.txt read.??
As indicated in the last example, the ? and * wildcards can be used.


============
Output files
============
By default, the sorted/merged output will be sent to the stdout which can 
be the screen or a redirected output file. So:
        XSORT
will write the output to the screen, while
        XSORT > file
will send it to file, and 
        XSORT | program
will allow program using the output of XSORT. This allows using XSORT as a 
filter. 
You can also use the /O (or -O) option to specify the output file:
        XSORT -o file
will write to file.


======= 
Options 
======= 
XSORT options are the following:

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.
/T      Inform the user of program's state each other second.
/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 XSORT 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 perfoming 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 short files. 


=============
Merging files
=============
If you want to merge already sorted files, use the /M option. Merging will be 
automatically used when the program (probably SORT) 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.


========================
Ending Ctrl-Z characters
========================
By default, XSORT 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.


========================
Dealing with large lines
========================

By default, XSORT may read lines whose length does not exceeds 10240 
characters, while SORT is limited to 1024 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 XSORT to use lines of length <= n-2 (the last two characters are 
necessary to hold the newline and null characters), with n <= 4294967295 in 
XSORT and n <= 65535 in SORT.


=============================
Dealing with very large files
=============================
XSORT and SORT are able to deal with very large files. After using all the 
conventional (and, in the case of XSORT, all virtual memory including extended
memory) they will write to the disk partial output files and then merge them.
When dealing with very large files:
 - Use XSORT if you have a 386 or more powerful computer.
 - Use the /T option if you want to be kept informed each other second of the 
   program state.
 - Consider using BREAK ON as discussed below


====================
Stopping the program
====================
When the program is sorting/merging files, it can be stopped by pressing the 
ESC key. This method does not work when reading or writing files, because it 
proved to be very dangerous. If you want to stop the program when it is 
accessing the disk, before starting it use the DOS command:
        BREAK ON
Then pressing Break or Ctrl-C will abort the operation.


============================= 
Error messages and exit codes 
============================= 
When an error happens, XSORT or SORT will terminate with a non-zero exit code 
and issue one of the following messages:

Exit 
code Message                         Meaning
---- -------                         -------
  0  (none)                          Successful operation (includes using
                                     /? or -?)
  1  User break                      ESC, 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 
     Try using /Q, /H or /C!   sorting a very large file. Try another 
                                     sort method.


====================
Suggestions and bugs
====================
The Author would gratefully welcome information about any bug or problem found 
in the program. Suggestions to improve XSORT in future versions are also 
welcome. Write to: 

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


===================================
Other programs from the same author
===================================

Sinfo
-----
Sinfo is designed to help Windows programmers by providing information on many 
aspects of Windows. It can display full information on current classes, 
windows, modules and tasks. There are some advanced (though highly risky) 
commands to unload modules and libraries and to free leaked memory. You can 
also examine and save to a file the contents (or the hex dump) of any global or 
local heap block. It is possible to see (and terminate) hidden tasks. It can 
also be used as an advanced substitute for the Task Manager (in this way it can 
be accessed very quickly). Hidden tasks can be optionally listed and you can 
hide (and shown again) windows and make them a top most window (or delete this 
property). For instance, some DLL libraries cannot be simultaneously used for 
more than one program. If the program crashes, the library may be left in 
memory and cannot be reused without restarting Windows. The knowledgeable user 
can use Sinfo to free it. This possibility is especially useful when developing 
programs, but it has also helped us with a very known commercial package which 
crashes repeatedly leaving a library in memory. When developing programs (or 
testing other people's applications) it is not difficult to get the cursor 
lost. Sinfo can recover it for you. 

Toolbar
-------
Toolbar is intended to provide some features that I found lacking in the 
Program Manager and File Manager of the retail Windows 3.1. To start with, 
while working in File Manager, you can drag an item and drop it over some 
running programs. But if one of these programs is not running and you drop the 
item over its icon, the program is not started. Instead, the dropped item is 
added to the corresponding group of Program manager. Of course, sometimes this 
is just what you wanted. One could say that the groups in Program manager were 
meant more for organization of programs than for running them. On the other 
hand, most programs still lack the ability to accept dropped files and you 
cannot use with them this drag and drop feature. 
Since my screen tends to be cluttered with windows, I also wanted the ability 
to place (in a permanent and compact way) at a corner of the screen the 
utilities I used most often. Program Manager groups are nice but big and I do 
not need to see the names of my favorite utilities: I can easily recognize them 
by their icons. The utilities should always be at hand - ready to be started by 
double-clicking them (as in Program Manager) or by dropping an item on them. 
For instance, this is a nice way to provide the most important facility missing 
in File Manager: a file viewer. 
Toolbar is the answer to these wishes. It provides an alternative to the groups 
of Program Manager with the following distinctive characteristics:
It can be used either as a substitute for Program Manager (which, in turn, can 
be run from Toolbar), or as a normal application installed in Program Manager 
(or in the current shell program). 
It is better suited for running programs: there are multiple ways of running 
programs and advanced settings can be used. 
All programs in a toolbar are always visible (as long as the whole window is on 
the screen). They are held together in a very compact way, to be as unobtrusive 
as possible. Optionally, you can force a toolbar to be always visible on top of 
other windows. In order to save space, the title bar can be suppressed (or 
displayed to have useful information at hand).
Items from File Manager can be dropped on any program installed as a tool. It 
only needs to be able to accept file names on the command line. Most MS-DOS and 
Windows programs have this ability. A program can also be started by double-
clicking (or single clicking the right button), or by using the ENTER key, or a 
user selected accelerator key.
You can choose between running an instance of the program for each dropped 
file, or running a single instance of the program for all of the dropped files.
Programs can be easily added, removed and reordered. The corresponding caption, 
command line, working directory, icon and other options can be easily changed.
You can implement a full tree of nested toolbars.
You can drag files to and from Toolbar. Program Manager does not allow dragging 
of  its elements outside of its windows.
Utilities (small utility programs that use a toolbar button as its display 
window) make Toolbar more compact and extensible. A few are provided with 
Toolbar: trashcan, alarm clock, menu, memory, resources, information and blank 
icon. Additionally, new utilities can be added by the user (the programming
interface is fully documented and sample source code is included).
Toolbar supports most of the same user interface as Program Manager.
Toolbar is able to transparently use (and to translate to its own format) group 
files from Program Manager.
And more!

