DATASERV (kappserv) functions


LIBRARY ROUTINE

kpds_copy_location_data - copy all location data from one object to another object.

LIBRARY CALL

int kpds_copy_location_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 location segment of one object into the location segment contained in another object. If the location segment exists in the destination object, then its data will be replaced with the data from the source object. If the location segment does not exist in the destination object, it will be created.

The location 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 : axis assignment, position, and offset. The resulting copy will be transposed to be in the default axis ordering. The resulting copy will also appear to be shifted by the source position and offset.

The resulting copy will contain data in the most explicit grid type between the source and the destination.

For example, if the destination grid type is curvilinear, and the source grid type is uniform, the resulting copy will contain curvilinear data. However, if the destination grid type is uniform, and the source grid type is curvilinear, then the destination must be curvilinear. In general, the copy can not contain less data than is contained in the source.

If the destination grid type is not set, then the copy will preserve the source grid type.

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 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.

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

In the above example, the data resulting from the copy will be interpolated to a new size and cast to a new data type. 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 location segment will be reflected in the destination data object from the source to the destination since they describe the physical state of the data. The grid type of the destination will always match the grid type of the source in this case.

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

none

FILES

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

SEE ALSO

kappserv(3)

COPYRIGHT

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