home *** CD-ROM | disk | FTP | other *** search
/ CICA 1996 August / CICA2_0896.bin / utils / jreader / sortf.doc < prev    next >
Text File  |  1991-09-19  |  13KB  |  340 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                            SORTF File Sorting Utility
  11.  
  12.                            Version 2.37 - Sep 20, 1991
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                                      Index
  19.                                      -----
  20.  
  21.  
  22.                  Purpose  ................................... 1
  23.                   Format  ................................... 1
  24.                   Remarks  ...................................1
  25.  
  26.                  Options summary  ........................... 2
  27.                  Invoking from Quick Basic................... 3
  28.  
  29.                  Examples  .................................. 4
  30.  
  31.                  Version history  ........................... 5
  32.  
  33.                  Usage restrictions  ........................ 6
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.           Copyright (c) Vernon D. Buerg 1985-90. ALL RIGHTS RESERVED.
  54.  
  55.  
  56. SORTF Command                                             Version 2.37  Page 1
  57. -------------                                             Sep 20, 1991
  58.  
  59. Purpose:   The SORTF program reads record data from a file,  sorts the
  60.            records, and writes the data to another file.
  61.  
  62. Format:
  63.            SORTF [d:][path]fname[.ext] [d:][path]fname[.ext]
  64.                  [/+nnnn[,len]] -or- [/-nnnn,[len]]
  65.                  [/Lnnnn]
  66.                  [/R] [/C] [/Q]
  67.                  [/K] or [/X]
  68.  
  69. Remarks:   Records are read from the input file,  sorted,  and written
  70.            to the output file.
  71.  
  72.            Two types of records may be sorted:
  73.  
  74.            1)  logical  records.   Each  record  ends  with a carriage
  75. |              return and line feed, and  may be up to 8192 characters
  76.                in length.
  77.  
  78.            2)  fixed length  records.  Each record  is of length  L as
  79.                defined  by  the  '/Lnnnn'  parameter.  The records may
  80.                contain any  kind of  data, including  carriage return,
  81.                line feed, and end-of-file without effecting the record
  82. |              length. The maximum record is 8192 bytes.
  83.  
  84.  
  85.            The sort  order is  in ascending  ASCII character sequence.
  86.            You may supply the /R  parameter to reverse the sort  order
  87.            for all fields, or supply /- parameters for each key  field
  88.            to  be  sorted  in  reverse  order.   The  key  fields  are
  89.            processed from  left to  right as  supplied in  the command
  90.            line.
  91.  
  92.            The /C option may be added to cause SORTF to treat the  key
  93.            fields  as  case  insensitive  data.   That  is, lower case
  94.            letters in the key field are treated as upper case letters.
  95.  
  96.            You may  supply up  to sixteen  key offsets  and lengths by
  97.            using the /+ or /- parameter, one for each key position and
  98.            its length.   If /+  and /-  are omitted,  the key is taken
  99.            from the first character position for a length of 11.
  100.  
  101. |          The position 'nnnn' may be a value from one to 8192.
  102.  
  103. |          The key length 'len' may be  a value from 1 to 8192. The /+
  104.            operand  specifies  that  the  specified  key  is sorted in
  105.            ascending order.  The /- specifies desending sort order for
  106.            that key.
  107.  
  108.            Use the /Q option to suppress the display of  informational
  109.            messages.  Error messages can not be suppressed.
  110.  
  111.  
  112. SORTF Command           OPTIONS SUMMARY                   Version 2.37 Page 2
  113. -------------                                             Sep 20, 1991
  114.  
  115.  
  116.            /C  specifies  that  the  keys  are  case  insensitive;  if
  117.                supplied, all lower case  characters in the key  fields
  118.                are  converted  to  upper  case  for  the  purposes  of
  119.                sorting.
  120.  
  121.            /R  sort in  reverse order;  over-rides any  /- options and
  122.                treats them all as /+ options.
  123.  
  124.            /Q  suppress informational messages.
  125.  
  126.  
  127.            /K  creates an output file that consists of sorted key data
  128.                which includes a 5-byte information prefix.
  129.  
  130.            /X  like /K, except that the 5-byte information prefix is
  131.                omitted, and a cr/lf (carriage return and line feed)
  132.                is added to each record.
  133.  
  134.  
  135.            /L  specifies the sorting of fixed length records
  136.  
  137.            /+  defines the location  and length of  a key field  to be
  138.                sorted in ascending order
  139.  
  140.            /-  defines the location  and length of  a key field  to be
  141.                sorted in descending order
  142.  
  143.  
  144.  
  145. SORTF Command           INVOKING FROM QUICK BASIC         Version 2.37  Page 3
  146. -------------                                             Sep 20, 1991
  147.  
  148.  
  149.         To invoke SORTF from a Quick Basic program, you can use either
  150.         the SHELL or CALL statements.  Use of SHELL is straightforward.
  151.  
  152.         Use of CALL requires that you include SORTF.OBJ when you LINK
  153.         your QB program.
  154.  
  155.         You need to make memory available to SORTF from your QB
  156.         program.  For QB version 3 and earlier, you can use the LINK
  157.         '/CP:nnnn' option.  For QB 4 and later, I don't know how you
  158.         release memory.  For BC 7, you can use the SETMEM function.
  159.  
  160.  
  161.         In the QB program : CALL SORTF ("test.fil new.fil /+1,12")
  162.                      -or-   SHELL "sortf test.fil new.fil /+1,12"
  163.  
  164.  
  165.         For CALL:           LINK qbprogram + SORTF /CP:5000;
  166.  
  167.  
  168.         The /CP:5000 option will limit the QB program to 80K plus the
  169.         size of its code, data and stack. Whatever is left can be used
  170.         by CALLed programs. That amount will be about 120K less than
  171.         the DOS available memory.
  172.  
  173.  
  174.         For BC 7, here's an example of using SETMEM to release memory:
  175.  
  176.                 M1&=Setmem(0)                   ' Get heap size
  177.                 M2&=Setmem(-M1&+128000)         ' Release all but 128k
  178.                 Call SORTF (" "+infile$+" "+outfile+" /options")
  179.                 M3&=Setmem(M1&)                 ' Re-allocate all to heap
  180.  
  181.  
  182. SORTF Command                EXAMPLES                     Version 2.37  Page 4
  183. -------------                                             Sep 20, 1991
  184.  
  185.          o  to  sort  a  file  in  descending order with the keys in
  186.            position 10:
  187.  
  188.                 SORTF TEST.DAT TEST.SRT /R/+10
  189.  
  190.          o  to sort the same file using keys with 24 characters:
  191.  
  192.                 SORTF TEST.DAT TEST.SRT /R/+10,24
  193.  
  194.          o  to sort a file of fixed length, binary records; the input
  195.            file contains records of 18 bytes each,  the  key is  two
  196.            bytes  at  position  17  in  each  record  in  descending
  197.            order, and 11 bytes at postion 1 in ascending order:
  198.  
  199.                 SORTF SRTCATS.RND SRTCATS.IND /L18 /-17,2 /+1,12
  200.  
  201.          o  to sort on different keys, but creating an an output file
  202.            with the keys only:
  203.  
  204.                 SORTF TEST.DAT TEST.KEYS /-10,2 /+20,4 /-16,3 /K
  205.  
  206.            Note the use of /-.  It specifies that the first and  third
  207.            keys  are  sorted  in  descending  order, the second key is
  208.            sorted in ascending order.
  209.  
  210.            The format of the keys-only file using /K is:
  211.  
  212.            Offset  Length   Contents
  213.            ------  ------   ------------------------------------------
  214.              0       2      Length of data record excluding CR and LF
  215.              2       3      Offset to record in input file
  216.                              +0  hi-byte of 3-byte address offset
  217.                              +1  low word of address offset
  218.              5       n      Variable key data, depends on key definitions
  219.  
  220.            The format of the keys-only file using /X is:
  221.  
  222.            Offset  Length   Contents
  223.            ------  ------   ------------------------------------------
  224.              0       n      Variable key data, depends on key definitions
  225.              n       2      Carriage return and line feed
  226.  
  227.            In the example above, the variable key data format is:
  228.  
  229.              5       2      Data in records at offset 10
  230.              7       4      Data in records at offset 20
  231.             11       3      Data in records at offset 16
  232.             14       0      End of key record.
  233.  
  234.            The length of  each keys-only record  is 5 plus  the sum of
  235.            the individual key lengths.  The default, if no /+ or /- is
  236.            specified, is 16 bytes each.
  237.  
  238. SORTF Command           VERSION HISTORY                   Version 2.37  Page 5
  239. -------------                                             Sep 20, 1991
  240.  
  241.  2.0, July 11, 1985.  Corrects CR/LF problem.
  242.  
  243.  2.1, August 3, 1985. Corrects a problem sorting files larger than 64K.
  244.  
  245.  2.15, Dec 27, 1985.  Corrects problems with first record of file.
  246.                       Adds /C option to treat keys as case insensitive data
  247.                       The key length may be specified on the command line
  248.  
  249.  2.17, Feb 25, 1987.  Correct problem when maximum records exceeded
  250.                       Convert to COM program
  251.  
  252.  2.20, June 28, 1987. Add /Q option to suppress informational messages
  253.                       Change to allow up to 16 key field specifications
  254.  
  255.  2.23, Aug 6, 1987.   Add "-" option to sort individual fields in reverse order
  256.                       Add /K option to produce output file with keys only
  257.  
  258.  2.24, Sep 15, 1987.  Add /Lnnn option for sorting fixed length records
  259.  
  260.  2.25, Sep 19, 1987.  Correction for /L dropping last char of file and fouling
  261.                       records.
  262.  
  263.  2.26, Dec 16, 1987.  Cosmetic changes
  264.  
  265.  2.27, Feb 1, 1988.   Fix divide overflow on large files; terminate with
  266.                       message "Maximum records exceeded"
  267.  
  268.  2.29, March 5, 1988. Release gotten memory
  269.                       Add SORTF entry point for CALL from Quick Basic
  270.  
  271.  2.30, May 23, 1988.  Change maximum record size from 255 to 1023
  272.                       Change default key length from 12 to 11
  273.  
  274.  2.31, Feb 16, 1989.  Add /X option like /K to write file with keys only,
  275.                       and a cr/lf at the end of each record.
  276.  
  277.  2.32, Feb 18, 1989.  Correct problem LINKing with QB 4.5
  278.  2.33, Mar 16, 1989.  Expand record size limit from 1024 to 8192 bytes.
  279.  2.34, Feb 8,  1990.  Allow command line numbers to exceed 2 digits.
  280.                       Correct collation of multiple keys.
  281.  2.35, Feb 15, 1990.  Correct use of /K with record lengths over 255 bytes
  282.                       Allow records to be terminated by CR-LF, just CR,
  283.                       or just LF line feed.
  284. |2.36, Sep 18, 1991.  Correct problem with files over 16k records.
  285. |2.37, Sep 20, 1991.  Improve speed for ascending sorts
  286.  
  287.  
  288. SORTF Command           RESTRICTIONS                      Version 2.37  Page 6
  289. -------------                                             Sep 20, 1991
  290.  
  291.            Depending on the amount of  memory available,  up to  40000
  292.            records may be sorted.  The maximum file  size that  can be
  293.            sorted depends  on the  maximum number  of records  and the
  294.            average record  length.  For  example,  the  file  size  is
  295.            limited to 3.2 mb for a file consisting of 80-byte records.
  296.  
  297.  
  298.            The advantages of using  SORTF  instead of the SORT filter:
  299.                 - files larger than 63K may be sorted
  300.                 - less time is required
  301.                 - sort order can be based on up to 16 fields
  302.                 - fixed length files can be sorted
  303.  
  304.            For  best  results,  place the  input file  on the  fastest
  305.            available drive, e.g. RAM disk.
  306.  
  307.  
  308.  
  309.            Written by  Vernon Buerg  for the  IBM PC  using DOS 2.0 or
  310.            later.  You may distribute SORTF given these restrictions:
  311.  
  312.            o  the program shall be supplied in its original, unmodified
  313.               form, which includes this documentation;
  314.  
  315.            o  no fee is charged;
  316.  
  317.            o  for-profit use without a license is prohibited;
  318.  
  319.            o  the program may not  be included, or bundled, with  other
  320.               goods  or  services.   Exceptions  may  be  granted  upon
  321.               written  request  only. This  also applies to  clubs  and
  322.               distributors.
  323.  
  324.  
  325.            For use by corporations and other institutions, contact  me
  326.            for a licensing agreement.
  327.  
  328.            If you find SORTF useful, your gift of $15,  or any amount,
  329.            would be greatly appreciated.
  330.  
  331.  
  332.                 Vernon D. Buerg
  333.                 139 White Oak Circle
  334.                 Petaluma, CA  94952
  335.  
  336.                 Data: (707) 778-8944, 24-hour BBS
  337.                 CompuServe: 70007,1212 (Go IBMSYS)
  338.  
  339.  
  340.