contents   index   previous   next

SafeArrayGetElement

 

f90VB Modules

 

f90VBDefs, f90VBSafeArrays

Summary

 

Retrieves the value stored in an element of a Safe Array.

Syntax

 

Syntax Variation 1:

 

subroutine SafeArrayGetElement (SARef, Value, IdxVector, iRet)

Syntax Variation 2:

{
Integer(SAFEARRAY_KIND),intent(in):: SARef |
type(FSafeArray),intent(in):: SARef |
}
{
integer(BYTE_KIND),intent(out):: Value |
integer(SHORT_KIND),intent(out):: Value |
integer(LONG_KIND),intent(out):: Value |
integer(BSTR_KIND),intent(out):: Value |
real(FLOAT_KIND),intent(out):: Value |
real(DOUBLE_KIND),intent(out):: Value |
real(DATE_KIND),intent(out):: Value |
type(CURRENCY),intent(out):: Value |
type(VARIANT),intent(out):: Value |
}
integer(LONG_KIND),dimension(:),intent(in):: IdxVector
integer(HRESULT_KIND),intent(out):: iRet

 

subroutine SafeArrayGetElement (SARef, Value, Idx, iRet)

Syntax Variation 3:

{
Integer(SAFEARRAY_KIND),intent(in):: SARef |
type(FSafeArray),intent(in):: SARef |
}
{
integer(BYTE_KIND),intent(out):: Value |
integer(SHORT_KIND),intent(out):: Value |
integer(LONG_KIND),intent(out):: Value |
integer(BSTR_KIND),intent(out):: Value |
real(FLOAT_KIND),intent(out):: Value |
real(DOUBLE_KIND),intent(out):: Value |
real(DATE_KIND),intent(out):: Value |
type(CURRENCY),intent(out):: Value |
type(VARIANT),intent(out):: Value |
}
integer(LONG_KIND),intent(in):: Idx
integer(HRESULT_KIND),intent(out):: iRet

 

subroutine SafeArrayGetElement (SARef, Value, Idx1, Idx2, iRet)

{
Integer(SAFEARRAY_KIND),intent(in):: SARef |
type(FSafeArray),intent(in):: SARef |
}
{
integer(BYTE_KIND),intent(out):: Value |
integer(SHORT_KIND),intent(out):: Value |
integer(LONG_KIND),intent(out):: Value |
integer(BSTR_KIND),intent(out):: Value |
real(FLOAT_KIND),intent(out):: Value |
real(DOUBLE_KIND),intent(out):: Value |
real(DATE_KIND),intent(out):: Value |
type(CURRENCY),intent(out):: Value |
type(VARIANT),intent(out):: Value |
}
integer(LONG_KIND),intent(in):: Idx1
integer(LONG_KIND),intent(in):: Idx2
integer(HRESULT_KIND),intent(out):: iRet

Arguments

 

SARef [Input]

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

 

Value [Output]

A variable where the requested value of the Safe Array is to be stored. See comments for more information.

 

IdxVector [Input]

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

 

Idx, Idx1, Idx2 [Input]

For one-dimension arrays, Idx is the index of the element to be retrieved. 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 calls SafeArrayLock and SafeArrayUnlock automatically, before and after retrieving the element, so it is an expensive operation. If the Safe Array element is a BString, automation interface, or Variant, the function returns a copy the element, so the calling program must call StrFree, Release or VariantClear to release the memory used by variable Value.

Argument Value

 

SafeArrayGetElement does not attempt to coerce the Safe Array element into the type of Value, 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 retrieving 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:

 

 

Value returned in argument iRet Description
S_OK Success.
DISP_E_BADINDEX The specified index was invalid.
E_INVALIDARG One of the arguments is invalid.
E_OUTOFMEMORY Memory for Value could not be allocated.

Examples

 

See examples in SafeArrayPutElement.

Related Topics

 

For information about See
Changing the value of a Safe Array element SafeArrayPutElement
Accessing data in a Safe Array using a mapped Fortran array SafeArrayAccessData

 

SafeArrayGetElementSize