WDB (Wave Database) API Header File to Create a WDB

API Functions to create a file or in memory Wave Database.

WDB Datatypes

Time Data

All time data uses the WdbTime data type.

typedef zUInt64 WdbTime;
#define WdbTimeInvalid  ((WdbTime)(-1))
#define WdbTimeNoChange ((WdbTime)(-2))

typedef enum {
    WdbTimeUnitUndef  = 0,
    WdbTimeUnitSecond = 1,
    WdbTimeUnitMilli  = 2,
    WdbTimeUnitMicro  = 3,
    WdbTimeUnitNano   = 4,
    WdbTimeUnitPico   = 5,
    WdbTimeUnitFemto  = 6
} WdbTimeUnit;

Value Types

Signal value use the WdbValue enumeration.

typedef enum {
    WdbVx=0,
    WdbVz=1,
    WdbV0=2,
    WdbV1=3,
    WdbVv=4,
    WdbVw=5,
    WdbV_=6, /* no value */
    WdbV__=7 /* never stored */
} WdbValue;

Variable Types

Variable types use the WdbVarType enumeration.

typedef enum {
    WdbVarUnknown,
    WdbVarEvent,
    WdbVarInteger,
    WdbVarParameter,
    WdbVarReal,
    WdbVarReg,
    WdbVarSupply0,
    WdbVarSupply1,
    WdbVarTime,
    WdbVarTri,
    WdbVarTriand,
    WdbVarTrior,
    WdbVarTrireg,
    WdbVarTri0,
    WdbVarTri1,
    WdbVarWand,
    WdbVarWire,
    WdbVarWor,

    WdbVarGroup,
    WdbVarAlias,

    WdbVarInvalid
} WdbVarType;

Alias Types

Types of alias variables.

typedef enum {
    WdbAliasNone,
    WdbAliasPin,
    WdbAliasPort,
    WdbAliasNet,

    WdbAliasInvalid
} WdbAliasType;

Var Dir

Directions of variables.

typedef enum {
    WdbVarDirNone,
    WdbVarDirIn,
    WdbVarDirOut,
    WdbVarDirInOut,

    WdbVarDirInvalid
} WdbVarDir;

Signal Types

Type of a signal and it’s value.

typedef enum {
    WdbValUnknown,
    WdbValScalar,
    WdbValVector,
    WdbValReal,

    WdbValMember, /* of a vector or group */
    WdbValGroup,

    WdbValInvalid
} WdbValType;

Scope Types

Scope types use the WdbScopeType enumeration.

typedef enum {
    WdbScopeUnknown,
    WdbScopeModule,
    WdbScopeTask,
    WdbScopeFunction,
    WdbScopeBegin,
    WdbScopeFork,

    WdbScopeInvalid
} WdbScopeType;

String Conversion Helpers

Helper functions to convert types to strings.

const char*  WdbValue2Str(WdbValue value);
const char*  WdbVarType2Str(WdbVarType vartype);
const char*  WdbAliasType2Str(WdbAliasType aliastype);
const char*  WdbValType2Str(WdbValType valtype);
const char*  WdbScopeType2Str(WdbScopeType stype);
const char*  WdbVarDir2Str(WdbVarDir vardir);
WdbVarType   WdbStr2VarType(const char* str);
WdbAliasType WdbStr2AliasType(const char* str);
WdbValType   WdbStr2ValType(const char* str);
WdbScopeType WdbStr2ScopeType(const char* str);
WdbVarDir    WdbStr2VarDir(const char* str);
void         WdbVarTypeUsageList(const char*** list);
void         WdbAliasTypeUsageList(const char*** list);
void         WdbValTypeUsageList(const char*** list);
void         WdbScopeTypeUsageList(const char*** list);
void         WdbVarDirUsageList(const char*** list);

Wave Database Handle

The opaque Wdb handle is used by all API functions, to store the internal state.

typedef struct WdbStruct Wdb;

Callbacks

Wdb Callbacks structure is used to generate progress information and message output.

typedef struct {
    int  (*progress)(const char* what, double percent);
    void (*msg)(zMessage_Type type, const char* msg);
} WdbCallbacks;

Default Callbacks

Default functions for progress and messaging.

#define WdbDefaultCallbacks ((WdbCallbacks*)1)

No Callbacks

No functions for progress and messaging.

#define WdbNoCallbacks ((WdbCallbacks*)NULL)

Signal Number

The data type WdbSigNo is returned and used as arguments by the other API functions.

typedef int WdbSigNo;

#define WdbInvalidSigNo (-1)

Create Options

Options are use to control the creation of the WDB database by the WdbCreateMem and WdbCreateFile functions.

gcd: saves space by finding the greatest common divisor (GCD) for stored timesteps.
zip: saves space by compressing a whole buffer with zip.
skipdupl: save space by ignoring value changes to same value as previous change
collapse: save space by collapsing multiple value changes at same timestep.
skipLeadX: ignore value changes until first non X value.

WDB API Functions

Create a WDB

The WdbCreateMem() function creates a memory-located file (this is not useful for the write interface, but can be used together with the read interface). This function always returns an empty Wdb.

The WdbCreateFile() function creates an external WDB file and uses core memory only for buffering. This function may fail but return a Wdb and set ok to zFalse - call WdbErrorMsg() to get the error message.

During execution the callback functions are called if the are not set to NULL.

Wdb* WdbCreateMem(
    zBool zip,
    zBool gcd,
    zBool skipDupl,
    zBool collapse,
    zBool skipLeadX,
    zBool generateStats,
    WdbCallbacks*);

Wdb* WdbCreateFile(
    const char* fname,
    zBool zip,
    zBool gcd,
    zBool skipDupl,
    zBool collapse,
    zBool skipLeadX,
    zBool generateStats,
    WdbCallbacks*,
    zBool* ok);

Restore a WDB File

The WdbRestore() function restores a WDB from the binary wdb file.

If ok is set to zFalse there was an error - call WdbErrorMsg() to get the error message.

During execution the callback functions are called if the are not set to NULL.

Wdb* WdbRestore( const char* fname, WdbCallbacks*, zBool* ok);

Check a WDB File

The WdbCheck() function tries to open a binary WDB file.

It returns zTrue if everything is ok. If there are problems zFalse is returned. If msg != NULL it contains more details..

zBool WdbCheck(const char* fname, WdbCallbacks*, char msg[256]);

Close the WDB

The WdbClose() function empties all internal buffer, writes all pending data and close the database. The given handling is not valid anymore.

It returns zTrue if everything is ok. If there are problems zFalse is returned - call WdbErrorMsg() to get the error message.

zBool WdbClose(Wdb*);

Print Stats Of The WDB

The WdbPrintStats() function prints different statistics about the wdb. Stats about compressed and uncompressed blocks per signal or accumulatively.

call WdbErrorMsg() to get the error message.

void WdbPrintStats(Wdb*, zBool);

Save the WDB

The WdbSave() function saves the in memory database to a file.

It returns zTrue if everything is ok. If there are problems zFalse is returned - call WdbErrorMsg() to get the error message.

zBool WdbSave(Wdb*, const char* fname);

Dump the WDB

The WdbMemDump() function dumps the in memory database to a file.

It returns zTrue if everything is ok. If there are problems zFalse is returned - call WdbErrorMsg() to get the error message.

zBool WdbMemDump(Wdb*, const char* fname);

Store Header Information

The WdbSetDate(), WdbSetVersion() functions are used to store header information in the WDB. The data is store as strings. The WdbSetTimescale() is used to store header information in the WDB needed to convert from WdbTime steps into real time and vice versa.

They return zTrue if everything is ok. If there are problems zFalse is returned - call WdbErrorMsg() to get the error message.

zBool WdbSetDate(     Wdb*, const char* str);
zBool WdbSetVersion(  Wdb*, const char* str);
zBool WdbSetTimeScale(Wdb*, unsigned timeFactor, WdbTimeUnit unit);

Store Variable and Scope Definitions

All variables belong to a hierarchical scope. During the definition of variables with WdbVar() the scope can be changed by calling WdbScope(). WdbUpScope() or WdbPathScope(). The signal identifier sigNo can be used multiple times in different scopes. The next usable sigNo is returned by a call to WdbNextSigNo().

The end the variable definitions and start adding value changes the function WdbEndDefinitions() needs to be called.

The function WdbAddDefinitions() reenables adding Scopes, Variables.

The function WdbFindVar() returns the sigNo of a named variable or -1 if not found. This works only for in memory databases.

The function WdbFindAlias() returns the sigNo of a named and typed alias variable or -1 if not found. This works only for in memory databases.

The function WdbHideVar() hides the variable referenced by sigNo, if hide is zTrue, otherwise unhides it. This works only for in memory databases.

The functions, except WdbNextSigNo(), return zTrue if everything is ok. If there are problems zFalse is returned - call WdbErrorMsg() to get the error message.

zBool    WdbScope(         Wdb*, WdbScopeType, const char* name);
zBool    WdbPathScope(     Wdb*, WdbScopeType, zBool rel,
                                              const char** names, int namesLen);
zBool    WdbUpScope(       Wdb*);
WdbSigNo WdbNextSigNo(     Wdb*);
zBool    WdbVar(           Wdb*, WdbVarType, WdbValType,
                   const char* name, int w, WdbSigNo sigNo);
zBool    WdbAlias(         Wdb*, WdbAliasType,
                   const char* name, int w, WdbSigNo sigNo, const char* iname);
zBool    WdbEndDefinitions(Wdb*);
zBool    WdbAddDefinitions(Wdb*);
zBool    WdbFindVar(       Wdb*, const char* name, WdbSigNo* sigNo);
zBool    WdbFindAlias(     Wdb*, const char* name, WdbAliasType,
                                                const char* iname, WdbSigNo*);
zBool    WdbHideVar(       Wdb*, const char* name, zBool hide);
zBool    WdbDirVar(        Wdb*, const char* name, WdbVarDir dir);

Store Signal Value Changes

The function WdbAddTime() defines a new time which is used for all following value changes until a new call to WdbAddTime() is made.

The function WdbAddScalar() stores a new value for given signal.

WdbAddVector() store a complete bit vector. The given width w must match the width given to WdbVar() during variable definition.

The function WdbDone() marks the end of all value changes.

If there are problems zFalse is returned - call WdbErrorMsg() to get the error message.

Note	Todo WdbAddEvent() and WdbAddReal() are not implemented yet.

zBool WdbAddTime(  Wdb*, WdbTime tm, zBool* stopPtr);
zBool WdbAddScalar(Wdb*, WdbSigNo sigNo, WdbValue val);
zBool WdbAddVector(Wdb*, WdbSigNo sigNo, WdbValue* values, int w);
zBool WdbAddEvent( Wdb*, WdbSigNo sigNo);
zBool WdbAddReal(  Wdb*, WdbSigNo sigNo, double value);
zBool WdbDone(     Wdb*);

Get Error Message

The WdbErrorMsg() is used to get a more detailed on the last error occurred.

const char* WdbErrorMsg(Wdb*);