viLock

Syntax

viLock(ViSession vi, ViAccessMode lockType, ViUInt32 timeout, ViKeyId requestedKey, ViKeyId accessKey);

Note: Shared locks ARE supported by HiSLIP devices but are NOT supported on other types of network devices.

Description

This function is used to obtain a lock on the specified resource. The caller can specify the type of lock requested (exclusive or shared lock) and the length of time the operation will suspend while waiting to acquire the lock before timing out. This function can also be used for sharing and nesting locks.

The requestedKey and accessKey parameters apply only to shared locks. These parameters are not applicable when using the lock type VI_EXCLUSIVE_LOCK. In this case, requestedKey and accessKey should be set to VI_NULL. VISA allows user applications to specify a key to be used for lock sharing through the use of the requestedKey parameter.

Alternatively, a user application can pass VI_NULL for the requestedKey parameter when obtaining a shared lock, in which case VISA will generate a unique access key and return it through the accessKey parameter. If a user application does specify a requestedKey value, VISA will try to use this value for the accessKey.

As long as the resource is not locked, VISA will use the requestedKey as the access key and grant the lock. When the operation succeeds, the requestedKey will be copied into the user buffer referred to by the accessKey parameter.

The session that gained a shared lock can pass the accessKey to other sessions for the purpose of sharing the lock. The session wanting to join the group of sessions sharing the lock can use the key as an input value to the requestedKey parameter.

VISA will add the session to the list of sessions sharing the lock, as long as the requestedKey value matches the accessKey value for the particular resource. The session obtaining a shared lock in this manner will then have the same access privileges as the original session that obtained the lock.

It is also possible to obtain nested locks through this function. To acquire nested locks, invoke the viLock function with the same lock type as the previous invocation of this function. For each session, viLock and viUnlock share a lock count, which is initialized to 0. Each invocation of viLock for the same session (and for the same lockType) increases the lock count.

A shared lock returns with the same accessKey every time. When a session locks the resource a multiple number of times, it is necessary to invoke the viUnlock function an equal number of times in order to unlock the resource. That is, the lock count increments for each invocation of viLock, and decrements for each invocation of viUnlock. A resource is actually unlocked only when the lock count is 0.

Parameters

Name	Dir	Type	Description
vi	IN	ViSession	Unique logical identifier to a session.
lockType	IN	ViAccessMode	Specifies the type of lock requested, which can be VI_EXCLUSIVE_LOCK or VI_SHARED_LOCK.
timeout	IN	ViUInt32	Absolute time period (in milliseconds) that a resource waits to get unlocked by the locking session before returning this operation with an error. VI_TMO_IMMEDIATE and VI_TMO_INFINITE are also valid values.
requestedKey	IN	ViKeyId	This parameter is not used and should be set to VI_NULL when lockType is VI_EXCLUSIVE_LOCK (exclusive lock). When trying to lock the resource as VI_SHARED_LOCK (shared lock), a session can either set it to VI_NULL so that VISA generates an accessKey for the session, or the session can suggest an accessKey to use for the shared lock. See "Description" for more details.
accessKey	OUT	ViKeyId	This parameter should be set to VI_NULL when lockType is VI_EXCLUSIVE_LOCK (exclusive lock). When trying to lock the resource as VI_SHARED_LOCK (shared lock), the resource returns a unique access key for the lock if the operation succeeds. This accessKey can then be passed to other sessions to share the lock.

Return Values

Type ViStatus	This is the function return status. It returns either a completion code or an error code as follows.
Completion Codes	Description
VI_SUCCESS	The specified access mode was successfully acquired.
VI_SUCCESS_NESTED_EXCLUSIVE	The specified access mode was successfully acquired, and this session has nested exclusive locks.
VI_SUCCESS_NESTED_SHARED	The specified access mode was successfully acquired, and this session has nested shared locks.
Error Codes	Description
VI_ERROR_INV_ACCESS_KEY	The requestedKey value passed is not a valid access key to the specified resource.
VI_ERROR_INV_LOCK_TYPE	The specified type of lock is not supported by this resource.
VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT	The given vi does not identify a valid session or object.
VI_ERROR_RSRC_LOCKED	The specified type of lock cannot be obtained because the resource is already locked with a lock type incompatible with the lock requested.
VI_ERROR_TMO	The specified type of lock could not be obtained within the specified timeout period.

See Also

viUnlock. For more information on locking, see Programming with VISA in the Agilent VISA User’s Guide.