gtpc2me6C/C++ Language Support User's Guide

TO2_getPropertyValueFromPID-Retrieve a Property Value

This function retrieves the current value of the named property.

Format

#include <c$to2.h>
long TO2_getPropertyValueFromPID(const TO2_PID_PTR   pid_ptr,
                                       TO2_ENV_PTR   env_ptr,
                                 const char          name[],
                                       enum TO2_PROPERTY_TYPE  *type,
                                       long         *valueLength,
                                       void         *value,
                                       enum TO2_PROPERTY_MODE  *mode);

pid_ptr
The pointer to the persistent identifier (PID) assigned to the collection that owns the property.

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

name
A string that is the name of the property being retrieved.

type
The pointer to an area where the type enumeration of the property can be returned.

valueLength
The length of the field where the value of the property will be returned. This field will be overlaid with the actual length of the value of the property.

value
The pointer to the field where the value of the property will be returned.

mode
The pointer to an area where the mode enumeration of the property can be returned.

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_DATA_LGH

TO2_ERROR_DELETED_PID

TO2_ERROR_ENV

TO2_ERROR_LOCATOR_NOT_FOUND

TO2_ERROR_PARAMETER

TO2_ERROR_PID

TO2_ERROR_ZERO_PID

Programming Considerations

This function does not use TPF transaction services on behalf of the caller.

Examples

The following example retrieves the value of a named property attribute from a TPFCS database collection.

#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          keyset;
TO2_PROPERTY_TYPE propertyType;
TO2_PROPERTY_MODE propertyMode;
 
char propertyName[32] = "X.Property.attribute            ";
char value;
long valueLength = sizeof(value);

  ·
  ·
  ·
if (TO2_getPropertyValueFromPID(&keyset, env_ptr, propertyName, &propertyType, &valueLength, &value, &propertyMode) == TO2_ERROR) { printf("TO2_getPropertyValueFromPID failed!\n"); process_error(env_ptr); } else printf("TO2_getPropertyValueFromPID successful!\n");

Related Information