DATASERV (kappserv) functions


LIBRARY ROUTINE

kpds_put_data - store a unit of data to a segment in a data object.

LIBRARY CALL

int
kpds_put_data(
   kobject object,
   char   *primitive,
   kaddr   data)

INPUT

OUTPUT

none

RETURN VALUE

TRUE on success, FALSE otherwise

DESCRIPTION

This function is used to store data in a data object.

The first argument is the data object that will be accessed in order to put the data.

The second argument is the data primitive that is to be written. 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 stored, 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 stored. Successive calls to kpds_put_data will result in adjacent points being stored, 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 fourth argument is the data to be written. This must be a non-NULL pointer to valid data of the appropriate size (as defined, for example, by the KPDS_VALUE_SIZE attribute) and data type (as defined, for example, by the KPDS_VALUE_DATA_TYPE attribute).

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

none

FILES

$DATASERV/objects/library/kappserv/src/primitive.c

SEE ALSO

kappserv(3)

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.