Accessing data with SafeArrayGetElement and SafeArrayPutElement

This is the easiest mechanism to read or write data to a Safe Array. Once you have secured a handle to a Safe Array (either because you created the Safe Array in your application or because you received the Safe Array handle from the program calling your subroutine) you can read an element in the array using SafeArrayGetElement. The general syntax for calling this procedure is as follows:

call SafeArrayGetElement(SARef, Value, Idx, iRet)

SARef can be either a Safe Array handle or a Fortran Safe Array Structure. Value is a variable of the same type as the base type of the Safe Array. Idx is an integer vector with the Safe Array indexes (or coordinates) that identify the Safe Array element you want to access. If the call to SafeArrayGetElement is successful, iRet is set to S_OK, and variable Value contains the value of the requested Safe Array’s element. If an error occurs, the content of Value is undetermined and iRet contains an error flag. Subroutine SafeArrayPutElement uses exactly the same syntax, but in this case, the indicated element of the Safe Array is replaced with the content of variable Value.

SafeArrayGetElement and SafeArrayPutElement automatically lock and unlock the Safe Array during their execution, so your application doesn’t need to explicitly call SafeArrayLock or SafeArrayUnlock. This is convenient, but also makes access to elements of the Safe Array slower. The overhead of locking and unlocking an array is not very high. However, array data are typically accessed inside loops that iterate through many of the array’s elements, so having to lock and unlock the array in each iteration may become very expensive in terms of performance. SafeArrayGetElement and SafeArrayPutElement are good options when you only need to access a few array elements, or when you are working with very large arrays and want to provide the OS the opportunity to manage the memory used by the Safe Array between calls to retrieve or store data.