DATASERV (kappserv) functions


LIBRARY ROUTINE

kpds_copy_value_data - copy all value data from one object to another object.

LIBRARY CALL

int kpds_copy_value_data(
   kobject object1,
   kobject object2,
   int     copy_through_presentation)

INPUT

OUTPUT

RETURN VALUE

TRUE if copy was successful, FALSE otherwise

DESCRIPTION

This function copies all of the data contained in the value segment of one object into the value segment contained in another object. If the value segment exists in the destination object, then its data will be replaced with the data from the source object. If the value segment does not exist in the destination object, it will be created.

The value data can be optionally copied through the presentations of the two data objects. This implies that any presentation stages which are normally invoked during a kpds_get_data on the source object or a kpds_put_data call on the destination object will be used for the copy.

Any of the following presentation stages can be invoked on either the source object or the destination object : casting, scaling, normalizing, padding, and interpolating.

The following presentation stages can be invoked on only the source object : mapping, axis assignment, position, and offset. The resulting copy will be mapped through the map and transposed to be in the default axis ordering. The resulting copy will also appear to be shifted by the source position and offset.

These presentation stages are brought into the data pipeline by setting the appropriate presentation attributes on the data objects. Please see the chapter on polymorphic data services in the data services manual for more information on the various presentation attributes.

The following example may help in visualizing the process. The source object has mapping mode set to map the data, a presentation data type different from the physical data type, and a presentation size different from the physical size. The destination object only has a different presentation and physical data type.

              _______________________
             | _____________________ |
        _____||______  ---->        ||
       |___mapping___|              ||
        _____||______               ||
       |interpolating|              ||
        _____||______          _____||______
       |___casting___|        |___casting___|
         ____||_____            ____||_____
        |           |          |           |
        |  source   |        	 |destination|
        |   data    |        	 |   data    |
        |___________|        	 |___________|

In the above example, the data resulting from the copy will be interpolated to a new size, cast to a new data type, and mapped through the object's map before being copied into the destination object. When being copied into the destination object, the data will be cast yet again before it finally is stored.

If the presentation and physical layers of the destination object are coupled then the destination attributes will be ignored and the source presentation attributes will be propogated to the destination physical layer. The copy, in essence, will be performed only through the source presentation, with the destination physical and presentation layers taking on the characteristics of the source presentation. By default, output objects are not coupled, so this behavior is typical.

The copy need not be performed using the presentation. If the data is not copied through the presentation, the destination data will be a direct copy of the physical source data. The physical size and data type of the value segment will be reflected in the destination data object from the source to the destination since they describe the physical state of the data.

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

none

FILES

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

SEE ALSO

kappserv(3)

COPYRIGHT

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