Data Definition File (DDF) Subsystem

The DDF subsystem provides services for accessing runtime DDF information. The data structures which the DDF subsystem uses are generated by the ddc compiler (see the ddc manual page). These data structures include all of the information which was specified in the text DDF. Before the DDF subsystem can be used a model must be created with the MDA subsystem. Most of the DDF functions work on the currently active model (see the mda_SetCurModel manual page). Because many of the DDF functions return pointers into the runtime DDF structures, care must be taken to not alter the values at the returned locations. Functions which return direct pointers are documented as such in their manual entries.

The runtime DDF is organized into several major data structures. The entity type/form pair (called a TF) serves as a key into the root level of the DDF. The TF corresponds to the #define which is generated from the entity name and consists of the type left shifted 16 bits which is logically ORed with the form. The actual index is derived from the TF and is called the TF index (or TFI for short). Since obtaining the TFI from a TF requires a binary search, most routines have two interfaces- one for obtaining information by TF and one by TFI. This allows an application to obtain a single piece of information by using the entity TF or multiple pieces by retrieving the TFI and then using that to locate the information (thus saving repeated binary searches on the TF). Routines which locate by TF will have the noun Entity in their name (e.g. ddf_GetEntityName). Those that locate by TFI will have the noun TFI in their name (e.g. ddf_GetTFIName). To uniquely identify an entity type across multiple DDFs, the DDF subsystem provides a structure which contains both the TF and the DDF it is defined in. The type of this structure is DDF_DTF. The combination of a TF and the DDF it is defined in is refered to as a DTF.
The global list of TFs can be retrieved by using the function ddf_GetTFList. This will return an array of all the available TFs in the current model. The function ddf_GetTFCount returns the number of TFs in the array. Note that this array will always be sorted by ascending TF pair. Several functions are provided to manage the TF pairs including ddf_Form (retrieves the form from a TF), ddf_Type (retrieves the type from a TF), and ddf_MakeTF (generates a TF from a type and a form).
One of the key data structures in the DDF is the field symbol table. Each entity has an entry in the symbol table. Each symbol table entry consists of an array of field definitions, one for each field specified in the text DDF. The functions ddf_GetEntityFields and ddf_GetTFIFields return a pointer to the symbol table entry of a given entity type. Various pieces of information about the field can then be obtained by using the ddf_GetFieldXxxxx functions. The application should never directly dereference a DDF_FLD structure pointer as the contents may change from one release of pdxlib to the next.
Field types are defined as DDF_SHORT, DDF_INT, DDF_LONG, DDF_FLOAT, DDF_DOUBLE, DDF_CHAR, DDF_FSTRING, DDF_VSTRING, DDF_PTR, DDF_COUNT, or DDF_LET.

Normally the xxxx_ddf.h file generated by ddc(1) is statically loaded (by being included in one function in an application or interface). A DDF can also be converted to a binary representation which can be loaded at runtime. This is done by running the ddf2ddb(1) utility on the xxxx_ddf.h file generated by ddc(1). The name of the resulting file is then passed to the function ddf_LoadDDF. Note that this can also be used to override the default DDF provided with a PDElib interface by calling ddf_LoadDDF after the interface xxxx_InitModelInfo call. Caution must be used when dynamically loading DDFs this way... any differences in the entity structures in the dynamically loaded DDF and those defined in the original DDF can cause unpredictable results. Items which can be safely changed include attributes, reftypes, ptrlists, and required values. Entities may also be added (but not deleted or changed in structure).