PK_GEOM_copy_o_t

struct PK_GEOM_copy_o_s
    {
    int                         o_t_version;        --- version number
    PK_ITEM_t                   destination;        --- destination for copies
                                                    --- (PK_ITEM_null)
    PK_GEOM_copy_t              copy_dependents;    --- which geometric
                                                    --- dependents to copy
                                                    --- (PK_GEOM_copy_always_c)
    PK_GEOM_copy_t              copy_attributes;    --- copy attributes
                                                    --- (PK_GEOM_copy_never_c)
    };
typedef struct PK_GEOM_copy_o_s PK_GEOM_copy_o_t;



This structure contains optional controls for PK_GEOM_copy

Used in:

PK_GEOM_copy

The option structure allows the caller to control the behaviour of the
copying operation.

destination:
------------
Specifies the destination for the copied geometry. It can take a partition,
PK_PARTITION_t, or a part, PK_PART_t, but no other PK_ITEM_t. Alternatively it
may be set to PK_ITEM_null.

If a partition is supplied through 'destination' then all copies will be
created as orphan geometry in the supplied partition.

If a part is supplied through 'destination' then all copies will be attached
to the supplied part as construction geometry.

If 'destination' is set to PK_ITEM_null then

    any copy of orphan geometry will be created as orphan geometry in its
    original's partition.

    any copy of construction and principal geometry will be attached as
    construction geometry in its original's part.


The behaviour is summarised in the following table:

-------------------------------------------------------------------------------
| Type of input |                       'destination'                         |
|   geometry    |    PK_ITEM_null     |    PK_PART_t    |    PK_PARTITION_t   |
-------------------------------------------------------------------------------
| Principal     |  Construction in    | Construction in | Orphan in supplied  |
| geometry      |  original part      | supplied part   | partition           |
-------------------------------------------------------------------------------
| Construction  |  Construction in    | Construction in | Orphan in supplied  |
| geometry      |  original part      | supplied part   | partition           |
-------------------------------------------------------------------------------
| Orphan        |  Orphan in original | Construction in | Orphan in supplied  |
| geometry      |  partition          | supplied part   | partition           |
-------------------------------------------------------------------------------


copy_dependents:
----------------
This option can be set to one of:

PK_GEOM_copy_always_c

All geometric dependents ( not limited to direct dependents only) of the input
geometries will be copied.

PK_GEOM_copy_auto_c

The geometric dependents of the input geometries will only be copied if
    a) the input geometry is placed in a different partition from that the
       copy of the geometry is destined for.
    b) the input geometry and its copy cannot share the dependent.
    c) the dependent is explicitly specified as an input geometry.

Note that the geometric dependencies between the input geometries will be
preserved amongst the copies of the geometries.


copy_attributes:
----------------
This option can be set to one of:

PK_GEOM_copy_always_c

All attributes belonging to the original geometries will be copied and attached
to the product geometries.

PK_GEOM_copy_never_c

None of the attributes belonging to the input geometries will be copied.


Exceptions:
-----------
Not all combinations of options are valid.

'copy_attributes' set to PK_GEOM_copy_always_c cannot be combined with a
partition supplied through  'destination' since orphan geometry cannot own
attributes.

'copy_dependent' cannot be set to PK_GEOM_copy_never_c.

'copy_attributes' cannot be set to PK_GEOM_copy_auto_c.

'destination' can not be given any other PK_ITEM_t than PK_PART_t and
PK_PARTITION_t.

Any of these choices will return PK_ERROR_contradictory_request.