SafeArrayPutElement

f90VB Modules

f90VBDefs, f90VBSafeArrays

Summary

Changes the value of an element of a Safe Array.

Syntax

Syntax Variation 1:

Syntax Variation 2:

Syntax Variation 3:

Arguments

SARef [Input]

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

Value [Input]

A variable or literal constant containing the value to be assigned to the Safe Array element. See comments for more information.

IdxVector [Input]

A vector with the indexes (coordinates) of the Safe Array element to be changed. See comments for more information.

Idx, Idx1, Idx2 [Input]

For one-dimension arrays, Idx is the index of the element to be changed. For bi-dimensional arrays, Idx1 is the index (coordinate) in the first dimension and Idx2 is the index (coordinate) of the second dimension. See comments for more information.

iRet [Output]

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

Comments

This function automatically calls SafeArrayLock and SafeArrayUnlock before and after assigning the element, so it is an expensive operation. If you need to change many elements of a Safe Array, using SafeArrayAccessData/SafeArrayUnAccessData is much more efficient.

If argument Value is a BString or Variant, the function puts a copy of Value in the Safe Array element. If Value is an automation interface, the function increments the counter of the interface (i.e. calls AddRef). If the existing Safe Array element is a BString, automation interface, or Variant, it is cleared correctly before assigning the new value.

Argument Value

SafeArrayPutElement does not attempt to coerce Value into the type of the Safe Array elements, so argument Value must have a type that is directly compatible with the base type of the Safe Array. For example, if the base type of a Safe Array is UI_2, Value must be of type integer(SHORT_KIND). Any other type will produce an error condition.

Argument IdxVector

The size of Idx must be at least equal to the number of dimensions of the Safe Array. The indexes of the vector correspond to dimensions of the array (i.e. first entry in Idx contains the coordinate for the first dimension, the second entry contains the coordinate for the second dimension, and so on). Use IdxVector when changing the values of elements in Safe Arrays that have three or more dimensions. For Safe Arrays with one or two dimensions, using Syntax Variation 2 or 3 is usually more convenient.

Argument iRet

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

Examples

See also examples for SafeArrayCreate.

!Demonstrates the use of SafeArrayGetElement and

!SafeArrayPutElement

!Copyright 1999-2000, Canaima Software

!All rights reserved

use f90VBDefs

use f90VBSafeArrays

use f90VBBstrings

use f90VBVariants

implicit none

integer(SAFEARRAY_KIND)::SAHndlR, SAHndlBStr, SAHndlVar

integer(LONG_KIND)::i,j

integer(HRESULT_KIND)::iRet

integer(BSTRHNDL_KIND)::TmpBStr

character(len=4)::TmpStr

type(VARIANT)::TmpVar

real(FLOAT_KIND)::TmpReal

integer(BSTRHNDL_KIND),pointer::MapArray(:,:)

real(FLOAT_KIND),pointer::MapReal(:,:)

!Initialize BStr and Variants

TmpVar = VariantCreate(iRet)

TmpBStr = 0

!Create a Safe Array of reals and set its data

call SafeArrayCreate(SAHndlR, VT_R4, 1, 3, 1, 3)

do i=1,3

    do j=1,3

        call SafeArrayPutElement(SAHndlR, real(i+j,4), &

                                 i,j,iRet)

    enddo

enddo

!create a Safe Array of BStrings and set its data

call SafeArrayCreate(SAHndlBStr, VT_BSTR, 1, 3, 1, 3)

do i=1,3

    do j=1,3

        write(TmpStr,'(f4.1)') real(i+j)

        !Create a temporal BString

        TmpBStr=BStrAlloc(TmpStr)

        !Copy the temporal BString to the appropriate 

        !element in the Safe Array

        call SafeArrayPutElement(SAHndlBStr, TmpBStr,i, &

                                 j,iRet)

        !release memory used by temporal BString

        call StrFree(TmpBstr)

    enddo

enddo

!Create a Safe Array of variants

call SafeArrayCreate(SAHndlVar, VT_VARIANT, 1, 3, 1, 3)

do i=1,3

    do j=1,3

        call SafeArrayPutElement(SAHndlVar,VariantCreate( &

                                 VT_R4, real(i+j,4)),i,j,iRet)

    enddo

enddo

!Print the content of the 3 safe arrays

print *,'Content of Safe Array SAHndlR:'

do i=1,3

    do j=1,3

        call SafeArrayGetElement(SAHndlR,TmpReal,i, &

                                 j,iRet)

        write(*,'(a1,i2,a1,i2,a2,f4.1)') &

                             '(',i,',',j,')=',TmpReal

    enddo

enddo

print *,'Content of Safe Array SAHndlBStr:'

do i=1,3

    do j=1,3

        !Create a temporal copy of the BString in the 

        !requested Safe Array element

        call SafeArrayGetElement(SAHndlBStr, TmpBStr ,i,j,iRet)

        !Copy the BString into a Fortran string for printing

        call StrCopy(TmpBStr,TmpStr)

        write(*,'(a1,i2,a1,i2,a2,a4)') &

                                '(',i,',',j,')=',TmpStr

        !Deallocate the temporal BString

        call StrFree(TmpBStr)

    enddo

enddo

print *,'Content of Safe Array SAHndlVar:'

do i=1,3

    do j=1,3

        call SafeArrayGetElement(SAHndlVar,TmpVar,i, j,iRet)

        write(*,'(a1,i2,a1,i2,a2,f4.1)') '(',i,',',j,')=', &

                                        VariantToReal(TmpVar)

    enddo

enddo

!Destroy Safe Arrays and their data

call SafeArrayDestroy(SAHndlR)

call SafeArrayDestroy(SAHndlBStr)

call SafeArrayDestroy(SAHndlVar)

stop

end

Related Topics

SafeArraySetBounds