gtpc2me3C/C++ Language Support User's Guide

TO2_getDRprotect -- Retrieve Dirty-Reader Protection Status

This function returns the dirty-reader protection status of the collection. Dirty-reader protection determines whether TPFCS will use the FILNC macro or the FILEC macro to file records. If dirty-reader protection is on (TO2_IS_TRUE), TPFCS will use the FILNC macro to file records. TPF transaction services maintains a copy of each record filed using a FILNC macro. Maintaining a copy of each record filed can cause the size of TPF transaction services to be enlarged. It can also cause TPF transaction services to either exceed the maximum allowed size or to actually run out of TPF transaction services buffers. So, dirty-reader protection should only be set on a collection that will be accessed by dirty readers.

Format

#include <c$to2.h>
BOOL TO2_getDRprotect (const TO2_PID_PTR  pid_ptr,
                             TO2_ENV_PTR  env_ptr);

pid_ptr
A pointer to the persistent identifier (PID) of the collection whose dirty-reader protection state will be retrieved.

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

Normal Return

TO2_IS_TRUE
Dirty-reader protection is active for the collection.

TO2_IS_FALSE
Dirty-reader protection is not active for the collection.

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. This function must also be used with a TO2_IS_FALSE return code to distinguish this return from an error return indication. If the error code returned by TO2_getErrorCode is TO2_IS_FALSE (0), this is the actual return code by the function. Otherwise, an error is indicated. For more information, see Error Handling.

The following error codes are common for this function:

TO2_ERROR_DELETED_PID

TO2_ERROR_NOT_INIT

TO2_ERROR_PID

TO2_ERROR_ZERO_PID

Programming Considerations

To avoid running out of commit scope buffers or exceeding maximum allowed size, consider the following:

Examples

The following example retrieves the dirty-reader protection status of the provided collection.

#include <c$to2.h>                /* Needed for TO2 API functions    */
#include <stdio.h>                /* APIs for standard I/O functions */
 
TO2_PID             pid_ptr;
TO2_ENV_PTR         env_ptr;
TO2_ERR_CODE        err_code;     /* TO2 error code value             */

  ·
  ·
  ·
/**********************************************************************/ /* retrieve the dirty-reader protect state from the collection */ /* and return it to the caller. */ /**********************************************************************/ if (TO2_getDRprotect(pid_ptr, env_ptr)) == TO2_IS_FALSE) { err_code = TO2_getErrorCode(env_ptr); if (err_code ! = 0) { printf("TO2_getDRprotect failed!\n"); process_error(env_ptr); } else printf("Dirty-reader protection is not active for the collection!\n"); } else printf("Dirty-reader protection is active for the collection!\n") ;

Related Information

TO2_setDRprotect -- Set Dirty-Reader Protection On.