SafeArrayCopySafeArrayAllocDescriptor
f90VB Modules
f90VBDefs, f90VBSafeArrays
Summary
Allocates a Safe Array descriptor structure and returns its handle.
Syntax
| subroutine SafeArrayAllocDescriptor | (SARef, vtType, nDims, iRet) |
| { | |
| integer(SAFEARRAY_KIND),intent(out):: | SARef | |
| type(FSafeArray),intent(out):: | SARef | |
| } | |
| integer(VARTYPE_KIND),intent(in):: | vtType |
| integer(LONG_KIND),intent(in):: | nDims |
| integer(HRESULT_KIND),intent(out),optional:: | iRet |
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 descriptor, 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.
iRet [Output/Optional]
Upon return, iRet contains S_OK or an error code. See comments for more information.
Comments
SafeArrayAllocDescriptor only allocates the Safe Array descriptor structure. To allocate the data-block for the Safe Array, you must call subroutine SafeArrayAllocData.
SafeArrayAllocDescriptor is useful when you want to create an array that contains a data type not supported by standard Safe Arrays. For example, to create an array of a user-defined type (UDT), you call SafeArrayAllocDescriptor with a vtType of VT_RECORD.
After a call to SafeArrayAllocDescriptor, you must manually set the size of the array elements (calling SafeArraySetElementSize) before allocating the Safe Array data-block.
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. | |
| E_UNEXPECTED | The array descriptor could not be locked. | |
| E_OUTOFMEMORY | Memory for the new Safe Array descriptor could not be allocated. | |
| E_INVALIDARG | One of the arguments is invalid. | |
Examples
See Example 2.4 (User Manual - Chapter 2).
Related Topics
| For information about | See | |
| Creating a Safe Array | SafeArrayCreate | |
| Destroying a Safe Array descriptor | SafeArrayDestroyDescriptor | |
| Allocating Safe Array data | SafeArrayAllocData | |