f90VB Fortran Safe Array structures (FSA)

Most applications use arrays on only one or two dimensions. Safe Arrays, however, can have up to thirty-two dimensions. It is hard to imagine an application using arrays with this many dimensions, but applications that handle arrays with three or four dimensions are not uncommon. Passing the indexes of many dimensions to f90VB Safe Array procedures can be confusing and prone to errors. Because of this, f90VB procedures accept direct indexes for up two dimensions. If you need to work with Safe Arrays that have more than two dimensions, then you must pass the indexes that identify an element through a vector of indexes. In these cases, using Fortran Safe Array Structures is usually a better option. A Fortran Safe Array Structure has the following definition:

type FSafeArray
     integer(POINTER_KIND)::DescHndl
     integer(LONG_KIND),pointer::Idx(:)
end type FSafeArray

Field DescHndl stores a Safe Array handle. Field Idx(:) is an allocatable vector that is used to store the indexes that identify a particular element in the Safe Array pointed by DescHndl. All functions and subroutines in f90VB’s Safe Array library accept Fortran Safe Array Structures in place of Safe Array handles. When you call procedure SafeArrayCreate using a FSA, the handle of the new Safe Array is stored in DescHndl, and vector Idx is allocated to the number of dimensions in the Safe Array. When you want to retrieve or store an element in the array, you set the entries in Idx to identify the array coordinates for the element. Example 2.3 is equivalent to Example 2.2, but instead of using a Safe Array handle, it uses a Fortran Safe Array Structure.

Example 2.3

program Example23

type(FSafeArray)::FSA

integer::i,j

!Allocate the Safe Array

Call SafeArrayCreate(FSA,VT_I4, 1, 20)

!Initialize all elements to 5

do i=1,20

   FSA%Idx(1)=i

   call SafeArrayPutElement(FSA,5)

enddo 

…

!Add 100 to all the elements

do i=1,20

   FSA%Idx(1)=i

   call SafeArrayGetElement(FSA,j)

   j=j+100

   call SafeArrayPutElement(FSA,j)

enddo 

…

!Release memory used by the Safe Array

call SafeArrayDestroy(FSA, iRet)

stop

end 

Example 2.3 could erroneously make you think that using Fortran Safe Array Structures may be an unnecessary complication. The advantages of the FSA approach however, will become clear if you need to manipulate arrays with many dimensions.