Datafile - Nigle Salt (ZX Computing-Apr/May 84)


[This is quite a nice little program - written by someone who knows  ]
[the difference between files and records.                           ]
[One little problem is that the "Listing 2" Letters sample program   ]
[had several errors in it. I've corrected them and here's a summary: ]
[line  1000 - file name not assigned                                 ]
[line  2000 - loop should start at 2, not 3                          ]
[line  2010 - record number not assigned                             ]
[lines 2020, 2060, 2075, 2080, 3010, 3070, 4000 - field number not   ]
[      assigned; irrelevant assignments to variables x and x1        ]
[If you've got DATAFILE.TAP then there's a sample CLIENT file to use ]
[with Datafile or Letters. Note that Letters and Toolkit must be     ]
[merged together before running Letters.                        JimG ]


DATAFILE

A multi-purpose file handling program from Nigel Salt in Kent.

Keeping records can be a laborious job - bits of paper
alterations, amendments etc etc. But now in this 
comprehensive and versatile program you have all the facilities
that most filing applications will require.
	Datafile impressed us in both operation and in programming
techniques. It is liberally REMmed so that the operation
of each section is explained and has been well documented
by Nigel for the operator to use.
	Whatever your interest, job, or need, Datafile will be of
use. Type it in and then read the following instructions on
using it.
	Datafile is a utility program which sets up a file in A$ in
accordance with parameters supplied by the user. The only limit
to the number of records held is the size of the memory of
your Spectrum. A 16K machine can only manage 28
records 100 characters long but fields within each record
can be any length and each field can be given a name up to
6 characters long.
	Toolkit  is  a  set  of subroutines designed to enable
you to use files generated by Datafile in your own programs.
The sample application program Letters (on side 2 of your
cassette) gives an example of one such application.
	The uses of these routines is manifold. You might use
them to set up a directory of your records and tapes or
books. You could equally use Datafile to keep track of all
your business clients. The example which follows guides
you through every stage of Datafile and explains the use of
Toolkit routines.


USING THE PROGRAM

	On using the LOAD "" command and playing side 1 of
your tape you will be greeted with the main menu. Before
you can use a file it must be defined in the following ways:

1.      Select option from the menu. The program first asks you to
name your file. You can call it anything you like but for this
example enter CLIENT.
2.      Number of records. Once you have named your file the
program asks you how many records will be on this file. It is
always a good idea to specify more than you think will be
required to allow for future growth.
	For this example enter 10. This will mean that only 9
clients can appear on the file because Datafile uses the first
record to store information about the file size and structure.
3.      Record size. Each record can be any size you wish.
Obviously it must be equal to or greater than the maximum
number of characters of data that you wish to store on each
record. For the example enter 120.
4.      Number of fields. What you enter here requires some
thought. It is necessary to define one field for every item of
data which you want to hold on each client. The difficult part
may be deciding what constitutes an "item of data".
	Say you wanted to store the address of each client. You
could specify just one field called say, ADDRESS. This would
not be very useful because then you would be unable to access
individual lines of the address. A better solution would be
to define one field for each line of the address and call them
something like ADLIN1, ADLIN2 etc to refer to address line 1
and so on. For this example enter 10.
5.      Field definition. If you have followed the example
instructions then the program will now tell you that the CLIENT file
has 10 records of 120 characters each.
	The program will then ask for a name and size for each
field in turn. You can call the fields anything you like but any
name more than 6 characters long will cut short automatically.
I recommend that you give meaningful names to your fields
to make future use of your files easier. There is no restriction
on the length which you specify for each field providing that
the sum of the field lengths is less than the record length
which you entered at 3 (record size) above. For the example I
suggest that you enter the following field names and lengths:

Name of field   Length of field
INITS           6
NAME            15
ADLIN1          20
ADLIN2          15
ADLIN3          15
ADLIN4          10
PHONE           15
ACCNO           6
INVDAT          8
INVNO           6
		---
		116
		---

The total length of these fields is 116 characters which is less
than the 120 character size which we entered at 3 above.
When you have entered the data above you will have defined
all of the 10 fields which you specified for each client record
at 4 above. You will now be returned to the main menu.


ENTERING DATA

First select option 2 from the menu. If you have been following
the example then you will be asked for the value of INITS
in this record. For reasons which will become plain when
you use LETTERS, enter your own initials separated by full
stops. Your entry will now be displayed next to the field
name. If you have made a mistake don't worry, you will
be given an opportunity to put it right when you have entered
all the data for this record. Continue to enter your details
as prompted. If you just press "ENTER" when asked for a
value then that field will not be left empty. Clearly you will
not have an account number and you will not have invoices
outstanding yourself. Thus for these fields leave a blank. If
you later sort the file by invoice date for instance then records
with no invoice date will be put at the front of the file.
	Having entered your own details you will be asked
whether you wish to alter anything. If you enter "Y"
then you will be prompted to enter a new value for each field
in turn. If you just press "ENTER" when prompted
then the value for that field will be left unchanged. When you
are happy with the record content, press "ENTER" when
asked if you want to alter anything and you will be asked
whether you wish to enter any more records. If you enter "Y"
then the process above will begin again. If you just press
"ENTER" then you will be returned to the main menu.
	When you enter dates I suggest that you use the
American format: YY/MM/DD rather than the British format:
DD/MM/YY. If you do this then you will be able to sort your
records by date using the sort routine in Datafile. You might
wish to sort clients into Date of Birth order for example.


SORTING FILES

Select option "3" from the main menu. Assuming that
you have more than one record on your file you can now sort
them  alphabetically or numerically.
	The sort routine will first ask you for the name of the
field by which you want to sort your records. For example, if
you want to sort your file so that the records appear in
alphabetical order of names then you might enter NAME.
	If the field name that you have entered was a valid one
then the message "SORTING" will appear on your screen.
When sorting is complete you will be returned to the main
menu. If you have entered the name of a field which does not
exist then you will be asked to enter another. If you have
forgotten the names you assigned to the fields of your
record don't panic. Just press "ENTER" and you will be
returned to the main menu. You can now select option
"8" which will tell you the names that you gave (see PRINT
FILE DETAIL).


AMENDING/DELETING RECORDS

Select option "4" from the menu. You will be asked for
the name of a field. Say you know that the record which
you wish to amend is that of Mr West. This means that the
name WEST will be in the NAME field of that record. You
should thus enter NAME when asked for a field and WEST
when asked for a value for that field.
	If you enter a field name which you have not defined
then you will be asked to try another.  Just  pressing
"ENTER" at this point will return you to the menu. If the
value of the field does not exist on the file then a message will
be displayed to this effect. For example, if you had not
entered a record for Mr West when entering data.
	Once the record that you require has been found you will
be given the opportunity to alter each field in turn. If you
do not wish to amend a particular field then just press
"ENTER" when prompted for a new value.
	To delete a record select option "5" from the menu. As
when amending records, you will be asked for the information
that the program requires to find the record that you
wish to delete. When the record has been found it will be
removed from the file and you will be returned to the main
menu.


SAVING AND LOADING

Once you have got some data on your file you may want to
save the file to tape. To do this select option "6" from the
menu. The file will now be saved under the name by which it
was defined above. If you followed the example your file
will be saved as "CLIENT" DATA A$().
	When the file has been saved you will be prompted to
rewind the tape and prepare for verification. You will be returned
to the main menu when verification is completed. If
verification fails, use "GO TO 1" to return to the menu and
then try again.
	If you wish to update files which you have already saved
to tape then select option "7" from the menu. You will be
asked for the name of the file. If you have forgotten it then
just press "ENTER". The program will then load the first file
that it comes to on tape.
	When the program has loaded your file it will decode
the first record to determine the format of your file and the
names which you gave to its fields. It will then return to the
menu. You can find out the names of the fields etc by
selecting option "8".


PRINT FILE DETAIL

Select option "8" from the menu. The program will then
print the names of each of the fields in the file and tell you the
position that they occupy in each record.
	For example if field INITS starts at 1 and ends at 6 then
this tells you that INITS occupies the first 6 characters of
each record, ie. for record 2 INITS would be A$(2, 1 TO 6).
	To print the whole file select option "9" from the
menu. Each record on the file will be displayed in turn.


WARNING!

If you BREAK out of the program for any reason use "GO
TO 1" to return to the menu. Do not use "RUN" since this
will result in the loss of any data held on the current file.
	A list of the variables used by Datafile is given in REM
statements at the start of the program. You must not use
these variables in your own programs when you use
Toolkit to manipulate data held on files created by Datafile.


USING TOOLKIT

Each of the routines in TOOLKIT is designed to make
using Datafile files in your program easy. Each routine is fully
documented in REM statements.

1. Get field value. Each record in a Datafile file is stored as an
element of the array A$. For example, the first record in the
file will be A$(2). You will remember from the field definition
stage that each field within a record also has a
number and a name. The field number enables Toolkit to find
out the position of a field in each record. It might, for
instance, be A$(2,1 TO 6) as for INITS in the example. This
routine when supplied with a record number in RN and a field
number in FN will fetch the value of that field in record
number RN. The value is returned in Q$ and trailing
spaces are automatically removed.

2. Decoding dates. I have already  explained  the
usefulness of storing dates in the American format. This
routine will translate a date supplied in Q$ from the
American form to the British form.

3. Removing spaces. If you have given a field in a record a
value with less characters than the field length then the field
will contain spaces after your value. This routine removes
the unwanted spaces from a field value supplied in Q$ and
returns the trimmed value in Q$.

4. Read header. I explained above that the first record on a
Datafile file contains information required by Toolkit to use
the data in your file. When you use the LOAD routine this
routine is automatically called to find out the format of your
file.

5. Loading files. This routine will load a Datafile file and call
the header reading routine. The name of the file should be
in Q$ on entry to the routine. If you don't know the name than
let Q$ = "".

6. Find field number. The name of the field required should be
in Q$ on entry to the routine. The routine will then find out
the number of that field and return the result in FN. The
value of FN allows you to get the start and end positions of
that field from the numeric array F() which will have been
filled by the header read routine. F(FN,1) holds the
start position and F(FN,2) the end position. Thus, field 1 of
record 1 extends from A$(1,F(1,1)) to A$(1,F(1,2)).

7. Finding a record number. This routine returns in RN the
number of the record which has a value equal to that of Q$
in the field designated by FN. You should define Q$ and FN
before entry to the routine. The record number is returned
by the routine in RN.


LETTERS: A SAMPLE APPLICATION

If you followed the example that I have given you will now
have a file called CLIENT. LETTERS will input this file from
tape and then write a letter to each client reminding them of
the account that they have outstanding. Now you know
why your own details should be entered first.
	The listing of LETTERS should help you to develop
your own applications. I hope that Datafile meets all your
requirements.

------------------------------------------------------------------------------
TYPE: Utility

Comment:

This info file was typed by Jim Grimwood

Downloaded from:
Desert Island Disks -- http://www.image.dk/~frankie/
Maintained by:
Michael Bruhn -- frankie@image.dk
