gtpc2mhlC/C++ Language Support User's Guide

TO2_getPIDinventoryEntry-Get PID Inventory Entry for PID

This function causes TPF collection support (TPFCS) to locate the entry for the specified persistent identifier (PID) in the PID inventory collection of the data store (DS) and return a copy of the entry to the caller.

Format

#include <c$to2.h>
TO2_BUF_PTR TO2_getPIDinventoryEntry (TO2_PID_PTR  pid_ptr,
                                      TO2_ENV_PTR  env_ptr);

pid_ptr
The pointer to a field that contains the PID with an entry that will be retrieved from the PID inventory collection of the data store.

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

Normal Return

TPFCS returns a pointer to a formatted buffer that will contain the requested entry. The normal return is a pointer (TO2_BUF_PTR) to a structure (buffer) of type TO2_BUF_HDR (see Type Definitions).

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_NOT_INIT

Programming Considerations

It is the responsibility of the caller to issue a freec request to release the returned buffer when the caller has finished with it.

Examples

The following example retrieves the entry for a given PID.

#include <c$to2.h>                 /* Needed for TO2 API Functions    */
#include <stdio.h>                 /* APIs for standard I/O functions */
 
TO2_ENV_PTR      env_ptr;          /* Pointer to TO2 environment      */
TO2_PID          collectionPID;    /* subject PID                     */
 
TO2_BUF_PTR      buffer_ptr;
 
TO2_ERR_CODE     to2_rc=1;         /* return code receiver            */
TO2_ERR_TEXT_PTR err_textPtr;      /* TO2 error code text pointer     */

  ·
  ·
  ·
{ buffer_ptr = TO2_getPIDinventoryEntry(&collectionPID, env_ptr); if ((long) buffer_ptr == TO2_ERROR) { to2_rc = TO2_getErrorCode(env_ptr); err_textPtr = TO2_getErrorText(env_ptr, to2_rc); printf ("TO2_getPIDinventoryEntry failed, error code - %d\n ", to2_r c); printf ("TO2 Error Text is %s\n ", err_textPtr); } else printf("TO2_getPIDinventoryEntry successful\n"); free buffer_ptr; }

Related Information

TO2_createPIDinventoryKey-Create PID Inventory Key from PID.