2. Library Device Components - Library, Dataset, Attribute

Three modules are used to manage information about a library, its datasets and attributes. Each library device object, (eg. SDRCLib), uses a Library object and several Dataset and Attribute objects (one for each dataset and attribute respectively) to hold general information about the library, datasets and attributes associated with the library device. The user should use these objects to query for generic information about a library device.

Each library device module contains a function to return the Library object being used internally to manage generic library information, (eg. vdm_SDRCLibGetLibrary). In a DataFun object, this function is accessed using vdm_DataFunGetLibrary(). Once the Library object associated with a specific library device is obtained, general information such as the number of library datasets, dataset name and parameters, the number of dataset attributes, and attribute parameters and values may be queried.

Note that the actual reading of the contents of a dataset is performed by a library device function, (eg. vdm_SDRCLibReadDataset). In a DataFun object this function is accessed using vdm_DataFunReadDataset().

2.1. Maintain Library Information

A Library object maintains global library information and a set of Dataset objects. There is a unique Dataset object for each dataset on the library. The methods associated with a Library

Note that a Library object retrieved from a library device object belongs to the respective library device object. The library device object is responsible for its creation, destruction and definition. Invoke only query functions on such a Library object.

2.2. Function Descriptions

The currently available Library functions are described in detail in this section.

vdm_Library *vdm_LibraryBegin(void)

create an instance of a Library object

Create an instance of a Library object. Memory is allocated for the object private data and the pointer to the data is returned. By default the library contains no datasets.

Destroy an instance of a Library object using 

void vdm_LibraryEnd (vdm_Library *library)

Return the current value of a Library object error flag using 

Vint vdm_LibraryError (vdm_Library *library)

Returns

The function returns a pointer to the newly created Library object. If the object creation fails, NULL is returned.

void vdm_LibraryEnd(vdm_Library *p)

destroy an instance of a Library object

See vdm_LibraryBegin()

Vint vdm_LibraryError(vdm_Library *p)

return the current value of a Library object error flag

See vdm_LibraryBegin()

void vdm_LibraryDef(vdm_Library *p, const Vchar *path, Vint type)

define library path and type

Define the path and type of a library. Inquire of defined path and type as output arguments using 

void vdm_LibraryInq (vdm_Library *library,
                    Vchar *path,
                    Vint *type)

Errors

SYS_ERROR_ENUM is generated if an improper type is specified.

Parameters

  • p – Pointer to Library object.

  • path – Pathname to host file associated with the library

  • type – Type of library file 

    =SYS_ABAQUS_FIL         ABAQUS .fil data file
=SYS_ABAQUS_INPUT       ABAQUS .inp input file
=SYS_ABAQUS_ODB         ABAQUS .odb output data base
=SYS_ADAMS              MSC/Adams
=SYS_AFLR               AFLR grid file
=SYS_ANSYS_INPUT        ANSYS input (CDWRITE) file
=SYS_ANSYS_RESULT       ANSYS results file
=SYS_ANSYS_DPF          ANSYS Data Processing Framework (DPF)
=SYS_AUTODYN_RES        AUTODYN results file
=SYS_CGNS               CGNS data base
=SYS_CFX_RESULT         CFX results file
=SYS_COMSOL_SECTION     COMSOL Sectionwise file
=SYS_COMSOL_MPH         COMSOL mph ascii file
=SYS_COMSOL_MPHBIN      COMSOL mph binary file
=SYS_ENSIGHT            CEI/Ensight file format
=SYS_FEMAP_NEUTRAL      FEMAP neutral file
=SYS_FDI_NEUTRAL        FIDAP neutral file
=SYS_FLUENT_MESH        FLUENT mesh and data file
=SYS_GMV                GMV file
=SYS_HYPERMESH_ASCII    Altair HyperMesh ASCII file
=SYS_H3D                Altair H3D file
=SYS_LSTC_INPUT         LSTC/DYNA3D input file
=SYS_LSTC_HISTORY       LSTC/DYNA3D time history data base
=SYS_LSTC_STATE         LSTC/DYNA3D state data base
=SYS_LSTC_STATEFEMZIP   LSTC/DYNA3D FEMZIP state data base
=SYS_MARC_POST          MSC/Marc post data file
=SYS_MECHANICA_FNF      PTC/Mechanica FEM Neutral File
=SYS_MECHANICA_STUDY    PTC/Mechanica design study
=SYS_MEMORY             VKI memory object
=SYS_NASTRAN_BULKDATA   MSC/NASTRAN bulk data file
=SYS_NASTRAN_OUTPUT2    MSC/NASTRAN OUTPUT2 data file
=SYS_NASTRAN_XDB        MSC/NASTRAN XDB data file
=SYS_NASTRAN_H5         MSC/NASTRAN .h5 data file
=SYS_NATIVE             VKI native data base
=SYS_NATIVE_HDF5        VKI native HDF5 data base
=SYS_OBJ                OBJ file
=SYS_OPENFOAM           OpenFOAM file
=SYS_PAM_DAISY          ESI/PAM-CRASH DAISY file
=SYS_PAM_ERF            ESI/PAM-CRASH ERF file
=SYS_PATRAN_NEUTRAL     MSC/Patran neutral file
=SYS_PATRAN_RESULT      MSC/Patran result file
=SYS_PERMAS_POST        INTES/PERMAS result file
=SYS_PLOT3D_GRID        NASA/PLOT3D grid file
=SYS_PLOT3D_SOLUTION    NASA/PLOT3D solution or function file
=SYS_POLYFLOW           POLYFLOW mesh file
=SYS_SAMCEF             SAMCEF des file
=SYS_SDRC_UNIVERSAL     SDRC universal file
=SYS_STARCCM            STAR-CCM results file
=SYS_STL                STL ASCII text format
=SYS_STLBIN             STL binary format
=SYS_TECPLOT            Tecplot file format
=SYS_VTK_LEGACY         Vtk legacy file format

void vdm_LibraryInq(vdm_Library *p, Vchar path[], Vint *type)

inquire of defined path and type as output arguments

See vdm_LibraryDef()

void vdm_LibraryTOC(vdm_Library *p, const Vchar *name, Vint flag)

print a library table of contents

List the datasets in a library. The dataset name and parameters are listed. Use flag to list dataset attributes with the dataset names.

Errors

SYS_ERROR_MEMORY is generated if a memory allocation failure occurs.

Parameters

  • p – Pointer to Library object.

  • name – Dataset names to list. This name may contain wild card characters.

  • flag – Flag to list dataset attributes 

    =SYS_OFF      Do not print dataset attributes
=SYS_ON       Print dataset attributes

void vdm_LibraryAddDataset(vdm_Library *p, vdm_Dataset *dataset)

add dataset object to library

Add a dataset object to a library. Use vdm_LibraryGetNumDatasets() to return the number of datasets in the library.

Errors

SYS_ERROR_OPERATION is generated if the library or dataset have not been defined.

Parameters

  • p – Pointer to Library object.

  • dataset – Pointer to Dataset object to add.

void vdm_LibraryGetNumDatasets(vdm_Library *p, Vint *numdataset)

get number of datasets on library

Get the number of datasets on a library.

Parameters

  • p – Pointer to Library object.

  • numdataset – [out] Number of datasets on library.

void vdm_LibraryGetDataset(vdm_Library *p, Vint idst, vdm_Dataset **dataset)

get library dataset object

Get a dataset object associated with a library dataset. The dataset index, idst, is an integer in the range from zero to the number of datasets minus one. Use vdm_LibraryGetNumDatasets() to return the number of datasets on the library.

Errors

SYS_ERROR_VALUE is generated if an improper idst is specified.

Parameters

  • p – Pointer to Library object.

  • idst – Index of dataset object to get

  • dataset – [out] Pointer to Dataset object.

void vdm_LibrarySearchDataset(vdm_Library *p, const Vchar *name, Vint max, Vint idsts[], Vint *num)

search for datasets by name

Search all datasets in a library for those which match a given dataset name. The number of matching datasets, num, is returned. The value of num never exceeds the input value of max.

Parameters

  • p – Pointer to Library object.

  • name – Dataset name to search for. This name may contain wild card characters.

  • max – The maximum number of matching dataset indices to return. This number is the allocated size of the idsts array.

  • idsts – [out] Array of matching dataset indices.

  • num – [out] The number of matching datasets returned.

void vdm_LibraryMaxIds(vdm_Library *p, Vint *id1, Vint *id2, Vint *id3)

query for maximum dataset ids

Traverse all result type datasets in a library and find the maximum numeric identifiers used in the dataset names. A result dataset is defined as a dataset with a “DataType” attribute specified.

Parameters

  • p – Pointer to Library object.

  • id1 – [out] Maximum dataset first numeric identifier

  • id2 – [out] Maximum dataset second numeric identifier

  • id3 – [out] Maximum dataset third numeric identifier

2.3. Maintain Dataset Information - Dataset

A Dataset object maintains dataset parameters and a set of Attribute objects. There is a unique Attribute object for each dataset attribute. The methods associated with a Dataset object are the following.

Note that a Dataset object retrieved from a Library object belongs to the respective Library object. The Library object is responsible for its creation, destruction and definition. Invoke only query functions on such a Dataset object.

A special set of functions are provided to manage result datasets. These datasets have the following form:

dataset_name:id1:id2:id3

The dataset_name is an alphanumeric string consisting of two or more fields delimited by periods. A result dataset is characterized by a first field containing a supported result type and the last field indicating a node (.N), element (.E) or element node (.EL) result quantity. Use the function vdm_DatasetResult() to determine if a dataset contains a supported result type. The function vdm_DatasetDecode() will decode the numeric identifiers, id1, id2 and id3. The convenience routines vdm_DatasetContents() and vdm_DatasetDataType() will return the values of the Contents and DataType attributes. These attributes should be defined for any result dataset.

2.4. Function Descriptions

The currently available Dataset functions are described in detail in this section.

vdm_Dataset *vdm_DatasetBegin(void)

create an instance of a Dataset object

Create an instance of a Dataset object. Memory is allocated for the object private data and the pointer to the data is returned. By default the dataset contains no attributes.

Destroy an instance of a Dataset object using 

void vdm_DatasetEnd (vdm_Dataset *dataset)

Return the current value of a Dataset object error flag using 

Vint vdm_DatasetError (vdm_Dataset *dataset)

Returns

The function returns a pointer to the newly created Dataset object. If the object creation fails, NULL is returned.

void vdm_DatasetEnd(vdm_Dataset *p)

destroy an instance of a Dataset object

See vdm_DatasetBegin()

Vint vdm_DatasetError(vdm_Dataset *p)

return the current value of a Dataset object error flag

See vdm_DatasetBegin()

void vdm_DatasetDef(vdm_Dataset *p, const Vchar *name, Vlong lrec, Vint nrow, Vint ncol, Vint type)

define dataset parameters

Define dataset parameters. Currently, dataset names are limited to 256 characters including the terminating null character. The defined symbol DATASET_MAXNAME is set to the current maximum dataset name length. The length of the dataset contents in bytes is given by the product of lrec and the sizeof the data type indicated by type.

Inquire of defined name, lrec, nrow, ncol and type as output arguments using 

void vdm_DatasetInq (vdm_Dataset *dataset,
                     Vchar *name,
                     Vlong *lrec,
                     Vint *nrow,
                     Vint *ncol,
                     Vint *type)

Errors

SYS_ERROR_ENUM is generated if an improper type is specified.

Parameters

  • p – Pointer to Dataset object.

  • name – Name given to dataset

  • lrec – Length of dataset contents in type units

  • nrow – Number of dataset rows

  • ncol – Number of dataset columns

  • type – Data type of dataset contents 

    =SYS_INTEGER            Integer, type Vint
=SYS_FLOAT              Single precision, type Vfloat
=SYS_HOLLERITH          Hollerith, type Vuint
=SYS_DOUBLE             Double precision, type Vdouble
=SYS_COMPLEX            Complex, type Vfloat[2]
=SYS_DOUBLECOMPLEX      Double Complex, type Vdouble[2]

void vdm_DatasetInq(vdm_Dataset *p, Vchar name[], Vlong *lrec, Vint *nrow, Vint *ncol, Vint *type)

inquire of defined name, lrec, nrow, ncol and type as output arguments

See vdm_DatasetDef()

void vdm_DatasetGetNRow(vdm_Dataset *p, Vint *nrow)

get number of dataset rows

Query number of dataset rows.

Parameters

  • p – Pointer to Dataset object.

  • nrow – [out] Number of dataset rows.

void vdm_DatasetGetNCol(vdm_Dataset *p, Vint *ncol)

get number of dataset columns

Query number of dataset columns.

Parameters

  • p – Pointer to Dataset object.

  • ncol – [out] Number of dataset columns.

void vdm_DatasetAddAttribute(vdm_Dataset *p, vdm_Attribute *attribute)

add attribute object to dataset

Add an attribute object to a dataset. Use vdm_DatasetGetNumAttributes() to return the number of dataset attributes.

Parameters

  • p – Pointer to Dataset object.

  • attribute – Pointer to Attribute object to add

void vdm_DatasetGetNumAttributes(vdm_Dataset *p, Vint *numattributes)

get number of dataset attributes

Get the number of dataset attributes.

Parameters

  • p – Pointer to Dataset object.

  • numattributes – [out] Number of dataset attributes.

void vdm_DatasetGetAttribute(vdm_Dataset *p, Vint iatt, vdm_Attribute **attribute)

get dataset attribute object

Get an attribute object associated with an dataset attribute. The attribute index, iatt, is an integer in the range from zero to the number of attributes minus one. Use vdm_DatasetGetNumAttributes() to return the number of dataset attributes.

Errors

SYS_ERROR_VALUE is generated if an improper iatt is specified.

Parameters

  • p – Pointer to Dataset object.

  • iatt – Index of attribute object to get

  • attribute – [out] Pointer to Attribute object.

void vdm_DatasetSearchAttribute(vdm_Dataset *p, Vchar *name, Vint max, Vint *iatts, Vint *num)

search for dataset attributes by name

Search all attributes in a dataset for those which match a given attribute name. The number of matching attributes is returned. If the number of matching attributes, num, exceeds the maximum number of attribute indices to return, max, then only the first max matching attribute indices are returned in array iatts.

Parameters

  • p – Pointer to Dataset object.

  • name – Attribute name to search for. This name may contain wild card characters.

  • max – The maximum number of matching dataset attribute indices to return. This number is the allocated size of the iatts array.

  • iatts – [out] Array of matching attribute indices.

  • num – [out] The number of matching dataset attributes.

void vdm_DatasetDecode(vdm_Dataset *p, Vchar name[], Vint *id1, Vint *id2, Vint *id3)

decode a dataset name

Decode a dataset specification into its component name and numeric identifiers. A missing numeric identifier is returned as zero. Use vdm_DatasetResult() to identify a result dataset and parse the component name fields.

Parameters

  • p – Pointer to Dataset object.

  • name – [out] Dataset alphanumeric component name

  • id1 – [out] First numeric identifier

  • id2 – [out] Second numeric identifier

  • id3 – [out] Third numeric identifier

void vdm_DatasetIds(vdm_Dataset *p, Vint *id1, Vint *id2, Vint *id3)

parse result identifiers

Return the datset integer identifiers.

Parameters

  • p – Pointer to Dataset object.

  • id1 – [out] First numeric identifier

  • id2 – [out] Second numeric identifier

  • id3 – [out] Third numeric identifier

void vdm_DatasetEntType(vdm_Dataset *p, Vint *enttype, Vint *subtype)

parse result entity types

Parse the entity types of the result dataset specification. This is a convenience function to return a subset of the full set of dataset result parameters returned by vdm_DatasetResult().

Parameters

  • p – Pointer to Dataset object.

  • enttype – [out] Parent entity type, see vdm_DatasetResult()

  • subtype – [out] Child entity type

void vdm_DatasetResType(vdm_Dataset *p, Vint *type)

parse result type

Return the result type. This is a convenience function to return a subset of the full set of dataset result parameters returned by vdm_DatasetResult().

Parameters

  • p – Pointer to Dataset object.

  • type – [out] Result type 

    =SYS_RES_NONE         Unrecognized result
>=0                   Result type

void vdm_DatasetSect(vdm_Dataset *p, Vint *sect)

parse result section

Parse the section of the result dataset specification. This is a convenience function to return a subset of the full set of dataset result parameters returned by vdm_DatasetResult().

Parameters
void vdm_DatasetHist(vdm_Dataset *p, Vint *hist)

parse result history flag

This is a convenience function to return a subset of the full set of dataset result parameters returned by vdm_DatasetResult().

Parameters

  • p – Pointer to Dataset object.

  • hist – [out] History flag 

    x=0            No HIST field encountered
 =1            A HIST field encountered

void vdm_DatasetCplx(vdm_Dataset *p, Vint *cplx)

parse result complex type

Return the complex flag. This is a convenience function to return a subset of the full set of dataset result parameters returned by vdm_DatasetResult().

Parameters

  • p – Pointer to Dataset object.

  • cplx – [out] Complex flag 

    =0            No I field encountered
=1            An I field encountered

void vdm_DatasetQual(vdm_Dataset *p, Vint *nqua, Vint iqua[], Vchar cqua[])

parse result qualifiers

Return the qualifier types. This is a convenience function to return a subset of the full set of dataset result parameters returned by vdm_DatasetResult(). Note that valued qualifiers are returned as character strings in the cqua argument. Use vdm_DatasetQualVal() to parse valued qualifiers.

Parameters

  • p – Pointer to Dataset object.

  • nqua – [out] Number of qualifier types, 0 <= nqua <= SYS_NQUA_MAX

  • iqua – [out] Array of nqua qualifier types

  • cqua – [out] Optional generic qualifier string

void vdm_DatasetQualVal(vdm_Dataset *p, Vint *nqua, Vint iqua[], Vint dtyp[], Vint ival[], Vfloat fval[])

parse valued qualifiers

Return the valued qualifier types and associated integer or float values.

Parameters

  • p – Pointer to Dataset object.

  • nqua – [out] Number of valued qualifier types

  • iqua – [out] Array of nqua valued qualifier types

  • dtyp – [out] Data type of qualifier value 

    =SYS_INTEGER            Integer value 
=SYS_FLOAT              Float value

  • ival – [out] Array of nqua integer values

  • fval – [out] Array of nqua float values

void vdm_DatasetQualStrings(vdm_Dataset *p, Vint iqlr, Vchar name[], Vchar contents[])

return qualifier strings

Return qualifier strings. This is a convenience function to return strings associated with the built-in qualifiers, iqua, returned by vdm_DatasetQual(). The qualifier index, iqlr, is an integer in the range from zero to the number, nqua, of built-in qualifiers minus one.

Parameters

  • p – Pointer to Dataset object.

  • iqlr – Ith position of qualifier in iqua (vdm_DatasetQual()).

  • name – [out] Qualifier short name

  • contents – [out] Qualifier long descriptive contents

void vdm_DatasetResult(vdm_Dataset *p, Vchar root[], Vint *type, Vint *hist, Vint *nqua, Vint iqua[], Vchar cqua[], Vint *cplx, Vchar caux[], Vint *sect, Vint *enttype, Vint *subtype, Vint *id1, Vint *id2, Vint *id3)

parse result dataset component name

Parse a result dataset specification. This function is specifically designed to distinguish results datasets. A result dataset contains an alphanumeric component string with fields delimited by periods. The first field is returned in root and is checked to match one of the supported result types. If a recognizable type is found then type will contain the result type otherwise type will be set to SYS_RES_NONE.

If a SEC field is encountered indicating a result section point then the section location or number is returned in sect.

A set of qualifiers are delimited by left and right brackets, [ and ]. Each qualifier in turn is delimited by commas. If a qualifier string matches one of the specific supported types it is returned in iqua. All unsupported qualifier strings are returned in cqua separated by commas.

If the final field is N then a node based result is assumed. If the final field is E, EL or EIP then an element, element node or element integration point result is assumed respectively. If the final field is EF, EFN, EE or EEN then an element face, element face node, element edge or element edge node result is assumed respectively. If the final field is D then a degree of freedom based result is assumed. If the final field is PCL then a particle based result is assumed. If the final field is MOD then a mode based result is assumed. If the final field is PNL then a panel based result is assumed.

The component string itself is delimited from the dataset numeric identifiers, if they exist, by a colon.

Parameters

  • p – Pointer to Dataset object.

  • root – [out] Dataset alphanumeric result name

  • type – [out] Result type 

    =SYS_RES_NONE           Unrecognized result
>=0                     Result type

  • hist – [out] History flag 

    =0                      No HIST field encountered
=1                      A HIST field encountered

  • nqua – [out] Number of qualifier types, 0 <= nqua <= SYS_NQUA_MAX

  • iqua – [out] Array of nqua qualifier types

  • cqua – [out] Optional generic qualifier string

  • cplx – [out] Complex flag 

    =0                      No I field encountered
=1                      An I field encountered

  • caux – [out] Auxiliary alphanumeric string

  • sect – [out] Result section number 

    =SYS_ELEMSEC_BOT        Shell bottom
=SYS_ELEMSEC_TOP        Shell top
=SYS_ELEMSEC_MID        Shell midsurface
=SYS_ELEMSEC_ALL        All sections
=0                      No section
>0                      Section number

  • enttype – [out] Parent entity type 

    =SYS_NODE               Node
=SYS_ELEM               Element
=SYS_FACE               Element Face
=SYS_EDGE               Element Edge
=SYS_DOF                Degree of Freedom
=SYS_PARTICLE           Particle
=SYS_MODE               Mode
=SYS_PANEL              Panel

  • subtype – [out] Child entity type 

    =SYS_NODE               Node
=SYS_INTPNT             Integration Point
=SYS_NONE               None

  • id1 – [out] First numeric identifier

  • id2 – [out] Second numeric identifier

  • id3 – [out] Third numeric identifier

void vdm_DatasetDataType(vdm_Dataset *p, Vchar andata[], Vint *datatypeFIX)

get DataType attribute

This is a convenience function to access the character string value of the DataType attribute and the associated integer datatypeFIX constant. If the DataType attribute is not present, then andata contains a single null character.

Parameters

  • p – Pointer to Dataset object.

  • andata – [out] DataType attribute value

  • datatypeFIX – [out] Data type 

    =SYS_SCALAR             Scalar data
=SYS_VECTOR             Vector data
=SYS_TENSOR             Symmetric tensor data
=SYS_GENERALTENSOR      General Tensor data
=SYS_MATRIX_DIAG        Diagonal Matrix data
=SYS_MATRIX_SYMM        Symmetric Matrix data
=SYS_MATRIX_USYMM       Unsymmetric Matrix data
=SYS_SCALARS            Scalars data
=SYS_SIXDOF             Translation and rotation vector data
=SYS_DATATYPE_NONE      No DataType present

void vdm_DatasetContents(vdm_Dataset *p, Vchar ancont[])

get Contents attribute

This is a convenience function to access the character string value of the Contents attribute. If the Contents attribute is not present, then ancont contains a single null character.

Parameters

  • p – Pointer to Dataset object.

  • ancont – [out] Contents attribute value

void vdm_DatasetComplx(vdm_Dataset *p, Vint *cplx)

get complex type

This is a convenience function to access the complex type defined by the Complex attribute. If the Complex attribute is not present, then cplx is returned as SYS_COMPLEX_NONE. The function name is deliberately misspelled to avoid compile errors.

Parameters

  • p – Pointer to Dataset object.

  • cplx – [out] Complex type 

    =SYS_COMPLEX_NONE            Real, not part of complex number
=SYS_COMPLEX_REAL            Real part of complex number
=SYS_COMPLEX_MAGNITUDE       Magnitude part of complex number
=SYS_COMPLEX_IMAGINARY       Imaginary part of complex number
=SYS_COMPLEX_PHASE           Phase part of complex number
=SYS_COMPLEX_REALIMAGINARY   Real and imaginary
=SYS_COMPLEX_MAGNITUDEPHASE  Phase and magnitude

void vdm_DatasetDimensions(vdm_Dataset *p, Vchar dimensions[])

return dataset type physical dimensions

Return the physical dimensions of the dataset result type. If the dataset does not contain a specific result type or the dimensions of the result are unknown a blank string (zero length) string is returned.

Parameters

  • p – Pointer to Dataset object.

  • dimensions – [out] Dataset result type physical dimension string

2.5. Maintain Attribute Information - Attribute

An Attribute object maintains attribute parameters and associated attribute values. An attribute value may be either integer, real or character. The methods associated with an Attribute object are the following.

Instance an Attribute object initially using vdm_AttributeBegin(). The attribute value type and length is defined using vdm_AttributeDef(). Note that an Attribute object retrieved from a Dataset object belongs to the respective Dataset object. The Dataset object is responsible for its creation, destruction and definition. Invoke only query functions on such an Attribute object. Query attribute values using the type specific functions vdm_AttributeValueDouble(), vdm_AttributeValueFloat(), vdm_AttributeValueInteger() and vdm_AttributeValueString().

2.6. Function Descriptions

The currently available Attribute functions are described in detail in this section.

vdm_Attribute *vdm_AttributeBegin(void)

create an instance of an Attribute object

Create an instance of a Attribute object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of an Attribute object using 

void vdm_AttributeEnd (vdm_Attribute *attribute)

Return the current value of an Attribute object error flag using 

Vint vdm_AttributeError (vdm_Attribute *attribute)
Make a copy of an Attribute object. The private data from the fromattribute object is copied to the attribute object. Any previous private data in attribute is lost. 
void vdm_AttributeCopy (vdm_Attribute *attribute,
                        vdm_Attribute *fromattribute)

Returns

The function returns a pointer to the newly created Attribute object. If the object creation fails, NULL is returned.

void vdm_AttributeEnd(vdm_Attribute *p)

destroy an instance of an Attribute object

See vdm_AttributeBegin()

Vint vdm_AttributeError(vdm_Attribute *p)

return the current value of an Attribute object error

See vdm_AttributeBegin()

void vdm_AttributeDef(vdm_Attribute *p, const Vchar *name, Vint length, Vint type)

define attribute parameters

Define attribute parameters. Currently, attribute names are limited to 256 characters including the terminating null character. The defined symbol ATTRIBUTE_MAXNAME is set to the current maximum attribute name length. Attribute values are limited to an array of 256 characters including the terminating null character, 64 integers, 64 floats, or 32 doubles. If the specified length is less than the maximum, then the length is truncated to the maximum length for the data type. The defined symbol ATTRIBUTE_MAXVALUE is set to the current maximum attribute value length in bytes.

Inquire of defined name, length, and type as output arguments using 

void vdm_AttributeInq (vdm_Attribute *attribute,
                       Vchar *name,
                       Vint *length,
                       Vint *type)

Errors

  • SYS_ERROR_VALUE is generated if a negative or zero length is specified.

  • SYS_ERROR_ENUM is generated if an improper type is specified.

Parameters

  • p – Pointer to Attribute object.

  • name – Name given to attribute

  • length – Length of attribute value in type units

  • type – Data type of attribute value 

    =SYS_INTEGER  Integer, type Vint
=SYS_FLOAT    Single precision, type Vfloat
=SYS_CHAR     Character, type Vchar
=SYS_WCHAR    Wide character, type Vwchar
=SYS_DOUBLE   Double precision, type Vdouble

void vdm_AttributeInq(vdm_Attribute *p, Vchar name[], Vint *length, Vint *type)

inquire of defined name, length, and type as output arguments

See vdm_AttributeDef()

void vdm_AttributeSetValueiv(vdm_Attribute *p, const Vint ivalue[])

set integer attribute values

Set a integer attribute value. The length and data type of the attribute value must have been previously defined using vdm_AttributeDef(). Use vdm_AttributeValueInteger() to return integer valued attributes.

Parameters

  • p – Pointer to Attribute object.

  • ivalue – Attribute value

void vdm_AttributeSetValuefv(vdm_Attribute *p, const Vfloat fvalue[])

set float attribute values

Set a float attribute value. The length and data type of the attribute value must have been previously defined using vdm_AttributeDef(). Use vdm_AttributeValueFloat() to return float valued attributes.

Parameters

  • p – Pointer to Attribute object.

  • fvalue – Attribute value

void vdm_AttributeSetValuedv(vdm_Attribute *p, const Vdouble dvalue[])

set double attribute values

Set a double attribute value.

The length and data type of the attribute value must have been previously defined using

vdm_AttributeDef(). Use vdm_AttributeValueDouble() to return double valued attributes.

Parameters

  • p – Pointer to Attribute object.

  • dvalue – Attribute value

void vdm_AttributeSetValuec(vdm_Attribute *p, const Vchar cvalue[])

set string attribute values

Set a character attribute value. The length and data type of the attribute value must have been previously defined using vdm_AttributeDef(). Use vdm_AttributeValueString() to return character valued attributes.

Parameters

  • p – Pointer to Attribute object.

  • cvalue – Attribute value

void vdm_AttributeValueInteger(vdm_Attribute *p, Vint ivalue[])

get integer attribute values

Return an integer valued attribute.

Errors

SYS_ERROR_OPERATION is generated if the value is not defined as integer.

Parameters

  • p – Pointer to Attribute object.

  • ivalue – [out] Integer attribute values

void vdm_AttributeValueFloat(vdm_Attribute *p, Vfloat fvalue[])

get float attribute values

Return a float valued attribute.

Errors

SYS_ERROR_OPERATION is generated if the value is not defined as float.

Parameters

  • p – Pointer to Attribute object.

  • fvalue – [out] Float attribute values

void vdm_AttributeValueDouble(vdm_Attribute *p, Vdouble dvalue[])

get double attribute values

Return a double valued attribute.

Errors

SYS_ERROR_OPERATION is generated if the value is not defined as double.

Parameters

  • p – Pointer to Attribute object.

  • dvalue – [out] Double attribute values

void vdm_AttributeValueString(vdm_Attribute *p, Vchar cvalue[])

get character attribute values

Return a character valued attribute.

Errors

SYS_ERROR_OPERATION is generated if the value is not defined as character.

Parameters

  • p – Pointer to Attribute object.

  • cvalue – [out] Character attribute values

void vdm_AttributeCopy(vdm_Attribute *p, vdm_Attribute *fromp)

make a copy of an Attribute object

See vdm_AttributeBegin()