    			Psion DATA file conversion programs
    			===================================

    			(c) Copyright Psion PLC 1994, all rights reserved

Release:	V1.00F
Date:		14th. March 1994
Author:		Colly Myers
Compuserve ID:  100013,3205
CIX ID:		colly

DISCLAIMER

This program is not an official Psion product, and as such is not
directly supported by Psion PLC or any of its associated companies.
However any problems can be reported to the author either either on
Compuserve or CIX. Supporting files and documentation regarding the
problem should also be sent to the author if you require the problem
to be treated with any urgency.

This program and documentation are provided "as is" without warranty of
any kind, either expressed or implied. In no event will Psion be liable
to you for any damages arising out of the use or inability to use this
program and/or the development files and documentation.

LICENSE

These programs are free and may be re-distributed as you see fit.

INTRODUCTION
============

The two program supplied, TEXT2DBF.EXE and DBF2TEXT.EXE are IBM/PC
programs which can be used to convert between delimited text files and
the Psion DATA .DBF files as used on the Psion S3 and S3a. These programs
are both capable of handling fields within a record of greater than 255
bytes.

LABEL FILES
===========

The .DBF files contain a special record which contains the information for
the label template, used to label the fields in the file. Since most PC
programs are not capable of producing a label record as part of the
delimited text file, a separate file is used for the label information.

This file is a plain text file with one record per label. A record may be
blank in which case the corresponding label will be blanked. All blank
records at the end of the file are ignored.

An example file for the defaul labels supplied with the DATA program
is supplied in the file default.lab. If you edit the file you will
notice that the Home, Work and Fax fields all start with what looks
like a CLUB (as in SPADE,HEARTS,DIAMONDS and CLUBS). This character
has the value ASCII 5 and can be entered by holding down the ALT key
and pressing 5 on the numeric keyboard. Alternatively the file
default.lab can be edited and the character can be cut and pasted.

Label files are best created with a text editor, such as EDIT.EXE
supplied with MSDOS, or NOTEPAD.EXE supplied with Windows.

A label file can be automatically created by DBF2TEXT.EXE. The file
so created is suitable for use with TEXT2DBF.EXE.

QUOTING
=======

Some programs produce delimited text files with the fields quoted. i.e.

"PSION","SERIES 3A","256K"
"PSION","SERIES 3","128K"

These quotes can be removed by TEXT2DBF.EXE as they are not required by
the DATA program, by specifying the -Q flag. A very few programs do not
use the " character for quoting, in which case the the quote character
can be specified after -Q. If your text looked as follows:

'PSION','SERIES 3A','256K'
'PSION','SERIES 3','128K'

the quotes could be removed by specifying -Q'

It does not matter if some of the fields are not quoted and some are the
program will deal with all variations correctly.

Quotes can be generated by DBF2TEXT when going form the .DBF file to a
delimited text file by specifying the same -Q argument as for TEXT2DBF.EXE.

Both programs correctly handle nested quotes within a field, i.e.

"This is ""quoted"" ok"

gives after removal of the quotes

This is "quoted" ok

NOTE:

If a field is expected to contain the field delimiter then it is necessary
to use quoting. e.g.

1st., Floor,Anywhere St.,London

Will give rise to four fields. What was probably intended using quotes is:

"1st., Floor","Anywhere St.","London"

which gives rise to just three fields, since the first comma is between
quotes.

DELIMITERS
==========

The text files are assumed by default to contain one record per line where
a line is delimited by CARRIAGE RETURN,LINEFEED. The maximum record length
supported by DATA is 4094 characters. The end of line delimiter cannot
be changed at this time.

Within a record each field is assumed by default to be separated by a comma.
If the defaul is not suitable then it can be changed by specifying the -D
option on the command line to either program. -D must be followed by the
delimiter character or ^ followed by a letter. The second form is used to
specify control characters which are difficult to enter on the command
line. The case of the letter following ^ is irrelevant. Thus ^i and ^I
are the same. ^i implies CTRL+I which is Ascii 9 which is TAB.

-D,	specifies comma as the delimiter (the default if -D is missing).
-D:	specifies : as the delimiter.
-D^i	specifies TAB as the delimiter.
-D^j	specifies LINE FEED as the delimiter.

TEXT2DBF.EXE
============

This program converts a delimited text file to a .DBF file compatible
with the DATA program on the Psion Series 3 and Psion Series 3a. An
optional label file can also be specified. The command line arguments
are as follows:

TEXT2DBF [-Q[char]] [-Dchar] [-Lfilename[.lab]]
         [-Ofilename[.dbf]] filename[.txt]

-Qchar             Strip quotes char from text fields (optional)
-Dchar             Specify the delimiter as char (optional)
-Lfilename[.lab]   The name of a label file (optional)
-Ofilename[.dbf]   The name of the output file to be created (optional)
filename[.txt]     The name of the input file to convert.

DBF2TEXT.EXE
============

This program converts a .DBF file, from the DATA app on the Psion Series 3
or Psion Series 3a, to a delimited text file. Optionally a label file can
also be produced. The command line arguments are as follows:

DBF2TEXT [-Q[char]] [-Dchar] [-Lfilename[.lab]]
         [-Ofilename[.dbf]] filename[.txt]

-Qchar             Add quote character char to all fields (optional)
-Dchar             Specify the delimiter as char (optional)
-Lfilename[.lab]   The name of a label file to create (optional)
-Ofilename[.txt]   The name of the output file to create (optional)
filename[.dbf]     The name of the input file to be converted

OMISSIONS
=========

The .DBF file contains a number of settings which reflect the options
available with the DATA app, such as WRAP ON/OFF, the current printer
driver, the font size etc. Apart from the field labels none of these
other settings can be set. The next version of the programs will
address this issue.

When fields are entered in the DATA app editor, a soft carriage return
can be used to force a new line between two labels. The soft carriage
returns are actually present in the data for the field as character
ASCII 21. This character looks like the character at the start of the
line below:



The next version of DBF2TEXT will allow an option to discard these
characters or to convert them to a field delimiter. Currently they
get passed straight through.


