Share via

COMARRAY( ) Function

  • Article

Specifies how arrays are passed to COM objects.

COMARRAY(oObject [, nNewValue])

Return Values

Numeric

Parameters

  • oObject
    An object reference to the COM object.

  • nNewValue
    Specifies how an array is passed to the COM object specified with oObject. The following table lists the settings for nNewValue and how the array is passed to the COM object.

    nNewValue Description
    0 The array is a zero-based array, and it is passed by value.
    1 (Default) The array is a one-based array, and it is passed by value. Compatible with earlier versions of Visual FoxPro.
    10 The array is a zero-based array, and it is passed by reference.
    11 The array is a one-based array, and it is passed by reference.
    100 The array is a fixed size array and cannot be redimensioned.
    1000 Byte arrays are not converted to strings.

    Issue COMARRAY( ) without the nNewValue argument to return the current setting.

Remarks

Earlier versions of Visual FoxPro can only pass arrays to COM objects by value. Also, the array passed to the COM object is assumed be a one-based array, meaning that the first element, row, and column in the array is referenced with 1.

However, some COM objects require that arrays passed to them be passed by reference, or the array passed is zero-based (the first element, row, and column in the array are referenced with 0), or both. COMARRAY( ) lets you specify how the array is passed to the COM object, and assumes you know how the array should be passed to the COM object.

Note that COMARRAY( ) is only used when arrays are passed to COM objects using the following syntax:

oComObject.Method(@MyArray)

When a byte array (VT_UI1) is used to communicate with a COM server, Visual FoxPro converts the byte array into a string. The additive nValue of 1000 retains the original proper type of the array and does not convert the result to a string.

If a client is passing a byte array by reference to a Visual FoxPro COM Server, the Visual FoxPro COM Server must also set the nValue additive to 1000. This can be done by putting the following call in the Init event of the Visual FoxPro COM Server:

COMARRAY(THIS,1000)

If the @ token is omitted, only the first element of the array is passed to the COM object, and COMARRAY( ) has no effect.

The additive nValue of 100 as used in the following example enables you to prevent redimensioning of an array (to run this example, first build the class definition into a DLL named "t1.dll"). You should check for possible errors after calling the server, in case the server attempts to redimension the array.

LOCAL loSvr, laTest
loSvr = NEWOBJECT("t1.arrayhandler")
DIMENSION laTest[10]
laTest=3
? COMARRAY(loSvr,11 + 100)
* The COM server will return an error on the next line of code
* because arrays passed to loSvr will not allow re-dimensioning.
loSvr.RedimensionArray(@laTest,4)
? ALEN(laTest)

DEFINE CLASS ARRAYHANDLER AS CUSTOM OLEPUBLIC
    PROCEDURE RedimensionArray(aArray, nRows)
        DIME aArray[nRows]
    ENDPROC
ENDDEFINE

See Also

COMCLASSINFO( ) | CREATEOBJECT( ) | GETOBJECT( )