gtpc2mcbC/C++ Language Support User's Guide

TO2_copyCollectionWithOptions-Make a Copy Using Options

This function creates a copy of the specified collection using the specified data definition and returns its persistent identifier (PID) as a parameter. This function does not copy the properties of the source collection.

Format

#include <c$to2.h>
long TO2_copyCollectionWithOptions (const TO2_PID_PTR     sourceCollect,
                                          TO2_ENV_PTR     env_ptr,
                                          TO2_PID_PTR     copyCollect,
                                    const TO2_OPTION_PTR  optionListPtr);

sourceCollect
The pointer to the PID assigned to the collection that will be copied.

env_ptr
The pointer to the environment as returned by the TO2_createEnv function.

copyCollect
The pointer to where the PID for the copy of the collection will be stored.

optionListPtr
The pointer to a returned options list from a TO2_createOptionList function call or NULL if no options are required.

Normal Return

The normal return is a positive value.

Error Return

An error return is indicated by a zero. When zero is returned, use the TO2_getErrorCode function to determine the specific error code. For more information, see Error Handling.

The following error codes are common for this function:

TO2_ERROR_DDNAME

TO2_ERROR_ENV

TO2_ERROR_METHOD

TO2_ERROR_NOT_INIT

TO2_ERROR_PID

TO2_ERROR_ZERO_PID

Programming Considerations

Examples

The following example creates a persistent copy of an existing collection using a specified data definition.

#include <c$to2.h>                /* Needed for TO2 API functions   */
 
TO2_ENV_PTR    env_ptr;           /* Pointer to the TO2 environment */
TO2_PID        sourceCollect;     /* must create collection and save
                                     its PID here before copy...    */
TO2_PID        copyCollect;       /* will obtain PID for copied
                                       collection below...          */
TO2_OPTION_PTR optionListPtr;
u_char  dd_name[] = "NAME_OF_USER_DD_DEFINITION      ";

  ·
  ·
  ·
optionListPtr=TO2_createOptionList(env_ptr, TO2_OPTION_LIST_CREATE, /* create options */ TO2_CREATE_DD, /* use provided dd name*/ TO2_OPTION_LIST_END, /* end of options */ dd_name); /* address of ddname */ if (TO2_copyCollectionWithOptions(&sourceCollect, env_ptr, &copyCollect, optionListPtr) == TO2_ERROR) { printf("TO2_copyCollectionWithOptions failed!\n"); process_error(env_ptr); } else { printf("TO2_copyCollectionWithOptions successful!\n"); }

Related Information