gtpc2menC/C++ Language Support User's Guide

TO2_restore-Restore a Previously Captured Collection

This function restores the specified collection to the database using its previously assigned data definition (DD) values and assigns a new persistent identifier (PID) to the collection. If the collection also has assigned properties, the properties will also be restored as part of the TO2_restore request.

Format

#include <c$to2.h>
TO2_BUF_PTR TO2_restore (const TO2_PID_PTR  pid_ptr,
                               TO2_ENV_PTR  env_ptr,
                               TO2_PID_PTR  newPidPtr,
                         const void        *data,
                         const long        *dataLength,
                         const long        *mountTimeOut);

pid_ptr
The pointer to the PID of the captured collection.

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

newPidPtr
The pointer to the location where the PID assigned to the restored collection will be returned.

data
The positioning data from the TO2_capture function call.

dataLength
The pointer to an area that contains the length of the positioning data.

mountTimeOut
The pointer to an area that contains the number of seconds to wait for the mount of the external device.

Normal Return

For a normal return, the TO2_restore function will return a buffer item that contains the user data written as part of the TO2_capture request. The normal return is a pointer (TO2_BUF_PTR) to a structure (buffer) of type TO2_BUF_HDR (see Type Definitions).

Error Return

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

The following error codes are common for this function:

TO2_ERROR_ENV

TO2_ERROR_DATA_LGH

TO2_ERROR_NO_XTERNAL_DEFINED

TO2_ERROR_NO_XTERNAL_DEVICES

TO2_ERROR_PERMANENT_XTERNAL

TO2_ERROR_TAPE_FORMAT

TO2_ERROR_TIMEOUT

TO2xd_ERROR_tapeBlocked

Programming Considerations

Examples

The following example restores a persistent collection.

#include <c$to2.h>                    /* Needed for TO2 API functions    */
#include <stdio.h>                    /* APIs for standard I/O functions */
TO2_BUF_PTR    buffer_ptr;            /* Pointer to buffer               */
TO2_ENV_PTR    env_ptr;               /* Pointer to the TO2 environment  */
TO2_PID        collect;               /* will hold collection's PID      */
TO2_PID        newpid;                /* will hold collection's PID      */
char          *positionData;                                             */
long           positionDataLength;                                       */
long           timeOut = 5*60;        /* time out mount in 5 minutes     */
 

  ·
  ·
  ·
buffer_ptr=TO2_restore (&collect, env_ptr, &newpid, positionData, &positionDataLength; &timeOut); { printf("TO2_restore failed!\n"); process_error(env_ptr); } else printf("TO2_restore successful!\n");

Related Information