Read the data for a field

saf_read_field is a function defined in field.c.

Synopsis:

int saf_read_field(SAF_ParMode pmode, SAF_Field *field, SAF_FieldTarget *target, int member_count, SAF_RelRep *req_type, int *member_ids, void **Pbuf)

Formal Arguments:

  • pmode: The parallel mode.
  • field: The field which is to be read.
  • target: Field targeting information.
  • member_count: A count of the number of members of the collection in which the field’s dofs are n:1 associated with that are actually being written in this call. This value is ignored if you are reading the entire field’s dofs in this call (i.e., req_type = SAF__TOTALITY). Also note that as a convenience, we provide the macro SAF__WHOLE_FIELD which expands to a comma separated list of appropriate values for this argument and the next two, for the case in which the whole field is being read in this call.
  • req_type: The type of I/O request. We use a relation representation type here to specify the type of the partial request because it captures the necessary information. Pass SAF__HSLAB if you are reading the dofs of a partial hyperslab of the members of the associated collection. In this case, member_ids points to 3 N-tuples of starts, counts and strides of the hyperslab (hypersample) request. Pass SAF__TUPLES, if you are reading the dofs for an arbitrary list of members of the associated collection. In this case, the member_ids points to a list of N-tuples. In both cases, ‘N’ is the number of indexing dimensions in the associated collection. Finally, pass SAF__TOTALITY if you are reading the entire field’s set of dofs.
  • member_ids: Depending on the value of req_type, this argument points to 3 N-tuples storing, respectively, the starts, counts and strides in each dimension of the associated collection or to a list of member_count N-tuples, each one identifying a single member of the associated collection or to NULL in the case of a SAF__TOTALITY request.
  • Pbuf: [IN``|``OUT] A pointer to a buffer pointer which is to receive the values read. The caller may supply a pointer to a value of NULL if this function is to allocate a buffer. If the caller supplies a pointer to a non-NULL pointer (to a buffer) then it is up to the caller to ensure that the buffer is of sufficient size to hold all of the data retrieved. The caller should use saf_describe_field or saf_get_count_and_type_for_field to determine the datatype of the values read.

Description: This is function is used to read a field’s data. If the field is not an indirect reference to other fields, this call involves real disk I/O. All functions in SAF with either “read” or “write” in the name potentially involve real disk I/O.

This function allows a client to read either the entire field’s data or a portion of the field’s data. Recall that the degrees of freedom (dofs) of a field are n:1 associated with the members of some collection in the set upon which the field is defined. We call this collection the associated collection.

In order to specify a partial request, the client is required to specify which members of the associated collection it is reading the dofs for. Ultimately, those members may be specified using a N dimensional hyperslab (or hypersample) or an arbitrary list of N-tuples. In either case, the number of dimensions, ‘N’, is the number of indexing dimensions in the associated collection.

At present, there are several limitations. First, the collection must be 1 dimensionally indexed. Next, only the hyperslab mode or a single member in tuple-mode are supported; not hypersamples and not an arbitrary list. Also, if the field is a multi-component field, then the only supported interleave mode is SAF__INTERLEAVE_VECTOR.

Finally, we provide as a convenience the macro SAF__WHOLE_FIELD which expands to a comma separated list of values, 0, SAF__TOTALITY, NULL, for the three arguments member_count, req_type, member_ids for the case in which the client is reading the whole field in this call.

Preconditions:

  • pmode must be valid. (low-cost)
  • field must be a valid field handle. (low-cost)
  • Pbuf must be non-null. (low-cost)
  • If partial I/O request, associated collection must be 1D indexed, req_type must be SAF__HSLAB. (high-cost)
  • If field targeting of storage decomposition is used, the read must be a SAF__ALL mode read or the. (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.

Issues: A partial I/O request looks a lot like a subset relation. In fact, we even use the same data type, SAF__SRType, to identify the type of partial I/O request. It may be difficult for a client to distinguish between making a partial I/O request and making real subsets. In theory, there really should be no difference. The act of reading/writing a portion of a field is the act of defining a subset of the base space the field is defined on and then restricting the field to that subset. In the current implementation, this requires, at a minimum, the ability to create transient objects such as the subset representing the piece of the field being read/written in this call. In addition, it really requires decoupling the storage containers into which field’s data goes from declaring and reading/writing fields.

For an indirect field the the local fields are all “similar”. That is, they have the same algebraic type, association category, units and such. This function should check for this but doesn’t. In the future some differences can be smoothed-over (such as units) but some probably can not (such as algebraic type).

The proper use of pmode is not fully worked out.

Multiple indirection may actually fall out of this solution but that is not at all clear.

When remapping an indirect field we only look in the top-scope of the file containing the field’s base space when searching for the subset relations. [rpm 2004-05-24]

See Also: