gtpc2meqC/C++ Language Support User's Guide

TO2_setCollectionAccessMode -- Set the Access Mode of a Collection

This function is used to change the access mode of a collection. The access mode is used to determine what class of functions may be applied against a collection.

Format

#include <c$to2.h>
long  TO2_setCollectionAccessMode (const      TO2_PID_PTR        pid_ptr,
                                              TO2_ENV_PTR        env_ptr,
                                         enum TO2_COLLECT_MODE * mode);

pid_ptr
A pointer to the persistent identifier (PID) of the collection whose access mode will be changed.

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

mode
The pointer to an enumerated data type of TO2_COLLECT_MODE which is the new access mode for the collection. The access mode can be used to prevent a collection from being deleted or from being changed. The valid modes are:

TO2_COLLECT_MODE_NORMAL
This is the default mode that TPFCS sets all collections to when they are created. The collection can be read, appended to, updated, and deleted.

TO2_COLLECT_MODE_NOCHANGE
The collection can be read and deleted. It cannot be appended to or updated.

TO2_COLLECT_MODE_NODELETE
The collection can be read, appended to, or updated but, the collection cannot be deleted.
Note:
The mode applies to the collection and not to its elements so that an application can delete all the elements in a collection with this mode but it cannot delete the actual collection itself.

TO2_COLLECT_MODE_READONLY
The collection can only be read. It cannot be updated, deleted, or appended to.

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:

Programming Considerations

Examples

The following example sets the access mode of a collection to prevent it from being deleted.

#include <c$to2.h>             /* Needed for TO2 API functions    */
 
long   setNoDeleteForCollect(const TO2_PID_PTR   pid_ptr,
                                   TO2_ENV_PTR   env_ptr);
 

  ·
  ·
  ·
/* */ /* issue To2_setCollectionAccessMode call to set the */ /* collection's access mode to NODELETE. */ /* '1' - successful, '-1' - error on request. */ /* */ long setNoDeleteForCollect(const TO2_PID_PTR pid_ptr, TO2_ENV_PTR env_ptr) { TO2_COLLECT_MODE mode=TO2_COLLECT_MODE_NODELETE; if (TO2_setCollectionAccessMode(pid_ptr, env_ptr, &mode) == TO2_ERROR) { process_error(env_ptr); return -1; } return 1; }

Related Information