You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Current »

Data File Conversion

Applies to: WG3.x

Editor's note: this chapter is new in the WG3 layer. It is from section 4 ("Data File Conversion") of the Developer's Addendum for Worldgroup 3.12 (wg312dev; the earlier 3.10 edition, devad3, is the same text apart from "3.10" for "3.12", BC5 for BC50, InstallShield V5.0 for V5.1 and spelling). The addendum has no figures. Prose is unrewritten; "Header check" notes record where the printed text disagrees with the WG3.2 headers. It extends chapter 9 (Databases), which only advises keeping spare bytes in records; the chapter documents WGSDFCVT.EXE, the .CVT file format and the dfc*() API (dfcapi2.h).

The previous data file conversion API’s and .CVT file structures had many shortcomings. Most notably, it became harder to create .CVT files that could properly track and upgrade multiple versions of one data file between both DOS and NT/95. Certain situations would cause data files to be converted more than once, thereby destroying the data contained in the file. These and many other issues forced us to create a new data file conversion API.

Backward compatibility

The new data file conversion API does not remove old functions. Existing .CVT files and custom conversions will continued to be supported through the new API, with a few exceptions:

1. .CVT files that are used to convert a file to Worldgroup NT/95 and specify “DestPacked: YES” are no longer supported. Because of shortcomings in the old system, there is no way to say with 100% certainty that a .CVT file is intended to convert to a Worldgroup NT/95 file. You have to change all .CVT files that fall into this category to the new style.

2. Custom conversion programs will only be passed one of 2 strings as the conversion type: “2.0 to NT”, “3.0 to NT”. No modifications are being made to pass “2.0 to 3.1 NT” or any equivalent. If you need to do data file conversions that may require this information, you need to change to the new style custom conversions.

WGSDFCVT.EXE

This utility was totally re-written. The old interface that asked you which files you wanted to convert no longer exists. Instead, the new interface scans all .CVT files and decides if a conversion needs to take place. If a data conversion is required, the operator is asked to specify the directory he would like to back up files to. Leaving this option blank forces no backup. No other user intervention exists, and a screen of information regarding the files wgsdfcvt is converting appears. If no datafile conversion needs to take place, nothing is displayed to the user.

Conversion file theory

The old conversion file API’s worked on the premise that if the “From” file existed and the .CVT file was in the directory, then it needed conversion. Because of this, installation programs needed to have some smarts built into them, to decide which copies of the .CVT files should be installed.

The new API uses one .CVT file per data file. Each .CVT file contains either a custom conversion program, or the entire history of the data file, including the current and older versions of the file layouts, thereby eliminating the need to have an intelligent installation program. WGSDFCVT can now focus on converting all older versions of a file to its newest form.

Either through .CVT file, or through custom conversion, a list of all versions of a data file are submitted to the conversion API. The conversion API goes through this list and determines the number of previous versions that exist. Under normal circumstances there is only one previous file. However, if multiple files exist, it converts the one with the most recent date and time. As the need arises to make changes to a data file, additions to the existing .CVT file or custom conversion program simplify the conversion process.

As an example, a .CVT file might provide information on the history of WGSUSR2.DAT in such a way that WGSDFCVT.EXE creates a list of files much like this:

DOS Platform                                            NT/95 Platform

BBSUSR.DAT      (pre-Worldgroup 3.00)                   WGSUSR2.DAT (Current Version)
WGSUSR2.DAT (Current Version)

Installing and converting on NT/95:

WGSDFCVT.EXE searches for existing copies of BBSUSR.DAT and WGSUSR2.DAT. If BBSUSR.DAT exists, it reads a record out of the database, converts it in memory to the WGSUSR2.DAT DOS form, then in memory to the WGSUSR2.DAT WNT form and saves it in the new datafile.

Installing and converting on DOS:

WGSDFCVT.EXE searches for an existing copy of BBSUSR.DAT. If BBSUSR.DAT exists, it reads a record out of the database, converts it in memory to the WGSUSR2.DAT DOS form, then saves it in the new datafile.

.CVT files are used mainly to convert data files from one platform to another. If your conversions require more than simple re-aligning of fields (adding fields for instance), then you can create a custom conversion program and supply your own set of conversion functions.

.CVT file formats

The .CVT file formats are completely different from the older version. There is no longer a need to have multiple .CVT files for one data file. Each .CVT file contains all information pertaining to the life of its associated data file. Numerous examples of the new .CVT file structure can be found in \WGSERV\WGSDFCVT. The new .CVT file format is as follows:

[;]
Description: <description>

Developer: <developer name>

[CustomConversion: <conversion file>]

[
BeginFile: <platform>,<file>[,<platform>,<file>...]
<tagname 1>     TYPE=<field type> [ELEMS=<length>]  [VARIABLE]
...
<fldtagN> TYPE
EndFile

[
BeginFile: <platform>,<file>[,<platform>,<file>,...]
...
]
]

The ; operator

The semi-colon “;” is used as a remark. All text after the semi-colon is ignored.

Description:

This is a required field. Include a description of the data file that this .CVT file is associated with. Text is truncated past 30 characters of the description.

Developer:

This is a required field. Include the name of your company. This field is used to determine the difference between the new and old .CVT files. Text is truncated past 30 characters of the developer name.

CustomConversion:

Use this field to specify a custom conversion program for a data file. No other fields should be included if a custom conversion is present. Custom conversion programs are described later in this document.

BeginFile: and EndFile

These are required fields for any NON-Custom Conversion .CVT file. For every BeginFile:, there is exactly one EndFile. Data Fields are required between each occurrence of BeginFile: and EndFile, and are discussed later in this document. The BeginFile: Line contains a list of platforms and data file names separated by commas. Only one platform/data file is required, however, you may include as many as you want. Each BeginFile:/EndFile combination is a list of data fields contained within a data file. It is quite possible that a data file has the same set of fields for both DOS and WNT, the only difference being the data alignment (DOS being packed, and WNT being unpacked). The following is an example taken from WGSUSR.CVT:

BeginFile: DOS, WGSUSR2, WNT, WGSUSR2
(data fields here)
EndFile

This combination inside a .CVT file specifies that the data fields contained within BeginFile: and EndFile belong to the files: WGSUSR2.DAT on the DOS platform, and WGSUSR2.DAT on the WNT platform.

The only valid platform identifiers are: DOS for DOS Btrieve 5.x datafiles, and WNT for Btrieve 6.x data files. The data file conversion API assumes the following: DOS platforms are packed/little endian, and WNT platforms are unpacked/little endian. If your conversion requires that these defaults not be followed, you must create a custom conversion and bypass these defaults.

Data Fields

Data Fields are similar to their old versions. You must have at least one data field for every BeginFile:/EndFile combination. Data Fields are defined as follows:

<Tag Name>      TYPE=<Field Type>       [ELEMS=<length>]        [VARIABLE]

Tag Name

A 19 character or less name for the data type. This generally is the same name as the variable it represents in the data structure. There can only be one occurrence of each Tag Name within each BeginFile:/EndFile combination.

TYPE

Valid field types are: CHAR, SHORT, LONG, FLOAT, DOUBLE, OPAQUE, and STRUCT.

ELEMS

This specifies the number of occurrences of this field type in this data field. For instance, if you are creating a field type for the following variable:

SHORT MyString[500];

your data field would look like this:

MYSTRING                TYPE=SHORT              ELEMS=500

ELEMS is not a required field and omitting it sets the number of elements to 1.

VARIABLE

The keyword VARIABLE is used to designate a variable length field. Variable length fields only work on the last Data Field in your list. You must include the ELEMS field when you use the VARIABLE keyword, however, the ELEMS field should specify the maximum number elements that could be present in this variable field.

TYPE=STRUCT and EndStruct

The previous version of the data file API had two serious flaws: You could only nest structures one deep, and you could not remove data fields that were within structures. This is no longer the case. Structures are now defined in the same way that BeginFile:/EndFile are used. The following is WGSMENU.CVT. It has an example of variable length structures:

BeginFile: DOS,BBSMENU
MENUTYPE        TYPE=CHAR
PAGENAME        TYPE=CHAR       ELEMS=16
PARENTPAGE      TYPE=CHAR       ELEMS=16
FILENAME                TYPE=CHAR       ELEMS=80
MODULENAME      TYPE=CHAR       ELEMS=25
COMMANDSTG      TYPE=CHAR       ELEMS=60
GOLOCK                  TYPE=CHAR       ELEMS=16
FLAGS                   TYPE=SHORT
MENUTITLE       TYPE=CHAR       ELEMS=43
NPAGES                  TYPE=SHORT
ICHANGE                 TYPE=LONG
SPARE                   TYPE=CHAR       ELEMS=70
PGLINK                  TYPE=STRUCT     ELEMS=25                VARIABLE
        POSITION                TYPE=SHORT
        SELCHR                  TYPE=CHAR
        ICONAME                 TYPE=CHAR       ELEMS=9
        DESTPAGE                TYPE=CHAR       ELEMS=16
        OPTDSP                  TYPE=CHAR
        KEYREQ                  TYPE=CHAR       ELEMS=16
        SHORTD                  TYPE=CHAR       ELEMS=31
        LONGD                   TYPE=CHAR       ELEMS=50
EndStruct
EndFile

All field names are unique. Field names within substructs must have different names than any other fields in your .CVT files. You can not have a field named “KEY” inside a structure and outside a structure.

New Data File Conversion API

All previous data file conversion API’s still exist and are supported, however, you should migrate your software to the new API functions. The new API’s and structures are located in the file DFCAPI2.H.

DFCLIST structure

typedef struct tagDFCLIST {        /*  Platform Specific list of files     */
     INT Platform;                 /*  Operating system for file list      */
     pDFCFILE file;                /*  Pointer to the file information     */
} DFCLIST,*pDFCLIST;

Used to create a list of files that the dfc library should check for conversion. An array of these structures are passed to dfcRegister(). Your DFCLIST array must end with a platform of DFC_END and a file of NULL.

Platform

Valid values are DFC_DOS, DFC_WNT, and DFC_END. DFC_END is used to mark the end of the list.

file

pointer to an array of DFCFILE structures that contain a list of files specific to the given platform. This can be NULL when the Platform is DFC_END.

DFCFILE structure

typedef struct tagDFCFILE {        /* Datafile information                 */
     CHAR Name[GCMAXPTH];          /*  Name of the datafile                */
     pDFCFUNCTION cnvfunc;         /*  Conversion function                 */
     pDFCDATAFIELDS cnvfields;     /*  Conversion fields                   */
} DFCFILE,*pDFCFILE;

Used to create an array of files that apply to a specific platform. The DFCFILE structure is directly related to the DFCLIST structure. All DFCFILE structure arrays must end with a blank name.

Name

The name of the data file without the extension. A blank name specifies the end of a file list.

cnvfunc

Pointer to a conversion function or NULL to use dfcConvertDefault. This function is used to convert data from the previous version of the file. If this pointer is for the first file in a list it is ignored.

cnvfields

Pointer to an array of DFCDATAFIELDS structures. This array contains information on each data field within the data file similar to those used in .CVT files.

DFCDATAFIELDS structure

typedef struct tagDFCDATAFIELDS {  /* Datafile fields definition           */
     CHAR Name[DFC_NAMSIZ];        /*  Name of the field                   */
     UINT Type;                    /*  Type of the field                   */
     INT nelems;                   /*  Number of elements                  */
     struct tagDFCDATAFIELDS *substruct;/*  Pointer to sub structure       */
} DFCDATAFIELDS,*pDFCDATAFIELDS;

Used to create a set of data fields contained within a data file. This structure is used in conjunction with the DFCFILE structure. All DFCDATAFIELDS must end with a blank name and a type of DFCFLD_END.

Name

A 19 character or less name for the data field. Leave this field blank to specify the end of the list.

Type

Valid types are: DFCFLD_CHAR, DFCFLD_SHORT, DFCFLD_LONG, DFCFLD_FLOAT, DFCFLD_DOUBLE, DFCFLD_OPAQUE, DFCFLD_STRUCT.

For variable length fields use: DFCFLD_VCHAR, DFCFLD_VSHORT, DFCFLD_VLONG, DFCFLD_VFLOAT, DFCFLD_VDOUBLE, DFCFLD_VOPAQUE, DFCFLD_VSTRUCT.

DFCFLD_END is used to specify the end of the list.

nelems

The number of elements in this field. For variable length fields, specify the maximum number of fields.

substruct

If the field type is DFCFLD_STRUCT or DFCFLD_VSTRUCT, you must supply another array of DFCDATAFIELDS for that structure, otherwise this parameter is NULL.

DFCOFFSETS structure

typedef struct tagDFCOFFSETS {     /* Offset information structure         */
     CHAR Name[DFC_NAMSIZ];        /*  Name of the variable                */
     UINT Type;                    /*  Type of record it is                */
     INT nelems;                   /*  Number of elements                  */
     UINT Offset;                  /*  Offset within data record           */
} DFCOFFSETS,*pDFCOFFSETS;

A bunch of internal structures are created when you call dfcRegister() with your file list. The DFCOFFSETS structure is an internal list past to you as part of the DFCFILEINFO structure. This contains information on each one of your data fields. The DFCOFFSETS structure and the DFCDATAFIELDS structures are closely related. This structure is never created by you. You can obtain pointers to this structure from within your conversion functions by calling dfcFindOffset().

Name

The name of the data field. Equivalent to the names from your DFCDATAFIELDS structure.

Type

The type of data field. Equivalent to the types from your DFCDATAFIELDS structure.

nelems

The number of elements in the data field. Equivalent to the number of elements from your DFCDATAFIELDS structure.

Offset

The offset within the data that this field is at. If you have the following structure:

CHAR String[20];
CHAR Test[10];

and you called dfcFieldOffst() for the TEST data field, the offset would be 20. The offset does account for alignment. DOS versions and WNT versions of the same data fields may produce different offsets.

Applies to: WG3.x

Header check: no dfcFieldOffst() exists; the function is dfcFindOffset() (dfcapi2.h:127; section "dfcFindOffset()" below).

DFCFILEINFO structure

typedef struct tagDFCFILEINFO {    /*  File info to pass to conversions    */
     INT Platform;                 /*  Current system Platform             */
     CHAR Name[GCMAXPTH];          /*  Conversion file                     */
     INT Type;                     /*  Conversion macros (CVTBIGEND...)    */
     pDFCDATAFIELDS Fields;        /*  Pointer to the fields in data       */
     pDFCOFFSETS Offsets;          /*  Pointers to offset information      */
     UINT Offsetsn;                /*  Number of offsets                   */
     struct flddef *fdef;          /*  Field definition array (set up)     */
     CHAR *Data;                   /*  Pointer to actual data              */
     size_t DataLength;            /*  Length of the data                  */
     struct flddef** fdefs;        /*  Used to allocate memory for fdef    */
     UINT fdefsn;                  /*  Number of field defs                */
} DFCFILEINFO,*pDFCFILEINFO;

If you have created conversion functions, you are passed two pointers to this structure. The structure contains a wealth of information about specific files being converted.

Platform

The platform this DFCFILEINFO structure belongs to, either DFC_DOS or DFC_WNT.

Name

The name of the file this DFCFILEINFO structure is associated with.

Type

These are the data types for Platform (i.e. Big/Little Endien, Packed/Unpacked). This variable can be used in calls to the cvtData() functions.

Fields

A pointer to the array of DFCDATAFIELDS structures you passed to dfcRegister().

Offsets

A pointer to an array of DFCOFFSETS structures created based on your DFCDATAFIELDS structures. These are most easily accessed through the use of the function dfcFindOffset().

Offsetsn

The number of offsets contained in the Offsets array.

fdef

A pointer to a field definition array created based on the array of DFCDATAFIELDS.

Data

If you are passed this information in the from parameter of a conversion function, it contains the data read directly from the data file. If you are passed this information in the to parameter of a conversion function, it contains a buffer that is allocated to the largest amount of bytes a record can take. You can use that buffer to store your converted data.

DataLength

This serves two purposes. In the from parameter of a conversion function, it is the size in bytes of the data present in the Data field. In the to paremater of a conversion function, it is the size in bytes of the supplied Data field. In variable length records, the DataLength field from the to parameter should be changed to reflect the correct size of the record being inserted.

fdefs

Used to produce the fdef field. This field should not be used or modified.

fdefsn

The number of fdefs in the array. This field should not be used or modified.

DFCPFCONVERT structure

typedef struct tagDFCPFCONVERT {   /*  Platform conversion                 */
     INT PlatformFrom;             /*  Platform converting from            */
     INT PlatformTo;               /*  Platform converting to              */
     pDFCFUNCTION cnvfunc;         /*  Pointer to conversion function      */
} DFCPFCONVERT,*pDFCPFCONVERT;

Used to specify a list of conversion functions that convert data from one platform to another. Currently the only combination of platforms supported is DOS to WNT.

PlatformFrom

Valid values are DFC_DOS, DFC_WNT, and DFC_END. Currently only DFC_DOS is supported as part of the PlatformFrom field. DFC_END is used to specify the end of a list.

PlatformTo

Valid values are DFC_DOS, DFC_WNT, and DFC_END. Currently only DFC_WNT is supported as part of the PlatformTo field.

cnvfunc

Pointer to a conversion function used to convert data from PlatformFrom to PlatformTo.

dfcAskBackup()

VOID
dfcAskBackup(VOID);                /*  Ask the backup directory            */

Ask the user what directory they wish to back files up to. If you are using dfcRegister to convert your data files, this function is automatically called by the internal API’s.

dfcBackupDirectory()

Applies to: WG3.x

const CHAR * vs CHAR * hazard. CHAR *dfcBackupDirectory(VOID) returns a writable CHAR * (dfcapi2.h); treat it as read-only. The dfc* string parameters (descrp, FileFrom, FileTo, stg, file, FieldName, ModuleName) are const CHAR *.

CHAR *
dfcBackupDirectory(VOID);          /*  Returns pointer to backup directory */

If you are using dfcRegister to convert your data files, this function is automatically called by the internal API’s.

Returns

Pointer to the directory the user has asked to back files up.

dfcBackupRequired()

GBOOL
dfcBackupRequired(VOID);           /*  Is a backup required?               */

Returns

TRUE if the user has requested to back up their data files,

FALSE if they have not.

dfcConvertDefault()

DFCFUNCTION                        /*  Pointer to new data                 */
dfcConvertDefault(                 /* Default conversion function          */
pDFCFILEINFO from,                 /*  File information converting from    */
pDFCFILEINFO to);                  /*  File information converting to      */

Default conversion function. This function is called if you do not supply your own custom conversion function.

from

A pointer to a DFCFILEINFO structure that gives you information on the file you are converting from. See the section titled “DFCFILEINFO” for more details.

to

A pointer to a DFCFILEINFO structure that gives you information on the file you are converting to. See the section titled “DFCFILEINFO” for more details.

Returns

A pointer to the converted data.

dfcConvertPFDefault()

DFCFUNCTION                        /*  Pointer to new data                 */
dfcConvertPFDefault(               /* Default Platform conversion          */
pDFCFILEINFO from,                 /*  File information converting from    */
pDFCFILEINFO to);                  /*  File information converting to      */

Platform default conversion function. This function is called only when converting from one platform to another (i.e. DOS to WNT), unless you have provided your own platform conversion function.

from

A pointer to a DFCFILEINFO structure that gives you information on the file you are converting from. See the section titled “DFCFILEINFO” for more details.

to

A pointer to a DFCFILEINFO structure that gives you information on the file you are converting to. See the section titled “DFCFILEINFO” for more details.

Returns

A pointer to the converted data.

dfcDisplayBackup()

VOID
dfcDisplayBackup(VOID);            /*  Display backup notice               */

Displays a notice that says “Backing up data files”. If you are using dfcRegister to convert your data files, this function is automatically called by the internal API’s.

dfcDisplayInfo()

VOID
dfcDisplayInfo(                    /* Display DFC information              */
const CHAR *Description,           /*  Description to display              */
const CHAR *FileFrom,              /*  File converting from                */
const CHAR *FileTo,                /*  File converting to                  */
ULONG Records);                    /*  Number of records to display        */

Updates display information about your custom conversion on the screen. If you are using dfcRegister to convert your data files, this function is automatically called by the internal API’s.

Description

A 30 character description of the data file being converted.

FileFrom

Name of the data file that is being converted.

FileTo

Name of the data file you are converting to.

Records

Total number of records that are in the data file.

dfcDisplayStats()

VOID
dfcDisplayStats(                   /*  Display the stats bar               */
ULONG TotalRecords,                /*  Total records in conversion         */
ULONG DoneRecords);                /*  Number of records completed         */

Used to update the number of records converted. If you are using dfcRegister to convert your data files, this function is automatically called by the internal API’s.

TotalRecords

Total number of records in the database.

DoneRecords

Total number already converted.

dfcDisplayShutdown()

VOID
dfcDisplayShutdown(VOID);          /*  Release captured video screen       */

Closes all windows that may have been opened while using dfcDisplay... functions. If you are using dfcRegister to convert your data files, this function is automatically called by the internal API’s.

dfcError()

VOID
dfcError(                          /*  Print an error to screen            */
const CHAR *stg,                   /*  String to print                     */
...);                              /*  Extra arguments                     */

A generic error handling routine. Calling this function causes your custom conversion program to immediately end.

stg

A message to display upon the termination of your program.

dfcFieldSize()

UINT                               /*  Number of bytes of field size       */
dfcFieldSize(                      /* Gets field size of data type         */
UINT Type);                        /*  Type of datafield                   */

Gets the size in bytes of a given data field type.

Type

Valid types are: DFCFLD_CHAR, DFCFLD_SHORT, DFCFLD_LONG, DFCFLD_FLOAT, DFCFLD_DOUBLE, DFCFLD_OPAQUE, DFCFLD_STRUCT, DFCFLD_VCHAR, DFCFLD_VSHORT, DFCFLD_VLONG, DFCFLD_VFLOAT, DFCFLD_VDOUBLE, DFCFLD_VOPAQUE, DFCFLD_VSTRUCT

Returns

The size in bytes of the data type passed, or 0 if the data type is not found.

dfcFilePlatform()

INT                                /*  DFC_DOS, DFC_WNT, DFC_END           */
dfcFilePlatform(                   /* Files platform                       */
const CHAR *file);                 /*  Pointer to file to check            */

Checks a data file and returns what platform the file belongs to (DOS/WNT). There are limitations to this function. If the program that is calling this function is compiled for DOS. It does not recognize WNT data files. We do not support data file conversion from Worldgroup NT/95 to Worldgroup DOS. If you are using dfcRegister to convert your data files, this function is automatically called by the internal API’s.

File

Data file to check the platform on.

Returns

DFC_DOS for a btrieve 5.x data file.

DFC_WNT for a btrieve 6.x data file.

DFC_END on error.

dfcFindOffset()

pDFCOFFSETS                        /*   returns ptr to field offset info   */
dfcFindOffset(                     /* find offset of a particular field    */
pDFCFILEINFO info,                 /*   file information converting from   */
const CHAR *FieldName);            /*   name of field to find              */

Find the offset of a data field within a DFCFILEINFO structure. This function is primarily used within a conversion function to get information on a particular field.

info

Pointer to a DFCFILEINFO structure. Usually either the to or from fields in a conversion function.

FieldName

Name of the data field you want the offset structure for. These names are contained in the DFCLIST structure you passed to dfcRegister().

Returns

A pointer to a DFCOFFSETS structure, or NULL if FieldName does not exist.

dfcGetFDA()

struct flddef *                    /*  Pointer to FDA structure            */
dfcGetFDA(                         /* Get an FDA from type of convert      */
UINT Type);                        /*  Type of option                      */

Gets an FDA for a given data type.

Type

Valid types are: DFCFLD_CHAR, DFCFLD_SHORT, DFCFLD_LONG, DFCFLD_FLOAT, DFCFLD_DOUBLE, DFCFLD_OPAQUE, DFCFLD_STRUCT, DFCFLD_VCHAR, DFCFLD_VSHORT, DFCFLD_VLONG, DFCFLD_VFLOAT, DFCFLD_VDOUBLE, DFCFLD_VOPAQUE, DFCFLD_VSTRUCT

Returns

A pointer to a valid flddef structure or NULL. This structure could be used as part of a call to cvtData().

dfcRegister()

GBOOL                              /*  TRUE if conversion took place       */
dfcRegister(                       /*  Register and search for files       */
const CHAR *descrp,                /*  Description name                    */
const DFCLIST *dfc,                /*  pointer to all DFCFILES             */
const DFCPFCONVERT *pfconv,        /*  Platform Converter                  */
INT Key,                           /*  Key number to use (-1 for physical) */
INT Direction);                    /*  Direction (DFC_FORWARD/DFC_BACKWARD)*/

Notifies the data file conversion API of a list of files to check for conversion.

descrp

A 30 character or less description of the data file to check. Anything past 30 characters is truncated.

dfc

A pointer to a DFCLIST structure that contains a list of files to check for conversion.

pfconv

A pointer to a DFCPFCONVERT structure that contains a list of platform conversion functions. You can pass NULL if you wish to use the default platform conversion functions.

Key

The Btrieve key to be used if a data file conversion is needed. Pass -1 to convert the data file in physical record order.

Direction

The direction to read, if a data file conversion is needed. Valid values are DFC_FORWARD or DFC_BACKWARD.

Returns

TRUE if a conversion took place,

FALSE if a conversion did not take place.

dfcRegisterGDB()

GBOOL                              /*  TRUE if conversion took place       */
dfcRegisterGDB(                    /*  Register conversion for GDB         */
const CHAR *descrp,                /*  Description of conversion           */
const DFCLIST *dfc,                /*  Pointer to list of information      */
const DFCPFCONVERT *pfconv,        /*  Pointer to OS conversions           */
const CHAR *ModuleName);           /*  Module name registering             */

Notifies the data file conversion API of a conversion that takes place in the generic database.

descrp

A 30 character or less description of the data file to check. Anything past 30 characters is truncated.

dfc

A pointer to a DFCLIST structure that contains a list of files to check for conversion.

pfconv

A pointer to a DFCPFCONVERT structure that contains a list of platform conversion functions.

ModuleName

The module name from the generic database. This value is used in determining which records get passed to your conversion functions.

Returns

TRUE if a conversion took place,

FALSE if a conversion did not take place.

DFCCONVERT (Conversion functions)

Applies to: WG3.x

Header check: there is no type DFCCONVERT in WGDEV/INC. The conversion-function type is DFCFUNCTION (typedef VOID* DFCFUNCTION;) and pDFCFUNCTION in dfcapi2.h; dfcConvertDefault() returns DFCFUNCTION (dfcapi2.h:117). The heading and the sample in "Adding another data file version" use the name DFCCONVERT.

typedef VOID* DFCFUNCTION;
typedef DFCFUNCTION (*pDFCFUNCTION)(pDFCFILEINFO from,pDFCFILEINFO to);

These functions are created to handle data conversion from one form to another. They are normally set up as part of a DFCFILE structure. Platform conversion functions handle modifying the latest version of DOS to the latest version of WNT only. If you are converting from an older version of a DOS file to WNT, your file is first converted to the newest version of DOS, then your platform conversion function is called to convert it to WNT.

from

Pointer to a DFCFILEINFO structure containing information about the file being converted.

to

Pointer to a DFCFILEINFO structure containing information about the file converting to.

Returns

This function must return a pointer to the converted data. You can use the to->Data field to store your converted data. If you are converting a record that is variable length, the from->DataLength reflects the size of the converting from record. You must specify the length of the converting to record by modifying to->DataLength. You may return NULL to NOT convert this record.

Creating a custom conversion program

Every custom conversion program requires that you include the file DFCAPI2.H. This header file contains all function prototypes and structure definitions. The following is a step by step procedure for creating WGSVBCVT.EXE (The file that converts WGSVBL2.DAT).

Create the DFCLIST structure

The Worldgroup Variables data file exists on both DOS and NT/95 platforms. The following structure was created:

static DFCLIST VariableList[]={
     {DFC_DOS, VariableDOS},
     {DFC_WNT, VariableWNT},
     {DFC_END, NULL},
};

VariableDOS and VariableWNT are pointers to DFCFILE structures.

Create the DFCFILE structures

The DOS versions of the Worldgroup Variables data file are BBSVBL.DAT and WGSVBL2.DAT. Thus, the following was created:

static DFCFILE VariableDOS[]={
     {"BBSVBL",     NULL,               bbsvbl},
     {"WGSVBL2",    ConversionDOS1,     wgsvbl2},
     {"", NULL, NULL},
};

Both bbsvbl and wgsvbl2 are pointers to DFCDATAFIELDS structures that define the contents of each data file. ConversionDOS1 is a custom conversion function to convert BBSVBL.DAT to WGSVBL2.DAT.

There is only one version of the Worldgroup Variables data file for NT/95, Thus:

static DFCFILE VariableWNT[]={
     {"WGSVBL2",    NULL,               wgsvbl2},
     {"", NULL, NULL},
};

The reason wgsvbl2 is contained within both file lists is because each file has the exact same data field layout. The only difference is the PACKED vs. UNPACKED.

Create the DFCDATAFIELDS structures

As seen in the creation of the DFCFILE structures, that are two different DFCDATAFIELDS structures that need to be created:

static DFCDATAFIELDS bbsvbl[]={
     {"KEY",        DFCFLD_CHAR,   4,             NULL},
     {"VARSTUFF",   DFCFLD_VCHAR,  OVBRECSZ-4,    NULL},
     {"", DFCFLD_END, NULL},
};
static DFCDATAFIELDS wgsvbl2[]={
     {"KEY",        DFCFLD_CHAR,   4,                       NULL},
     {"VARSTUFF",   DFCFLD_VCHAR,  sizeof(struct sysvb3)-4, NULL},
     {"", DFCFLD_END, NULL},
};

Notice the DFCFLD_VCHAR fields (Variable CHAR) specify the largest record size that “VARSTUFF” could possibly be.

Creating the platform conversion function list

On most custom conversion programs there is no need for a special function to convert data from the DOS platform to the WNT platform. However, for WGSVBCVT.EXE, there was a need to modify the data manually before saving the WNT version. When this need arises, it is necessary to create a DFCPFCONVERT structure that contains a list of platform conversion functions:

static DFCPFCONVERT PlatformConverts[]={
     {DFC_DOS, DFC_WNT,  PlatformConvert},
     {DFC_END, DFC_END, NULL},
};

The function PlatformConvert will be called when converting data from DOS to WNT.

Create the custom conversion functions

As part of the DFCFILE structures, we specified one conversion function: ConversionDOS1(), and as part of the DFCPFCONVERT structure, we also specified on conversion function: PlatformConvert(). Custom conversion functions are created when you need to transform one version of a datafile to another version, and the transformation requires that you add new fields, or re-adjust somethings value. Custom conversion functions are passed two pointers to DFCFILEINFO structures which provide a wealth of information about both the file you are converting from and the file you are converting to. Here are the two custom conversion functions for WGSVBCVT.EXE:

static DFCFUNCTION                 /*  Pointer to data                     */
ConversionDOS1(                    /* Converstion from BBSVBL to WGSVBL2   */
pDFCFILEINFO from,                 /*  Pointer to from data                */
pDFCFILEINFO to)                   /*  Pointer to to data                  */
{
     return(ConversionVBL(from,to,TRUE,FALSE,NGROUPS));
}
static DFCFUNCTION                 /*  Pointer to data                     */
PlatformConvert(                   /* Converstion from BBSVBL to WGSVBL2   */
pDFCFILEINFO from,                 /*  Pointer to from data                */
pDFCFILEINFO to)                   /*  Pointer to to data                  */
{
     return(ConversionVBL(from,to,FALSE,TRUE,NUMGRPS));
}

The ConversionVBL() function handles all possible data conversions for WGSVBCVT.EXE, and takes the following paramaters:

static DFCFUNCTION                 /*  Pointer to data                     */
ConversionVBL(                     /* Converstion function                 */
pDFCFILEINFO from,                 /*  Pointer to from data                */
pDFCFILEINFO to,                   /*  Pointer to to data                  */
GBOOL EatOldCreds,                 /*  Eat old credits up?                 */
GBOOL TakeLongs,                   /*  Take variables as longs? (or shorts)*/
INT nGrp)                          /*  Number of groups                    */

from

Pointer to DFCFILEINFO structure received in conversion function.

to

Pointer to DFCFILEINFO structure received in conversion function.

EatOldCreds

From Worldgroup 2.00 to Worldgroup 3.00, there were a number of credits tracking variables in this structure that were removed. Specifying TRUE removes those variables.

TakeLongs

From Worldgroup 2.00 to Worldgroup 3.00, there were a number of variables that were changed from SHORTs to LONGs. Specifying TRUE expects the data to be of type LONG.

nGrp

The number of groups we track for changed from Worldgroup 2.00 to Worldgroup 3.00.

Putting it all together

Now that every structure required for the conversion is complete, there is only one thing left: registering all of this information with the data file conversion API. Your programs main() routine should look like this:

INT
main(VOID)
{
TRY
     dfcRegister("Worldgroup Variables",VariableList,PlatformConverts,
      -1,DFC_FORWARD);
EXCEPT
     return(0);
}

Your conversion programs no longer receive command line arguments to specify what is being converted. Instead, it is the conversion APIs job to figure out what needs to be converted based on the structures you have created. Calling dfcRegister() notifies the conversion API of the different files, datatypes and conversion functions, and everything else is handled for you. Your conversion functions are only called if a data file conversion takes place.

Adding another data file version

This is the easy part. If the need ever arises to create another version of a data file that already has a custom conversion, it is simple to add it to your conversion program. For instance, say we created a new version of Worldgroup Variables that contained a LONG variable in between the “key” and “varstuff” variables. We would have to do the following (additions are in bold and italicized):

1. Add it to our files list, they would now look like this:

static DFCFILE VariableDOS[]={
     {"BBSVBL",     NULL,               bbsvbl},
     {"WGSVBL2",    ConversionDOS1,     wgsvbl2},
     {"WGSVBL3",    ConvertTo3,         wgsvbl2},
     {"", NULL, NULL},
};
static DFCFILE VariableWNT[]={
     {"WGSVBL2",    NULL,               wgsvbl2},
     {"WGSVBL3",    ConvertTo3,         wgsvbl3},
     {"", NULL, NULL},
};

2. Add our new data fields**:**

static DFCDATAFIELDS wgsvbl3[]={
     {"KEY",        DFCFLD_CHAR,   4,                       NULL},
     {"NEWVAR",     DFCFLD_LONG,   1,                       NULL},
     {"VARSTUFF",   DFCFLD_VCHAR,  sizeof(struct sysvb3)-4, NULL},
     {"", DFCFLD_END, NULL},
};

3. Create the function ConvertTo3:

static DFCCONVERT
ConvertTo3(
pDFCFILEINFO from,
pDFCFILEINFO to)
{
        UINT NewvarOffset;
        pDFCOFFSET pnewvar;
        LONG NewvarSet=10;
        DFCCONVERT Answer;

Applies to: WG3.x

Header check: pDFCOFFSET should read pDFCOFFSETS (} DFCOFFSETS,*pDFCOFFSETS;, dfcapi2.h; dfcFindOffset() returns pDFCOFFSETS); DFCCONVERT should read DFCFUNCTION (see the note under "DFCCONVERT"). The sample also uses NGROUPS, which is NUMGRPS in WG3.2 (MAJORBBS.H:62).

        // Get the offset in the new data of our new variable
        pnewvar=dfcFindOffset(to,“NEWVAR”);
        NewvarOffset=pnewvar->Offset;
        // We can use the default conversion function because nothing is changing
        //  except the fact that we are adding a new variable
        Answer=dfcConvertDefault(from,to);
        //  Add the new variable to the data
        memcpy(&Answer[NewvarOffset],&NewvarSet,sizeof(LONG));
        //  return the new data.
        return(Answer);
}

4. Remove the Platform conversion functions:

Because our new data file does not require any special attention when going from DOS to WNT, we no longer need a platform conversion function. We need to remove our DFCPFCONVERT structure, and change our dfcRegister line to the following:

dfcRegister("Worldgroup Variables",VariableList,NULL,-1,DFC_FORWARD);

Previous: Major BBS v10: 21 Development Environment (Worldgroup 3.x)  |  Contents  |  Next: Major BBS v10: 23 InstallShield

  • No labels