SafeArrayLock

f90VB Modules

f90VBDefs, f90VBSafeArrays

Summary

Adds a lock to the lock-counter of a Safe Array. A locked Safe Array cannot be redimensioned or destroyed. The array remains locked until SafeArrayUnlock is called.

Syntax

Arguments

SARef [Input]

A handle to, or a Fortran Safe Array structure containing a handle to, an allocated Safe Array descriptor.

iRet [Output, Optional]

Upon return, iRet contains S_OK or an error code. See comments for more information.

Comments

Note that SARef must be a reference to an allocated Safe Array descriptor.

A Safe Array can be accessed at the same time by more than one program, thread or the operating system. Use this subroutine to prevent other threads and/or processes from changing the characteristics of a Safe Array or reallocating its data-block while you are using the array. Note that locking a Safe Array does not stop other processes and/or threads from changing the data in the array.

To decrease the lock-counter of an array, use SafeArrayUnlock. Calls to SafeArrayLock and SafeArrayUnlock must be paired, i.e. you should issue only one call to SafeArrayUnlock for each call to SafeArrayLock in your subroutine.

Most f90VB subroutines internally lock/unlock Safe Arrays as necessary, so SafeArrayLock seldom needs to be used. Subroutine SafeArrayAccessData also adds a lock to the array’s lock-counter, which is later released when you call SafeArrayUnAccessData.

Argument iRet

Indicates success or failure of the subroutine. The following codes can be returned in this argument:

Examples

!Demonstrates the use of SafeArrayLock and

!SafeArrayUnlock

!Copyright 1999-2000, Canaima Software

!All rights reserved

use f90VBDefs

use f90VBSafeArrays

implicit none

integer(SAFEARRAY_KIND)::SAHndl

integer(HRESULT_KIND)::iRet

integer(SHORT_KIND)::BaseArray(3,3)

integer(SHORT_KIND),pointer::MapArray(:,:)

integer::i,j

!Create a new Safe Array from BaseArray

call SafeArrayCreate(SAHndl,VT_I2,1,3,1,3)

!Print number of locks in the array

print *,'Array Created. Locks:', SafeArrayLocks(SAHndl)

!Map the Safe Array into a Fortran Array

call SafeArrayAccessData(SAHndl,MapArray)

!Print number of locks in the array

print *,'Array Mapped. Locks:', SafeArrayLocks(SAHndl)

!Initialize Safe Array data using mapped array

do i=0,2

    do j=0,2

        MapArray(i+1,j+1)=i+j

    enddo

enddo

!print values in the safe array using mapped array

print *,'Contents of array SAHndl:'

do i=1,3

    print *, (MapArray(i,j),j=1,3)

enddo

!Call sub ChangeData, which adds 1 to all the

!safe array elements. Note that the fact that the

!array is locked does not stop ChangeData from

!changing the value of the array elements

call ChangeData(SAHndl)

!print values in the safe array using mapped array

print *,'Contents of array after ChangeData:'

do i=1,3

    print *, (MapArray(i,j),j=1,3)

enddo

!Call subroutine Destroy which attempts to destroy

!the safe array. Note that it is not successful, 

!because the array has a lock

call Destroy(SAHndl)

!invalidate Fortran array map and unlocks safe array

call SafeArrayUnAccessData(SAHndl)

!Print number of locks in the array

print *,'Array UnMapped. Locks:', SafeArrayLocks(SAHndl)

!put a lock in the array

call SafeArrayLock(SAHndl)

!Print number of locks in the array

print *,'Array Locked. Locks:', SafeArrayLocks(SAHndl)

!Call subroutine Destroy which attempts to destroy

!the safe array. Note that it is not successful, 

!because the array has a lock

call Destroy(SAHndl)

!remove the lock from the array and call DestroyArray

call SafeArrayUnlock(SAHndl)

!Print number of locks in the array

print *,'Array Unlocked. Locks:', SafeArrayLocks(SAHndl)

!Call subroutine Destroy which is successful this time

!because the safe array does not have any locks

call SafeArrayDestroy (SAHndl)

stop

end

subroutine ChangeData(SAHndl)

    use f90VBDefs

    use f90VBSafeArrays

    implicit none

    integer(SAFEARRAY_KIND)::SAHndl

    integer(SHORT_KIND),pointer::MapArray(:,:)

    integer(HRESULT_KIND)::iRet

    print *,'Changing array data...'

    call SafeArrayAccessData(SAHndl,MapArray,iRet)

    !Print number of locks in the array

    print *,'Array Mapped (ChangeData). Locks:', &

             SafeArrayLocks(SAHndl)

    if (iRet.eq.S_OK) then

        MapArray=MapArray+1

    endif

    call SafeArrayUnAccessData(SAHndl)

    !Print number of locks in the array

    print *,'Array UnMapped (ChangeData). Locks:', &

            SafeArrayLocks(SAHndl)

end subroutine ChangeData

subroutine Destroy(SAHndl)

    use f90VBDefs

    use f90VBSafeArrays

    implicit none

    integer(SAFEARRAY_KIND)::SAHndl

    integer(HRESULT_KIND)::iRet

    print *,'Attempting to destroy the Safe Array...'

    call SafeArrayDestroy(SAHndl, iRet)

    if (iRet.eq.S_OK) then

        print *,'Array destroyed'

    else

        print *,'Array could not be destroyed'

    endif

end subroutine Destroy

Related Topics

SafeArrayPutElement