gtpc2mdnC/C++ Language Support User's Guide

TO2_createSortedSetWithOptions-Create an Empty Sorted Set Collection with Options

This function creates an empty sorted set collection using the specified options and assigns a persistent identifier (PID) to the collection.

A sorted set collection is the same as a sorted bag collection except that the sort fields of added elements must be unique.

Format

#include <c$to2.h>
long  TO2_createSortedSetWithOptions (TO2_PID_PTR     pid_ptr,
                                      TO2_ENV_PTR     env_ptr,
                                const TO2_OPTION_PTR  optionListPtr,
                                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.

optionListPtr
The pointer to a returned options list from a TO2_createOptionList function call or NULL if no options are required.

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 256 bytes. The sortFieldLength value must be less than or equal to 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 less than or equal to 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

TO2_ERROR_LOCATOR_NOT_UNIQUE

Programming Considerations

Examples

The following example creates a persistent sorted set collection.

#include <c$to2.h>                             /* Needed for TO2 API funcs      */
#include <stdio.h>                             /* APIs for standard I/O funcs   */
 
TO2_ENV_PTR    env_ptr;                        /* Pointer to the TO2 environ.   */
TO2_PID        collect;                        /* will hold collection's PID    */
u_char         ddname[] = "NAME_OF_USER_DD_DEFINITION  ";
long           entryLength;                    /* PTR to Max Entry Length       */
long           sortFieldLength;                /* PTR to field length           */
long           sortFieldDisplacement;          /* PTR to key field length disp. */
TO2_OPTION_PTR optionListPtr;
char           recoupname[] "HOSP0001";
 

  ·
  ·
  ·
/* invoke TO2 to create opt lst */ optionListPtr=TO2_createOptionList(env_ptr, TO2_OPTION_LIST_CREATE, /* create options */ TO2_CREATE_SHADOW, /* use shadowing */ TO2_CREATE_DD, /* use provided ddname */ TO2_CREATE_RECOUP, /* use provided recoup */ TO2_OPTION_LIST_END, /* end of options */ ddname, /* address of ddname */ recoupname); /* addr of recoup key */ if (optionListPtr == TO2_ERROR) { process_error(env_ptr); } if (TO2_createSortedSetWithOptions(&collect, env_ptr, optionListPtr, &entryLength, &sortFieldLength, &sortFieldDisplacement) == TO2_ERROR) { printf("TO2_createSortedSetWithOptions failed!\n"); process_error(env_ptr); } else { printf("TO2_createSortedSetWithOptions successful!\n"); }

Related Information