AldurFile OPX, v1.10 © 2003-4 Graham L. Holden * * * NOTE * * * As of version 1.04, AldurFile has been allocated an official Symbian UID. If you have a version prior to this installed, e.g. v1.01 or v1.02, you should remove it first (Control Panel, Add/Remove), otherwise confusion will ensue. Once you have version 1.04 or later installed, you will not have to worry about this issue since the Psion's installer will recognise and remove older versions. * * * NOTE * * * AldurFile is an OPX that provides extra file and directory handling functions for OPL programmers. Features include: -- Allows the Archive attribute (whether a file has been modified since the last backup) to be examined or changed; -- Allows you to test whether a given filename is a directory or not; -- Provides an alternative to the DIR$() function that allows the programmer to: -- step through more than one directory listing at a time (for example, to traverse recursively down the directory tree), -- filter the visible files by their attributes (modified, read-only, system, hidden, directory-or-not), -- filter visible files by one or more UIDs (EPOC's Unique IDentifiers that say what type a file is), -- sort the list of files by name, extension, modification time etc., -- access the entries in a directory as though they were held in an array, -- quickly access a file's properties (size, attributes, UIDs). -- Provides convenient file-and-path parsing routines, without having to use PARSE$(). -- Provides string formatting functions for a file's attributes, size and date/time of modification. INSTALLATION ============ AldurFile is delivered as two pairs of EPOC Installation (.SIS) files. The first file of each pair is intended for OPL developers' use while writing applications that will make use of AldurFile.Opx. The second file of each pair is designed for redistribution to developers' end-users as part of the application's installation process. Both of these two installation files come in two flavours. One flavour is intended for development or deployment on real EPOC devices (e.g. 5mx or Revo); the other flavour is targeted for the PC-based EPOC Emulator but is otherwise identical. Development ----------- Install either or both of AldurFileDEV.SIS (on a Psion) and AldurFileDEV-WINS.SIS (on the Emulator) depending on where you intend doing your development work. The following files will be installed on the chosen installation drive of your system: \System\Opl\AldurFile.oxh \System\Opx\AldurFile.opx \AldurSoft\AldurFileOpx.hlp \AldurSoft\AldurFileOpx The file AldurFile.oxh provides the interface to the functions implemented in AldurFile.oxh. The file AldurFile.hlp describes how to use the OPX, and AldurFileOpx is an OPL program demonstrating some of the OPX's features. To use the OPX, add the following line near the top of you OPL source code: Include "AldurFile.oxh" and start writing your application. Distribution ------------ If you intend distributing your application to others, you will need to ensure that your end-users get AldurFile.opx installed on their machines. To do this, you will need to include AldurFile.SIS with your distribution. If you are going to package your application in a .SIS file, you can simply include AldurFile.SIS as one of its components. This will ensure that as your application is installed, AldurFile is installed as well. If you distribute your application as discrete files, you will need to include AldurFile.SIS among them. Your end-user installation instructions will need to direct your users to install AldurFile.SIS. On no account should you just include the AldurFile.opx file in your package, either as a component of a .SIS file or as a standalone file. Doing this would bypass the version-control system that EPOC uses and may result in your package overwriting a newer version of AldurFile.opx with an older one. Installing AldurFile.SIS on your users' machines will install the following files to their chosen drive: \System\Opl\AldurFile.oxh \System\Opx\AldurFile.opx If you intend to make your application available for use with the PC-based Emulator, you should follow the instructions above, but use AldurFile-WINS.SIS in place of AldurFile.SIS. The non-'DEV' versions of AldurFile's installation packages are provided so your end-users can use your application without cluttering up their systems with the help file and example OPL source included in the developer versions. If you think your end-users would benefit from these files, or your application is aimed at developers, feel free to include the 'DEV' version of the .SIS file in your distribution. LICENCE ======= The copyright in AldurFile -- the .SIS files and all component files -- is retained by the author, Graham L. Holden. The package, and/or any files within it, may only be used and distributed in accordance with the terms of this licence. If you cannot agree to be bound by the terms of the licence, you must stop using AldurFile and delete all copies of the .SIS files and any component files from your system(s). Personal Use ------------ Everybody is granted permission to use AldurFile to develop and run programs they develop for their own personal use, and to run any third-party programs they may acquire that make use of AldurFile. Distribution ------------ Where permitted, AldurFile must only be distributed as one or more of the standard package files: AldurFileDEV.SIS, AldurFileDEV-WINS.SIS, AldurFile.SIS or AldurFile-WINS.SIS. No component file or files may be distributed outside of these packages. These four .SIS files may be freely distributed provided that no charge is made. The .SIS files may be made available for download on a website provided that no charge is made either to download the files or to join, or otherwise be able to access the files. The files may not be held on a 'pay' or commercial website unless they are freely available to all visitors without them having to pay, join or provide credit-card details. A link should be provided back to my website so that users can check for updated versions. Distribution of Developed Programs ---------------------------------- The use of AldurFile to develop any program or application that you want to distribute to others is permitted providing the following conditions are observed: -- If you include AldurFile as part of your distribution, this can only be as one of the four .SIS files above, either as a standalone file, or preferably incorporated into your application's .SIS file. You may not distribute AldurFile's component files separately. Should you choose not to include AldurFile with your package (e.g. by relying on your users to acquire it for themselves) then the remaining conditions still apply. -- In your documentation and/or within the program (e.g. an 'About' screen) you must acknowledge your use of AldurFile and include a link to my website. -- Programs developed with AldurFile may be distributed as you see fit, e.g for free, as shareware or commercially. -- I would appreciate being informed of any use you make of AldurFile, partly for my own interest and partly so I can let people know if I release any updates. Offering me a free copy of anything you develop would be doubly-appreciated but is in no way compulsory. Warranty -------- The software is offered "as is" with no warranty as to its suitability for any particular purpose. Your use of the software is entirely at your own risk and no liability will be accepted for any loss arising from the such use. However, without formally committing myself to any course of action, I will attempt to rectify any faults found in the software and would be glad for any feedback concerning the software. CONTACT ME ========== At the time of writing (June 2006), I can be reached by e-mail on: "g-holden" and "AldursLair.com", joined by an "@" sign. or mvia my website at: www.AldursLair.com/epoc I also try to keep an eye on the Psion-related newsgroups, including: comp.sys.psion.apps comp.sys.psion.misc comp.sys.psion.programmer I appreciate any feedback on this package, especially bug reports and typos in the help text. Suggestions for new features or improved clarity of the documentation are welcome, but no promises are made! I love 'dabbling' on the Psion, so any requests for future OPXs will be given a reasonable hearing. Graham Holden. REVISIONS ========= Version 1.10, 12th October 2004 Fixed a bug in v1.09 if KSortByDateAndName% was used. Apologies for the delay in getting this released. Version 1.09, 20th September 2004 Added the ability to combine two or more directory searches into one directory list: -- DirAppend&: and DirMerge&: allow new entries to be appended (or sorted into) an existing list. -- DirOpenEmpty&: is an alternative to DirOpen&: to start the process with an empty list. -- Corresponding functions exist for Dir...UID&:. However, please note that at present: -- Duplicate entries are NOT removed from a combined list; -- All entries in a combined list must come from the same directory. Version 1.08, 20th November 2003 A better attempt at meeting the request that triggered 1.07: -- DirNextHaving%: and DirNextLacking%: have been added to allow you to step through entries of the Current Directory List with or without certain attributes. -- IsOpen%:, DirIsOpen%:, and DirIsOpenAt%: have been added to test whether a file is open or not. NOTE: A couple of the constants defined in v1.07 have been superseeded (KRemoveIfOpen% and KRemoveIfClosed%). Version 1.07, 13th November 2003 By request, an extra function: -- DirFilter: has been added which allows open or closed files to be filtered out of the current Directory List. Version 1.06, 19th March 2003 The first bug fix! -- DirOpen&: or DirSort: would panic if called with the new sort option KSortByDateAndName% for an empty directory. Version 1.05, 17th March 2003 A couple of extra features added after using the OPX myself: -- The SetFmtTriadTails: command can be used to control the trailing strings of FmtTriad$: and DirSize$: when in "round to Kb or MB" mode. -- A new option, KSortByDateAndName%, is available with DirOpen&:, DirOpenUID&: and DirSort: (see below) to list files in day-groups sorted by name. -- DirSort: is available to re-sort an active directory list. -- Two synonyms have been added to AldurFile.oxh: -- ParseFilePath$: is equivalent to ParseDriveAndPath$: -- ParseFileName$: is equivalent to ParseFileAndExt$: Version 1.04, 12th March 2003 (now with official Symbian UID) Implementation of earlier ideas/requests: -- A file's attributes can be returned as a formatted string, either directly from an active directory list or from a free-standing attribute value. see DirAttrib$:, DirAttribAt$:, FmtAttrib$: and SetFmtAttrib:. -- A file's size can be returned as a triad-separated string, either directly from an active directory list or from a free-standing size (or any numeric) value. see DirSize$:, DirSizeAt$:, FmtTriad$:, FmtTriadEx$: and SetFmtTriad:. -- A file's date/time of modification can be returned as a formatted string, either directly from an active directory list or from a free-standing date/time value. see DirDateTime$:, DirDate$:, DirTime$:, FmtDateTime$:, FmtDate$:, FmtTime$:, FmtDateTimeEx$:, FmtDateEx$:, FmtTimeEx$:, SetFmtDateTime:, SetFmtDate: and SetFmtTime:. Version 1.02, 3rd March 2003 (now released as AldurFile.opx) Was already adding directory traversal functions when another poster on comp.sys.psion.programmer requested something similar. -- Added the DirXXX: functions to allow multiple directories to be scanned and accessed like an array. -- Added ParseXXX: functions to combine and split a filename from/into its components. Version 1.01, 25th February 2003 (originally released as FileUtil.opx) Initial release in response to a plea for help on comp.sys.psion.programmer. -- Implemented Archive-attribute testing and setting; -- Implemented testing for a directory.