VDAFS Interface (VDAF) Subsystem

The VDAF subsystem is the top level subsystem in the VDAFS interface. The VDAF subsystem provides VDAFS schema dependent functions for accessing VDAFS data stored in a model. The reader should be familiar with the mda and ddf subsystems (see mda_intro and ddf_intro) before reading this manual page.

The VDAFS interface consists of the VDAFS DDF and several subsystems (all four characters with the first being "v"). The function vdaf_Initialize must be called once before any other VDAFS interface function. The call to vdaf_Initialize must follow the pdx_Initialize call. Once processing is complete, the function vdaf_Terminate should be called prior to calling pdx_Terminate.

To create a VDAFS model, the following code sequence is used:

#include "ddf_Interface.h"
#include "mda_Interface.h"
#include "vdaf_Interface.h"
     
MDA_MODEL_INFO m_info;
int model;
        .
pdx_Initialize (PDX_NOOPT);
vdaf_Initialize (VDAF_NOOPT);
        .
mda_GetModelDefaults (MDA_NOOPT, &m_info);
vdaf_InitModelInfo (VDAF_NOOPT, &m_info);
        .
/*  Other m_info fields set  */ 
        .
mda_AllocateModel (MDA_NOOPT, &m_info, &model);

The model is now ready to have VDAFS entities added. The model can be populated with the contents of an ASCII VDAFS file by calling mda_ParseFile. The contents of a model can be written to an ASCII VDAFS file by calling mda_FormatFile. The mda_intro manual page describes how additional entities are added to the model.

The file header information is stored as an entity in the model. This entity is automatically created when the model is allocated and will always be locked in memory. The Header entity structure pointer can be retrieved by using the function vdaf_Header. Also, the database pointer of the Header entity can be obtained with the function vdaf_HeaderDbptr. The Header entity may be dereferenced like any other entity in the model. The application may modify it as appropriate using the mda functions.

The MDA subsystem provides the capability of storing backpointers to referencing entities. The ASCII VDAFS file parser will automatically generate backpointer information if the backptrs field in the model_info structure is set to 1 before calling mda_AllocateModel.

In a VDAFS file, it is essential that an entity be declared before it is referenced by another entity. In this way, the VDAFS parser is able to read the entities into the model in the order that they occurred in the file. However, once the VDAFS model is established, entities can be deleted, added and moved. As a result, the VDAFS formatter cannot simply write the entities back out to a file in the order that they are in the model. A method had to be developed in which the formatter could write out the entities to a file in such a way that each entity would be declared in the file before it is referenced by another entity.

In order to accomplish this, a set of rules had to be established for the VDAFS model. These rules assume that there are only two types of entities: Set Entities and Non-Set Entities. A Set Entity is an entity that resides within a Set. That is, an entity in-between the BEGINSET and ENDSET markers. Alternately, a Non-Set Entity is an entity that is not is a Set.

1. A Non-Set Entity can reference a Non-Set Entity.
2. A Non-Set Entity can reference a Set Entity.
3. A Set-Entity can reference a Set-Entity in the SAME Set.

Simply put, entities can point into Sets, but entities cannot point out of Sets. The following are some situations that are illegal in the VDAFS model. In each case, an entity is pointing out of a Set:

A. A Set Entity cannot reference a Non-Set Entity.
B. A Set Entity cannot reference a Set Entity in a DIFFERENT Set.

The above rules must be followed if a VDAFS model is to be formatted correctly with the function vaff_FormatFile. Please refer to the vaff_intro page for more information on the VDAFS ASCII file formatter.