TO2_removeKeyPath: Remove a key path from a collection

This function allows an application program to remove an alternate key path from a collection. z/TPF collection support (z/TPFCS) will delete the key path from the collection and release all the resources of that key path back to the z/TPF system.

Note: This function does not support all collections. See Table 1 for collections that are supported for this function.

Last updated

Changed for PUT00.

Format

#include <tpf/c_to2.h>
int  TO2_removeKeyPath (const TO2_PID_PTR  pid_ptr,
                               TO2_ENV_PTR  env_ptr,
                         const char        *name);
pid_ptr
The pointer to the persistent identifier (PID) assigned to the collection.
env_ptr
The pointer to the environment as returned by the TO2_createEnv function.
name
The pointer to a string that is the name of the alternate key path that will be removed from the collection.

Normal return

The normal return is a positive value.

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_LOCATOR_NOT_FOUND
  • TO2_ERROR_METHOD
  • TO2_ERROR_NOT_INIT
  • TO2_ERROR_PID
  • TO2_ERROR_RESERVED_NAME
  • TO2_ERROR_ZERO_PID

Programming considerations

  • The TO2_removeKeyPath function cannot be used to delete the primary key path.
  • This function uses z/TPF transaction services on behalf of the caller.

Examples

The following example removes the specified key path from the collection. 
#include <tpf/c_to2.h>                /* TO2 API function prototypes      */
#include <stdio.h>                /* APIs for standard I/O functions  */

TO2_ENV_PTR      env_ptr;         /* Pointer to TO2 Environment       */
TO2_PID          keyset;
char 
            name[] ="fieldA";   /* name of key path to remove       */  
⋮

if (TO2_removeKeyPath(&keyset,
                      env_ptr,
                      name) == TO2_ERROR)
{
   printf("TO2_removeKeyPath failed!\n");
   process_error(env_ptr);
}
else
{
   printf("TO2_removeKeyPath was successful!\n");
}

Related information

See z/TPF collection support: non-cursor overview for more information about this function and z/TPF C/C++ language support.