home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / LS321.ZIP / LSORT.HLP < prev    next >
Text File  |  1990-09-22  |  16KB  |  430 lines
  1. LSORT 3.20 (C) Copyright London Computing, 1983,1984,1985,1986,1987,1988,1990.
  2. All rights reserved.
  3.  
  4. LSORT is a general purpose sort/merge utility written in Microsoft C 5.1.
  5. It runs on IBM PCs and compatibles with at least 192KB and either two floppy
  6. disks or a fixed disk.  It runs best when there is at lease 320KB available.
  7.  
  8. LSORT is User Supported Software,  if this program proves useful, please
  9. make a contribution ($25 suggested) to:
  10.  
  11. London Computing, P.O. Box 696  Cherry Hill, NJ 08003
  12.  
  13. Anyone sending a contribution will receive a disk containing the source code
  14. to LSORT as well as a copy of the LSRT sort filter.  LSRT is similar to the
  15. DOS SORT filter but works much faster and will sort on multiple fields.
  16.  
  17. You may make copies of this software and distribute to other users as long as
  18. there is no charge or other consideration and this notice is not removed or
  19. bypassed.
  20.  
  21. LSORT will sort MSDOS files and dBase II and dBase III databases. (dBase III
  22. memo files are not sorted but .DBF files will be sorted.)  Each file may be
  23. sorted using 1 to 32 sort fields. The file to be sorted may contain either
  24. fixed length records, variable length records or comma delimited records.
  25. Variable length records are records ending with cr/lf. Comma delimited records
  26. are variable length records where the fields are also variable length and
  27. separated by a comma. Character fields may be enclosed in either single or
  28. double quotes. It will merge up to 5 files using 1 to 32 sort fields. dBase
  29. databases may not be merged. Any field may be sorted in either ascending or
  30. descending sequence. LSORT allows for three user defined field types to be
  31. used: X,Y and Z. You must write your own comparison subroutine to compare user
  32. defined fields.
  33.  
  34. The sort knows about:                       field type
  35.  
  36. character fields (to 127 bytes)                   C
  37. upper case character fields (sort fields are      U
  38.    translated to upper case before compare)
  39. 2 byte integers in internal  format               I
  40. 4 byte integers in internal format                L
  41. floating point numbers (ieee)                     F
  42. double precision floating point (ieee)            D
  43. zoned decimal  numbers                            N
  44.    (Text format numbers,  Decimals are allowed)
  45.    (LSORT now supports scientific notation as)
  46.    (well, using E notation, eg. .98 == 9.8E-1)
  47. 1 byte logical fields (dBase II or III)           T
  48. User defined field type X                         X
  49. User defined field type Y                         Y
  50. User defined field type Z                         Z
  51.  
  52. A zoned decimal number is stored as a character string and may contain
  53. leading and trailing spaces, minus sign, decimal point and digits.
  54.  
  55. NOTE: zoned decimal numbers sort very slowly!
  56. The only reasonable field types for comma delimited files are C or N. LSORT
  57. will accept other field types, but the results are undefined.
  58.  
  59.  
  60. LSORT will prompt you for all parameters and file names or you may specify
  61. some or all of the parameters on the command line when you invoke the sort.
  62.  
  63. The maximum record length is 4096 bytes.  Files will be sorted in memory if
  64. possible.
  65.  
  66. Files larger than available memory are sorted in pieces and then merged
  67. together.  If you have a floppy only system, you should have LSORT on the A
  68. drive and the file to be sorted on the B drive.  Place a copy of LSORT on an
  69. otherwise empty disk and use as your A drive.  You may need a formatted empty
  70. disk for work files on the B drive.
  71.  
  72.  
  73. SYNTAX:
  74.  
  75.  
  76. LSORT [-h | -m] -- will prompt you for all necessary information.
  77.  or
  78. LSORT [-h | -m] sort specifications--will take the specification specified and
  79.                                   prompt you for any others.
  80.  
  81. Specify -h if you are using a fixed (hard disk) for your output and merge
  82. files. This will eliminate mount messages. This is the default for LSORT 3.01.
  83. Specify -m if you are using mountable disks (floppy, Bournouli, etc.).  This
  84. allows you to mount disks to contain work files and output files.
  85.  
  86.  or
  87.  
  88. LSORT -R  -- will restart a sort.
  89.  
  90.  
  91. Sort Specifications:
  92.  
  93. You will be asked to specify either a SORT or MERGE operation.
  94.  
  95. If you ask for a SORT, you may tell LSORT to use either a QUICKSORT or
  96. HEAPSORT for internal sorting.  You will also be asked to specify two
  97. devices to hold merge files if any are needed.  Merge files may be placed on
  98. floppy disk, hard disk or RAM disk.  The specified drive must be large
  99. enough to hold the entire input file.  You will be given the opportunity to
  100. change floppy disks if desired before each merge drive is used and before
  101. the output file is written.  The program will wait for you to press 'Y'
  102. before proceeding.  This is not really a problem for unattended sorting
  103. if you use redirected input or specify all prompts on the command line.
  104.  
  105. If you specify SORT or MERGE you will be prompted for your input file(s) and
  106. output file as well as the definition of the key fields to be used in the
  107. comparisons.  Fields are specified by their starting position and length.
  108. The types of fields have been listed above.
  109.  
  110. The sort specifications may be entered on the command line in the order
  111. requested by LSORT. Each parameter should be separated from the others with
  112. one or more spaces.  You will not be prompted for any specification on the
  113. command line (including requests to change disks).
  114.  
  115. The sort will ask for the following information in the order shown:
  116.  
  117. Type of Sort:  You may reply:
  118. S -- for QUICKSORT
  119. H -- for HEAPSORT
  120.  
  121. Merge Drive 1:  You may reply with any drive letter, although it is best to
  122. specify a fixed disk (if any).
  123.  
  124.  
  125. Merge Drive 2:  This should be different from drive 1 if you are using
  126. floppy disks, but should be a fixed disk if you have one.
  127.  
  128. Name of input file: You may specify any name including drive letter and
  129. path.  Specify :X to use a user specified input routine.
  130.  
  131. Name of output file:  See above.  Specify :X to use a user specified output
  132. routine.
  133.  
  134. File Type (Unless you are sorting a dBase file):  You may reply F for a
  135. fixed length file (all records are the same length), V for a varying
  136. length file (records must end with CR LF.) or D for comma delimited files.
  137.  
  138.  
  139. If you entered 'F' for a fixed file, you will be prompted for the record
  140. length.
  141.  
  142. You will then be prompted for field definitions.  Each field definition has
  143. four parts:    starting position (from 1)  or  starting field (delimited files)
  144.                field length (in bytes)         (no prompt for delimited files)
  145.                field type (See above list of valid types)
  146.                sort order (A--Ascending, D--Descending)
  147.  
  148. In order to work as efficiently as possible, LSORT does not check the
  149. starting position of a field against the actual length of a record.  If some
  150. field starts past the end of a record (e.g. sort field 1 starts in column 10
  151. but the record is only 8 bytes long), the results will be undefined and most
  152. certainly not what you want.  Please be careful.
  153.  
  154. Enter a '0' for the starting position to end the prompt for field
  155. definitions.
  156.  
  157. If you are sorting a dBase file, you will see a list of fields.  You may
  158. specify a field by name, in which case you will only be prompted for the
  159. sort order or you may enter starting position, length, type and order as
  160. above.
  161.  
  162. Following the '0' that ends field definitions, you may specify a series of
  163. 'Y's if you know that the disks currently mounted will hold merge work files
  164. and the output file.  These may be omitted if you specified the -H flag.
  165.  
  166. example 1:
  167.  
  168. Sort file test.dat on positions 1-5,char,ascending and 6-7, binary integer,
  169. descending.  Use drive C for the work files and put the sorted file in
  170. test.srt.
  171.  
  172. Issue the following command:
  173.  
  174. LSORT S C C test.dat test.srt V 1 5 C A 6 2 H D 0 Y Y Y
  175.       | | | |        |        | |_____| |_____| | | | |
  176.       | | | input    output   F |       |       | | | response to mount
  177.       | | | file     file     i sort    sort    | | | output file message.
  178.       | | | name     name     l field 1 field 2 | | |
  179.       | | |                   e starts  starts  | | response to mount 2nd
  180.       | | merge drive 2         at byte at byte | | merge volume message.
  181.       | |                     T 1, is 5 6, is 2 | |
  182.       | merge drive 1         y byte    byte    | response to mount first
  183.       |                       p char-   long    | merge volume message.
  184.       sort using              e acter   integer |
  185.       quicksort                 string  sorted  ends list of sort fields.
  186.                                 ascend- descend-
  187.                                 ing     ing
  188.  
  189.  
  190.  
  191. Merge Specification:
  192.  
  193. Enter 'M' to indicate the merge operation.
  194.  
  195. You will be asked to enter the number of files to be merged followed by 1-5
  196. files to be merged. They are entered one at a time.
  197.  
  198. You will be asked to enter a file type, output file and a field list as
  199. above.
  200.  
  201. example:
  202.  
  203. Merge files t1.dat t2.dat and t3.dat on positions 4-7 defined as a character
  204. field, ascending.
  205.  
  206. LSORT M 3 t1.dat t2.dat t3.dat   test.mrg V 4 4 c a 0 y y
  207.       | | |      |      |        |        | |_____| | |_|
  208.       | | input  input  input    output   | |       | |
  209.       | | file 1 file 2 file 3   file     | merge   | response to mount
  210.       | |                                 | field   | messages
  211.       | merge 3 files                     | 1       |
  212.       |                                   |         end of list of merge
  213.       do a merge                          file      fields
  214.                                           type
  215. Restarting:
  216.  
  217. If a sort stops in the middle due to lack of space or is stopped by you by
  218. pressing ^BREAK, it may be restarted by issuing the LSORT -R command
  219. providing the dataset(s), SORTPARM.DAT and (DB3PARM.DAT for dBase III files
  220. only) are still available and further providing all files LSMERGE?.DAT are
  221. still available. The sort will be restarted at the beginning of the LSSORT
  222. phase (where the input file is read and sorted) or at the beginning of an
  223. LSMERGE pass, where several partially sorted files are combined.
  224.  
  225. User Exits:
  226.  
  227. You may define your own user exits to read and write data and you may define
  228. your own compare routines for the standard field types or for user defined
  229. field types. These routines must be written in Assembler in DeSmet C88 or in
  230. any other language that can be linked to DeSmet C88.
  231.  
  232. User input:  (Available for Sorting Only)
  233.  
  234. Specify :X as the name of the input file. LSORT uses a routine named USERIP
  235. to read the records to be sorted. You may write your own version of USERIP
  236. and link it with LSORT to create a custom version containing your own input
  237. routine.
  238.  
  239. USERIP is used as follows:
  240.  
  241. int l,userip();
  242. char buffer[...];
  243.  
  244. l = userip(buffer);
  245.  
  246. USERIP must return the length of the record read which must be <= 4096 or -1
  247. for end of file. If you have specified V type files, USERIP must return a
  248. string ending with a '\0'. The string length must include the trailing '\0'.
  249.  
  250. User Output:
  251.  
  252. Specify :X as the name of the output file. LSORT uses a routine called
  253. USEROP to write to the :X file. You may write your own user output routine
  254. to be used to write the final sorted or merged output by creating a custom
  255. version of USEROP and relinking LSORT to create a custom LSORT. USEROP works
  256. as follows:
  257.  
  258. int buflen;
  259. char buffer[...];
  260.  
  261. userop(buffer,buflen);     /* userop must write buflen bytes from buffer */
  262.                            /* buflen == 0 means that you want to write a
  263.                               0 terminated string */
  264. userop(NULL,-1);           /* userop must perform end of file processing */
  265.  
  266.  
  267. Sample versions of userip and userop appear below:
  268. /* Userip to return a varying length string */
  269. #define CPMEOF 26
  270. #include "stdio.h"
  271. userip(s)
  272. char *s;
  273. {
  274.  static char firsttime = 1;
  275.  static int inchan;
  276.  char *fgets();
  277.  int l;
  278.  /* input is string buffer, max length 4k, 4k always available      */
  279.  /* this routine must return length of string or EOF if end of file */
  280.  /* example follows: (Note length of string includes 0 byte at end  */
  281.       if (firsttime) {
  282.             firsttime=0;
  283.             inchan=fopen("usertest.dat","r");
  284.       }
  285.       if (fgets(s,4096,inchan))
  286.             return strlen(s)+1;
  287.       else
  288.             return EOF;
  289. }
  290.  
  291. /* Userip to return a fixed length string */
  292. #define CPMEOF 26
  293. #define STRLEN 128
  294. #include "stdio.h"
  295. userip(s)
  296. char *s;
  297. {
  298.  static char firsttime = 1;
  299.  static int inchan;
  300.  char *fgets();
  301.  int c,l;
  302.  /* input is string buffer, max length 4k, 4k always available      */
  303.  /* this routine must return length of string or EOF if end of file */
  304.  /* example follows: (Note length of string includes 0 byte at end  */
  305.       if (firsttime) {
  306.             firsttime=0;
  307.             inchan=fopen("usertest.dat","r");
  308.       }
  309.       if ((l=read(inchan,buffer,STRLEN)) == STRLEN)
  310.             return STRLEN;
  311.       else
  312.             return EOF;
  313. }
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323. userop(s,l)
  324. char *s;
  325. int l;
  326. {
  327. /* s is string to write, l is length or 0 if 0 terminated or -1 for close */
  328.       static char firsttime = 1;
  329.       static int otchan;
  330.       if (firsttime) {
  331.             firsttime = 0;
  332.             otchan = fopen("usertest.srt","w");
  333.       }
  334.  
  335.       if (l == -1 || s == NULL)
  336.             fclose(otchan);
  337.       else if (l) /* write an F type record */
  338.             while(l--) fputc(*s++,otchan);
  339.       else fputs(s,otchan); /* write a V type record */
  340. }
  341.  
  342.  
  343. User Compare Routines:
  344.  
  345. You may define up three user defined fields: X,Y,Z.  You must write a compare
  346. routine for each field type used.  The routine names are:
  347.  
  348.       sxcmp --  for field type X.
  349.       sycmp --  for field type Y.
  350.       szcmp --  for field type Z.
  351.  
  352. The compare routines are called with three arguments, the address of the
  353. first field, the address of the second field and the field length. The
  354. routine must return 1 if field 1 < field 2, 0 if field1 == field2 and -1 if
  355. field1 > field2.
  356.  
  357. Sample routines are shown below:
  358.  
  359. sxcmp(a,b,l)
  360. long int *a,*b;
  361. int l;
  362. { /* this routine compares two long integers */
  363. long int c;
  364. c = *a - *b;
  365. return c <0 ? -1 : c == 0 ? 0 : 1;
  366. }
  367.  
  368. sycmp(a,b,l)
  369. int *a,*b;
  370. int l;
  371. { /* this routine compares two integers (2 bytes) */
  372. int c;
  373. c = *a - *b;
  374. return c <0 ? -1 : c == 0 ? 0 : 1;
  375. }
  376.  
  377.  
  378. szcmp(a,b,l)
  379. float *a,*b;
  380. int l;
  381. { /* this routine compares two floating numbers */
  382. float c;
  383. c = *a - *b;
  384. return c<0 ? -1 : c == 0 ? 0 : 1;
  385. }
  386.  
  387.  
  388.  
  389. Linking user written routines:
  390.  
  391. For MicroSoft C.
  392.  
  393. Compile your user written routines using Microsoft C 5.1 to create .OBJ files.
  394. Modify the file lsort.crf to include your routines before LSORTCMP:
  395.  
  396. lsort.obj +
  397.                   <=== place your routines here
  398. lsortcmp.obj +
  399. lsortdbf.obj +
  400. lsortio.obj +
  401. lsortprm.obj +
  402. lsortqk.obj +
  403. lsortsub.obj +
  404. lssort.obj +
  405. lsuser.obj +
  406. lsmerge.obj 
  407.  
  408. Re-link LSORT with the following statement:
  409. LINK /stack:8192 @lsort.crf;
  410. BIND lsort
  411.  
  412. LSMENU
  413.  
  414. Enter LSMENU instead of LSORT for the menu driven interface.
  415.  
  416. LSMENU will display an SAA like menu that makes it easier to use LSORT.
  417.  
  418. The menuing system uses drop down menus that allow you to:
  419.  
  420. o   Specify the operations (Sort / Merge) to be performed.
  421. o   Specify Work Drives
  422. o   Specify or Pick Input File(s) using a 'point and shoot' interface.
  423. o   Specify or Pick the Output file.
  424. o   Select the records type: (Fixed, Variable, Delimitted or dBase)
  425. o   Specify the Sort Fields using a context sensitive assistant that will
  426.     either display the names of dBase fields or display a file and let you
  427.     mark fields.
  428. o   Save a sort specification in a file for quick re-use.
  429. o   Load a sort specification.
  430.