SDFDBE (DATA component) Foundation

The SDFDBE manages ASCII files in System Data Format. The default file extension is ".TXT". Each line in the file has the same length and contains one record. Character, date, logical and numeric data types are supported, but the memo data type does not exist under the SDFDBE. The specification for a TXT file is as follows:

When a TXT file in SDF format is created, either with COPY TO...SDF, DbExport(), or DbCreate(), a second file is created containing the structure description for the fields in the TXT file. By default this file has the extension SDF and is an ASCII file which could also be created using a simple text editor. The structure definition is supported in the familiar INI file format that can be written in its generalized form as follows:

[<Section>] 
<Keyword>=<Value> 

In an SDF file there are two sections: [INFO] and [FIELDS]. The following program example creates a TXT file in SDF format which illustrates this:

PROCEDURE Main 
   LOCAL i 

                                       // create TXT file 
   DbCreate( "TEST", { {"CHARACTER", "C", 10, 0}, ; 
                       {"DATE"     , "D",  8, 0}, ; 
                       {"LOGICAL"  , "L",  1, 0}, ; 
                       {"NUMERIC"  , "N",  6, 2}  }, ; 
             "SDFDBE" ) 

   USE Test VIA SDFDBE                 // open using SDF engine 

   FOR i:=1 TO 10                      // append 10 records 
      DbAppend() 
      REPLACE FIELD->character WITH Replicate( Chr(64+i), i ), ; 
              FIELD->Date      WITH Date()+i                 , ; 
              FIELD->Logical   WITH (i % 2 == 0)             , ; 
              FIELD->Numeric   WITH (i ^ 2) / 2 
   NEXT 

   CLOSE Test                          // close file 
RETURN 

The example creates a TXT file with four fields and appends 10 records to the file. The file TEST.SDF is created as a structure file along with the data file TEST.TXT holding the data created in the FOR..NEXT loop. The structure file TEST.SDF looks like this:

[INFO] 
file=TEST.TXT 
fieldcount=4 
recsize=27 
reccount=10 

[FIELDS] 
CHARACTER=C,10,0 
DATE=D,8,0 
LOGICAL=L,1,0 
NUMERIC=N,6,2 
[END] 

The first section [INFO] describes the file TEST.TXT that contains the data. This includes the file name without directory (file), the number of fields (fieldcount), the length of a record (recsize) and the number of records (reccount). The second section [FIELDS] describes the fields in the file TEST.TXT. Field names appear on the left side of the equals operator and data type, field length and decimal places are specified as a comma separated list on the right side. The definition is terminated with the section [END]. Note that both files (SDF and TXT file) must be located in the same directory.

After the example code above has run, the file TEST.TXT contains ten records with the following contents:

A         19950822F000.50 
BB        19950823T002.00 
CCC       19950824F004.50 
DDDD      19950825T008.00 
EEEEE     19950826F012.50 
FFFFFF    19950827T018.00 
GGGGGGG   19950828F024.50 
HHHHHHHH  19950829T032.00 
IIIIIIIII 19950830F040.50 
JJJJJJJJJJ19950831T050.00 

The SDF DatabaseEngine manages this file and allows database operations to be performed on the file. This includes defining filter conditions using SET FILTER or DbSetFilter(), as well as creating relations with DbSetRelation() or SET RELATION. If the SDFDBE is connected to a compound DBE that contains the NTXDBE (SDFNTX), indexes can also be created for an ASCII file existing in the SDF format.

The SDF format imposes certain restrictions in programming. For example, it is not possible to delete records, because there is no provision in the SDF file format for deletion flags. For this reason, a call to the function DbDelete() causes a runtime error if the file is managed using the SDFDBE. Also, the SDFDBE opens the file exclusively which means ASCII files in the SDF format cannot be simultaneously used in the concurrent operation of several programs. The following table lists all common operations not supported by the SDFDBE:

The SDF DatabaseEngine can be configured in specific ways using the function DbeInfo(). The SDF file format and the access mechanism can be affected when the SDF or TXT file are created. The following table gives an overview of the special #define constants that can be passed to the function DbeInfo() when the DatabaseEngine is SDFDBE:

The default values are shown in the column "Value".

SDFDBE_AUTOCREATION

This constant determines whether only the SDF file or the SDF file and the TXT file are created by DbCreate(). The default value for this setting is .F. (false) and the function DbCreate() creates only the SDF file (structure file) and not the TXT file by default. If the TXT file does not exist when USE or DbUseArea() opens the file, it is created.

If this setting is .T. (true), DbCreate() generates the SDF file as well as an empty TXT file. Any previously existing TXT file with this name is overwritten.

SDFDBE_DECIMAL_TOKEN

The delimiter for decimal places in numeric values can be set using this value. The default is the period. The comma is specified as the separator for decimal places in numeric values by the following code:

DbeInfo( COMPONENT_DATA, SDFDBE_DECIMAL_TOKEN, "," ) 

When the delimiter is specified as the ASCII character 0 (= Chr(0)) the SDFDBE ignores any delimiters for numeric fields. It then uses the field specification as found in the structure extended file (SDF file). Example:

SDF file:

CHAR=C,4,0 
NUMERIC=N,6,2 

TXT file:

AAAA004321 
BBBB987654 

In this case the field NUMERIC would have the value 43.21 for the first record and 9876.54 for the second one.

SDFDBE_LOGICAL_TOKEN

This setting specifies the two characters used for logical values and specify the values that represent true and false. The default is "TF". A character string containing two characters is specified for this setting. The first character represents true and the second character represents false. The following program code specifies the character "1" for the logical value true and the character "0" for the logical value false.

DbeInfo( COMPONENT_DATA, SDFDBE_LOGICAL_TOKEN, "10" ) 

SDFDBE_STRUCTURE_EXT

This constant determines the file extension for the structure file (SDF file). The default is .SDF.