KeySoft Databases

A database is a computer application that looks after information for you.  KeySoft's Address List, KeyList, is an example of a simple database.  You can enter names, addresses and phone numbers into it, look them up, change them, print them, and so on.  KeyList can handle other types of information as well because it is the file that KeyList is using that determines the type of information it handles.  For example KeyList could be used to keep a catalogue of your CD collection, or an inventory of all your household effects.  While KeySoft does not provide the facilities to create a new database, there are a number of different databases available which you can use and there is a special program called KLGEN with which you can create a database of your own, or modify the structure of an existing database.


Additional Databases Available

If you have KeySoft ST you will already have a number of different databases in your C:\KEYNOTE\KEYLIST directory.  

If you have a Companion, ask your distributor for the databases, or download them from PulseData's web site at http://www.pulsedata.co.nz.  Your KEYLIST directory is the best place to keep databases, so copy them into there.

The following databases are available:

Book catalogue
Business contacts
Inventory
Membership
Music catalogue
Personal contacts

To use one of these databases first select it using the "Select KeyList file" option in the KeyList Menu.  Now use KeyList in the usual way to add records, lookup records, print them, etc.  You can copy records from one database file to another using KeyList's Copy option.  You can also print records, emboss them (if you have a Braille Companion) or copy records from a database to a document.  However before printing, embossing or copying records from one of these databases, you must write a special template that specifies the format of the fields you want included in the printout or copy.  See Section 9.9 of the Keynote Companion or KeySoft User's Manual, or Section 9.11 of the Braille Companion User's Manual. 

Once a database has been selected, it will remain in use until you select another one.  So to return to using KeyList for addresses you must use the "Select KeyList file" option again to select the "Address Notebook".


Braille Databases

While the Keynote Companion and the QWERTY versions of KeySoft can only use one type of database, the Braille Companion can use either a text database or a braille database. Text databases are identical to the ones used by the QWERTY models of KeySoft and on the Braille Companion computer braille must be used for all entries into a text database.  Braille databases are different in that grade 1 and grade 2 braille can be used.  Each field has its own expected or default grade but an entry can be made in any grade.  KeyList keeps track of the actual grade in which each field entry was made.  This allows each field to default to an appropriate grade but allows the user flexibility in the grade of entry.  For example, a person's name might be entered in grade 2 braille but an email address might be entered in computer braille.


Creating Your Own Database

If you want to create your own database or change the field configuration of an existing database, a program called KLGEN is available to do this.  KLGEN is a standard DOS application.  It does not speak so it must be used with a screen reader, unless of course, you are sighted.   Because it requires a screen reader it cannot be run on the Keynote or Braille Companion.  You can, however, use databases created or modified by KLGEN on a Companion, but you must run KLGEN itself on a desktop or laptop computer.  It was written for Pulse Data International's own internal use and as such has not been exhaustively tested.  We do not guarantee that KLGEN will work in the way you expect and can take no responsibility for anything it does or does not do.  KLGEN is supplied as standard with KeySoft ST and is installed in the C:\KEYNOTE\KEYLIST directory.  If you don't have a copy and want to obtain one, contact your KeySoft distributor or download it from PulseData's web site at http://www.pulsedata.co.nz.

KLGEN allows you to create a new database or modify an existing database.  You can create databases with up to 40 fields in each record, with each field containing up to 50 characters.


Modifying Existing Databases

KLGEN is intended for use on empty databases.  If you alter the field configuration of a database that already contains data, KLGEN will not reformat the data to the new configuration and the database will be unusable.  If you need to add or remove fields from an existing database or change the length of fields, use the following procedure:

A. Make a copy of the existing database, giving it a new name.

B. Use KLGEN to make the necessary changes to the new database.

C. When you exit KLGEN you are asked whether or not you wish to clear the existing data.  Answer Yes.

D. Using KeyList, select your old database using the Select KeyList File option.  Now use KeyList's Copy option, to copy the data from the old database to the new one.  If the field names do not match, KeyList allows you to control how the fields are copied.  For more details see Section 9.10.2 of the KeySoft and Keynote Companion User's Manual or Section 9.12.2 of the Braille Companion User's Manual.


Using KLGEN

To run KLGEN, just type KLGEN.  

First, you will be prompted for the DOS file name of the database you wish to work on.  For a "text" address list this is always in the form, KEYn.LST and for a braille address list it is in the form, KEYn.BAL.  If you do not know the DOS name of the database you want to work on, use KeySoft to copy the database file into a new subdirectory.  It will then be the only file in the subdirectory and a DIR will show you what its DOS name is.  When copying the file back again, use KeySoft rather than DOS because the number after "KEY" in the DOS filename may have to change when the file is copied.  If you use DOS to copy the file you may inadvertently overwrite another file.

After entering the DOS filename you will be asked for the KeySoft name for this file.  Enter a new one, or edit the existing one as required.

You are then shown the first of a series of screens that allow you to define the database.  To move around within each screen, use the ARROW and TAB keys.  To move between screens, use the PageUp and PageDown keys.

When you have finished using KLGEN you can either exit KLGEN and save the changes you have made, by pressing ALT with X, or quit without saving any changes you may have made, by pressing ALT with Q.

The screens are as follows:

A. The first screen is used to enter the name and length of each field in the database.  The field name is the text that KeyList speaks when referring to the field.  For example, "Surname", "Zip code" etc. A field name may consist of up to 25 characters.  The field length is the maximum number of characters the KeyList user will be able to enter into this field.  It may be between 1 and 50 characters.  As mentioned previously, a database may have up to 40 fields in total.

B. The next screen is used to enter a type for each field.  A field's type is a number that tells KeyList how to treat the entry in the field.  There are 11 different types as follows:

0 General.  This is used for a general text field.

1 Spell.  When entries in this type of field are reviewed, KeyList will spell them.  Use this for post codes, part numbers etc.

2 Name. KeyList will interpret the text in this type of field as a name.  For example, 'Dr' will be pronounced as 'Doctor' rather than 'Drive'.

3 Address.  KeyList will interpret the text in this type of field as an address.  For example, 'St' will be 'Street' rather than 'Saint'.

4 City.  KeyList will interpret the text in this type of field as the name of a city.

5 State.  KeyList will interpret the text in this type of field as the abbreviation for a State.  For example 'NE' is spoken as 'Nebraska' rather than 'Northeast'.

6 Country. KeyList will interpret the text in this type of field as the name of a country.

7 Organisation. KeyList will interpret the text in this type of field as the name of an organisation.

8 Password.  KeyList will not display or speak entries into this type of field.

9 Filename.  This type of field is used to store the name of a KeyWord text file that resides in the KEYTERM directory or folder.  In KeyList, special commands are available for this type of field, as follows:

a) In addition to typing a file name, a filename can be entered by selecting it from the KEYTERM directory or folder.  This is done by pressing CTRL with D on a QWERTY keyboard or SPACE with S on the Braille Companion.
b) When reviewing this type of field on the Braille Companion, the file can be opened by pressing Enter.

10 Filename with path.  This type of field holds both a KeyWord text file name and the path to the file.  The options available for the 'filename' type field are also available for this type of field. 

C. The third screen allows you to specify the order in which the records are sorted within the database.  This controls the order in which the records appear when you step through them in the Look-up option.  Fields are designated by typing the ordinal number of the field as shown on the screen above the input area.  Only a few fields are usually entered here.  For example in the Address Notebook that comes with KeySoft, the records are sorted first by Surname, then First name, followed by City.  This was specified by entering 1, 2, and 8 as the field sort order.

D. The fourth screen specifies the fields that are to be spoken when a record is initially reviewed, and the order in which they are announced.  For example, in the Address Notebook, the field announce order is 1, 2, meaning that the Surname and then the first name is spoken.

E. Next there is a prompt for the First Voice phone number field.  If your database does not contain any voice phone numbers, set this to zero.  Otherwise enter the number of the first field that contains a voice phone number.

F. After the First Voice phone number prompt is a prompt for the Second Voice phone number field.  If your database contains more than one voice phone number, then enter the number of the field containing the second phone number here.  Otherwise set this entry to 0.

G. Next is a prompt for a Data phone number field.  KeyTerm uses this when dialling an information service.

H. Fax phone number field.  KeySoft does not currently use this.

I. The next prompt is "Include KT parameters?"  This is asking if you want a set a KeyTerm parameters stored with each record.  These parameters include everything from the Baud Rate prompt onwards in a Directory of Services entry.

J. Email Service Field.  KeyTerm uses the field nominated at this prompt as the Service Name to look up in the Directory of Services and call to send email to this person.  If you are not going to be using your database in this way set this entry to 0.

K. Email Address Field. KeyTerm uses the field nominated at this prompt as the email address of the "owner" of this record.

L. This screen appears only when operating on braille address lists.  It allows you to specify the default braille grade for each field and allows automatic entry of number or capital signs.  Entries are as follows:

0 Default to grade 0 (computer braille)
1 Default to grade 1
2 Default to grade 2.  However if the Preferred Braille Grade is 1 then the default will be grade 1 instead).

Automatic entry of number or capitals signs applies only to grades 1 and 2 and is indicated by adding a value to the required grade, as follows:

For an automatic number sign add 4.  For example for a default braille grade of grade 1 and an automatic number sign, set the braille "grade" for this field to 5.  You might use this for a phone number, for example.

For an automatic capital sign add 8.  This is a useful feature that ensures that names, for example, always start with a capital sign.

For a double capital sign add 16.  This of course, produces entries that are all capitals.
