gtpc2mbsC/C++ Language Support User's Guide

TO2_addKeyPath-Add a Key Path to a Collection

This function allows an application program to add key paths to a persistent collection to access the data elements of the collection in an order different from the primary key path. The application can define as many as 16 unique alternate key paths (in addition to the primary key path) for a collection.

Note:
This function does not support all collections. See Table 47 for collections that are supported for this function.

Format

#include <c$to2.h>
long  TO2_addKeyPath (const TO2_PID_PTR  pid_ptr,
                            TO2_ENV_PTR  env_ptr,
                      const char        *name,
                      const long        *fieldLength,
                      const long        *fieldDisplacement);

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.

name
The pointer to a string that is the name that will be assigned to the new key path. The key path name can be a maximum of 16 characters. Two key paths in the same collection cannot have the same name.

fieldLength
The pointer to an area that contains the length of the key path field. The field length must be 248 bytes or less.

fieldDisplacement
The pointer to an area that contains the 0-based displacement of the key path field.

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_LGH

TO2_ERROR_LOCATOR_NOT_UNIQUE

TO2_ERROR_MAX_KEYPATHS

TO2_ERROR_METHOD

TO2_ERROR_NOT_INIT

TO2_ERROR_PID

TO2_ERROR_RESERVED_NAME

TO2_ERROR_ZERO_PID

Programming Considerations

Examples

The following example creates key paths for the zip code, state, and country code fields of a customer entry for the passed collection pointer.

#include <c$to2.h>            /* TO2 API function prototypes     */
#include <stddef.h>           /* standard definitions (offsetof) */
#include <stdio.h>            /* APIs for standard I/O functions */
 
/*    Customer name entry:                                       */
   struct customerEntry {
       char   lastName[48];   /* customer's last name            */
       char   firstName[48];  /* customer's first name           */
       char   street[48];     /* street address                  */
       char   city[48];       /* city name                       */
       long   stateCode;
       long   countryCode;
       long   zipCode;        /* customer's zip code             */
  };
   typedef struct customerEntry CUST;
 
 
   long createCustomerKeyPath(TO2_PID_PTR pid_ptr,
                              TO2_ENV_PTR env_ptr)
{
 
   long rc;                    /* return code                    */
 /*  key path field values                                       */
   CUST customer;
   char name[17];             /* name of key path                */
   long offset;               /* off set of field                */
   long length;               /* length of field                 */
 
 /*  work areas                                                  */
 
 
 /****************************************************************/
 /* Using TO2_addKeyPath create the additional key paths.        */
 /****************************************************************/
 
    length=sizeof(customer.zipCode);
    offset=offsetof(customer, zipCode);
    strcpy(name,"ZIPCODE");
    if (TO2_addKeyPath(pid_ptr,
                       env_ptr,
                       name,
                       &length,
                       &offset) == TO2_ERROR)
    {
      printf("TO2_addKeyPath failed!\n");
      process_error(env_ptr);
    }
 
    length=sizeof(customer.stateCode);
    offset=offsetof(customer, stateCode);
    strcpy(name,"STATECODE");
    if (TO2_addKeyPath(pid_ptr,
                       env_ptr,
                       name,
                       &length,
                       &offset) == TO2_ERROR)
    {
      printf("TO2_addKeyPath failed!\n");
      process_error(env_ptr);
    }
 
    length=sizeof(customer.countryCode);
    offset=offsetof(customer, countryCode);
    strcpy(name,"COUNTRYCODE");
    if (TO2_addKeyPath(pid_ptr,
                       env_ptr,
                       name,
                       &length,
                       &offset) == TO2_ERROR)
  {
     printf("TO2_addKeyPath failed!\n");
     process_error(env_ptr);
  }
 /*      ... return to the caller ...                     */
     return 1;
}

Related Information