gtpc2mbtC/C++ Language Support User's Guide

TO2_addRecoupIndexEntry-Add an Entry to a Recoup Index

This function describes the location of user-embedded file addresses or persistent identifiers (PIDs) in collection elements.

Format

#include <c$to2.h>
long TO2_addRecoupIndexEntry (      TO2_ENV_PTR                   env_ptr,
                              const void                         *indexName,
                              const void                         *entryToken,
                              const enum TO2_RECOUP_ENTRY_TYPE    entryType,
                              const long                         *displacement,
                              const enum TO2_RECOUP_ENTRY_ACCESS  accessType,
                              const long                         *accessValueLen,
                              const void                         *accessValue);

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

indexName
The pointer to the 8-byte recoup index name to which the entry will be added.

entryToken
The pointer to the user-defined entry token. The token is an identifier for the given entry and must be unique in an index and must be 8 bytes long.

entryType
The embedded recoup information type indicator.

TO2_RECOUP_ENTRY_FA
The index entry being added describes a 16-byte area that contains a file address. See TPF Database Reference for more information about the format of the file addresses embedded in collections.

TO2_RECOUP_ENTRY_PID
The index entry being added describes a PID.

displacement
The displacement into the collection element for the user-embedded PID or file address. The displacement is 0-based.

accessType
For heterogeneous collections, the means to access the collection element.

TO2_RECOUP_ACCESS_INDEX
Use an index to access the element.

TO2_RECOUP_ACCESS_KEY
Use a key to access the element.

TO2_RECOUP_ACCESS_NOTUSED
Use for homogeneous and binary large object (BLOB) collections.

accessValueLen
For heterogeneous collections, the length of the index or key value that is used to access the element that contains the embedded recoup information. The length of an index must be 4 bytes. For homogeneous and BLOB collections, NULL is passed.

accessValue
For heterogeneous collections, the index or key value that is used to access the element that contains the embedded recoup information. For homogeneous and BLOB collections, NULL is passed.

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

Examples

The following example adds an entry to a recoup index.

#include <c$to2.h>                  /* Needed for TO2 API Functions    */
#include <stdio.h>                  /* APIs for standard I/O functions */
 
#define KEY_OFFSET 20
 
TO2_ENV_PTR      env_ptr;           /* Pointer to TO2 environment      */
u_char           indexName[]="INDEX001"; /* index identifier   */
char             entryToken;[8];    /* pointer to the entry token      */
TO2_RECOUP_ENTRY_TYPE entryType;    /* PID or FA index entry           */
long             displacement;      /* displacement to element         */
TO2_RECOUP_ENTRY_ACCESS accessType; /* key or index to access element  */
long             accessValueLen;    /* key length                      */
u_char           accessValue[]="JACOB";  /* key to access element     */
 

  ·
  ·
  ·
memcpy(entryToken, "MYDSNAME",8); entryType = TO2_RECOUP_ENTRY_PID; displacement = KEY_OFFSET; accessType = TO2_RECOUP_ACCESS_KEY; accessValueLen = sizeof(accessValue); if (TO2_addRecoupIndexEntry(env_ptr, indexName, &entryToken, entryType, &displacement, accessType, &accessValueLen, accessValue) == TO2_ERROR) { printf ("TO2_addRecoupIndexEntry failed!\n"); process_error(env_ptr); } else printf("TO2_addRecoupIndexEntry successful\n");

Related Information