SafeArrayCreate

f90VB Modules

f90VBDefs, f90VBSafeArrays

Summary

Subroutine SafeArrayCreate allocates a new Safe Array Descriptor and data-block. Depending on the syntactic variation used, the subroutine will also initialize the data-block of the Safe Array. If SafeArrayCreate fails, the returned Safe Array handle is null.

Syntax

Syntax Variation 1:

Syntax Variation 2:

Syntax Variation 3:

Syntax Variation 4:

Arguments

SARef [Output]

Can be either a Safe Array Handle or a Fortran Safe Array structure. Upon return, SARef contains a handle to the new Safe Array, or a null handle if the subroutine is not successful.

vtType [Input]

The base type of the Safe Array (i.e. the type of each element of the array). Can be any of the values that appear in Table 2.1 (User Manual - Chapter 2). Neither the VT_ARRAY nor the VT_BYREF masks can be set. VT_EMPTY and VT_NULL are not valid base types for the array.

nDims [Input]

Number of dimensions of the Safe Array. Can be any value between 1 and 60.

IdxBound [Input]

Vector of type SafeArrayBound. Contains information about the lower bound and number of elements of each dimension of the Safe Array. See comments for more information.

LBound, UBound, LBound1, UBound1, LBound2, UBound2 [Input]

The lower and upper bounds for a one-dimension Safe Array (LBound and UBound). In the case of bi-dimensional Safe Arrays use LBound1, UBound1, LBound2, UBound2. The suffix x in LBoundx and UBoundx, represents the dimension (1 for the first dimension or rows, and 2 for the second dimension or columns). Any values in the integer range (including negative values) are allowed, as long as the upper bound is higher than the lower bound.

FortranArray [Input]

A Fortran array used as the base to create the Safe Array. The new Safe Array will have the same number of dimensions and type as FortranArray (some changes in type that do not involve conversions are allowed). The data in FortranArray is also used to initialize the data-block of the Safe Array. See comments for more information.

Comments

Use subroutine SafeArrayCreate to create Safe Arrays in a single operation. SafeArrayCreate allocates an array descriptor and the data-block used by the Safe Array. To allocate array descriptors and data-blocks independently, you can use a combination of calls to SafeArrayAllocDesc and SafeArrayAllocData.

The new Safe Array is returned as a handle or as a Fortran Safe Array structure. If a Fortran Safe Array structure is used, then subroutine SafeArrayCreate also allocates the structure’s array of indexes (field Idx(:)) to the appropriate size (i.e. the number of dimensions of the Safe Array).

To destroy Safe Arrays created with SafeArrayCreate use subroutine SafeArrayDestroy.

Argument IdxBound

IdxBound is a vector of type SafeArrayBound, indicating the bounds of each dimension of the array. The indexes of the vector correspond to dimensions of the array (i.e. first entry in IdxBound describes the bounds of the first dimension, the second entry describes the bounds of the second dimension, and so on). Use IdxBound when creating Safe Arrays with more than two dimensions. For one-dimension and bi-dimensional arrays it is easier to use Syntax Variation 2 and 3.

Argument FortranArray

The fourth syntax variation of SafeArrayCreate offer very simple ways to create Safe Arrays that contain an identical representation of Fortran array. When this syntax is used, the information from argument FortranArray is used to set the dimensions and data in the Safe Array. Argument vtType must be a type compatible with the elements of FortranArray. Because Fortran does not have unsigned numeric variables, argument vtType can be used to indicate that the new Safe Array is of type unsigned integer, in spite of the fact that FortranArray elements are signed integers. Only VT-Types that are directly compatible with the type of the passed FortranArray are accepted; SafeArrayCreateArray does not perform real data-type conversions (i.e. if the type of FortranArray is real, passing a vtType value of VT_UI2 will result in a null Safe Array handle). Table 2.2 (User Manual - Chapter 2) describes the allowed values of vtType for each kind of FortranArray.

Examples

!Demonstrates several different ways to create Safe Arrays

!Copyright 1999-2000, Canaima Software

!All rights reserved

use f90VBDefs

use f90VBSafeArrays

implicit none

!Declare several Safe Array handles and 

!Fortran Array Structures

integer(SAFEARRAY_KIND)::SAHndlA, SAHndlB, SAHndlC

type(FSafeArray)::FSA_A

integer(SHORT_KIND),dimension(10)::FortranArrayA

integer(HRESULT_KIND)::iRet

type(SafeArrayBound),dimension(2)::IdxBound

integer(SHORT_KIND),dimension(:),pointer::MappedArray

integer(LONG_KIND)::i

!Initialize Fortran Arrays

do i=1,10

    FortranArrayA(i)=i

enddo

!Allocate A Safe Array using Syntax Variation 4

!initializing the Safe Array using the data in FortranArrayA

call SafeArrayCreate(SAHndlA, VT_I2, FortranArrayA);

!Allocate a similar Safe Array using Syntax Variation 2

call SafeArrayCreate(SAHndlB, VT_I2, 1, 10)

!Initialize its data

do i=1,10

    call SafeArrayPutElement(SAHndlB,int(i,SHORT_KIND),i,iRet)

enddo

!Allocate a similar array using Syntax Variation 1

IdxBound(1)%LowerBound=1

IdxBound(1)%nElements=10

call SafeArrayCreate(SAHndlC, VT_I2, 1, IdxBound)

!Initialize its data

do i=1,10

    call SafeArrayPutElement(SAHndlC,int(i,SHORT_KIND),i,iRet)

enddo

!Allocate a similar Safe Array, returning the handle

!in a Fortran Safe Array structure

call SafeArrayCreate(FSA_A, VT_I2, FortranArrayA);

!Prints data for the three Safe Arrays using a 

!mapped Fortran Array

call SafeArrayAccessData(SAHndlA,MappedArray,iRet)

print *,'Safe Array SAHndlA:'

print *,(MappedArray(i),i=1,10)

call SafeArrayUnAccessData(SAHndlA)

call SafeArrayAccessData(SAHndlB,MappedArray,iRet)

print *,'Safe Array SAHndlB:'

print *,(MappedArray(i),i=1,10)

call SafeArrayUnAccessData(SAHndlB)

call SafeArrayAccessData(SAHndlC,MappedArray,iRet)

print *,'Safe Array SAHndlC:'

print *,(MappedArray(i),i=1,10)

call SafeArrayUnAccessData(SAHndlC)

call SafeArrayAccessData(FSA_A,MappedArray,iRet)

print *,'Safe Array FSA_A:'

print *,(MappedArray(i),i=1,10)

call SafeArrayUnAccessData(FSA_A)

!Destroy Safe Arrays

call SafeArrayDestroy(SAHndlA,iRet)

call SafeArrayDestroy(SAHndlB,iRet)

call SafeArrayDestroy(SAHndlC,iRet)

call SafeArrayDestroy(FSA_A,iRet)

stop

end

Related Topics

SafeArrayDestroy