gtpc2mepC/C++ Language Support User's Guide

TO2_restoreWithOptions-Restore a Collection Using the Specified Options

This function restores the specified collection to the database using the specified options and assigns a persistent identifier (PID) to the collection. If the collection also has assigned properties, the properties will also be restored as part of TO2_restoreWithOptions request.

Format

#include <c$to2.h>
TO2_BUF_PTR TO2_restoreWithOptions (const TO2_PID_PTR     pid_ptr,
                                          TO2_ENV_PTR     env_ptr,
                                          TO2_PID_PTR     newPidPtr,
                                    const TO2_OPTION_PTR  optionListPtr,
                                    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.

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

data
The positioning data from a 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, TO2_restoreWithOptions 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, 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_ENV

TO2_ERROR_DATA_LGH

TO2_ERROR_DD_NOT_FOUND

TO2_ERROR_NO_XTERNAL_DEFINED

TO2_ERROR_NO_XTERNAL_DEVICES

TO2_ERROR_NO_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 the 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          */
u_char         ddname[] =  "NAME_OF_USER_DD_DEFINITION   ";
char          *positionData;                                                 */
long           positionDataLength;                                           */
TO2_OPTION_PTR optionListPtr;
long           timeOut = 5*60;        /* time out mount in 5 minutes         */
 

  ·
  ·
  ·
/* invoke TO2 to create opt list */ optionListPtr=TO2_createOptionList(env_ptr, TO2_OPTION_LIST_CREATE, /* create options */ TO2_CREATE_SHADOW, /* use shadowing */ TO2_CREATE_DD, /* use provided ddname*/ TO2_OPTION_LIST_END, /* end of options */ ddname); /* address of ddname */ if (optionListPtr == TO2_ERROR) { process_error(env_ptr); return; } buffer_ptr=TO2_restoreWithOptions (&collect, env_ptr, &newpid, optionListPtr, positionData, &positionDataLength, &timeOut); { printf("TO2_restoreWithOptions failed!\n"); process_error(env_ptr); } else printf("TO2_restoreWithOptions successful!\n");

Related Information