# oamOpenObject

Starts an editing session on the specified managed object. Returns a handle to be used with subsequent NMS OAM service function invocations.

#### Prototype

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 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.

#### Details

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.

#### See also

oamCloseObject

#### Example

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;
}