gtpc2mdrC/C++ Language Support User's Guide

TO2_definePropertyWithModeForPID-Define a Property with a Mode

This function defines a property with a mode. This function cannot be used to change an existing property value.

Format

#include <c$to2.h>
long TO2_definePropertyWithModeForPID (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,
                                       const enum TO2_PROPERTY_MODE *mode);

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. 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. TPFCS assumes a length of 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.

mode
A character string with one of the following values:

TO2_PROPERTY_NORMAL
There are no restrictions on the property you can read, change, or delete.

TO2_PROPERTY_NOCHANGE
The property can only be read and deleted. It cannot be changed.

TO2_PROPERTY_NODELETE
The property can be read or changed, but it cannot be deleted.

TO2_PROPERTY_READONLY
The property can only be read. It cannot be changed or deleted. A TO2_PROPERTY_READONLY mode is deleted only when the target collection is deleted.

Normal Return

The normal return is a positive value.

Error Return

An error return is indicated by a zero. When zero is returned, the TO2_getErrorCode function can be used 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_PARAMETER

TO2_ERROR_PID

TO2_ERROR_PROPERTY_MODE

TO2_ERROR_PROPERTY_TYPE

TO2_ERROR_ZERO_PID

Programming Considerations

A commit scope will be created for the TO2_definePropertyWithModeForPID request. If the request is successful, the scope will be committed. If an error occurs while processing the TO2_definePropertyWithModeForPID request, the scope will be rolled back.

Examples

The following example defines a property attribute with a mode for 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_CHAR;
TO2_PROPERTY_MODE propertyMode = TO2_PROPERTY_NORMAL;
 
char propertyName[32] = "X.Property.attribute            ";
char value = 'x';
long valueLength = sizeof(value);
 

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

Related Information