gtpc2mgsC/C++ Language Support User's Guide

TO2_createPIDinventoryKey-Create PID Inventory Key from PID

This function is used by TPF collection support (TPFCS) utility routines to create a key from an input persistent identifier (PID) that can be used to access the entry of the PID in the PID inventory collection. The created key will be returned in the specified buffer and the length of the key will overlay the bufferLength field.

Format

#include <c$to2.h>
long TO2_createPIDinventoryKey (TO2_PID_PTR  pid_ptr,
                                TO2_ENV_PTR  env_ptr,
                                void        *buffer,
                                long        *bufferLength);

pid_ptr
The pointer to a field where the temporary PID assigned to the sequence collection will be returned.

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

buffer
A pointer to a buffer where the key will be returned.

bufferLength
A pointer to a field that contains the length of the buffer. The buffer should be large enough to hold the data to be returned plus 16 additional bytes for a header. This field will be overlaid with the actual length of the key.

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_NOT_INIT

Programming Considerations

None.

Examples

The following example creates the key 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                     */
 
u_char           buffer[32];
long             bufferLength=sizeof buffer;
 
TO2_ERR_CODE     to2_rc=1;         /* return code receiver           */
TO2_ERR_TEXT_PTR err_textPtr;      /* TO2 error code text pointer    */

  ·
  ·
  ·
{ if ((to2_rc = TO2_createPIDinventoryKey(&collectionPID, env_ptr, buffer, bufferLength)) == TO2_ERROR) { to2_rc = TO2_getErrorCode(env_ptr); err_textPtr = TO2_getErrorText(env_ptr, to2_rc); printf ("TO2_createPIDinventoryKey failed, error code - %d\n ", to2_ rc); printf ("TO2 Error Text is %s\n ", err_textPtr); } else printf("TO2_createPIDinventoryKey successful\n"); }

Related Information

TO2_getPIDinventoryEntry-Get PID Inventory Entry for PID.