gtpc2meuC/C++ Language Support User's Guide

TO2_size-Return the Size of the Collection

This function obtains the size of a collection or the number of entries contained in a collection.

Format

#include <c$to2.h>
long  TO2_size    (const TO2_PID_PTR   pid_ptr,
                         TO2_ENV_PTR   env_ptr);

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

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

Normal Return

size
The size of the collection. The value returned for all collections except a BLOB is the number of entries. For a BLOB, the value returned is the number of bytes.
Note:
For an array collection, not all entries may actually be in use.

Error Return

An error return is indicated by a zero. When zero is returned, use the TO2_getErrorCode function to determine if the zero return code is the actual size of the collection or if the zero return indicates that an error has occurred. If the TO2_getErrorCode function also returns a zero, the zero return is the size of the collection. Otherwise, the zero return was an error return. For more information, see Error Handling.

The following error codes are common for this function:

TO2_ERROR_ENV

TO2_ERROR_PID

Programming Considerations

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

Examples

The following example determines the size of a specified 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          blob;
long             size;
 
TO2_ERR_CODE     err_code;        /* TO2 error code value             */
TO2_ERR_TEXT_PTR err_text_ptr;    /* TO2 error code text pointer      */

  ·
  ·
  ·
if ((size = TO2_size(&blob, env_ptr)) == TO2_ERROR) { err_code=TO2_getErrorCode(env_ptr); if (err_code == TO2_IS_FALSE) printf("The collection is empty\n"); else { printf("TO2_size failed\n"); process_error(env_ptr); } } else { printf("TO2_size successful!\n"); printf("Collection size is %d\n",size); }

Related Information

TO2_setSize-Set the Size of the BLOB.