gtpc2me8C/C++ Language Support User's Guide

TO2_includes-Search Collection for Element Equal to the Argument

This function causes the collection to be searched for an element equal to the argument and returns a TO2_IS_TRUE or TO2_IS_FALSE indication.

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

Format

#include <c$to2.h>
BOOL  TO2_includes (const TO2_PID_PTR   pid_ptr,
                          TO2_ENV_PTR   env_ptr,
                    const void         *value,
                    const long         *valueLength);

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.

value
The pointer to the value to test.

valueLength
The pointer to the length of the value to test.

Normal Return

TO2_IS_TRUE
The collection contains the argument.

TO2_IS_FALSE
The collection does not contain the argument.

Error Return

An error return is indicated by a zero return value and a nonzero error code. When zero is returned, use the TO2_getErrorCode function to determine the specific error code. For the TO2_IS_FALSE result, check the TPFCS error code by entering TO2_getErrorCode to distinguish this result from an error return indication. If the error code is zero, the Boolean result is false. Otherwise, an error is indicated and you can retrieve the error text by entering TO2_getErrorText. For more information, see Error Handling.

The following error codes are common for this function:

TO2_ERROR_ENV

TO2_ERROR_METHOD

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 prints data values if they are present in a 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 the TO2 environment      */
TO2_PID          bag;
char             bagdata[] = "Bag:Collection:Element:.Data";
long             bagdatalength;                             /* length */
 
if (TO2_includes(&bag,
                 env_ptr,
                 &bagdata,
                 &bagdatalength) == TO2_IS_FALSE)
{
   err_code = TO2_getErrorCode(env_ptr);
   if ((err_code != 0))
   {
   printf("TO2_includes failed!\n");
   process_error(env_ptr);
   }
   else
   {
   printf("Bag does not include value.\n");
   }
}
else
   printf("Bag includes value.\n");

Related Information