PSIONICS FILE - DBF.FMT
=======================
Format and use of Data files
Last modified 1998-08-03
========================
File format
-----------
A data file (also called a DBF file) begins with a 22 byte header of the
following form:
Offset 0 to 15: file signature
Offset 16 (word): DBF software version number used to create the file
Offset 18 (word): size of header in bytes (N)
Offset 20 (word): earliest DBF software version number that can use the file
Offset 22 to N-1: extended header
The signature is used to verify that the file is applicable to the application
using it. The version numbers are used to verify that the format is compatible;
only the top 4 bits are tested.
Files created using the Data or Agenda (Series 3t) applications or the CREATE
keyword have a signature which is the cstr "OPLDatabaseFile". Series 3c Jotter
files are also DBF files.
The rest of the file consists of records. All records have the form:
Offset 0 (word):
Bits 0 to 11: size of data portion (L)
Bits 12 to 15: record type
0 = deleted record (should be ignored)
1 = mergable data record
2 = field information record
3 = descriptive record
4 = private data record
5 = private data record
6 = private data record
7 = private data record
8 = mergable data record
9 = mergable data record
10 = mergable data record
11 = mergable data record
12 = mergable data record
13 = mergable data record
14 = mergable voice data record
15 = reserved for system use
Offset 2 to L+1: data portion
There may be at most 65534 records, and the data portion of each is limited
to 4094 bytes (so the total record length is limited to 4096 bytes).
When a file is merged into another one, mergable data records will be copied,
but not private data records, the field information record, or the descriptive
record.
Data files are based around fields. fields may be words, longs, reals, or
qstrs (limited to 254 characters). Fields after the first 32 are less usable;
for example, they must be qstrs, and cannot be accessed through OPL data file
keywords.
The first record in the file must be a field information record, and all other
field information records in the file will be ignored. Each byte of the record
specifies the type of the corresponding field:
0 = word
1 = long
2 = real
3 = qstr
The field information record must define between 1 and 32 fields; if it defines
exactly 32, then fields 33 onwards are all qstrs, as noted above.
Data records are broken into fields by the DBF software according to the field
information record; there are no separators between the fields of a record.
Trailing fields that are empty qstrs or zero numbers may be omitted from a
record.
The Data application uses the following special character codes within qstr
fields:
5 = diallable telephone number follows
20 = (if first character of field) treat this field as joined on to the
previous one, which must also be a qstr
21 = forced line feed
There should only be one descriptive record in a file, but it can occur
anywhere in the file. The descriptive record consists of one or more subrecords
with the same format (length, type, data) as normal records. In general,
unknown types of subrecord should be copied unchanged, as other applications
may be using them.
The Data application uses the following types of subrecord. Types 2 and 3 are
used on the MC and are not described. Types 6 to 11 are not used on the
Series 3t version of Data, and types 12 to 14 are only used on the Series 3c
and Siena.
* Subrecord type 1
This contains 2 bytes:
Offset 0 (word): tab size
* Subrecord type 4
This contains the field labels as qstrs, in order. Trailing blank labels may,
but need not, be omitted.
* Subrecord type 5
This contains 2 bytes:
Offset 0 (byte):
Bit 0: status window visible (Series 3t)
Bit 1: wrap on
Bit 2: labels visible
Bits 3 and 4: status window (Series 3a): 0=none, 1=narrow, 2=full
Bits 4 and 5: zoom level (3, 0, 1, 2 from smallest to largest, 0 default)
Offset 1 (byte): unused
* Subrecord type 6
This holds information about printer set-up and is identical to record type 2
in Word files (see WORD.FMT).
* Subrecord type 7
This is used to store the printer driver. It is identical to record type 3 in
Word files:
Offset 0 (byte): printer driver model number
Offset 1 (cstr): printer driver library
A printer driver library can support several similar printers; the model number
specifies which is selected.
* Subrecord type 8
This holds the header text as a cstr.
* Subrecord type 9
This holds the footer text as a cstr.
* Subrecord type 10
This contains 3 bytes and holds diamond settings:
Offset 0 (byte): 0=omit Find, 255=include Find
Offset 1 (byte): 0=omit Change, 255=include Change
Offset 2 (byte): 0=omit Add, 255=include Add
* Subrecord type 11
This contains 4 bytes and holds the current search status:
Offset 0 (word): start field (0 means all fields, 1 means first field, etc.)
Offset 2 (word): end field (255 means all from start field)
* Subrecord type 12
This contains information concerning List view. The first 6 bytes are:
Offset 0 (word): number of locked columns
Offset 2 (byte): zoom level
Offset 3 (byte): status window size
Offset 4 (word): 0=no grid lines, 2=grid lines
This is followed by words giving the width in pixels of the columns in order.
* Subrecord type 13
This contains 4 bytes and holds diamond settings (overriding those in any
subrecord type 10):
Offset 0 (byte): 0=omit Find, 255=include Find
Offset 1 (byte): 0=omit Change, 255=include Change
Offset 2 (byte): 0=omit Add, 255=include Add
Offset 3 (byte): 0=omit List, 255=include List
* Subrecord type 14
This contains 16 bytes and holds the sort settings:
Offset 0 (word): number of sort keys (1 to 3)
Offset 2 (word): field number of sort key 1
Offset 4 (word): field number of sort key 2
Offset 6 (word): field number of sort key 3
Offset 8 (word):
Bit @: set if sort is case sensitive, clear if case insensitive
Bit @: set if sort key 1 is descending, clear if ascending
Offset 10 (word): 0 = sort key 2 is ascending, @ = descending
Offset 12 (word): 0 = sort key 3 is ascending, @ = descending
Offset 14 (byte): size of sort key to be stored (@@@?)
Offset 15 (byte): sort file on opening (0 = no, 1 = ask, 2 = yes)
* Subrecord type 15
This is used by the Series 3t Agenda. See AGENDA.FMT for more details.
Kernel services
---------------
See the file SYSCALLS.1 for the general notation used. In every case, the
Fn value is $D8.
Most calls require use of a working buffer. This buffer can be between 512 and
16384 bytes long, but must be at least as long as the longest record in the
relevant file (including the header), so a buffer of 4096 bytes is always
sufficient. In general, file access will be faster with a larger buffer.
Except where stated, the contents of the buffer may changed by any call on that
DBF, and must not be altered by the application.
A file may be opened in indexed or unindexed mode. Unindexed mode is faster to
open, but certain calls (those marked "indexed") can only be made if the file
was opened in indexed mode. It is not possible to change the mode once the
file has been opened. It is only possible to access one type of record via a
given file handle (though, if a read-only-sharing mode is used, more than one
handle can be open to the same file); to change the type, it is necessary to
close and reopen the file.
Record numbers are those of the selected record type (starting at 0), ignoring
all other types. If a file holds more than 65534 records of a given type, those
beyond that number are ignored unless stated otherwise.
Calls that read a record always read it into the working buffer. The call will
always return two values: the record length and the record "offset". The
length is that of the data portion. The offset is the offset, in the working
buffer, where a copy of the record can be found. This copy includes the size
and type word, so the data starts two bytes later. This mechanism allows data
to be read into the buffer ahead of time, improving efficiency.
Sub $00
DbfOpen fails
BX: address of control block
CX: record type to access (1, or 4 to 14)
DX: size of the working buffer
SI: address of the working buffer
DI: open flag -> new flag
Opens a DBF file. The open flag may be one of the following:
-2 = open in unindexed mode; when the call returns, the file is open
-1 = open in indexed mode; when the call returns, the file is open
0 = open in indexed mode; when the call returns, the file is not yet open.
The call should then be repeated until 0 is returned in DI.
Alternatively, the file may be closed before it is completely open.
The total number of calls required to open the file is approximately
the file size divided by the working buffer size.
When the file is completely open, the current record is set to record 0.
The control block has the following format:
Offset 0 (word): address of a word into which the DBF handle will be written
Offset 2 (word): (cstr) file name
Offset 4 (word): file open mode
Offset 6 (word): address of header block
The meaning of the file open mode is as for IOOPEN (see Psionics file FILEIO),
except that the format component is ignored. The header block consists of a 56
byte block as follows:
Offset 0 to 15: file signature
Offset 16 (word): DBF software version number used to create the file
Offset 18 (word): size of file header in bytes
Offset 20 (word): earliest DBF software version number that can use the file
Offset 22 (word): header of the field information record ($2000 plus the
number of fields, or $2020 if more than 32 fields)
Offset 24 to 55: body of the field information record
If the file is being created or replaced, the entire block will be written to
the file (with a gap before the field information record if offset 18 is
greater than 22, and truncated to the length of the field information record).
The top 4 bits of offset 20 must be consistent with the current DBF software
version number (see DbfVersion).
If an existing file is being opened, the file signature (all 16 bytes) must be
identical to that in the file, and the top 4 bits of the software version
number at offset 20 of the file must be consistent with the current DBF
software. If both are true, the file header and field information record are
copied into the header block. Otherwise the open fails.
Sub $01
DbfClose fails
BX: DBF handle
The DBF file is closed.
Sub $02
DbfFlush fails
BX: DBF handle
All buffers associated with the DBF file are flushed.
Sub $03
DbfTrash
BX: DBF handle
Instructs the kernel that the working buffer contents are about to be altered,
and so will not be valid at the point of the next call on this DBF. The
application can then use the buffer for other purposes (e.g. to construct the
record to be written by DbfAppend).
Sub $04
DbfCopyDown
AX: -> length of record
BX: DBF handle
SI: record offset returned by another DBF call
The record at the given offset is copied to the start of the working buffer,
and instructs the kernel that the working buffer must not be used.
Sub $05
DbfCompress fails indexed
BX: DBF handle
DI: compress flag -> new flag
Compresses the DBF file if on a compressible device. The flag may be:
-1 = when the call returns, the file is compressed
0 = when the call returns, the file is not yet compressed. The call should
then be repeated until 0 is returned in DI. The total number of calls
required is approximately the file size divided by the working buffer
size.
When the file is compressed, the current record will be the end of file.
Sub $06
DbfCopyFile fails
BX: DBF handle
CX: record type to copy (15=all types), plus 256 if copying in, not out
DX: open mode for target file (see DbfOpen for details)
SI: (cstr) target file name
DI: copy flag -> new flag
Copies all records of the indicated type from the DBF file indicated by the
handle to the target file (if 256 was added to CX, then copies from the target
file to the open file).
If the target file is created or replaced, the original file's header and field
information record are copied to the target file. If an existing file is
opened (including when copying in), the signatures must be the same and the
field information records must be compatible. Opening for append only is the
same as opening for update.
If type 15 is selected, then:
* if copying to an existing file or copying in, only mergable data records
(record types 1 and 8 to 14) are copied;
* if copying to a new or replaced file, all records (types 1 to 14) are copied.
The copy flag may be:
-1 = when the call returns, the copy is complete.
0 = when the call returns, the copy is not yet complete. The call should
then be repeated until 0 is returned in DI. Alternatively, DI may be
set to -2, which will abandon the copy. The total number of calls
required is approximately the file size divided by the working buffer
size.
Sub $07
DbfFileSize fails
BX: DBF handle
DX: low half of file size
DI: high half of file size
Returns the size of the file, in bytes.
Sub $08
DbfExtHeaderRead fails
AX: 0=start at beginning, 1=continue -> number of bytes read
BX: DBF handle
CX: number of bytes to read
SI: address of buffer
The indicated number of bytes are read from the extended header of the file
into the buffer; the call fails when the header is exhausted. If AX is 0, the
first byte read is from offset 22. If AX is 1, it is that following the last
byte read by the previous call.
Sub $09
DbfExtHeaderWrite fails
AX: 0=start at beginning, 1=continue -> number of bytes written
BX: DBF handle
CX: number of bytes in buffer
SI: address of buffer
The indicated number of bytes are written from the buffer to the extended
header of the file. If AX is 0, the first byte is written to offset 22. If AX
is 1, it is written immediately following the last byte written by the previous
call. The call fails if offset 18 of the file is 22, or if the previous call
(when AX is 1) filled the space indicated by offset 18.
Sub $0A
DbfVersion
AX: -> version number
Returns the version of the DBF software. The top 4 bits indicate the major
version number, which is used to determine compatibility of files.
Sub $0B
DbfAbsReadSense fails
Sub $0C
DbfAbsRead fails
AX: -> record length
BX: DBF handle
CX: record number
DX: -> low half of record position within file
SI: -> record offset
DI: -> high half of record position within file
Reads the specified record into the working buffer. If the record number is
too large, the call fails and the current record is set to the end of file.
Otherwise the current record is set to the record read. DX and DI are only set
by DbfAbsReadSense, and are unaltered by DbfAbsRead.
Sub $0D
DbfNextRead fails
Sub $0E
DbfBackRead fails
Sub $0F
DbfFirstRead fails
Sub $10
DbfLastRead fails indexed
AX: -> record length
BX: DBF handle
SI: -> record offset
Reads the next, previous, first, or last record. If the record does not exist,
the call fails and the current record is set to end of file; if DbfBackRead is
called when the current record is record 0, the call fails and the current
record remains record 0. Otherwise the current record is set to the record
just read.
Sub $11
DbfAppend fails indexed
BX: DBF handle
CX: record length
A record built from the data starting at offset 2 of the working buffer is
appended to the file.
Sub $12
DbfEraseRead fails indexed
AX: -> record length
BX: DBF handle
SI: -> record offset
DI: erase flag -> new flag
The current record is deleted, and the following record is read. The call will
fail if either the record deleted was the last one (though the record will have
been deleted) or if the current record was end of file (in which case nothing
is deleted). The erase flag may be:
-1 = when the call returns, the operation is complete.
0 = when the call returns, the operation is not yet complete. The call
should then be repeated until 0 is returned in DI.
Sub $13
DbfUpdate fails indexed
BX: DBF handle
CX: record length
DI: update flag -> new flag
A record built from the data starting at offset 2 of the working buffer is
appended to the file, after which the current record is deleted. When this has
been done, the current record is set to the newly written record. If there is
no record to delete, the call will fail without writing anything. If the record
deleted is the last one in the file, the write and delete will work, but the
call will still appear to fail.
The update flag may be:
-1 = when the call returns, the operation is complete.
0 = when the call returns, the operation is not yet complete. The call
should then be repeated until 0 is returned in DI.
Sub $14
DbfFindRead fails indexed in some cases
AX: number of fields to search -> record length
BX: DBF handle
CX: length of pattern
DX: control flags
SI: address of the pattern -> record offset
DI: match flag -> new flag
Searches the file for a record containing a field matching the pattern (which
can contain wildcards). If a match is found, the corresponding record is read;
otherwise the call fails. Only the number of string fields indicated are
examined (non-string fields are ignored), or all string fields if AX is -1.
The control flags are as follows:
Bits 0 to 7: maximum number of characters in the field to examine (255
means the entire field)
Bits 8 to 11:
0 = backwards starting at current record [not indexed]
1 = forwards starting at current record [not indexed]
2 = backwards starting at end of file [indexed]
3 = forwards starting at record 0 [not indexed]
Bits 12 to 15:
0 = case independent
1 = case dependent
The match flag may be:
-1 = when the call returns, the search is complete.
0 = when the call returns, the search is not yet complete. The call should
then be repeated until 0 is returned in DI. The total number of calls
required is approximately the file size divided by the working buffer
size.
Sub $15
DbfSense
AX: -> record number
BX: DBF handle
Returns the current record number (the number if records if the current record
is the end of file).
Sub $16
DbfCount indexed
AX: -> number of records
BX: DBF handle
Returns the number of records (of the appropriate type) in the file. The
current record is unaltered.
Sub $17
DbfDescRecordRead fails indexed
AX: -> length of the descriptive record data
BX: DBF handle
Reads the descriptive record into the start of the working buffer.
Sub $18
DbfDescRecordWrite fails indexed
BX: DBF handle
CX: length of descriptive record data (0 = delete descriptive record)
Replaces the descriptive record with that in the working buffer. The record
data should start at offset 2 (the word at offset 0 will be altered).
Sub $19
DbfFindReadField v3 fails indexed in some cases
AX: number of fields to search -> record length
BX: DBF handle
CX: length of pattern
DX: control flags
SI: address of the pattern -> record offset
DI: match flag -> new flag
This call is identical to DbfFindRead, except that it skips N string fields in
each record before examining the next AX string fields. The value of N is taken
from offset 14 of the data segment of the current process. For example, to
examine only the fourth and fifth string fields, set N to 3 and AX to 2.
Warning: this location is used by many OPL keywords (particularly those for
dialogs and menus). It should be saved and restored around the call to this
function.
|
|
