gtpc2mhjC/C++ Language Support User's Guide

TO2_getPathInfoFor-Retrieve Path Information for a Collection Structure

This function allows the TPF collection support (TPFCS) browser to retrieve information about paths between specific structure elements of a collection or the location of a specific collection data element.

Format

#include <c$to2.h>
long  TO2_getPathInfoFor(const TO2_PID_PTR   pid_ptr,
                               TO2_ENV_PTR   env_ptr,
                               TO2_PID_PTR   returnPidPtr,
                         const long         *pathType,
                         const void         *pathInfo);

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.

returnPidPtr
The pointer to where the PID assigned to the output collection will be stored.

pathType
The type of path being requested:

TO2_PATH_KEY
Return path information about the specified key.

TO2_PATH_RRN
Return path information about the specified relative record number (RRN).

TO2_PATH_INDEX
Return information about the location of the specified entry index.

TO2_PATH_RBA
Return information about the location of the specified relative byte address (RBA).

pathInfo
The pointer to the required information based on the type of path specified.

TO2_PATH_KEY
An array of three pointers where:

 Pointer 1 
Is the address of a string that is the key path name, or zero if the primary key path is to be used.

 Pointer 2 
Is the address of a long constant that contains the length of the key.

 Pointer 3 
Is the address of the key whose path will be retrieved.

TO2_PATH_RRN
The address of a long integer that contains the RRN whose path will be retrieved.

TO2_PATH_INDEX
The address of a long integer that contains the decimal index value whose starting location will be retrieved.

TO2_PATH_RBA
The address of a long integer that contains the hexadecimal RBA whose location will be retrieved.

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_UNIQUE

TO2_ERROR_METHOD

TO2_ERROR_NOT_INIT

TO2_ERROR_PID

TO2_ERROR_DATA_LGH

TO2_ERROR_ZERO_PID

Programming Considerations

Examples

The following example retrieves the key path information for a specific key in the collection.

#include <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;
TO2_PID          returnPID;
char             key[KEYSIZE];
char             keyPath="";
long             keyLength;
long             pathType=0;
void           * pathValue[3];

  ·
  ·
  ·
/********************************************************************/ /* ... now call TO2 to retrieve the key path for the specified */ /* key value using the specified key path. */ /********************************************************************/ pathType=(long) TO2_PATH_KEY; /* set path info for key */ pathValue[0]=&keyPath; /* pointer to key path name */ pathValue[1]=&keyLength; /* pointer to keyLength */ pathValue[2]=key; /* pointer to key */ if (TO2_getPathInfoFor(&keyset, env_ptr, &returnPID, &pathType, pathValue) == TO2_ERROR) { printf("TO2_getPathInfoFor failed!\n"); process_error(env_ptr); } else { printf("TO2_getPathInfoFor was successful!\n"); }

The following example retrieves the key path information for a specific RRN in the collection.

#include <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;
TO2_PID          returnPID;
long             pathType=0;
long             RRN=45637;

  ·
  ·
  ·
/*******************************************************************/ /* ... now call TO2 to retrieve the path for the specified RRN. */ /* */ /*******************************************************************/ pathType = (long) TO2_PATH_RRN; /* set path info for RRN */ if (TO2_getPathInfoFor(&keyset, env_ptr, &returnPID, &pathType, &RRN) == TO2_ERROR) { printf("TO2_getPathInfoFor failed!\n"); process_error(env_ptr); } else { printf("TO2_getPathInfoFor was successful!\n"); }

Related Information

None.