gtpc2mdqC/C++ Language Support User's Guide

TO2_definePropertyForPID-Define or Change a Property for a Collection

This function defines or changes a property. The property can only be changed if the new and old types match and if the mode is NORMAL.

Format

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

pid_ptr
The pointer to the persistent identifier (PID) assigned to the collection for which the property is being defined.

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 defined or redefined. The maximum name length is 64 characters.

type
A symbol that has one of the following values:

TO2_PROPERTY_CHAR
Property value is a character. TPFCS assumes a 1-byte length.

TO2_PROPERTY_DOUBLE
Property value is a double integer (8 bytes). The maximum for a DOUBLE type is 263 -1. It is stored and displayed as the internal representation of the number. This consists of a sign bit, a 7-bit hexadecimal characteristic, and a 24-bit hexadecimal fraction (significand), which is preceded by an implied decimal point. The number is calculated as:
(-1)x(sign bit) x (significand) x (Base^Exponent)

where: Exponent=characteristic - Bias and the Bias=64 and the Base=16 in an System/370 environment.

TO2_PROPERTY_LONG
Property value is a long integer (4 bytes).

TO2_PROPERTY_STRING
Property value is a C string. The string must be delimited by a NULL character. The maximum string length is 256 characters.

TO2_PROPERTY_STRUCT
Property value is a structure. The valueLength parameter must contain the length of the struct. The maximum struct length is 1000 bytes.

valueLength
The length of the value that will be assigned to the defined property.

value
The value that will be assigned to the defined property based on the type selected.

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_MODE_MISMATCH

TO2_ERROR_PARAMETER

TO2_ERROR_PID

TO2_ERROR_PROPERTY_TYPE

TO2_ERROR_ZERO_PID

Programming Considerations

Examples

The following example defines a property attribute to 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;
char propertyName[32] = "X.Property.attribute            ";
TO2_PROPERTY_TYPE propertyType = TO2_PROPERTY_CHAR;
char value = 'x';
long valueLength = sizeof(value);
 

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

Related Information