f90VB Safe Array handles

A Safe Array is always represented through its handle. You declare a Safe Array handle in your Fortran program as follows:

integer(SAFEARRAY_KIND)::SafeArrayHndl

Once you have declared the Safe Array handle, you can create the Safe Array descriptor and its data-block by calling f90VB’s function SafeArrayCreate, for example:

Call SafeArrayCreate(SafeArrayHndl,VT_I4, 1, 20)

This creates a Safe Array vector of 4-byte integers (VT_I4 is a constant that indicates the type of elements in the Safe Array) with indexes that go from 1 to 20. The handle to this Safe Array is assigned to variable SafeArrayHndl.

There are three basic subroutines to access the data in a Safe Array; SafeArrayGetElement, SafeArrayPutElement and SafeArrayAccessData [06]. The following short program creates a Safe Array vector of 4-byte integers and sets all its values to 5.

Example 2.1

program Example21

integer(SAFEARRAY_KIND)::SafeArrayHndl

integer::i,j

!Allocate the Safe Array

Call SafeArrayCreate(SafeArrayHndl,VT_I4, 1, 20)

!Initialize all elements to 5

do i=1,20

   call SafeArrayPutElement(SafeArrayHndl,5,i)

enddo 

…

!do something else with the Safe Array

…

!Release memory used by the Safe Array

call SafeArrayDestroy(SafeArrayHndl, iRet)

stop

end 

Notice that we call SafeArrayDestroy before exiting the program to instruct the OS to release the memory associated to the Safe Array.

To read entries from a Safe Array, you can use procedure SafeArrayGetElement. SafeArrayGetElement and SafeArrayPutElement have the same call syntax:

Call SafeArrayGetElement(SafeArrayHndl, Value, index, [index,] iRet)

Where argument SafeArrayHndl is a handle to an allocated Safe Array, Value is a variable containing the value you want to store in the Safe Array (or a variable that will receive the value stored in the array when using SafeArrayGetElement). Argument index is the index of the entry where you want to store or retrieve the value. For bi-dimensional Safe Arrays, you can also pass an additional index, to indicate the column of the entry to retrieve or restore [07]. If the call to SafeArrayGetElement or SafeArrayPutElement is not successful, argument iRet contains a negative number upon return from the subroutine.

The code in Example 2.2 adds a few instructions to Example 2.1 to increment by one hundred all the values in the Safe Array referenced by SafeArrayHndl. This illustrates the use of SafeArrayGetElement and SafeArrayPutElement.

Example 2.2

program Example22

integer(SAFEARRAY_KIND)::SafeArrayHndl

integer::i,j

!Allocate the Safe Array

Call SafeArrayCreate(SafeArrayHndl,VT_I4, 1, 20)

!Initialize all elements to 5

do i=1,20

   call SafeArrayPutElement(SafeArrayHndl,5,i)

enddo 

…

!Add 100 to all the elements

do i=1,20

   call SafeArrayGetElement(SafeArrayHndl,j,i)

   j=j+100

   call SafeArrayPutElement(SafeArrayHndl,j,i)

enddo 

…

!Release memory used by the Safe Array

call SafeArrayDestroy(SafeArrayHndl, iRet)

stop

end 

SafeArrayPutElement and SafeArrayGetElement automatically lock and unlock the referenced Safe Array. You will learn more about locks later in this chapter.