gtpc2mc8C/C++ Language Support User's Guide

TO2_capture-Capture a Collection to an External Device

This function causes the specified collection to be written to an external device along with all associated data required to restore the collection to the database.

Format

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

pid_ptr
The pointer to the persistent identifier (PID) assigned to the collection that will be captured.

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

xternalToken
The token returned by the TPFxd_archiveStart function call.

data
The user data to write to the external device.

dataLength
The pointer to an area that contains the length of the user 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_capture function will return a buffer item that contains the required positioning information for a TO2_restore 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_DATA_LGH

TO2_ERROR_ENV

TO2_ERROR_EODAD

TO2_ERROR_METHOD

TO2_ERROR_NO_XTERNAL_DEFINED

TO2_ERROR_NO_XTERNAL_DEVICES

TO2_ERROR_NOT_INIT

TO2_ERROR_PERMANENT_XTERNAL

TO2_ERROR_PID

TO2_ERROR_TIMEOUT

TO2_ERROR_ZERO_PID

TO2xd_ERROR_tapeBlocked

Programming Considerations

Examples

The following example causes the specified collection to be written to an external device.

#include <c$to2.h>
#include <c$tpxd.h>
 
TO2_PID          capturePID;
TO2_ENV_PTR      env_ptr=NULL;
TO2_BUF_PTR      buffer_ptr;
TPFxd_extToken  *token_ptr;
char             data[80];
long             dataLength=sizeof(data);
long             return_code;
long             timeOut=5*60;   /* time out mount in 5 minutes */

  ·
  ·
  ·
/****************************************************************/ /* We need to activate the archiving external device support by */ /* obtaining a token. Upon a successful return, the token will */ /* be used on every TO2_capture call for this archive run. */ /****************************************************************/ if ((return_code = TPFxd_archiveStart(&token_ptr, WT, ASAVAILABLE)) != TPFxd_SUCCESS) { printf("TPFxd_archiveStart failed!\n"); process_TPFerror(); return(); } if ((buffer_ptr = TO2_capture(&capturePID, env_ptr, token_ptr, data, &dataLength, &timeOut)) == NULL); { printf("TO2_capture failed!\n"); process_error(); } else printf("TO2_capture successful!\n"); TPFxd_archiveEnd()

Related Information