gtpc2mdaC/C++ Language Support User's Guide

TO2_createRecoupIndex-Create a Recoup Index

This function creates a TPF collection support (TPFCS) recoup index.

Format

#include <c$to2.h>
long  TO2_createRecoupIndex (      TO2_ENV_PTR              env_ptr,
                             const void                    *indexName,
                             const enum TO2_RECOUP_TYPE     collectionType,
                             const enum TO2_RECOUP_CONTROL  control,
                             const char                     userProgramName,[]
                             const char                     functionName[],
                             const char                     description[]);

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

indexName
The pointer to the 8-byte recoup index name for the recoup index that will be created.

collectionType
A pointer to the collection type.

TO2_RECOUP_IGNORED
The collection is a binary large object (BLOB), which indicates that the recoup index is not homogeneous or heterogeneous.

TO2_RECOUP_HOMOGENEOUS
All elements in the collection have the same displacement to the persistent identifier (PID) or file address and can be recouped the same way.

TO2_RECOUP_HETEROGENEOUS
Not all elements contain an embedded file address or PID, or the displacements are different (that is, not all elements can be recouped the same way).

control
An indicator to which processing restrictions apply.

TO2_RECOUP_CONTROL_NONE
No specific control instructions.

userProgramName
A pointer to the user exit program name, if TO2_RECOUP_CONTROL_USER was specified, otherwise NULL is passed. userProgramName can be up to 4 bytes.

functionName
The name of the function in the user program to activate if TO2_RECOUP_CONTROL_USER was specified, otherwise NULL and the program never will be activated.

description
The description of the recoup index can be up to 256 bytes.

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 code is common for this function:

TO2_ERROR_ENV

Programming Considerations

The index cannot be shared by different structures; for example, between bag and key sorted bag collections.

Examples

The following example creates a homogeneous recoup index.

#include <c$to2.h>                  /* Needed for TO2 API Functions     */
#include <stdio.h>                  /* APIs for standard I/O functions  */
 
TO2_PID          collect;           /* target object's PID              */
TO2_ENV_PTR      env_ptr;           /* Pointer to TO2 environment       */
TO2_RECOUP_TYPE  collectionType = TO2_RECOUP_HOMOGENEOUS;
TO2_RECOUP_CONTROL control = TO2_RECOUP_CONTROL_NONE;
                                    /* Processing restrictions          */
u_char           indexName[]="INDEX003"; /* index identifier            */
 

  ·
  ·
  ·
if (TO2_createRecoupIndex(env_ptr, indexName, collectionType, control, userProgramName, functionName, description) == TO2_ERROR) { printf ("TO2_createRecoupIndex failed!\n"); process_error(env_ptr); } else printf("TO2_createRecoupIndex successful!\n");

Related Information