AFile - User's Manual AboutThisDoc This manual describes release 2.10 of the utility AFile. This program is (c)1993 by Denis GOUNELLE, any commercial usage or selling without author's written authorization is strictly forbidden. You can copy and spread this program under the following conditions: - all the files are provided - the files are not modified in any way - you don't charge more than $6 for copy fee In spite of several tests, no warranty is made that there are no errors in AFile. YOU USE THIS PROGRAM AT YOUR OWN RISK. In no event will I be liable for any damage, direct or indirect, resulting of the use of AFile. Introduction AFile is a file manager, which allows to define records and gives you an access to data with an Intuition interface. The program offerts the standard printing, sorting, importing/exporting functions. You can also define input masks and use AREXX scripts to process your files. Criticisms and suggestions will always be welcomed. Write to: M. GOUNELLE Denis Boite 71 6, rue des cailloux 92110 CLICHY - FRANCE You can also send a message to the following Internet address : "gounelle@alphanet.ch". Note that this mailbox is not mine, so please send only short messages. As I don't have direct access to the messages, don't expect an answer before a dozen of days. Thanks to Yves PERRONOUD for his suggestions. Installation AFile needs the "mathieedoubbas.library" which is provided by Commodore on system disks. AFile is now localized, so it can adapt itself to your favorite language. All you have to do is to copy the good catalog file into the directory corresponding to your language. For exemple, if your default language is french, copy the "français.catalog" into the "SYS:Locale/Catalogs/Français" directory, under the name "AFile.catalog." The german catalogue was translated by Stefan SALEWSKI. Getting_started AFile may be run either from the CLI or from the Workbench. In both cases, you can specify a file to use, with the habitual method, so the program will jump directly to the visualisation/modification screen. Otherwise, the main screen will appear. AFile uses the default font and screen mode. The main screen has a menu with the following commands: New file Defines a new file. A file requester will appear, so you can specify the name of the file to create, then a special requester will allow you to define the structure of the file. This requester is described in the "Structure_definition" section. Modify file Modifies the structure of an existing file. A file requester will appear, so you can specify the name of the file to modify, then a special requester will allow you to modify the structure of the file. This requester is described in the "Structure_modification" section. Open file Opens an existing file. A file requester will appear, so you can specify the name of the file to open, then you will see the visualisation/modification screen. This screen is described in the "Data_access" section. Execute script Executes an AREXX script. A file requester will appear, so you can specify the name of the script to run. The AREXX interface of AFile is described in the "AREXX_Interface" section. Quit Terminates the program. Structure_definition AFile handles files made of fixed length records. All the records have the same structure, made of an unlimited number of fields. Each field is defined by it's name, size and type. Field's name can't be longer than 32 characters, and may contain any character. However, you shouldn't use spaces if you think you will use AREXX to access to the file. Of course, each field's name must be unique. Field's size is limited to 65535 bytes, except for "DATE" and "BOOLEAN" fields, which are 8 bytes and 1 bytes long, respectively. For numeric fields, you can also specify the number of digits after the decimal point. Possible field's types are : ALPHA alphabetic value only ("a" to "z", "A" to "Z") NUMERIC numeric value (real or integer) ALPHANUM any value (letters, digits, special characters) DATE date (day, month, year) BOOLEEN boolean value ('T' or 'F') The definition structure requester is made of a display area, where are displayed the field's definitions (name/type/length). You can use the scroller to scroll the display. The current field is displayed under a blue background. To select a field, you just have to click upon it's definition: it will automatically copied in the gadgets. To define a new field, you'll have to enter it's name and length in the "Name" and "Length" (and eventually "Digits") string gadgets, and to select it's type with the "Type" cycle gadget. Then you must click upon the "Add" gadget: the new field will be added to the list, and selected as the current field. If the field can't be added (no memory, name not unique, etc...) the screen will flash. The "Add" gadget adds the new field as the last field. The "Insert" gadget inserts it before the current field. The "Remove" gadget removes the current field. The "Replace" gadget replaces the current field. This allow (for example) to modify the name, size or type of a file. The definition requester also has a menu, with the following commands: Copy structure Copies the structure of an existing file. Note that the structure currently displayed in the requester will be lost ! A file requester will appear, so you can select the file which structure is to be copied. Abort Cancels structure definition, and go back to main screen without creating the file. Save Records structure definition, and go back to main screen after creating the file. Encrypt data Data in the file will be encryted, with a password that you will have to provide when you record structure definition. This password will be asked for each time the user will try to access to the data. CAUTION : if you ever forget this passord, you will never be able to access to data in the file !! Structure_modification This allows you to modify the structure of an existing file: you may add some fields, remove some others, modify a field's length, etc... However, you can't modify a field's type, or delete all the fields. The modification requester is quite the same as the definition requester (see "Structure_definition" section). The only differences are that the "Type" gadget and "Copy structure" menu item are disabled. Once the structure modified, use the "Save" menu item to record your changes: AFile will automatically convert the file into the new structure. Take care that deleted records will be lost during this operation, and that this convertion may fail if there is not enough free space on the volume where is the file. If some data will be lost during the convertion (shorter or removed fields, deleted records, etc... ), you will be asked to confirm the operation. With the "Options" menu, you can remove or add data encryption. If the encryption option is enabled when you record the new structure, AFile will ask you to enter a password. This can also be used to change the password for a file: you just have to ask to modify the structure of this file, record the structure without any change, and enter the new password. Data_access The visualisation/modification screen is made of a display area, where data is displayed, of a status line and a row of gadgets. The gadgets showing the data should be the same width as the corresponding field, except if the screen is not large enough. Each time you modify the value of a field, AFile will check that this new value is compatible with the field's type. Dates must be entered in the "DD/MM/YY" format, but entering "?" is an easy way to specify today's date (see the "Alias" section). The status line shows the file's name, and current position in the file under the X/Y form, where X is the current record number and Y the last record number. If the current record has been modfied, "Modified" is displayed at the right of the status line. The row of gadgets allows the following operations (from left to right): go to the first record go to the previous record write the current record go to the next record go to the last record go to a specifed record delete the current record print n records starting from the current record Last, the two right-most gadgets allow to display the previous and next fields page, if all the fields can't be displayed together on the same page. You can control how the records are printed, with an AREXX script. To use this feature, you just have to call the program with the "PRINTSCRIPT " from the CLI, or to add a "PRINTSCRIPT=" line in the "TOOL TYPES" field of the file icon. The script will be called for each record to print, with it's output redirected to the printer (so you can use the "SAY" command to output data). If the current record has been modified, the changes will automatically be written if you move to another record. When you are on the last record, asking to go to the next record will automatically create a new record. All other operations may be started with menus. These menus are described in the "File_menu", "Edit_menu" and "Special_menu" sections. File_menu Undelete For the program, deleting a record just mean setting a flag for this record, which tells this record is deleted and must not be accessed. The record is not actually removed: data is still here. The menu item allows you to clear all deletion flags, so the corresponding records may be accessed again. Pack file Actually removes deleted record (you will be asked for confirmation). After this, you won't be able to undelete these records, but the file will be smaller because the data for these records will be definitly removed. Take care that this operation may fail if there is not enough free space on the volume where is the file. Informations Displays some informations about the current file: name, number of fields, record size, number of available records, number of deleted records. Print structure Prints the file's structure, that is the definition of all the fields. You can print the structure to the printer, or the a file. Close file Close the current file, and go back to main screen. Edit_menu Cancel changes Reads the current record from the file, so cancels all changes since last write. Select mask Selects an input mask. A file requester will appear, so you can specify the mask to load. Input masks are described in the "Input_mask" section. Forget mask Forgets the current input mask. Import Imports data from an ASCII file. The new records will be appended to the end of the file. A special requester will appear, so you can specify the required parameters. This requester is described in the "Import_Export" section. Export Exports data to an ASCII file. All the records will be exported. A special requester will appear, so you can specify the required parameters. This requester is described in the "Import_Export" section. Search Searches a record with a given value in a specified field. A field request will appear, so you can specify which field the value is to be searched in. AFile will then ask you which value is to be searched, and start the search from the current record. By default, the program searched for an exact match, but if the search string begins with a "?" (i.e. "?foo") AFile will search any record which the specified field contains the value (i.e. it will find "I've fooled you"). To search a value beginning with a "?", you just have to add a "\" character before. So : "foo" search exact match with "foo" "?foo" search a field which contains "foo" "\?foo" search exact match with "?foo" "\\foo" search exact match with "\foo" "\foo" search exact match with "foo" Seach next Continues searching, starting from next record. Special_menu Activate sort Sorts the records using a specified field. A first requester will appear so you can specify the field which is to be used for sorting. A second requester will allow you to specify sort parameters: increasing/decreasing order, case dependant/independant. Once the sorting done, AFile will display the first record in the sorting order. Then all your moves withing the records (first/previous/next/last) will be made in the sorting order. Take care that AFile only does a "logical" sort: the order of the records within the file is not actually modified. Sorting a file may use a lot of memory if the file contains a lot of records. As long as the sort is activated, you won't be able to add or remove records, to modified a value in the field which is used for sorting, and to use the "Undelete" or "Pack file" menu items. Forget sort Cancels the last sort. This will not only free all memory used for the sort but also allow you to add or remove records. Your moves whithin the records will be made in the "physical" order of the records in the file. Reorder records This actually modifies the order of the records in the file (you will be asked for confirmation). Take care that this operation may fail if there is not enough free space on the volume where is the file, and that all deleted records will be definitly lost. Executer script Executes an AREXX script. A file requester will appear, so you can specify the name of the script to run. The AREXX interface of AFile is described in the "AREXX_Interface" section. Import_Export You must first select the source (destination) file. Then you will have to specify the field delimiter and record delimiter characters. These delimiters may be entered as a single character (i.e. "/") or as an ASCII decimal code (i.e. 10 for a new line character). If you want to use an ASCII decimal code, it must have at least two digits: "2" specifies character "2", "02" specified character which ASCII decimal code is 2. Last, you will have to specify the order in which the fields are to be imported (exported): enter "1" for the first field, "2" for the second field, etc... If you don't specify a order number for a field, it won't be imported (exported). When importing data, the order number may be considered as a column number: it allows to ignore some data, or to swap two fields. Input_mask Input masks allow both to help the user while he or she is entering data, and to verify the data he or she has entered. For AFile, an input mask is an AREXX script, with some specialy written comments. Here is an example of mask, to show the format to use: /* * Example of input mask for AFile * This script is called each time the QUANTITY and ENTRY_DATE fields * are changed * * $MSG * NUMBER - Product number * QUANTITY y Quantity received * PROVIDER - Provider's name * ENTRY_DATE y Delivery's date * $END */ PARSE ARG field value SELECT /* refuses negative values */ WHEN field = 'QUANTITY' THEN DO IF value >= 0 THEN EXIT 0 END /* make sure that date is not after today's date */ WHEN field = 'DATE_ENTREE' THEN DO IF value <= DATE( 'SORTED' ) THEN EXIT 0 END END EXIT 10 As you can see, the mask specifications must be entered between a line in the " * $MSG" format, and in a line in the " * $END" format. The specification lines can be either in the " *" format, or specify (from left to right) a field's name, if we must call the script, and a message. The message is displayed above the status line when the corresponding field is selected. If the flag in column two is not "-", the AREXX script is called each time the value of the field is modified, with the field's name and the new value as arguments. It must return a 0 return code if the value is to be accepted, or a non-0 return code if the value is to be refused. Date values will be supplied in the "AAAAMMDD" format, and boolean values will be either 'T' or 'F'. The script cannot use the SEEK, WRITE, APPEND, DELETE, SEARCH, SORT, RELEASE, SETFIELD, and CLOSE functions on the current field. To select an input mask, you have to use the "Select mask" item of the "Edit" menu. To cancel the mask, use the "Forget mask" item. You may also gives the mask name at startup: from the CLI, use the "INPUTMASK " argument, from the Workbench add a "INPUTMASK=" line in the "TOOL TYPES" field of the file's icon. Last, you may associate an input mask to a data file, so it will automatically be loaded each time the data file will be opened. To do this, the input mask file's name must be the name of the data file, followed by the ".mask" suffix. For example, if you want to define an input mask for a data file named "Addresses", it's name must be "Addresses.mask". The two files must be in the same directory. Alias The alias allow you to make data entering easier, by defining shortcuts. An example is the possibility to enter "?" in a "DATE" field, in order to have today's date. This possibility is built in AFile, but you can also define your own aliases, with a text file made of lines in the following format: field's namealiasvalue The notation stands for one or more tabulation characters. Empty lines and lines beginning with ";" character are ignored. The aliases file's name must be the name of the data file, followed by the ".alias" suffix. For example, if you want to define aliases for a data file named "Addresses", the aliases file's name must be "Addresses.alias". The two files must be in the same directory. The aliases file will be automatically opened when the data file will be opened. Here is an alias example: if you create an aliases file with a "COUNTRYUSAUNITED STATED OF AMERICA" line, each time the user will enter the "USA" value in the "COUNTRY" field, it will automatically be replaced by the "UNITED STATES OF AMERICA" value. Take care that aliases substitution is made before running input mask's script (see the "Input mask" section). AREXX_Interface The AREXX port's name is "AFile_rexx". You may run a script either from the "Project" menu of the main screen, or from the "Special" menu of the visualisation/modification screen. In this case, the current file is automatically selected as the working file, and the current record is this file is the record currently displayed. The following commands are accepted: OPEN name Opens the given file, and go to the first record of this file. The file is *NOT* selected as the working file. SELECT name Selects the given file as the working file. The file must have been opened with an "OPEN" command. CLOSE name Close the given file CLOSE ALL Close all the opened files The following commands are applied to the working file: APPEND Apppends a new record, and go to this record SEEK FIRST Go to the first record SEEK LAST Go to the last record SEEK NEXT Go to the next record SEEK PREV Go to the previous record SEEK n Go to the n-th record SEARCH name value [NOCASE] Searches a record which named field has the given value (see description of item "Search" in the "Edit_menu" section for conventions about value). If the "NOCASE" is specified, the search will be case independant. SEARCH NEXT Searches next occurence INFO Returns informations on the current file, in the RESULT variable: "full pathname" . SORT name [DECREASE] [NOCASE] Activates a sort on the named field. If the "DECREASE" option is specified, the records will be sorted in reverse order. If the "NOCASE" option is specified, the sort will be case independant. RELEASE Forget currently activated sort. The following commands are applied to the current record of the working file: WRITE Update current record DELETE Delete current record GETFIELD name Returns the value of the named field, in the RESULT variable SETFIELD name value Modifies the value of the named field. CAUTION !! THE VALUE *MUST* BE SPECIFIED WITHIN DOUBLE QUOTES ("value") !! FIELDTYPE name Returns the named field's type (A/N/S/D/B) FIELDLEN name Returns the name field's length in file's structure definition. For numeric fields, the decimal point is taken in account if the number of digits is not 0. If failed, all these commands return 10 in the RC variable. They return 0 if all is ok. Historique AFile is written almost fully in C language, and was developped on an Amiga 3000 UNIX-1 (10 Mb RAM, internal HD disk drive, internal hard disk of 100 Mb, external SyQuest drive of 88 Mb, external floppy disk drive, 1960 monitor and Star LC24-10 printer) connected by a null-modem cable to an A500 with 1 Mb RAM. v1.00 25-Jul-93, 60448 bytes v1.10 07-Aug-93, 62632 bytes o Added input masks o Added AREXX commands "FIELDTYPE" and "FIELDLEN" o When a sort is activated, displays "sorted on