gtpc2mdq | C/C++ Language Support User's Guide |
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
- A commit scope will be created for the TO2_definePropertyForPID
request. If the request is successful, the scope will be
committed. If an error occurs while processing the
TO2_definePropertyForPID request, the scope will be rolled
back.
- The default mode for properties that are created using this API is
TO2_PROPERTY_NORMAL. To specify a different mode, use
TO2_definePropertyWithModeForPID.
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