4.7.2. API Functions for Properties

Each of the functions returns a negative value if failure and a positive value for success. The following functions will retrieve the entire array of values for a property specified by its name. The id must be the id for the property group. The method to get the property group id will be given later.

Writing

The functions below are used to write properties. Property arrays are always one-dimensional arrays but can be any size. The size should be appropriate for the type of data stored. For example, if the property array stores the material property for a dataset of elements, the size of the property array should be the same as the number of elements.

C/C++

int xfWritePropertyInt(xid GroupId, const char *Name, int Num, int *Property, 
                       int Compression);
int xfWritePropertyFloat(xid GroupId, const char *Name, int Num, float *Property,
                         int Compression);
int xfWritePropertyDouble(xid GroupId, const char *Name, int Num, double *Property,
                          int Compression);
int xfWritePropertyString(xid GroupId, const char *Name, int Num, char **Property,
                          int StringLength, int Compression);

FORTRAN

SUBROUTINE  XF_WRITE_PROPERTY_INT(GroupId, Name, Num, Property, Compression, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
INTEGER, INTENT(IN)      :: Num
INTEGER, INTENT(IN)      :: Property(*)
INTEGER, INTENT(IN)      :: Compression
INTEGER, INTENT(OUT)     :: Error
 
 
SUBROUTINE  XF_WRITE_PROPERTY_FLOAT(GroupId, Name, Num, Property, Compression, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
INTEGER, INTENT(IN)      :: Num
REAL, INTENT(IN)      :: Property(*)
INTEGER, INTENT(IN)      :: Compression
INTEGER, INTENT(OUT)     :: Error
 
 
SUBROUTINE  XF_WRITE_PROPERTY_DOUBLE(GroupId, Name, Num, Property, Compression, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
INTEGER, INTENT(IN)      :: Num
REAL(DOUBLE), INTENT(IN) :: Property(*)
INTEGER, INTENT(IN)      :: Compression
INTEGER, INTENT(OUT)     :: Error
 
SUBROUTINE  XF_WRITE_PROPERTY_STRING(GroupId, Name, Num, Property, Compression, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
INTEGER, INTENT(IN)      :: Num
CHARACTER(len =*), INTENT(IN)    :: Property(*,*)
INTEGER, INTENT(IN)      :: Compression
INTEGER, INTENT(OUT)     :: Error

Reading

The following functions are used to determine what property names are used in the group or to see if a property exists. The names of all properties are limited to 256 characters.

C/C++

int xfDoesPropertyWithNameExist(xid GroupId, const char *Name, int *Exists);
int xfGetPropertyNumber(xid GroupId, const char *Name, int *Num);
// Names must be a 2D array size NumberOfProperties by 256 (max should be 256)
int xfGetPropertyNames(xid GroupId, char **Names); ???

FORTRAN

SUBROUTINE  XF_DOES_PROP_W_NAME_EXIST (GroupId, Name, Exists, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
LOGICAL, INTENT(OUT)     :: Exists
INTEGER, INTENT(OUT)     :: Error
 
SUBROUTINE  XF_GET_PROPERTY_NUMBER (GroupId, Number, Error);
INTEGER(XID), INTENT(IN) :: GroupId
INTEGER, INTENT(OUT)     :: Number, Error
 
SUBROUTINE  XF_GET_PROPERTY_NAMES(GroupId, Number, Names, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(OUT)  :: Names(*, Number)
INTEGER, INTENT(OUT)   ::    Error

There may be times when the type of a property is unknown. The following function allows the user to get the type of data that is stored in a property. The function sets the integer ‘type’. The types, associated constants, and associated numbers are given in Table 3.

Table 3 Possible property types and the number associated with them.

1 XF_TYPE_INT

integer

2 XF_TYPE_FLOAT

single precision float (4 bytes)

3 XF_TYPE_DOUBLE

double precision float (8 bytes)

4 XF_TYPE_STRING

string

11 XF_TYPE_OTHER

other - not used directly using XMDF. Have to use HDF5 calls to work with data

C/C++

int xfGetPropertyType(xid GroupId, const char *Name, int *Type);

FORTRAN

SUBROUTINE  XF_GET_PROPERTY_TYPE(GroupId, Name, Type, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
INTEGER, INTENT(OUT)     :: Type, Error

If the property type is a string, we need to know the maximum string length used in the array. The following function gets the maximum length for a string data set.

C/C++

int xfGetPropertyStringLength(xid GroupId, const char *Name, int *MaxLength);

FORTRAN

SUBROUTINE  XF_GET_PROPERTY_STRING_LENGTH(GroupId, Name, MaxLength, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
INTEGER, INTENT(OUT)     :: MaxLength, Error

All of the functions to retrieve properties must already be allocated to the correct size. The correct size can be determined using the xfGetPropertyNumber function.

C/C++

// get the number of items in the attribute
int xfGetPropertyNumber (xid GroupId, const char *Name, int *Size);
 
int xfReadPropertyInt(xid GroupId, const char *Name, int *Property);
int xfReadPropertyFloat(xid GroupId, const char *Name, float *Property);
int xfReadPropertyDouble(xid GroupId, const char *Name, double *Property);
int xfReadPropertyString(xid GroupId, const char *Name, char **Property,
                        int StringLength);

The following function reads property strings with the property ID and allocates the required memory. Calling the function below is easier than calling xfReadPropertyString above, which requires the number and maximum length of the properties and also requires you to allocate memory. a_Properties does not need to be allocated before calling this function. If the function is successful, the memory stored in a_Properties must be free'd after this function is called.

int xfAllocateReadPropertyString (xid a_Id, const char *a_Name,
                                  int *a_Number, int *a_MaxLength,
                                  char **a_Properties);

FORTRAN

SUBROUTINE  XF_GET_PROPERTY_NUMBER(GroupId, Name, Size, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
INTEGER, INTENT(OUT)     :: Size, Error
 
SUBROUTINE  XF_READ_PROPERTY_INT(GroupId, Name, Property, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
INTEGER, INTENT(OUT)     :: Property(*), Error
 
SUBROUTINE  XF_READ_PROPERTY_FLOAT(GroupId, Name, Property, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
REAL, INTENT(OUT)     :: Property(*)
INTEGER, INTENT(OUT)     :: Error
 
SUBROUTINE  XF_READ_PROPERTY_DOUBLE(GroupId, Name, Property, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
REAL(DOUBLE), INTENT(OUT)     :: Property(*)
INTEGER, INTENT(OUT)     :: Error
 
SUBROUTINE  XF_READ_PROPERTY_INT(GroupId, Name, Property, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
LOGICAL, INTENT(OUT)     :: Property(*)
INTEGER, INTENT(OUT)     :: Error
 
SUBROUTINE  XF_READ_PROPERTY_STRING(GroupId, Name, Property, Error);
INTEGER(XID), INTENT(IN) :: GroupId
CHARACTER(len=*), INTENT(IN) :: Name
CHARACTER(len=*), INTENT(OUT)     :: Property(*, *)
INTEGER, INTENT(OUT)     :: Error