gtpc2mdiC/C++ Language Support User's Guide

TO2_createSortedBag-Create an Empty Persistent Sorted Bag Collection

This function creates an empty persistent sorted bag collection using the default data definition (DD) and assigns a persistent identifier (PID) to the collection.

Format

#include <c$to2.h>
long  TO2_createSortedBag (      TO2_PID_PTR   pid_ptr,
                                 TO2_ENV_PTR   env_ptr,
                           const long         *entryLength,
                           const long         *sortFieldLength,
                           const long         *sortFieldDisplacement);

pid_ptr
The pointer to the location where the PID assigned to the new collection will be returned.

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

entryLength
The pointer to the maximum length of an entry in the collection. The maximum length is 1000 bytes.

sortFieldLength
The pointer to the length of the sort field. The maximum length is 248 bytes. The sortFieldLength value must be equal to or less than the entryLength value.

sortFieldDisplacement
The pointer to the displacement in the entry to the start of the sort field. The sortFieldLength value plus the sortFieldDisplacement value must be equal to or less than the entryLength value.

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_ENV

TO2_ERROR_LOCATOR_LGH

Programming Considerations

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

Examples

The following example creates a persistent sorted bag collection.

#include <c$to2.h>           /* Needed for TO2 API functions    */
#include <stdio.h>           /* APIs for standard I/O functions */
 
TO2_ENV_PTR env_ptr;         /* PTR to the TO2 environment      */
TO2_PID     collect;         /* will hold collection's PID      */
long        entryLength;     /* Max Entry Length                */
long        sortFieldLength; /* Field length                    */
long        sortFieldLengthDisplacement;   /* PTR to keyFLD     */

  ·
  ·
  ·
if (TO2_createSortedBag(&collect, env_ptr, &entryLength, &sortFieldLength, &sortFieldLengthDisplacement) == TO2_ERROR) { printf("TO2_createSortedBag failed!\n"); process_error(env_ptr); } else { printf("TO2_createSortedBag successful!\n"); }

Related Information