Seven basic rules for manipulating Safe Arrays

Rule 1: Allocate, destroy and access Safe Arrays only through the functions provided in f90VB.

There is nothing to stop you from creating a descriptor structure and filling it using the information provided in this chapter, but your program will likely face doomsday with the next release of windows.

Rule 2: Safe Array arguments are always passed by reference.

A subroutine that receives a Safe Array as an argument ALWAYS receives a handle to a Safe Array descriptor. The handle may be null, to indicate a Safe Array that has not been created yet, but you will never get the descriptor itself. This also means you can always change the data in the data-block of a Safe Array.

Rule 3: You only own Safe Arrays that expose themselves as available.

If your subroutine receives a null Safe Array handle, you own the Safe Array and can create or destroy it at your will.

If your subroutine receives a non-null Safe Array handle, what you can do with the array is indicated in its fFeatures field. You get access to the content of this field by calling f90VB’s procedure SafeArrayGetFeatures. If the bit flag of the Safe Array is set to FADF_FIXEDSIZE or FADF_STATIC you cannot reallocate or resize the array.

Rule 4: Never change the type of a Safe Array that has been passed to you.

If the program that called your subroutine declared a Safe Array of integers and passed it to you, it expects a Safe Array of integers back. If your subroutines need to change the type of a Safe Array, then the array must be passed and received as a Variant argument (see Chapter 3 for a description of Variant handling facilities provided by f90VB).

Rule 5: Always lock a Safe Array before accessing its data.

The operating system (or another program using the same Safe Array) may relocate the data-block to a different memory position. The only way you can ensure that the Safe Array’s pointer to the data-block is valid is by locking the Safe Array. Once a Safe Array is locked, it cannot be destroyed, redimensioned or reallocated until it is unlocked again.

Rule 6: Always unlock a Safe Array when you are done manipulating its data.

Failing to unlock a Safe Array will result in the OS not being able to destroy it later, with a consequent memory leak.

Rule 7: When you destroy a Safe Array, you are responsible for destroying objects and Bstrings that are referenced in the Safe Array’s data-block.

Safe Arrays of BStrings or objects do not contain the strings or objects in its data-block. Instead, it has handles to these entities. Destroying the Safe Array does not destroy the objects it points to.