home *** CD-ROM | disk | FTP | other *** search
/ PDA Software Library / pdasoftwarelib.iso / PSION / UTILS / JBST112A / JBSORT.TXT < prev   
Encoding:
Text File  |  1994-12-16  |  12.3 KB  |  422 lines
  1.                                 JBSort
  2.                             Version 1.1.2a
  3.                             (c)JBSoft 1994
  4.  
  5. JBSort is a utility to sort Data files by ASCII. It will, in fact,
  6. sort any database files created with Data or by the Psion OPL CREATE
  7. command. It works on both the S3 and S3a.
  8.  
  9. The program is normally started from the System screen by choosing a
  10. file listed under the JBSort icon. Alternatively, whilst the cursor is
  11. in the filelist below the JBSort icon, press Tab - this will enable
  12. you to navigate through the directories and drives in the normal way.
  13. Once the file to be sorted has been found and highlighted with the
  14. cursor, press Enter.
  15.  
  16. There is now extensive checking for memory availability and, should
  17. the program fail for lack of memory at any time, the system should be
  18. cleared of any temporary files made by the application at the time of
  19. the failure.
  20.  
  21. Alternatively, the application can be started from another program
  22. using the Operating System call that has been documented in many
  23. places (see Appendix A for details of the call) - if you provide a
  24. datafile name with this call then the application will automatically
  25. select that program for sorting. If no filename is given then a dialog
  26. is displayed enabling you to chose the file to sort.
  27.  
  28. The program can be run in the background but there may be a slight
  29. blip on the screen when the program is started - this is unavoidable
  30. without a total rewrite in Object Oriented Code. If it is run in the
  31. background then sensible defaults are used so that user inputted data
  32. is unnecessary. The program, when run in the background, will sort in
  33. ascending order using the first three fields as the key fields in the
  34. order in which they appear - it will over-write the existing file.
  35.  
  36. If the datafile chosen is open, an option is given to continue the
  37. sort or not. If it is decided to continue, and the file hasn't been
  38. opened by a program with the data details hard-coded, then the file
  39. will be closed and, after the sort, will be re-opened.
  40.  
  41. There is a small problem with the S3 in that, when the file is re-
  42. opened, the front screen will show the Application name (e.g. Data)
  43. rather than the filename. This can be cured by pressing the System
  44. button or going into the file. This problem is being investigated but
  45. I have no idea why it is happening so I don't hold out much hope for a
  46. proper fix.
  47.  
  48. N.B. As far as I can tell, it is impossible to find the owner of a
  49.      datafile opened in an application that doesn't have a filelist,
  50.      therefore the sort application will fail if a datafile currently
  51.      open by such an application is selected. This state is only true
  52.      of programs which don't have filelists - programs with lists will
  53.      work!
  54.  
  55. If run normally, a dialog is presented so that the Fields on which to
  56. sort can be chosen. If you only wish to sort on the one field then
  57. make all three field choices the same or, if you wish to sort on two
  58. fields, make fields two and three the same. The last option in the
  59. fieldnames list is <none> which can be selected as an alternative to
  60. making the choice the same as the previous selection.
  61.  
  62. Next, if run on an S3, another dialog is shown to enable you to
  63. specify a new filename in which the resultant sort will be placed,
  64. otherwise, on an S3a, this data choice is included in the field choice
  65. dialog. You may also specify a forwards or backwards sort (e.g. ABC or
  66.  
  67. CBA) and also, once the sort is completed, whether to exit the program
  68. or choose another file to sort.
  69.  
  70. Once this initialisation has been carried out the program will then
  71. sort the file and either exit or end on a file selection dialog where
  72. you can choose another file to sort.
  73.  
  74. The program works by creating a string (made up of the three field
  75. choices in order) for each record along with the position of the
  76. record in the file. This string is then sorted and the result is then
  77. written in the appropriate order to another file. Assuming that
  78. another file has not been specified for the result, the original file
  79. is then deleted and the new file renamed to that of the original.
  80.  
  81. To enable large data files to be sorted I have included a fall-back
  82. procedure that is hierarchical and works in the following order:-
  83.  
  84.      1. As specified.
  85.      2. Limit length of each field to 8 characters.
  86.      3. Reduce by one the number of fields to be sorted.
  87.      4. Repeat 3 until only one field is left - if it still fails then
  88.         the program fails.
  89.  
  90. Obviously, the further down the tree the program has to go, the longer
  91. it will take to complete its task.
  92.  
  93. Should the program fail at some point in the procedure then there
  94. should be no lasting damage as the last thing the program does is
  95. delete the original and substitute the new file, prior to that, the
  96. original file is not altered in any way. If the option to over-write
  97. was chosen and the program fails, there may be a file called JBZZ.DBF
  98. created. This can be deleted with no problems (this is the file that
  99. is renamed as the last action of the program).
  100.  
  101. Limitations
  102. -----------
  103. The program is currently limited to files that have less than 4000
  104. entries (this may be increased slightly if necessary).
  105.  
  106. The main limitation to my program is the 64k limit on data in any
  107. program (this 64k limit does not refer to the database size but the
  108. amount of data that an application can have). The actual sort takes
  109. place in memory and so there is a great deal of data temporarily held
  110. there. The probable limit to the size of the database is going to be
  111. around 5,000 entries but this is purely theoretical and could be
  112. wildly out. If you come across a database whose sort fails through
  113. lack of memory I would be grateful of that information along with the
  114. number of records (and type of fields being sorted) so that I can
  115. update this section of the 'manual'.
  116.  
  117. Sort is limited to 3 fields at present (again, this could be increased
  118. given the necessity).
  119.  
  120. The program requires sufficient space on the drive to create a
  121. duplicate file of the same length as the first file. The program
  122. checks for this availability and, if there is insufficient memory
  123. available, the program will fail. The program will also fail if there
  124. is insufficient RAM in which to run. As a guide, the program itself
  125. requires around 60k but this is variable and is somewhat related to
  126. the size of the file being sorted - it is impossible to give accurate
  127. figures due to variability of the files being sorted.
  128.  
  129. Bearing in mind I am a one-man-band and do not have access to every
  130. application going, it is possible that there is an program out there
  131. that creates data files which will not sort correctly, although I have
  132. not come across any so far. Should you encounter one of these, please
  133. let me know, and, if possible, provide a sample file so that I can
  134. adjust (fix) my program accordingly.
  135.  
  136. Thanks
  137. ------
  138. As usual, thanks go to Tom Dolbilin for his assistance in shaping this
  139. program. I would also like to thank Paul Steel for checking some
  140. things out and pointing out some problems.
  141.  
  142. Contact
  143. -------
  144. John Boyce
  145. CompuServe: 100014,1240
  146. CIX/Internet: jboyce@cix.compulink.co.uk
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199. Appendix A
  200. ==========
  201. The OS Call mentioned above is detailed in this Appendix.
  202.  
  203. Some explanation of the code will be necessary - here it is...
  204.  
  205. appname$ is the name of the application to run. It should include the
  206. path (e.g. "LOC::A:\APP\JBSORT.APP"). This is just a normal string.
  207.  
  208. cmdline$ is a complex string which presents a command line to the OS.
  209. It is made up of several parts:-
  210.  
  211.      1. Command byte &        This can be one of three characters:-
  212.                               O - open an existing file
  213.                               C - create a new file
  214.                               D - open an existing file in the
  215.                                   background (this only works for some
  216.                                   utilities - definitely not OPO or
  217.                                   OPA programs)
  218.                               These characters should be appended to
  219.                               the start of the Header string.
  220.         Header string         This is the public name under which the
  221.                               App appears (e.g. Data or Word or
  222.                               JBSort)
  223.      2. Default extension     This is the default extension for the
  224.                               file to be opened (e.g. .DBF)
  225.         & alias info          This is for alias information and should
  226.                               be separated from the extension data by
  227.                               a space
  228.      3. Data file to open     this should include the path of the file
  229.                               as well as the name
  230.  
  231. Each of the sections should be followed by a zero character - e.g.
  232.  
  233. "OJBSort"+chr$(0)+".DBF"+chr$(0)+"LOC::A:\DAT\ADDRESS.DBF"+chr$(0)
  234.  
  235. ppid% should be the address of an integer in which will be placed the
  236. process identity once the program has been started. This information
  237. can be discarded once the program has been run if no other actions are
  238. to be made on the running application (process).
  239.  
  240. Using the above examples as a guide, runapp% would be called thus:
  241.  
  242. err%=runapp%:("LOC::A:\APP\JBSORT.APP","OJBSort"+chr$(0)+".DBF"+chr$(0
  243. )+"LOC::A:\DAT\ADDRESS.DBF"+chr$(0),addr(pid%))
  244.  
  245. where the code should all be on one line of your program.
  246.  
  247. Almost any program can be run in this fashion, but to run OPO and OPA
  248. programs they have to be treated as files and the application name to
  249. be specified as the appname$ is ROM::SYS$PRGO.IMG. If an OPA file
  250. requires a file then this should be placed in the position of the OPA
  251. name and an extra parameter added which should be the application
  252. e.g.:
  253.  
  254. err%=runapp%:("ROM::SYS$PRGO.IMG","ONotepad"+chr$(0)+".PAD"+chr$(0)+"L
  255. OC::A:\NOTE\NOTEPAD.PAD"+chr$(0)+"LOC::A:\APP\NOTEPAD.OPA"+chr$(0),add
  256. r(pid%))
  257.  
  258. is an example of running Mark Esposito's Notepad program).
  259.  
  260. I have tried to include a lot of information on this call as there is
  261. nothing worse than getting just a little of the information and having
  262. to ask around for the rest. Obviously, the last few items discussed
  263. are not relevant to the current situation.
  264.  
  265. The aliases discussed earlier are a little too complex to explain in
  266. the context of this document and are dependant on the application
  267. recognising them (they also differ for each application so a list is
  268. not relevant).
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331. Code
  332. ----
  333.  
  334. PROC runapp%:(appname$,cmdline$,ppid%)
  335.      local ax%,bx%,cx%,dx%,si%,di%
  336.      local ret%,flags%
  337.      local cmdl$(128),img$(128)
  338.      cmdl$=cmdline$
  339.      img$=appname$+chr$(0)
  340.      ax%=$0100
  341.      bx%=addr(img$)+1
  342.      cx%=addr(cmdl$)
  343.      di%=ppid%
  344.      flags%=os($87,addr(ax%)) REM FilExecute
  345.      if (flags% and 1)
  346.           ret%=(ax% and $FF)-256 REM If a problem set ret% to err
  347.      else
  348.           ax%=$0600
  349.           bx%=peekw(ppid%)
  350.           flags%=os($88,addr(ax%)) REM ProcResume
  351.           if (flags% and 1)
  352.                ret%=(ax% and $FF)-256 REM set ret% to err
  353.           else
  354.                ret%=0
  355.           endif
  356.      endif
  357.      return ret% REM return problem (zero if none)
  358. ENDP
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397. Release Information
  398. ===================
  399. Version   Information
  400. ---------------------
  401. 1.0       First release to the public domain.
  402.  
  403. 1.0a      Bug-fix to actually make the program work on an S3!
  404.  
  405. 1.1       Dialogs are now shown differently if run on an S3 or an S3a
  406.           and appear in the style appropriate to the machine.
  407.           If the datafile is open, it can be closed and re-opened
  408.           under some circumstances.
  409.           Fixed occasional problem with making OPL Datafiles into Data
  410.           type files.
  411.           Added option to stay within the program after the sort is
  412.           complete.
  413. 1.1.1     Stopped machine from switching off when sorting large
  414.           databases.
  415.           Increased memory availability checking to stop occasional
  416.           corruption of sorted file.
  417. 1.1.2     Now closes database gracefully (allowing any changes to be
  418.           saved).
  419.           Cured problem of Alert when answering No to Close Datafile
  420.           dialog.
  421. 1.1.2a    Will now search larger files before running out of memory.
  422.           Fixed obscure bug with release of memory.