Starts an editing session on the specified managed object. Returns a handle to be used with subsequent NMS OAM service function invocations.
DWORD oamOpenObject ( CTAHD ctahd, const char *szName, HMOBJ *phObject, DWORD dwMode )
|
Argument |
Description |
|
ctahd |
[in] Context handle. |
|
szName |
[in] Pointer to a name of the managed object. |
|
phObject |
[out] Pointer to the handle of the managed object. |
|
dwMode |
[in] Specifies open mode. See the Details section for valid values. |
|
Return value |
Description |
|
SUCCESS |
|
|
CTAERR_BAD_ARGUMENT |
szName or phObject is NULL or 0. |
|
CTAERR_SVR_COMM |
Natural Access Server is not running. |
|
OAMERR_ACCESS_DENIED |
phObject is open to another application, and open modes do not allow use. |
|
OAMERR_FILE_READ_ERROR |
Error reading from database. |
|
OAMERR_NOT_ENOUGH_MEMORY |
Memory allocation error. |
|
OAMERR_NOT_FOUND |
phObject not found. |
|
OAMERR_SERVER_NOT_RUNNING |
Supervisor is shut down. |
To access configuration data in a managed object, a client application opens the object using oamOpenObject. With this function invocation, the application supplies an opening mode. Valid modes are:
|
Mode |
Description |
|---|---|
|
OAM_READONLY |
Opens the object for reading only. The application cannot change keyword values. |
|
OAM_READWRITE |
Opens the object for both reading and writing. The application can change the values of read and write keywords. A managed object cannot be opened in this mode if any other client application has it currently open. |
If a client application attempts to open a managed object for writing, and the object is currently open by another application, oamOpenObject fails and OAMERR_ACCESS_DENIED is returned to the application.
Note: A managed object can be opened in read-only mode (OAM_READONLY) even if it is currently open in read-only mode by another application.
If the object-opening attempt succeeds, oamOpenObject returns a handle to the object, to be used with subsequent editing functions.
For more information about opening and closing objects, see Accessing configuration data.
DWORD openObject( CTAHD ctahd, char *objName, HMOBJ *pObjHd, int bDoWrite )
{
DWORD ret;
DWORD mode = OAM_READONLY;
DWORD retry = 0;
if ( bDoWrite )
/* Caller wants to performs writes to keywords within the
* managed object.
*/
mode = OAM_READWRITE;
else
/* Only reads will be performed on the keywords
* within the managed object.
*/
mode = OAM_READONLY;
do
{
if ( retry )
/* Another thread or process has the object opened for write */
Sleep( 10 );
ret = oamOpenObject( ctahd, objName, pObjHd, mode );
} while ( ( ret == OAMERR_ACCESS_DENIED ) && (retry++ < 5);
if ( ret != SUCCESS )
{
char errMsg[ 100 ];
ctaGetText( ctahd, ret, errMsg, sizeof(errMsg) );
printf("oamOpenObject failed: %s\n", errMsg );
}
return ret;
}