4.12.1. API Functions
[4.12. Data Sets]

Multiple Data sets groups A multiple data sets group stores datasets for a specific spatial data object (mesh or grid). The mesh or grid that the data sets are to be used with is identified by using a global unique identifier or GUID. The following functions are used to create multiple data sets groups, retrieve paths to multiple data sets groups, and retrieve the GUID for the spatial data object. The GUID string should be of size XF_GUID_STRINGLENGTH as defined in the XMDF source code.

C/C++

int xfCreateMultiDatasetsGroup(xid ParentId, const char *Path,
                               const char *Guid);
int xfGetGroupPathsSizeForMultiDatasets(xid FileId, int *Num, int *MaxSize);
int xfGetAllGroupPathsForMultiDatasets(xid FileId, int Num, int Maxsize, 
                                       char *path);
int xfGetDatasetsSdoGuid(xid MultiDatasetsGroup, char *GUID);

FORTRAN

SUBROUTINE  XF_CREATE_MULTI_DATASETS_GROUP(ParentId, Path, Guid, Error)
INTEGER(XID), INTENT(IN) :: ParentId
CHARACTER(LEN=*), INTENT(IN) :: Path, Guid
INTEGER, INTENT(OUT)     :: Error
 
SUBROUTINE XF_GET_GRP_PTHS_SZ_MLT_DSETS (FileId, Num, Maxsize, Error)
INTEGER(XID), INTENT(IN) ::   FileId
INTEGER, INTENT(OUT) ::       Num, Maxsize, Error
 
SUBROUTINE XF_GET_ALL_GRP_PATHS_MLT_DSETS (FileId, Num, Size, Paths, Error)
INTEGER(XID), INTENT(IN) ::     FileId
INTEGER, INTENT(IN) ::  Num, Size
CHARACTER(len=Size), DIMENSION(Size, Num), INTENT(INOUT) ::  Paths
INTEGER, INTENT(OUT) :: Error
 
SUBROUTINE  XF_GET_DATASETS_SDO_GUID(MultiDatasetsGroup, Guid)
INTEGER(XID), INTENT(IN) :: ParentId
CHARACTER(LEN=XF_GUID_STRINGLENGTH), INTENT(OUT) :: Guid
INTEGER, INTENT(OUT)     :: Error

The multiple data sets group for a spatial data object is created automatically upon first use. The following function is used to open the data sets group associated with a spatial data object. Note this is the only case where a GUID is not needed for a multiple datasets group because the spatial data object that the datasets belong to is obvious.

C/C++

int xfOpenMultiDatasetsGroup(xid GridGroupId, xid *DatasetsGroupId);

FORTRAN

SUBROUTINE  XF_OPEN_MULTI_DATASETS_GROUP(GridGroupId, DatasetsGroupId, Error)
INTEGER(XID), INTENT(IN) :: GroupId
INTEGER(XID), INTENT(OUT):: DatasetsGroupId
INTEGER, INTENT(OUT)     :: Error

Shortcut to setup writing to datasets A shortcut is provided in XMDF to allow model developers to easily setup the files and groups to write datasets. This shortcut is the function xfSetupToWriteDatasets. This function should always be used by model developers because it ensures that all models used with XMDF have a consistent and easy to use method to begin writing datasets.

The arguments for xfSetupToWriteDatasets should be given to the model using an external text file or command line arguments. The arguments include the filename to save the datasets, the path to a special group called the multi-datasets group path, the path to start writing datasets in this path, the GUID for the spatial data object that all the datasets will be tied to, and the overwrite options. The overwrite options are listed below by number and the corresponding C/FORTRAN constant (either the number or the constant may be used).

XF_OVERWRITE_CLEAR_FILE - File is intended only for the datasets being written by this model. If a file exists with the filename, delete the file.

XF_OVERWRITE_CLEAR_DATASET_GROUP - Leave existing file if one exists but clear any existing datasets or groups currently in the path where datasets will be written (PathInMultiDatasetsGroup).

XF_OVERWRITE_NONE - Leave existing file and all data within the file. When the datasets are created they will overwrite any datasets with the same name and path.

C/C++

int xfSetupToWriteDatasets(const char *Filename,
                           const char *MultiDatasetsGroupPath, 
                           const char *PathInMultiDatasetsGroup,
                           const char *SpatialDataObjectGuid,
                           int OverwriteOptions,
                           xid *FileId,
                           xid *GroupId);

FORTRAN

SUBROUTINE  XF_SETUP_TO_WRITE_DATASETS (Filename, MultiDatasetsGroupPath,
                PathInMultiDatasetsGroup, SpatialDataObjectGuid,
                FileId, GroupId, Error)
INTEGER(XID), INTENT(IN)     :: GroupId
CHARACTER(len=*), INTENT(IN) :: Filename, MultiDatasetsGroupPath
CHARACTER(len=*), INTENT(IN) :: PathInMultiDatasetsGroup, SpatialDataObjectGuid
INTEGER(XID), INTENT(OUT)    :: FileId, GroupId
INTEGER, INTENT(OUT)         :: Error

Creating and Writing Data sets The following functions are used to create data sets to write to HDF5. The units for the data set are specified when the data set is created. The maximum length for the units is 100 characters.

Valid time units are identified using the constants TS_DAYS, TS_HOURS, TS_MINUTES, TS_SECONDS, or TS_NOTAPPLICABLE. The compression value is applied to all arrays in the data set.

C/C++

int xfCreateScalarDataset(xid DatasetGroupId, const char *Path, const char *Units,
                          const char *TimeUnits, int Compression, xid *DatasetId);
int xfCreateVectorDataset(xid DatasetGroupId, const char *Path, const char *Units,
                          const char *TimeUnits, int Compression, xid *DatasetId);

FORTRAN

SUBROUTINE  XF_CREATE_SCALAR_DATASET(DatasetsGroupId, Path, Units, TimeUnits,
                                 Compression, DatasetId, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsGroupId
CHARACTER(len=*), INTENT(IN) :: Path, Units, TimeUnits
INTEGER, INTENT(IN) :: Compression
INTEGER(XID), INTENT(OUT) :: DatasetId
INTEGER, INTENT(OUT)      :: Error
 
 
SUBROUTINE  XF_CREATE_VECTOR_DATASET(DatasetsGroupId, Path, Units, TimeUnits,
                                 Compression, DatasetId, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsGroupId
CHARACTER(len=*), INTENT(IN) :: Path, Units, TimeUnits
INTEGER, INTENT(IN) :: Compression
INTEGER(XID), INTENT(OUT) :: DatasetId
INTEGER, INTENT(OUT)      :: Error

All date/time values stored in XMDF should be stored as Julian dates for consistency. A Julian day is the absolute count of days that have elapsed since Noon Universal Time on January 1, 4713 BCE on the Julian calendar (http://aa.usno.navy.mil/data/docs/JulianDate.html). While Julian dates are a good standard date format to follow, they aren�t very meaningful to most people. XMDF contains functions to convert calendar days to Julian days and Julian days to Calendar days. The conversion algorithms were adapted from code on a website maintained by the U.S. Naval Observatory (http://aa.usno.navy.mil/data/docs/JulianDate.html).

C/C++

int xfCalendarToJulian (xbool a_bBceEra, int a_yr, int a_mo, int a_day, 
                       int a_hr, int a_min, int a_sec, double *a_julian);
int xfJulianToCalendar (xbool *a_bBceEra, int *a_yr, int *a_mo, int *a_day,
                        int *a_hr, int *a_min, int *a_sec, double a_julian);

FORTRAN

SUBROUTINE XF_CALENDAR_TO_JULIAN (era, yr, mo, day, hr, &
                                  min, sec, julian, error)
  INTEGER, INTENT(IN)       :: era
  INTEGER, INTENT(IN)       :: yr
  INTEGER, INTENT(IN)       :: mo
  INTEGER, INTENT(IN)       :: day
  INTEGER, INTENT(IN)       :: hr
  INTEGER, INTENT(IN)       :: min
  INTEGER, INTENT(IN)       :: sec
  REAL(DOUBLE), INTENT(OUT) :: julian
  INTEGER, INTENT(OUT)      :: error
 
SUBROUTINE XF_JULIAN_TO_CALENDAR (era, yr, mo, day, hr, &
                                  min, sec, julian, error)
  INTEGER, INTENT(OUT) :: era
  INTEGER, INTENT(OUT) :: yr
  INTEGER, INTENT(OUT) :: mo
  INTEGER, INTENT(OUT) :: day
  INTEGER, INTENT(OUT) :: hr
  INTEGER, INTENT(OUT) :: min
  INTEGER, INTENT(OUT) :: sec
  REAL(DOUBLE), INTENT(IN) :: julian
  INTEGER, INTENT(OUT) :: error

The following function is used to store a reference time for a data set. This reference time should be a double precision float specifying the Julian day of time zero for the simulation. The data set times are an array of offset values from the reference time.

C/C++

int xfDatasetReftime(xid DatasetId, double Reftime);

FORTRAN

SUBROUTINE  XF_DATASET_REFTIME(DatasetId, Reftime, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsGroupId
REAL(DOUBLE), INTENT(IN)  :: Reftime
INTEGER, INTENT(OUT)      :: Error

Data sets are written as single precision floats by default. When data set values are appended the number of values must match the number of values previously written. The timesteps must be written in chronological order. Scalar value arrays are two-dimensional arrays of size NumValues. Vector value arrays are three-dimensional arrays of size NumValues X NumComponents (reversed for FORTRAN). For the C library, all arrays must be contiguous arrays of the correct size.

XMDF stores the minimum and maximum values for each timestep in the data set. The minimum and maximum values can be specified or they are determined automatically from the values arrays. For vector data sets the minimum and maximum values are the minimum and maximum values for vector magnitudes.

C/C++

int xfWriteScalarTimestep(xid DatasetId, double Time, int NumValues,
                          float *Values);
int xfWriteScalarTimestepMinMax(xid DatasetId, double Time, int NumValues,
                                    float *Values, float Min, float Max);
 
int xfWriteVectorTimestep(xid DatasetId, double Time, int NumValues,
                          int NumComponents, float *Values);
int xfWriteVectorTimestepMinMax(xid DatasetId, double Time, int NumValues, 
                                    int NumComponents, float *Values, float Min,
                                    float Max);

FORTRAN

SUBROUTINE  XF_WRITE_SCALAR_TIMESTEP(DatasetId, Time, NumValues, Values, Error)
INTEGER(XID), INTENT(IN)  :: DatasetId
REAL(DOUBLE), INTENT(IN)  :: Time
INTEGER, INTENT(IN)       :: NumValues
REAL, DIMESNION(NumValues), INTENT(IN)       :: Values
INTEGER, INTENT(OUT)      :: Error
 
SUBROUTINE  XF_WRITE_SCALAR_TS_MIN_MAX (DatasetId, Time, NumValues, Values,
                                           Min, Max, Error)
INTEGER(XID), INTENT(IN)  :: DatasetId
REAL(DOUBLE), INTENT(IN)  :: Time
INTEGER, INTENT(IN)       :: NumValues
REAL, DIMENSION(NumValues), INTENT(IN)       :: Values
REAL, INTENT(IN)          :: Min, Max
INTEGER, INTENT(OUT)      :: Error
 
SUBROUTINE  XF_WRITE_VECTOR_TIMESTEP(DatasetId, Time, NumValues, Values, Error)
INTEGER(XID), INTENT(IN)  :: DatasetId
REAL(DOUBLE), INTENT(IN)  :: Time
INTEGER, INTENT(IN)       :: NumValues
REAL, DIMESNION(NumComponents, NumValues), INTENT(IN)       :: Values
INTEGER, INTENT(OUT)      :: Error
 
SUBROUTINE  XF_WRITE_VECTOR_TS_MIN_MAX (DatasetId, Time, NumValues, Values, Min,Max, Error)
INTEGER(XID), INTENT(IN)  :: DatasetId
REAL(DOUBLE), INTENT(IN)  :: Time
INTEGER, INTENT(IN)       :: NumValues
REAL, DIMENSION(NumComponents, NumValues), INTENT(IN)       :: Values
REAL, INTENT(IN)          :: Min, Max
INTEGER, INTENT(OUT)      :: Error

Activity Information

Activity/Inactive data set values can be specified in two ways. With the first method, a null value is defined for a data set. Any time a data set value is the null value any elements or cells containing the data value will be considered inactive for that time step. When null values are used, they must be set before writing the data set values or else the minimum and maximum values may be incorrect. A null value is set by writing a float property to the dataset group using the defined name PROP_NULL_VALUE. The second method to storing active/inactive data set locations is by using an activity array. For C, Activity arrays are two-dimensional arrays of unsigned characters of size number of times X the number of active values. For FORTRAN, the activity arrays are read/written using integers. The number of active values is based upon the number of cells or elements in the grid or mesh.

C/C++

int xfWriteActivityTimestep(xid DatasetId, int NumActiveVals, xbool *Active);

FORTRAN

SUBROUTINE  XF_WRITE_ACTIVITY_TIMESTEP(DatasetId, NumActiveVals, ActiveVals, Error)
INTEGER(XID), INTENT(IN)  :: DatasetId
INTEGER, INTENT(IN)       :: NumActiveVals
INTEGER, DIMENSION(NumActiveVals), INTENT(IN)   :: ActiveVals
INTEGER, INTENT(OUT)      :: Error

Datasets and Activity information can also be written in pieces which allows data from multiple arrays to be stored within a timestep

C/C++

int xfInitializeScalarTimestep(xid xScalarAId, double dTime,
                    int nValues, float minvalue, float maxvalue, 
                    int *timestepId);
int xfWriteScalarTimestepPortion(xid xScalarAId, int timestepId,
                    int numValuesToWrite, int startIndex, const float *a_values);
 
int xfInitializeVectorTimestep(xid a_Id, double dTime,
                   int nValues, int nComponents, float minvalue, float maxvalue, 
                   int *timestepId);
int xfWriteVectorTimestepPortion(xid a_Id, int timestepId,
                    int numValuesToWrite, int nComponentsToWrite,
                    int startIndex, int startComponent, const float *a_values);

int xfInitializeActivityTimestep (xid a_Id, int a_NumActive, int *a_timestepId);
int xfWriteActivityTimestepPortion(xid a_Id, int a_timestepId,
               int a_NumValuesToWrite, int a_startIndex,
               const unsigned char *a_activityValues);

FORTRAN

SUBROUTINE XF_INITIALIZE_SCALAR_TIMESTEP (a_Id, a_Time, a_NumValues, a_Minimum,&
                                          a_Maximum, a_timestepId, error)
INTEGER,              INTENT(IN)   :: a_Id
REAL*8,               INTENT(IN)   :: a_Time
INTEGER,              INTENT(IN)   :: a_NumValues
REAL*4,               INTENT(IN)   :: a_Minimum, a_Maximum
INTEGER,              INTENT(OUT)  :: a_timestepId
INTEGER,              INTENT(OUT)  :: error
 
SUBROUTINE XF_WRITE_SCALAR_TIMESTEP_PORTION (a_Id, a_timeStepId, &
                    a_NumValuesToWrite, a_startIndex, a_Values, error)

INTEGER,              INTENT(IN)   :: a_Id
INTEGER,              INTENT(IN)   :: a_timeStepId
INTEGER,              INTENT(IN)   :: a_NumValuesToWrite
INTEGER,              INTENT(IN)   :: a_startIndex
REAL*4, DIMENSION(*),   INTENT(IN)   :: a_Values
INTEGER,              INTENT(OUT)  :: error
 
SUBROUTINE XF_INITIALIZE_VECTOR_TIMESTEP(a_Id, a_Time, a_NumValues, a_NumComponents, &
                                         a_Minimum, a_Maximum, timeId, error)
INTEGER,                                        INTENT(IN)  :: a_Id
REAL*8,                                         INTENT(IN)  :: a_Time
INTEGER,                                        INTENT(IN)  :: a_NumValues, a_NumComponents
REAL*4,                                           INTENT(IN)  :: a_Minimum, a_Maximum
INTEGER,                                        INTENT(OUT) :: timeId
INTEGER,                                        INTENT(OUT) :: error

SUBROUTINE XF_WRITE_VECTOR_TIMESTEP_PORTION(a_Id, a_TimeId, a_NumValuesToWrite, &
              a_NumComponentsToWrite, a_startIndex, a_startComponent, a_Values, error)
INTEGER,                                        INTENT(IN)  :: a_Id
INTEGER,                                         INTENT(IN)  :: a_TimeId
INTEGER,                                        INTENT(IN)  :: a_NumValuesToWrite, a_NumComponentsToWrite
INTEGER,                                        INTENT(IN)  :: a_startIndex, a_startComponent
REAL*4, DIMENSION(*),  INTENT(IN)                           :: a_Values
INTEGER,                                        INTENT(OUT) :: error

SUBROUTINE XF_INITIALIZE_ACTIVITY_TIMESTEP (a_Id, a_NumActive, a_timestepId, error)
INTEGER,              INTENT(IN)   :: a_Id
INTEGER,              INTENT(IN)   :: a_NumActive
INTEGER,              INTENT(OUT)  :: a_timestepId
INTEGER,              INTENT(OUT)  :: error

SUBROUTINE XF_WRITE_ACTIVITY_TIMESTEP_PORTION (a_Id, a_timeStepId, &
                    a_NumValuesToWrite, a_startIndex, a_ActiveValues, error)
INTEGER,              INTENT(IN)   :: a_Id
INTEGER,              INTENT(IN)   :: a_timeStepId
INTEGER,              INTENT(IN)   :: a_NumValuesToWrite
INTEGER,              INTENT(IN)   :: a_startIndex
INTEGER*1, dimension(*), INTENT(IN)  :: a_ActiveValues
INTEGER,              INTENT(OUT)  :: error

Truncate Time Steps

The function xfSetDatasetNumTimes is used to truncate time steps to the specified NumTimes. Once called, xfWriteActivityTimestep must either never be called or must always be called once after each time step write, writes such as xfWriteScalarTimestep, xfWriteScalarTimestepMinMax, xfWriteVectorTimestep, xfWriteVectorTimestepMinMax.

C/C++

int xfSetDatasetNumTimes(xid DatasetId, int NumTimes);

FORTRAN

SUBROUTINE XF_SET_DATASET_NUM_TIMES(DatasetsId, NumTimes, Error)INTEGER(XID), INTEGER(XID), INTENT(IN) :: DatasetsId
INTEGER), INTENT(IN) :: NumTimes
INTEGER, INTENT(OUT) :: Error

Reading Data sets

To read data sets from an XMDF file, you need to first open the data set group and get a group id. If the file only contains data sets, this group id is the file id. The following function is used to get the data set group id from a mesh or grid. The variable EntityId is the group id for the mesh or grid.

C/C++

int xfGetDatasetGroupId(xid EntityId, xid *DatasetsGroupId);

FORTRAN

SUBROUTINE  XF_GET_DATASET_GROUP_ID(EntityId, DatasetsGroupId, Error)
INTEGER(XID), INTENT(IN)  :: EntityId
INTEGER(XID), INTENT(OUT) :: DatasetsGroupId
INTEGER, INTENT(OUT)      :: Error

The following function is called to get the number of scalar data sets and the maximum path length for scalar data sets inside a "data sets" folder. This information is necessary to allocate the arrays necessary to retrieve the scalar data set paths.

C/C++

int xfGetScalarDatasetsInfo(xid DatasetsId, int *Number,
                            int *MaxPathLength);

FORTRAN

SUBROUTINE  XF_GET_SCALAR_DATASETS_INFO(DatasetsId, Number, MaxPathLength, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(OUT)      :: Number, MaxPathLength
INTEGER, INTENT(OUT)      :: Error

The next function is used to get the paths to all scalar data sets inside a folder of data sets. These paths are the subsequent group paths to get to a data set divided by forward slashes �\�. Paths must be allocated to a size of NumDataSets X MaximumPathLength as obtained from GetScalarDatasetsInfo.

C/C++

int xfGetScalarDatasetPaths(xid DatasetsId, NumDatasets, MaxPathLength, 
                            char *Paths);

FORTRAN

SUBROUTINE  XF_GET_SCALAR_DATASET_PATHS(DatasetsId, NumDatasets, MaxPathLength, 
                                   Paths, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)       :: NumDatasets, MaxPathLength
CHARACTER(len=MaxPathLength), DIMENSION(NumDatasets) :: Paths
INTEGER, INTENT(OUT)      :: Error

The following functions are used to obtain paths to vector data sets and work just like their scalar data set counterparts.

C/C++

int xfGetVectorDatasetsInfo(xid DatasetsId, int *Number,
                            int *MaxPathLength);
int xfGetVectorDatasetPaths(xid DatasetsId, int NumDatasets, int MaxPathLength,
                            char *Paths);

FORTRAN

SUBROUTINE  XF_GET_VECTOR_DATASETS_INFO(DatasetsId, Number, MaxPathLength, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(OUT)      :: Number, MaxPathLength
INTEGER, INTENT(OUT)      :: Error
 
SUBROUTINE  XF_GET_VECTOR_DATASET_PATHS(DatasetsId, NumDatasets, MaxPathLength, 
                                   Paths, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)       :: NumDatasets, MaxPathLength
CHARACTER(len=MaxPathLength), DIMENSION(NumDatasets) :: Paths
INTEGER, INTENT(OUT)      :: Error

The variable Units must be a string of length at least 100.

C/C++

int xfGetDatasetUnits(xid DatasetId, char *Units);

FORTRAN

SUBROUTINE  XF_GET_DATASET_UNITS(DatasetsId, Units, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
CHARACTER(len=100), INTENT(OUT) :: Units
INTEGER, INTENT(OUT)      :: Error

The following functions are used to read time values.

C/C++

int xfGetDatasetReftime(xid DatasetId, double *Reftime);
int xfGetDatasetNumTimes(xid DatasetId, int *NumTimes);
int xfGetDatasetTimeUnits(xid DatasetId, UnitType *Units);

FORTRAN

SUBROUTINE  XF_GET_DATASET_REFTIME(DatasetsId, Reftime, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
REAL(DOUBLE), INTENT(OUT) :: Reftime
INTEGER, INTENT(OUT)      :: Error
 
SUBROUTINE  XF_GET_DATASET_NUMTIMES(DatasetsId, NumTimes, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER), INTENT(OUT)     :: NumTimes
INTEGER, INTENT(OUT)      :: Error
 
SUBROUTINE  XF_GET_DATASET_REFTIME(DatasetsId, Units, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
CHARACTER(len=100), INTENT(OUT) :: Units
INTEGER, INTENT(OUT)      :: Error

This function is used to retrieve the time offsets for every time step in the data set. The variable Times must already be allocated to the number of time steps.

C/C++

int xfReadDatasetTimes(xid DatasetId, int NumTimes, double *Times);

FORTRAN

SUBROUTINE  XF_READ_DATASET_TIMES(DatasetsId, NumTimes, Times, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)       :: NumTimes
REAL(DOUBLE), DIMENSION(NumTimes), INTENT(OUT) :: Times
INTEGER, INTENT(OUT)      :: Error

Minimum and maximum values at each time are written out automatically when a data set is stored. This information is used for to develop contour intervals in visualization packages. The following functions are used to retrieve the minimum and maximum values for the time steps. The arrays must already be allocated to the number of time steps.

C/C++

int xfGetDatasetMins(xid DatasetId, int  a_NumTimes, float *Mins);
int xfGetDatasetMaxs(xid DatasetId, int  a_NumTimes, float *Maxs);

FORTRAN

SUBROUTINE  XF_GET_DATASET_MINS(DatasetsId, NumTimes, Mins, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)       :: NumTimes
REAL(DOUBLE), DIMENSION(NumTimes), INTENT(OUT) :: Mins
INTEGER, INTENT(OUT)      :: Error
 
SUBROUTINE  XF_GET_DATASET_MINS(DatasetsId, NumTimes, Maxs, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)       :: NumTimes
REAL(DOUBLE), DIMENSION(NumTimes), INTENT(OUT) :: Maxs
INTEGER, INTENT(OUT)      :: Error
The following function is used to determine the number of values in each time step of a data set.

C/C++

int xfGetDatasetNumVals(xid DatasetId, int *NumVals);

FORTRAN

SUBROUTINE  XF_GET_DATASET_NUM_VALS(DatasetsId, NumVals, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(OUT)      :: NumVals
INTEGER, INTENT(OUT)      :: Error

The number of values in an activity array is not necessarily the same as the number of values in a data set. This function is used to determine the number of values in the activity array.

C/C++

int xfGetDatasetNumActive(xid DatasetId, int *NumActiveVals);

FORTRAN

SUBROUTINE  XF_GET_DATASET_NUM_ACTIVE_VALS(DatasetsId, NumActiveVals, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(OUT)      :: NumActiveVals
INTEGER, INTENT(OUT)      :: Error

The following function is used to retrieve the activity status for the data set. The variable Active must already be allocated to hold the number of active values.

C/C++

int xfReadActivityTimestep(xid DatasetId, int Timestep, int NumActive, 
                           xbool *Active);

FORTRAN

SUBROUTINE  XF_READ_ACTIVITY_TIMESTEP(DatasetsId, Timestep, NumActive, Active, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)      :: Timestep, NumActive
INTEGER, DIMENSION(NumActive), INTENT(OUT) :: Active
INTEGER, INTENT(OUT)      :: Error

The next two functions are used to retrieve values for a particular time step. The values arrays must be allocated at least as big as the variable NumVals.

C/C++

int xfReadScalarValuesTimestep(xid DatasetId, int Timestep, int NumVals,
                               float *Values);
int xfReadVectorValuesTimestep(xid DatasetId, int Timestep, int NumVals,
                               int NumComponents, float *Values);

FORTRAN

SUBROUTINE  XF_READ_SCALAR_VALUES_TIMESTEP(DatasetsId, Timestep, NumVals, Vals, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)      :: Timestep, NumVals
REAL, DIMENSION(NumVals), INTENT(OUT) :: Vals
INTEGER, INTENT(OUT)      :: Error
 
SUBROUTINE  XF_READ_VECTOR_VALUES_TIMESTEP(DatasetsId, Timestep, NumVals, NumComponents,
                                      Vals, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)      :: Timestep, NumVals, NumComponents
REAL, DIMENSION(NumVals), INTENT(OUT) :: Vals
INTEGER, INTENT(OUT)      :: Error

The next function is used to retrieve values for a data set index for one or more timesteps. The array Values must be a one-dimensional array of size at least NumTimesteps.

C/C++

int xfReadScalarValuesAtIndex(xid DatasetId, int Index, int FirstTimestep,
                              int NumTimesteps, float *Values);
int xfReadVectorValuesAtIndex(xid DatasetId, int Index, int FirstTimestep,
                              int NumTimesteps, int NumComponents, float *Values);

FORTRAN

SUBROUTINE  XF_READ_SCALAR_VALUES_AT_INDEX(DatasetsId, Index, FirstTimestep,
                                     NumTimesteps, Values, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)      :: Index, FirstTimestep, NumTimesteps
REAL, DIMENSION(NumTimesteps), INTENT(OUT) :: Values
INTEGER, INTENT(OUT)      :: Error
 
SUBROUTINE  XF_READ_VECTOR_VALUES_AT_INDEX(DatasetsId, Index, FirstTimestep,
                                     NumTimesteps, NumComponents, Values, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)      :: Index, FirstTimestep, NumTimesteps
REAL, DIMENSION(NumTimesteps, NumComponents), INTENT(OUT) :: Values
INTEGER, INTENT(OUT)      :: Error

One can also retrieve activity values at specific locations just like data set values. These functions work just like their data set value counterparts. Remember that activity indices are based upon elements and cells and may not be the same as the locations where the data set values exist.

C/C++

int xfReadActivityValuesAtIndex(xid DatasetId, int Index, int FirstTimestep,
                                int NumTimesteps, xbool *Activity);

FORTRAN

SUBROUTINE  XF_READ_ACTIVE_VALS_AT_INDEX (DatasetsId, Index, FirstTimestep,
                                     NumTimesteps, Activity, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER, INTENT(IN)      :: Index, FirstTimestep, NumTimesteps
INTEGER, DIMENSION(NumTimesteps), INTENT(OUT) :: Activity
INTEGER, INTENT(OUT)      :: Error

Timesteps can be deleted from the end of the existing dataset before continuing to add timesteps. Once timesteps have been deleted, care must be taken with writing the activity values for timesteps in the dataset.

The xfSetDatasetNumTimes function can be called after some number of timesteps have been written, i.e. after writing with any of the following xfWrite functions: xfWriteScalarTimestep, xfWriteScalarTimestepMinMax, xfWriteVectorTimestep, xfWriteVectorTimestepMinMax. For example, the xfSetDatasetNumTimes function, when called with an argument of 3, will delete all but the first 3 timesteps. Subsequent calls to the other xfWrite functions will append timesteps from the point of deletion.

If xfWriteActivityTimestep is to be called, then it must be called each time any of the other xfWrite functions are called. Failing to do this will cause the activity data to get out of sync with the rest of the timestep data.

C/C++

int xfSetDatasetNumTimes(xid DatasetId, int NumTimes);

FORTRAN

SUBROUTINE  XF_SET_DATASET_NUMTIMES(DatasetsId, NumTimes, Error)
INTEGER(XID), INTENT(IN)  :: DatasetsId
INTEGER), INTENT(IN)     :: NumTimes
INTEGER, INTENT(OUT)      :: Error

Changing Scalar Values

Scalar Values in datasets with floating point values can be changed by using the function xfChangeScalarValuesTimestepFloat

C/C++

int xfChangeScalarValuesTimestepFloat(xid a_Id, int a_TimestepIndex, 
               int a_NumValsToEdit, int *a_Indices, float *a_NewValues)

4.12.1. API Functions [4.12. Data Sets]

4.12.1. API Functions
[4.12. Data Sets]