Table of Contents

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.

Table of Contents

2.1 Maintain Library Information - Library

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 object are the following.

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.

Table of Contents

2.2 Function Descriptions

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

Table of Contents , Library

NAME

*vdm_LibraryBegin - create an instance of a Library object

C SPECIFICATION

vdm_Library *vdm_LibraryBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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)

Table of Contents , Library

NAME

vdm_LibraryAddDataset - add dataset object to library

C SPECIFICATION

void vdm_LibraryAddDataset (vdm_Library *library,
                            vdm_Dataset *dataset)

INPUT ARGUMENTS

library      Pointer to Library object.
dataset      Pointer to Dataset object to add.

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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

Table of Contents , Library

NAME

vdm_LibraryDef - define library path and type

C SPECIFICATION

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

INPUT ARGUMENTS

library      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_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

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

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)

Table of Contents , Library

NAME

vdm_LibraryGetDataset - get library dataset object

C SPECIFICATION

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

INPUT ARGUMENTS

library      Pointer to Library object.
idst         Index of dataset object to get

OUTPUT ARGUMENTS

dataset      Pointer to Dataset object.

ERRORS

SYS_ERROR_VALUE is generated if an improper idst is specified.

DESCRIPTION

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.

Table of Contents , Library

NAME

vdm_LibraryGetNumDatasets - get number of datasets on library

C SPECIFICATION

void vdm_LibraryGetNumDatasets (vdm_Library *library,
                                Vint *numdatasets)

INPUT ARGUMENTS

library      Pointer to Library object.

OUTPUT ARGUMENTS

numdatasets  Number of datasets on library.

DESCRIPTION

Get the number of datasets on a library.

Table of Contents , Library

NAME

vdm_LibraryMaxIds - query for maximum dataset ids

C SPECIFICATION

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

INPUT ARGUMENTS

library      Pointer to Library object.

OUTPUT ARGUMENTS

id1          Maximum dataset first numeric identifier
id2          Maximum dataset second numeric identifier
id3          Maximum dataset third numeric identifier

DESCRIPTION

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.

Table of Contents , Library

NAME

vdm_LibrarySearchDataset - search for datasets by name

C SPECIFICATION

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

INPUT ARGUMENTS

library      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.

OUTPUT ARGUMENTS

idsts        Array of matching dataset indices.
num          The number of matching datasets returned.

DESCRIPTION

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.

Table of Contents , Library

NAME

vdm_LibraryTOC - print a library table of contents

C SPECIFICATION

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

INPUT ARGUMENTS

library      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

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_MEMORY is generated if a memory allocation failure occurs.

DESCRIPTION

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

Table of Contents

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.

Table of Contents

2.4 Function Descriptions

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

Table of Contents , Dataset

NAME

*vdm_DatasetBegin - create an instance of a Dataset object

C SPECIFICATION

vdm_Dataset *vdm_DatasetBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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)

Table of Contents , Dataset

NAME

vdm_DatasetAddAttribute - add attribute object to dataset

C SPECIFICATION

void vdm_DatasetAddAttribute (vdm_Dataset *dataset,
                              vdm_Attribute *attribute)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.
attribute    Pointer to Attribute object to add

OUTPUT ARGUMENTS

None

DESCRIPTION

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

Table of Contents , Dataset

NAME

vdm_DatasetComplx - get complex type

C SPECIFICATION

void vdm_DatasetComplx (vdm_Dataset *dataset,
                        Vint *cplx)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

cplx         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

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetContents - get Contents attribute

C SPECIFICATION

void vdm_DatasetContents (vdm_Dataset *dataset,
                          Vchar *ancont)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

ancont       Contents attribute value

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetCplx - parse result complex type

C SPECIFICATION

void vdm_DatasetCplx (vdm_Dataset *dataset,
                      Vint *cplx)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

cplx         Complex flag
             =0                      No I field encountered
             =1                      An I field encountered

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetDataType - get DataType attribute

C SPECIFICATION

void vdm_DatasetDataType (vdm_Dataset *dataset,
                          Vchar *andata,
                          Vint *datatype)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

andata       DataType attribute value
datatype     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

DESCRIPTION

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

Table of Contents , Dataset

NAME

vdm_DatasetDecode - decode a dataset name

C SPECIFICATION

void vdm_DatasetDecode (vdm_Dataset *dataset,
                        Vchar *name,
                        Vint *id1,
                        Vint *id2,
                        Vint *id3)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

name         Dataset alphanumeric component name
id1          First numeric identifier
id2          Second numeric identifier
id3          Third numeric identifier

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetDimensions - return dataset type physical dimensions

C SPECIFICATION

void vdm_DatasetDimensions (vdm_Dataset *dataset,
                            Vchar *dimensions)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

dimensions   Dataset result type physical dimension string

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetEntType - parse result entity types

C SPECIFICATION

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

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

enttype      Parent entity type, see vdm_DatasetResult
subtype      Child entity type

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetGetNCol - get number of dataset columns

C SPECIFICATION

void vdm_DatasetGetNCol (vdm_Dataset *dataset,
                         Vint *ncol)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

ncol         Number of dataset columns.

DESCRIPTION

Query number of dataset columns.

Table of Contents , Dataset

NAME

vdm_DatasetGetNRow - get number of dataset rows

C SPECIFICATION

void vdm_DatasetGetNRow (vdm_Dataset *dataset,
                         Vint *nrow)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

nrow         Number of dataset rows.

DESCRIPTION

Query number of dataset rows.

Table of Contents , Dataset

NAME

vdm_DatasetHist - parse result history flag

C SPECIFICATION

void vdm_DatasetHist (vdm_Dataset *dataset,
                      Vint *hist)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

hist         History flag
             =0                      No HIST field encountered
             =1                      A HIST field encountered

DESCRIPTION

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

Table of Contents , Dataset

NAME

vdm_DatasetIds - parse result identifiers

C SPECIFICATION

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

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

id1          First numeric identifier
id2          Second numeric identifier
id3          Third numeric identifier

DESCRIPTION

Return the datset integer identifiers.

Table of Contents , Dataset

NAME

vdm_DatasetQual - parse result qualifiers

C SPECIFICATION

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

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

nqua         Number of qualifier types, 0 <= nqua <= SYS_NQUA_MAX
iqua         Array of nqua qualifier types
cqua         Optional generic qualifier string

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetQualStrings - return qualifier strings

C SPECIFICATION

void vdm_DatasetQualStrings (vdm_Dataset *dataset,
                             Vint ith,
                             Vchar *name,
                             Vchar *contents)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.
iqlr         Ith position of qualifier in iqua (vdm_DatasetQual).

OUTPUT ARGUMENTS

name         Qualifier short name
contents     Qualifier long descriptive contents

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetQualVal - parse valued qualifiers

C SPECIFICATION

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

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

nqua         Number of valued qualifier types
iqua         Array of nqua valued qualifier types
dtyp         Data type of qualifier value
             =SYS_INTEGER            Integer value
             =SYS_FLOAT              Float value
ival         Array of nqua integer values
fval         Array of nqua float values

DESCRIPTION

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

Table of Contents , Dataset

NAME

vdm_DatasetResType - parse result type

C SPECIFICATION

void vdm_DatasetResType (vdm_Dataset *dataset,
                         Vint *type)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

type         Result type
             =SYS_RES_NONE           Unrecognized result
             >=0                     Result type

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetResult - parse result dataset component name

C SPECIFICATION

void vdm_DatasetResult (vdm_Dataset *dataset,
                        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)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

root         Dataset alphanumeric result name
type         Result type
             =SYS_RES_NONE           Unrecognized result
             >=0                     Result type
hist         History flag
             =0                      No HIST field encountered
             =1                      A HIST field encountered
nqua         Number of qualifier types, 0 <= nqua <= SYS_NQUA_MAX
iqua         Array of nqua qualifier types
cqua         Optional generic qualifier string
cplx         Complex flag
             =0                      No I field encountered
             =1                      An I field encountered
caux         Auxiliary alphanumeric string
sect         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      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      Child entity type
             =SYS_NODE               Node
             =SYS_INTPNT             Integration Point
             =SYS_NONE               None
id1          First numeric identifier
id2          Second numeric identifier
id3          Third numeric identifier

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetSect - parse result section

C SPECIFICATION

void vdm_DatasetSect (vdm_Dataset *dataset,
                      Vint *sect)

INPUT ARGUMENTS

dataset      Pointer to Dataset object.

OUTPUT ARGUMENTS

sect         Result section number, see vdm_DatasetResult

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetDef - define dataset parameters

C SPECIFICATION

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

INPUT ARGUMENTS

dataset      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]

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

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)

Table of Contents , Dataset

NAME

vdm_DatasetGetAttribute - get dataset attribute object

C SPECIFICATION

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

INPUT ARGUMENTS

dataset      Pointer to Dataset object.
iatt         Index of attribute object to get

OUTPUT ARGUMENTS

attribute    Pointer to Attribute object.

ERRORS

SYS_ERROR_VALUE is generated if an improper iatt is specified.

DESCRIPTION

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.

Table of Contents , Dataset

NAME

vdm_DatasetGetNumAttributes - get number of dataset attributes

C SPECIFICATION

void vdm_DatasetGetNumAttributes (vdm_Dataset *dataset,
                                  Vint *numattributes)

INPUT ARGUMENTS

dataset       Pointer to Dataset object.

OUTPUT ARGUMENTS

numattributes Number of dataset attributes.

DESCRIPTION

Get the number of dataset attributes.

Table of Contents , Dataset

NAME

vdm_DatasetSearchAttribute - search for dataset attributes by name

C SPECIFICATION

void vdm_DatasetSearchAttribute (vdm_Dataset *dataset,
                                 const Vchar *name,
                                 Vint max,
                                 Vint iatts[],
                                 Vint *num)

INPUT ARGUMENTS

dataset      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.

OUTPUT ARGUMENTS

iatts        Array of matching attribute indices.
num          The number of matching dataset attributes.

DESCRIPTION

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.

Table of Contents

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.

Table of Contents

2.6 Function Descriptions

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

Table of Contents , Attribute

NAME

*vdm_AttributeBegin - create an instance of an Attribute object

C SPECIFICATION

vdm_Attribute *vdm_AttributeBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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)

Table of Contents , Attribute

NAME

vdm_AttributeDef - define attribute parameters

C SPECIFICATION

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

INPUT ARGUMENTS

attribute    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

OUTPUT ARGUMENTS

None

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.

DESCRIPTION

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)

Table of Contents , Attribute

NAME

vdm_AttributeSetValuec - set string attribute values

C SPECIFICATION

void vdm_AttributeSetValuec (vdm_Attribute *attribute,
                             const Vchar *cvalue)

INPUT ARGUMENTS

attribute    Pointer to Attribute object.
cvalue       Attribute value

OUTPUT ARGUMENTS

None

DESCRIPTION

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.

Table of Contents , Attribute

NAME

vdm_AttributeSetValuedv - set double attribute values

C SPECIFICATION

void vdm_AttributeSetValuedv (vdm_Attribute *attribute,
                              const Vdouble *dvalue)

INPUT ARGUMENTS

attribute    Pointer to Attribute object.
dvalue       Attribute value

OUTPUT ARGUMENTS

None

DESCRIPTION

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.

Table of Contents , Attribute

NAME

vdm_AttributeSetValuefv - set float attribute values

C SPECIFICATION

void vdm_AttributeSetValuefv (vdm_Attribute *attribute,
                              const Vfloat *fvalue)

INPUT ARGUMENTS

attribute    Pointer to Attribute object.
fvalue       Attribute value

OUTPUT ARGUMENTS

None

DESCRIPTION

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.

Table of Contents , Attribute

NAME

vdm_AttributeSetValueiv - set integer attribute values

C SPECIFICATION

void vdm_AttributeSetValueiv (vdm_Attribute *attribute,
                              const Vint *ivalue)

INPUT ARGUMENTS

attribute    Pointer to Attribute object.
ivalue       Attribute value

OUTPUT ARGUMENTS

None

DESCRIPTION

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.

Table of Contents , Attribute

NAME

vdm_AttributeValueDouble - get double attribute values

C SPECIFICATION

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

INPUT ARGUMENTS

attribute    Pointer to Attribute object.

OUTPUT ARGUMENTS

dvalue       Double attribute values

ERRORS

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

DESCRIPTION

Return a double valued attribute.

Table of Contents , Attribute

NAME

vdm_AttributeValueFloat - get float attribute values

C SPECIFICATION

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

INPUT ARGUMENTS

attribute    Pointer to Attribute object.

OUTPUT ARGUMENTS

fvalue       Float attribute values

ERRORS

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

DESCRIPTION

Return a float valued attribute.

Table of Contents , Attribute

NAME

vdm_AttributeValueInteger - get integer attribute values

C SPECIFICATION

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

INPUT ARGUMENTS

attribute    Pointer to Attribute object.

OUTPUT ARGUMENTS

ivalue       Integer attribute values

ERRORS

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

DESCRIPTION

Return an integer valued attribute.

Table of Contents , Attribute

NAME

vdm_AttributeValueString - get character attribute values

C SPECIFICATION

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

INPUT ARGUMENTS

attribute    Pointer to Attribute object.

OUTPUT ARGUMENTS

cvalue       Character attribute values

ERRORS

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

DESCRIPTION

Return a character valued attribute.