kaddr
kpds_get_data(
kobject object,
char *primitive,
kaddr data)
none
The first argument is the data object that will be accessed in order to retrieve the data.
The second argument is the data primitive that is desired. Data services understands a number of primitives that allow access to different parts of a data set. Except for the vector primitives (KPDS_VALUE_VECTOR, KPDS_MAP_VECTOR, KPDS_TIME_VECTOR, KPDS_LOCATION_VECTOR), the interpretation of all of these primitives depends on the attribute index order primitives (KPDS_VALUE_INDEX_ORDER, KPDS_MAP_INDEX_ORDER, etc). The index order attributes determine how data is retrieved and stored. Successive calls to kpds_get_data cause an automatic increment of the position of each part of the data set. How the position is incremented depends on the primitive that is being retrieved and the index order. For example, if a KPDS_VALUE_LINE is being retrieved, and the index order is KWIDTH, KHEIGHT, KDEPTH, ..., then the line will be defined in the width direction and successive lines can be indexed by incrementing the height dimension until it wraps around, then incrementing the depth dimension, and so on. Below is a list of the types of primitives that are available:
point specifies that a single value will be returned. Successive calls to kpds_get_data will result in adjacent points being returned, as described above. An example of a point primitive is the KPDS_VALUE_POINT primitive.
line specifies that a one-dimensional unit of data will be returned. The direction in which a line is defined is given by the first (or lowest order) value of the index order. In the above example, KWIDTH was the first value in the index order attribute. An example of a line primitive is the KPDS_VALUE_LINE primitive.
plane specifies that a two-dimensional unit of data will be returned. The plane is defined along the two lowest order dimensions in the index order for the segment specified. An example of a plane primitive is the KPDS_VALUE_PLANE primitive.
volume specifies that a three-dimensional unit of data will be returned. The volume is defined along the three lowest order dimensions in the index order for the segment specified. An example of a volume primitive is the KPDS_VALUE_VOLUME primitive.
region specifies that a n-dimensional unit of data will be returned. The n varies from segment to segment and is based on the dimensionality of the segment being accessed. For example, Data Services considers the Value segment to be a five-dimensional segment, so n is five for the value segment. A region front, upper corner is specified by the current position (for the Value segment, this is a five-tuple). The size of the region is given by the attribute KPDS_REGION_SIZE, which must be set prior to using this primitive. An example of a region primitive is the KPDS_VALUE_REGION primitive.
all specifies that all data for the specified segment should be retrieved and returned. An example of an all primitive is the KPDS_VALUE_ALL primitive.
vector specifies that a one-dimensional unit of data will be returned. The dimension in which this unit of data is defined is fixed for each segment. Thus, regardless of the index order, the same dimension will be used to obtain the vector of data. The only thing that is impacted by index order when retrieving vectors is the actual order in which the vectors in a data set are retrieved due to the auto-incrementing of position. An example of a vector primitive is the KPDS_VALUE_VECTOR primitive. For the five predefined part of a data set, each has a different dimension that specifies a vector. Below is a list of the data components and their associated vector definition:
.TS center; c c. Segment Vector Definition _ VALUE KELEMENTS MASK KELEMENTS MAP KWIDTH LOCATION KDIMENSION TIME KTIME .TE
The third argument, "data", serves as both an input and an output argument. As input, it dictates whether kpds_get_data must allocate space sufficient for the operation. If the argument is NULL, then memory will be allocated to store the data primitive requested. A pointer to that memory will be returned. If this argument is not NULL, then kpds_get_data assumes that the "data" argument is a pointer to a sufficient amount of memory with the correct dimensionality for the primitive (no memory allocation occurs). In this case, if this routine returns successfully, then the return value is the pointer "data".
none
none
$DATASERV/objects/library/kappserv/src/primitive.c