gtpc2meq | C/C++ Language Support User's Guide |
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:
- TO2_ERROR_PID
- TO2_ERROR_ZERO_PID
- TO2_ERROR_DELETED_PID
- TO2_ERROR_NOT_INIT
- TO2_ERROR_PARAMETER
Programming Considerations
- For information about how to specifically set the access mode to
TO2_COLLECT_MODE_READONLY, see TO2_setReadOnly-Set the Read-Only Attribute of the Collection.
- The recommended way to mark a collection as read-only is by using the
TO2_setCollectionAccessMode function.
- Using the TO2_setCollectionAccessMode function to set the
access mode of a collection will override a TO2_setReadOnly
setting.
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