[<<Previous Entry] [^^Up^^] [Next Entry>>] [Menu] [About The Guide]
 Apollo Varifield
------------------------------------------------------------------------------
 Apollo adds three new field types to the group of xBase field types. The
 previous section discussed Enhanced Date and Enhanced Numeric fields. The
 third field is an extremely flexible, variable-length and indexable field
 called of type V, for VariField.  This section will explain exactly what
 VariFields are, and why you might want to incorporate them into your table
 structures.

 VariFields: Variable-Length Fields

 VariFields allow you to store a portion of any character data in the .DBF
 field itself, with any additional amount being automatically stored in the
 MEMO file. This substantially reduces the amount of disk space required to
 store the data.  Plus, you can index on the portion that remains in the
 .DBF! What you get in functionality is sort of a cross between using a
 Character field and a Memo field. You get the best features of both.

 NOTE: In addition to the above description of storing character data in
 VariFields, you may store other types of data into VariFields as well.  For
 instance, you can store an xBase logical (T/F), in a VariField. You can even
 store a Logical for record one, and something else, a date for instance, in
 record two. Be aware that if you do this,  (store different types in the
 same field over different records) data-aware components in your application
 will lose cohesion. They will not work properly at all. For this reason, it
 is generally not advisable to store your data this way.

 How VariFields Work

 A 6 byte pointer is maintained at the end of the 'V' field entry within the
 DBF file. When you define the field width for a new table you  need to keep
 this in mind. For example, if you create your table with a 'V' field of 16
 bytes, the first 10 bytes are considered 'significant'. If you index on this
 field, the key will be 10-characters wide. The last six bytes are for the
 pointer information. The rest of your data will be stored away in the memo
 file.

 For example, if you store 30 characters of text into this field, the first
 10 characters are stored within the DBF field, with the remaining 20
 characters being automatically stored in the memo file.  No special
 functions are required to store or retrieve the field data in this manner.
 If, however, you store only 14 bytes into your 16 byte 'V' field, nothing
 will be written to the memo file.  Nothing needs to.  In this case, the
 VariField system is smart enough to see that, had the four byte pointer to
 the memo not been in the way, the whole entry would fit in the .DBF field
 alone.  So, it gives up the four bytes to your data. The last two bytes,
 however, are always reserved to store the length of the text in the 'V'
 field.

 Why Use VariFields?

 Depending on the structure and content of your data tables, it is possible
 to cut the size of your data files in half using VariFields and the
 compressed Numeric and Date fields discussed in the previous section. With
 VariFields, you can also reduce your index size, since indexes will only be
 created on the significant (e.g. defined minimum length) portion declared in
 the table structure. If you can significantly reduce the overall size of
 your data files as well as your index files, you can dramatically improve
 data processing speeds, especially on networks.

 What changes do I need to make in my source code?

 As with the enhanced date and numeric type fields, if you do not want to use
 these features, you don't need to worry about accounting for them. Your code
 will work as is. To take advantage of  VariFields, you need to learn how to
 create them and what to expect from them when you read and write data to
 those field types. You create VariFields via the additional field
 declarations available to you in the sx_CreateField function.

 Enhanced Date and Numeric Fields

 This section discusses two new field types: Enhanced date and numeric
 fields. Apollo enhances Date types and Numeric types by storing them in less
 space then their traditional DATE and NUMERIC counterparts.

 Why Use Enhanced Date and Numeric Fields?

 Depending on the structure and content of your data tables, it is possible
 to cut the size of your data files significantly using the compressed "I"
 (Integer) and "D" (Date) fields. DATE field values are stored in only three
 bytes (instead of the usual eight). Long integer NUMERIC values (2 billion)
 are stored in only four bytes (instead of up to 10). If you can
 significantly reduce the overall size of your data files, you can
 dramatically improve data processing speeds, especially on networks.

 What changes do I need to make in my source code?

 If you do not want to use these features, do nothing. Your code will work as
 is. To take advantage of them, you must create them. This is done using
 additional field declarations available in sx_CreateField function.

 NOTE: Enhanced DATE and NUMERIC fields are only supported under the SDEFOX
 and SDENSX database engines.

 Examples:

 You may still use the traditional Date (D) and Numeric (N) fields as usual.
 To use the enhanced storage dates and numerics, you define them a little bit
 differently in your table creation routines. Specifically, the difference is
 in the parameters passed to the sx_CreateField function.

 You normally create a table with sx_CreateNew followed by a series of  calls
 to sx_CreateField, and finally with a call to sx_CreateExec. This general
 procedure remains unchanged. Here is sample source code that creates a table
 that includes both traditional and enhanced fields:

 VB Example

 sx_CreateNew( "TEST.DBF", "TEST", SDEFOX, 5 )
 sx_CreateField( "LASTNAME", "C", 20, 0 )     ' Normal Char
 sx_CreateField( "AGE",      "N",  2, 0 )     ' Normal Numeric
 sx_CreateField( "HIREDATE", "D",  8, 0 )     ' Normal Date
 sx_CreateField( "SDATE",    "D",  3, 0 )     ' Enhanced Date
 sx_CreateField( "SALARY",   "I",  4, 0 )     ' Enhanced Numeric
 sx_CreateExec

 C Example

 sx_CreateNew( (BYTEP) "TEST.DBF", "TEST", SDEFOX, 5 )
 sx_CreateField( (BYTEP) "LASTNAME", (BYTEP) "C", 20, 0 )  // Normal Char
 sx_CreateField( (BYTEP) "AGE",      (BYTEP) "N",  2, 0 )  // Normal Numeric
 sx_CreateField( (BYTEP) "HIREDATE", (BYTEP) "D",  8, 0 )  // Normal Date
 sx_CreateField( (BYTEP) "SDATE",    (BYTEP) "D",  3, 0 )  // Enhanced Date
 sx_CreateField( (BYTEP) "SALARY",   (BYTEP) "I",  4, 0 )  // Enhanced
                                                           // Numeric
 sx_CreateExec();

 Enhanced Dates: Traditional DATE fields are always of length 8. To create an
 enhanced Date field, you declare the field with a length of 3. These are the
 only two acceptable options for the length parameter when declaring a DATE
 field.

 Enhanced Numerics: To use the compressed integer storage mechanism of
 enhanced numeric fields, declare a field of type 'I' with length of 4. Type
 'I' fields must always be declared with the length parameter of 4.

This page created by ng2html v1.05, the Norton guide to HTML conversion utility. Written by Dave Pearson