Read a non-sharable attribute

saf_get_attribute is a function defined in utils.c.

Synopsis:

int saf_get_attribute(SAF_ParMode pmode, ss_pers_t *obj, const char *name, hid_t *type, int *count, void **value)

Formal Arguments:

  • pmode: One of the parallel modes.
  • obj: The handle to the object from which the attribute will be read.
  • name: The name of the attribute. See SAF__ATT_NAMES and other reserved attribute names for special kinds of attribute queries.
  • type: IN``[``OUT] If type is NULL, this argument will be ignored. If type points to a valid datatype, then the attribute will be converted to the specified type as it is read. If it does not, there will be no data conversion and the output value will be the datatype of the data returned (the caller should invoke H5Tclose).
  • count: [OUT] The number of items in the attribute. If count is NULL, then the value of count will not be returned.
  • value: IN``[``OUT] Points to an array of count values each having datatype type. If value is NULL, then no attribute values will be returned. If value points to NULL, then the library will allocate the array of values which is returned. Otherwise the library assumes that value points to an array whose size is sufficient for storing count values of datatype type. That is, if value is pointing to non-NULL, then so must count point to non-NULL and the value pointed to by count will be used by SAF as the size, in items of type type, of the block of memory pointed to by value. For a SAF__ATT_NAMES query if the caller supplies a buffer for this argument then it should be a buffer of char pointers, the values of which will be allocated by this function.

Description: This function provides a method by which existing, generic, non-sharable attributes may be read from an object. Attributes are pieces of meta data which fall outside the scope of the sharable data model (i.e., things which are not fields) but which are often useful for conveying additional information. The meaning of a particular attribute is determined by convention, requiring additional communication between the writer and the reader (often in the form of documentation or word of mouth).

Preconditions:

  • pmode must be valid. (low-cost)
  • name must not be null. (low-cost)
  • count and value must be compatible for return value allocation. (low-cost)
  • obj must not be null. (low-cost)

Return Value: The constant SAF__SUCCESS is returned when this function is successful. Otherwise this function either returns an error number or throws an exception, depending on the value of the library’s error handling property.

Parallel Notes: Depends on pmode

Issues: On error, the argument return values are undefined.

If the attribute name is SAF__ATT_NAMES then the client must not preallocate space for the value return value, but must allow the library to handle the allocation. That is, if the arg passed for name is SAF__ATT_NAMES, the client must not pass value such that it points to a non-null pointer.

The reserved attribute name queries, SAF__ATT_FIRST and SAF__ATT_NEXT, are not yet implemented.

This is a weird interface. There should be a separate function to obtain the datatype and count of an attribute so that this function doesn’t need to return those values. The type and count arguments should instead specify what value is returned by this function. And the value should be just an optional `void*’ buffer which if not supplied is allocated and which is the successful return value of this function. [rpm 2004-08-25]

If the pool allocation is being used then we’ll have a problem if there are more attributes than what the string pool can store.

See Also: