SafeArrayGetFeatures

(SafeArrayFeatures)

f90VB Modules

f90VBDefs, f90VBSafeArrays

Summary

Returns the contents of the fFeatures field of a Safe Array descriptor. SafeArrayGetFeatures and SafeArrayFeatures are two aliases for the same function (i.e. they behave exactly the same), so only SafeArrayGetFeatures is described below.

Syntax

integer(SHORT_KIND) function SafeArrayGetFeatures

(SARef)

{
integer(SAFEARRAY_KIND),intent(in)::	SARef \|
type(FSafeArray),intent(in)::	SARef \|
}

Arguments

SARef [Input]

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

Comments

Note that SARef must be a reference to an allocated Safe Array descriptor.

The fFeatures field contains flags that describe attributes of an array that can affect how the array is released. The field describes what type of data is stored in the Safe Array, and how the array is allocated. This allows freeing the array without referencing its containing variant. The bits are accessed using the following constants:

*fFeatures*	Flags	Description
FADF_AUTO	0x0001	The array is allocated on the stack.
FADF_STATIC	0x0002	The array is statically allocated.
FADF_EMBEDDED	0x0004	The array is embedded in a structure.
FADF_FIXEDSIZE	0x0010	The array may not be resized or reallocated.
FADF_RECORD	0x0020	The array containing records. When set there will be a pointer to the IRecordInfo interface at negative offset 4 in the array descriptor.
FADF_HAVEIID	0x0040	The array that has an IID identifying interface. When set there will be a GUID at negative offset 16 in the array descriptor. This flag is set only when FADF_DISPATCH or FADF_UNKNOWN is also set.
FADF_HAVEVARTYPE	0x0080	The array that has a VT-Type. When set there will be a VT tag at negative offset 4 in the array descriptor that specifies the element type.
FADF_BSTR	0x0100	The array elements are BSTRs.
FADF_UNKNOWN	0x0200	The array elements are IUnknown interfaces (IUnknown*)
FADF_DISPATCH	0x0400	The array elements are IDispatch interfaces (IDispatch*)
FADF_VARIANT	0x0800	The array elements are Variants.
FADF_RESERVED	0xF0E8	Reserved

Once you retrieve the fFeatures field using SafeArrayGetFeatures, you can test what flags are set using a bit-wise AND operation (IAND).

Examples

program SafeArrayFeaturesExample

!Demonstrates how to test and set Safe Array features

use f90VBDefs

use f90VBSafeArrays

implicit none

integer(SAFEARRAY_KIND)::SAHndlR, SAHndlBStr, SAHndlVar

character(len=255)::FeatureStr

!Create several arrays and show their feature fields

call SafeArrayCreate(SAHndlR, VT_R8, 1,10)

call TestFeatures(SAHndlR,FeatureStr)

print *,'Features of Array SAHndlR:', trim(FeatureStr)

call SafeArrayCreate(SAHndlBStr, VT_BSTR, 1,10)

call TestFeatures(SAHndlBStr,FeatureStr)

print *,'Features of Array SAHndlBStr:', trim(FeatureStr)

call SafeArrayCreate(SAHndlVar, VT_VARIANT, 1,10)

call TestFeatures(SAHndlVar,FeatureStr)

print *,'Features of Array SAHndlVar:', trim(FeatureStr)

!Now set the fFeatures fields of SAHndlR to FADF_FIXEDSIZE

!So this array can be passed to a subroutine without the

!fear of the subroutine changing its dimensions

call SafeArraySetFeatures(SAHndlR, &

ior(SafeArrayFeatures(SAHndlR),FADF_FIXEDSIZE))

call TestFeatures(SAHndlR,FeatureStr)

print *,'Features of Modified Array SAHndlR:', trim(FeatureStr)

!Destroy the Safe Arrays

call SafeArrayDestroy(SAHndlR)

call SafeArrayDestroy(SAHndlBStr)

call SafeArrayDestroy(SAHndlVar)

stop

end

subroutine TestFeatures(SAHndl,FeatureStr)

use f90VBDefs

use f90VBSafeArrays

implicit none

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

character(len=*),intent(out)::FeatureStr

integer(SHORT_KIND)::Features,test

Features = SafeArrayFeatures(SAHndl)

FeatureStr=''

if (iand(Features,FADF_AUTO).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_AUTO '

if (iand(Features,FADF_STATIC).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_STATIC '

if (iand(Features,FADF_EMBEDDED).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_EMBEDDED '

if (iand(Features,FADF_FIXEDSIZE).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_FIXEDSIZE '

if (iand(Features,FADF_RECORD).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_RECORD '

if (iand(Features,FADF_HAVEVARTYPE).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_HAVEVARTYPE '

if (iand(Features,FADF_BSTR).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_BSTR '

if (iand(Features,FADF_UNKNOWN).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_UNKNOWN '

if (iand(Features,FADF_DISPATCH).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_DISPATCH '

if (iand(Features,FADF_VARIANT).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_VARIANT '

if (iand(Features,FADF_RESERVED).gt.0) &

FeatureStr = trim(FeatureStr) // ' FADF_RESERVED '

end subroutine TestFeatures

For information about	See
Changing the features of a Safe Array	SafeArraySetFeatures
Creating a Safe Array	SafeArrayCreate
Allocating a Safe Array descriptor	SafeArrayAllocDescriptor