odm_lock Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

odm_lock Subroutine

Purpose

Puts an exclusive lock on the requested path name.

Library

Object Data Manager Library (libodm.a)

Syntax

#include <odmi.h>

int odm_lock (LockPath, TimeOut)
char *LockPath;
int TimeOut;

Description

The odm_lock subroutine is used by an application to prevent other applications or methods from accessing an object class or group of object classes. A lock on a directory path name does not prevent another application from acquiring a lock on a subdirectory or object class within that directory.

Note: Coordination of locking is the responsibility of the application accessing the object classes.

The odm_lock subroutine returns a lock identifier that is used to call the odm_unlock subroutine.

Parameters

LockPath

Specifies a string containing the path name in the file system in which to locate object classes or the path name to an object class to lock.

TimeOut

Specifies the amount of time, in seconds, to wait if another application or method holds a lock on the requested object class or classes. The possible values for the TimeOut parameter are:

TimeOut = ODM_NOWAIT: The odm_lock subroutine is unsuccessful if the lock cannot be granted immediately.
TimeOut = Integer: The odm_lock subroutine waits the specified amount of seconds to retry an unsuccessful lock request.
TimeOut = ODM_WAIT: The odm_lock subroutine waits until the locked path name is freed from its current lock and then locks it.

Return Values

Upon successful completion, a lock identifier is returned. If the odm_lock subroutine is unsuccessful, a value of -1 is returned and the odmerrno variable is set to an error code.

Error Codes

Failure of the odm_lock subroutine sets the odmerrno variable to one of the following error codes:

ODMI_BAD_LOCK
	Cannot set a lock on the file. Check path name and permissions.
ODMI_BAD_TIMEOUT
	The time-out value was not valid. It must be a positive integer.
ODMI_BAD_TOKEN
	Cannot create or open the lock file. Check path name and permissions.
ODMI_LOCK_BLOCKED
	Cannot grant the lock. Another process already has the lock.
ODMI_LOCK_ENV
	Cannot retrieve or set the lock environment variable. Remove some environment variables and try again.
ODMI_MALLOC_ERR
	Cannot allocate sufficient storage. Try again later or contact the person responsible for the system.
ODMI_UNLOCK
	Cannot unlock the lock file. Make sure the lock file exists.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The odm_unlock subroutine.

List of ODM Commands and Subroutines.

Object Data Manager (ODM) Overview for Programmers in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.