BltDataCreateFile


< Prev  TOC  Next >

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 pack

This 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().


Field Descriptor

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: , Y/N/T/F/y/n/t/f). An empty date should be left blank (all spaces) and an empty logical should be left blank (a space).

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 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.

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 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.

The FD 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.

The FD 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.

The rest of the (unused) FD members must be set to 0 (binary 0).


All content Copyright © 1999 Cornel Huth. All rights reserved.