gtpc2mc8 | C/C++ Language Support User's Guide |
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);
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