SafeArrayReDim

f90VB Modules

f90VBDefs, f90VBSafeArrays

Summary

Re-dimensions a Safe Array preserving its current data. Only the number of elements in the last dimension of a Safe Array can be changed while preserving the current array’s data.

Syntax

Arguments

SARef [Input]

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

nElements [Input]

New value for the number of elements in the last dimension of the array. It must be a positive integer. See comments for more information.

iRet [Output, Optional]

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

Comments

Use SafeArrayReDim when you want to change the upper bound of the last dimension of an array while maintaining the data stored in the array. Only the number of elements in the last dimension of an array can be changed. To change the bounds of other dimensions, or the lower bound of the last dimension, you must destroy the array and create a new one.

If you reduce the number of elements in the last dimension of an array, SafeArrayReDim deallocates the array elements outside the new array boundary. So, for arrays of BStrings, StrFree is called for each of the elements outside the new bounds; for arrays of Variants, VariantClear is called; and for arrays of objects the objects’ reference counter are decreased (i.e. the objects’ Release method are called).

If the number of elements in the last dimension of an array is increased, SafeArrayReDim allocates and initializes the new array elements. Elements that already exist in the array are untouched.

If you want to re-dimension an array and do not need to preserve its data, calling SafeArrayDestroy to destroy the array, followed by SafeArrayCreate to create a fresh array with the new dimensions, could be a less expensive operation.

Note that SafeArrayReDim cannot be used to change the number of dimensions to an existing array. To do this you must create a new Safe Array.

Examples

!Demonstrates the use of SafeArrayReDim

!Copyright 1999-2000, Canaima Software

!All rights reserved

use f90VBDefs

use f90VBSafeArrays

integer(SAFEARRAY_KIND)::SAHndl

integer(HRESULT_KIND)::iRet

integer::i,j

!Create a new Safe Array

call SafeArrayCreate(SAHndl,VT_R4,1,5,1,3)

do i=1,SafeArrayUpperBound(SAHndl,1)

    do j=1,SafeArrayUpperBound(SAHndl,2)

        call SafeArrayPutElement(SAHndl,real(i+j,4),i,j,iRet)

    enddo

enddo

!Print the information and dimensions of the array

print *,'Array has been created and initialized...'

call PrintArrayInfo(SAHndl)

!Redimension the array adding two new columns

call SafeArrayReDim(SAHndl,5,iRet)

!Print the information and dimensions of the array

print *,''

print *,'Array redimensioned (Added 2 columns)...'

call PrintArrayInfo(SAHndl)

!Redimension the array removing 3 columns

call SafeArrayReDim(SAHndl,2,iRet)

!Print the information and dimensions of the array

print *,''

print *,'Array redimensioned (Removed 3 columns)...'

call PrintArrayInfo(SAHndl)

!Destroy the safe array

call SafeArrayDestroy(SAHndl,iRet)

stop

end

subroutine PrintArrayInfo(SAHndl)

    use f90VBDefs

    use f90VBSafeArrays

    integer(SAFEARRAY_KIND),intent(in)::SAHndl

    real(FLOAT_KIND),pointer::MapMtrx(:,:)

    integer(HRESULT_KIND)::iRet

    integer::i

    !Print the information and dimensions of the array

    print *,'Array Information:'

    print *,'Dimensions:',SafeArrayGetDim(SAHndl)

    print *,'Element type:', SafeArrayVarType(SAHndl)

    print *,'Element size:',SafeArrayGetElementSize(SAHndl)

    print *,'Feature flags:', SafeArrayGetFeatures(SAHndl)

    do i=1,SafeArrayGetDim(SAHndl)

        print *,'Dimension:',i

        print *,'   Lower bound:',SafeArrayLowerBound(SAHndl,i)

        print *,'   Upper bound:',SafeArrayUpperBound(SAHndl,i)

        print *,'   Number of elements:', SafeArrayNElements(SAHndl,i)

    enddo

    !Map the safe array to easily print its data

    call SafeArrayAccessData(SAHndl,MapMtrx,iRet)

    print *,'Array Data:'

    do i=1,ubound(MapMtrx,1)

        print *,(MapMtrx(i,j),j=1,ubound(MapMtrx,2))

    enddo

    !Unmap the safe array

    call SafeArrayUnAccessData(SAHndl,iRet)

end subroutine PrintArrayInfo

Related Topics

SafeArrayGetElementPtr