TBLT_RETC TBLT_ENTRY BltDataCreateFile(ULONG fileID, ULONG fields, FD *fieldListPtr, TBLT_FNCHAR *filenamePtr, ULONG maMode, TBLT_AUXPACK *apPtr); fileID I:first byte of the DBF file (low byte), memo block size (highword) fields I:number of fields fieldListPtr I:structure to use to build DBF field descriptors filenamePtr I:name of file to create (OEM characters recommended) maMode I:memory allocation mode apPtr I:auxiliary packThis routine creates a DBF data file based on the given field descriptor data.
The fileID
byte is typically 0x03 for DBF data files without a secondary
memo file. If memo fields are needed, .OR. 0x88 with 0x03 to get 0x8B,
which flags that this DBF is to include a like-named DBT (memo file). The
memo file is created automatically. All memo data is stored in this file.
To specify a memo block size other than 512 bytes, set the highword of fileID to that size. For example,
fileID = (1024 << 16) + 0x8B; // use 1024-byte memo blocks
The maximum block size is 65535 bytes. The size should be a multiple of 512 (512, 1024,...) for performance. The minimum size is 24 bytes.
Fields
indicates the number of field descriptors at fieldListPtr. Each
field's descriptor is 32 bytes long. See the compiler include file for the
technical structure of the field descriptor (FD). You can have as many
fields as you need (250 max recommended), and any number of different
field types. You can as many memo fields as you need, also, though one
or two is more typical.
The fieldListPtr
points to the field descriptors which
describe the DBF file to create. FDs are described below.
The filename
is the name to be given to the file to create.
maMode
is the memory allocation mode. In normal use this is specified
directly in each TBLT_DH structure, but at this point there is no TBLT_DH structure
allocated. The standard memory allocation mode is 0.
apPtr
is the pointer to an optional auxiliary pack. Set apPtr = 0 if there
is no pack. This pack lets you override the internal operating system IFS calls for this
handle, and set IFS options, such as 64-bit file offsets. See the supplemental
documentation for details. Once the file is opened, the apPtr is specified directly in the
TBLT_DH structure.
Returns: Non-zero indicates an error, otherwise the file is created. The file needs
to be opened before use with BltDataOpenFile()
.
Each field descriptor is 32 bytes in size; only the first 18 bytes are used and the remaing must be 0. For each field in the DBF data record, an FD (filled in by you) is used to describe that field with regard to its name, type, and size.
The FD (field descriptor) fieldName
is to be from 1 to 10 OEM characters
(zero-terminated) and may include the uppercase characters A to Z, and _.
The FD fieldType
is a single character. The available types are shown
below. Additional types are possible if support is added in the
BltFuncIx4BuildKey()
and BltFuncIx4SortCmp()
routines. All
data in standard DBF data fields is ASCII text. Bullet, however, allows binary data, too.
Standard types:
fieldType | type | size | example | notes |
---|---|---|---|---|
C | character | 1-254 (1-32000) | "40th Floor"
| with or without 0T |
N | numeric | 1-18 | ' 123.45'
| right-justified, decimal-aligned, no 0T |
D | date | 8 | '20001231'
| YYYYMMDD, no 0T |
L | logical | 1 | 'T'
| T,F,t,f,Y,N,y,n,<space> |
M | memo | 10 | '0000000001'
| memo #, blank if none, leading 0s or <spaces>, no 0T |
Common extended types:
fieldType | type | size | example | notes |
---|---|---|---|---|
F | numeric | 1-18 | ' 123.45'
| same as N |
B | memo | 10 | ' 2'
| binary memo field; same as M |
G | memo | 10 | ' '
| general memo field; same as M |
Bullet 3.0 extended types:
fieldType | type | size | example | notes |
---|---|---|---|---|
SORT_MIXED_S16 ('3') | signed short | 2 | SHORT
| requires SORT_MIXED sortCmpCode |
SORT_MIXED_U16 ('4') | unsigned short | 2 | USHORT
| requires SORT_MIXED sortCmpCode |
SORT_MIXED_S32 ('5') | signed long | 4 | LONG
| requires SORT_MIXED sortCmpCode |
SORT_MIXED_U32 ('6') | unsigned long | 4 | ULONG
| requires SORT_MIXED sortCmpCode |
SORT_MIXED_S64 ('7') | 64-bit long | 8 | INT64
| requires SORT_MIXED sortCmpCode |
SORT_MIXED_U64 ('8') | 64-bit unsigned long | 8 | UINT64
| requires SORT_MIXED sortCmpCode |
SORT_MIXED_DBL ('Y')
| IEEE FP double | 8 | DOUBLE
| requires SORT_MIXED sortCmpCode |
Any character may be used as the field type and any data may be used in a data field but only those listed in the three tables above can be used in an index. Only the standard fieldTypes are common to all Xbase versions since dBASE 3.1 (c.1985).
C-haracter field types are used to store text strings. C fields are typically, but not required to be, left-justified and zero-terminated.
N-umeric field types are used to store numbers, either integer or floating-point, in text format (for example, "12345.78"). When using this field type, this field in all records should be right-justified and decimal-point aligned. There is no zero-terminator on the field, nor is there on any Xbase field except C fields, and there it is only optional. The maximum field size is 18 digits (18.0), though 16 or fewer are recommeneded since most CPU/FPUs are limited to 16 significant digits.
D-ate and L-ogical field types use the same members as numerics
for field size, but their size is always constant: Date fields are 8 bytes
('YYYYMMDD') and Logical fields are 1 byte (any of the following:
M-emo field types are used to store a 10-byte ASCII memo block number
(similar in concept to a record number) of the first block allocated in a DBT
memo file for the memo data. Memo numbers are stored in ASCII (ie, not
binary). Typically, the memo number is stored with leading zeroes when there
is memo data (ie, a non-zero memo block number) and all spaces when there
is no memo data. However, it's possible that a memo field's contents created
by another Xbase application will have leading spaces instead. Therefore, care
must used when using sscanf() to convert the ASCII number to binary (the
An F field type is exactly the same as an N. Fields types B and G, for
binary and general memo types, are the same as M field types. Typically,
the M type is used memo text; B for memo binary data (images), and G is
used for Windows OLE support (whose use is very application-specific). The
low-level data structures are all the same for these three memo types.
SORT_MIXED S16 to SORT_MIXED_U64 are Bullet types for integer binary data. Binary data
is not normally used in Xbase DBF records, but it is very convenient to have. Also
available is the Y field type, which is for binary double (8-byte, IEEE floating-point)
data. When using these binary types, FD.fieldSize is not used by Bullet since the
sizes are already known (2/4/8 bytes). Therefore, you can use the fieldSize members
of FD to store the display format to be used for these types. For example, if using
a 'Y' field type, you can use the N size format (eg, 10.2) without regard to the
actual data size occupied in the DBF record. You may also simply use the actual data
size (2/4/8 bytes). These field types are only available to Bullet 3; other applications
won't be able to use them.
The FD
The FD
The rest of the (unused) FD members must be set to 0 (binary 0).
BltMemo*()
routines used binary values to specify which memo records
to read/write).
'0000000001' is a valid memo number, as stored in a DBF record
' 1' is also valid
' ' all spaces indicates no memo (all zeroes is not correct)
Memo number fields are not 0-terminated, making sscanf() dangerous when the
memo number has leading spaces (sscanf() ignores leading spaces when converting
from ASCII to binary), but a junk field can be placed after a memo field
to simplify reading and writing the memo number. A junk field would be a field
that isn't used for anything except to occupy the byte (set to 0) after a memo
field, as shown in this sample DBF record:
*
Stefan
Angstl
0000000001
\0
84489
Burghausen
Only a Character field should be terminated with a 0, but even that is not
required. Character fields are typically left-justified.
The FD fieldDA
is used in Bullet to store the start offset of each field
within the record. The first field starts at offset 1. This offset is calculated
by Bullet when the file is created, and again each time the DBF is opened since
not all Xbase implementations use this field this way. This field can be safely used in
this manner, even though it is not standard.
fieldSize.C_fieldLength
is used to describe the length of a
C-haracter field (only), and may be from 1 to 32000 bytes. The standard
maximum length of a character field is 254 bytes. Bullet 3 extends this to
32000 bytes. The recommended maximum character field length is 1000 bytes.
If more is required a memo field may be a better choice. A single memo can
hold any size data.
fieldSize.fs.fieldLength
and .fieldDC
are used
to describe the size of all other standard field types, including the N-umeric
field. .fieldLength is the total field length, in bytes. The .fieldDC is the number
of places to the right of the decimal point. A length of 8 and DC of 2 would allow
a "12345.67" to fill the field. Numbers are in ASCII text, and are right-justified
and decimal-point aligned. For all other known, standard field types .fieldDC
is set to 0, with fieldSize.fs.fieldLength
set to the required size, as
shown in the tables above.