Contents Previous Next Subchapters

Transfer O-Matrix Variables to the COM Server
Syntax status = OMServer.GetMatrix(omVarName)
See Also comgetdata

Description
Transfers the data in the O-Matrix variable omVarName to the O-Matrix server. The argument omVarName must be a character string that is a valid O-Matrix identifier and corresponds to a variable name that is currently active in O-Matrix. Note that this function transfers data from O-Matrix to the O-Matrix COM server. The GetData function must be called subsequently to transfer the data to the calling client.

The returned value status is an integer OM Server Status code. This value will equal 1 if the data transfer succeeded.

Data transfers by the O-Matrix COM server are managed with two function calls to enable clients to manage memory. The first call, GetMatrix transfers the matrix data and its attributes, (row and column dimensions), and the second call GetData copies the data to the client space.

The O-Matrix COM server transfers data as vectors to enable the different array handling mechanics of various languages and client tools to interact with the server. All matrices in O-Matrix are stored in column major order with row and column indices starting at 1. The following example provides a wrapper function, Vector2Matrix which handles the conversion of a returned data vector to a two-dimension VB array. A similar function can be applied to other languages.

Example
The following example illustrates using the GetMatrix and GetData functions to retrieve a matrix from O-Matrix and assign the result to a VB array variable.

At the O-Matrix command prompt enter

x = {[1, 2], [3, 4]}

 Create a new project and insert the following code into the new module.

Public OM As New OMServer

Private Function Vector2Matrix(vector As Variant, NR As Long, NC As Long) As Variant
    Dim i As Integer, j As Integer
    
    ' Copy to matrix of same dimension as OM data
    ReDim omMatrix(NR - 1, NC - 1) As Double
    For i = 0 To NR - 1
        For j = 0 To NC - 1
           omMatrix(i, j) = vector((j * NR) + i)
        Next j
    Next i

    Vector2Matrix = omMatrix
    
End Function

Private Function GetOMMatrix(OMVarName As String) As Variant
    Dim NR As Long          ' OM matrix dimensions
    Dim NC As Long
    Dim N As Long           ' Number of elements returned from O-Matrix
    Dim isOk As Integer
    
    ' Read data from O-Matrix and store in COM server
    isOk = OM.GetMatrix(matrixName:=OMVarName)
    If isOk <> 1 Then
        MsgBox ("Unable to transfer variable: " & OMVarName)
        Exit Function
    End If
    
    ' Array size will be one longer than actual in VB
    NR = OM.NRows()
    NC = OM.NCols()
    N = NR * NC
    ReDim omdata(N) As Double   ' Array for results from O-Matrix
    isOk = OM.GetData(arySize:=N, omdata:=omdata(0))
    If isOk <> 1 Then
        MsgBox ("Error transferring data for: " & OMVarName)
        Exit Function
    End If
        
    Dim matrix As Variant
    matrix = Vector2Matrix(omdata, NR, NC)
    GetOMMatrix = matrix
    
End Function

Sub Main()
    Dim isOk As Integer
    Dim omdata As Variant
    
    isOk = OM.Open
    If isOk <> 1 Then
        MsgBox ("Unable to establish connection to O-Matrix")
        Exit Sub
    End If
    
    omdata = GetOMMatrix("x")
    
    MsgBox ("First element of x: " & Str(omdata(0, 0)))
End Sub

 Run the example by pressing the F5 key. The sample will post a dialog that contains the number 1, which is the first element in the data returned from O-Matrix.