Contents Previous Next Subchapters

Getting Data Sent to an OMDDE Client
Source Files: omdde.c dderror.c omdde.h noserver.h

Prototype
char *OMClientGetMat(
     int             
id,
     enum type_mat  *
mtype,
     int            *
nr
     int            *
nc,
     void           *
data
)


Description
This function call retrieves a matrix that has been sent by a server to a client. The argument id is the integer index returned by a previous call to OMClientConnect . It specifies which server the matrix was sent from. The input values of mtype, nr, and nc do not matter. The output value of mtype specifies the type of the matrix and is one of those in the O-Matrix Types table. The value mtype might also be UNDEF_mat in which case the server does not yet have a matrix for the client. The output value of nr specifies the number of rows in the matrix. The output value of nc specifies the number of columns in the matrix. If the input value of data is equal to NULL, the elements of the matrix are not returned. This call can be used to determine the size of the matrix. If the input value of data is not equal to NULL, it must point to at least OMSize(mtype) times nr times nc bytes of memory. In this case, the elements of the matrix will be placed in the memory pointed to by data. These elements will be in column major order; i.e., the first column followed by the second etc. If the return value of OMClientGetMat is equal to "ok", the matrix was accepted. If the return value of OMClientGetMat is equal to "busy", the server is currently busy and cannot accept the matrix. Any other return value is an error message.

Example
The following example gets the matrix
     / 1 2 3 \
     | 2 4 6 |
     \ 3 6 9 /
from O-Matrix. It is in the file omcliget.c in the directory omwin\omdde. If you have the Microsoft Visual C++ compiler, it can be compiled and linked by executing the command
     nmake /f console.mak omcliget.exe
in that directory.

# include <stdio.h>
# include <malloc.h>
# include <assert.h>
# include "define\omdde.h"
# include "define\noserver.h"

int main()
{    
     int            id;
     int            ok;
     int             i;
     int             j;

     char           *msg;           
     enum type_mat  mtype;
     int            nr;
     int            nc;
     mint           *data;
     mint           dummy;

     // command that makes O-Matrix put the matrix on the link
     char           *cmd = "omlink(\"put\", seq(3) * seq(3)')";


     // initialize the omdde system
     ok = OMDdeInitialize();
     if( ! ok )
     {    printf("Cannot initialize OMDDE\n");
          return 1;
     }

     // connect to O-Matrix with this program as the client
     id = OMClientConnect("O-Matrix");
     if( id == OMDDE_CONNECTION_FAILED ) 
     {    printf("Cannot connect to O-Matrix\n");
          return 1;
     }

     // send the command to the O-Matrix server for execution
     msg = OMClientPutCmd(id, cmd);
     if( strcmp(msg, "ok") != 0 )
     {    printf("Command transfer failed: %s\n", msg);
          return 1;
     }

     /*
     wait for the command to complete execution
     */
     mtype = UNDEF_mat;
     data  = NULL;
     while( mtype == UNDEF_mat )
     {
          // ask the server to put a matrix on the link
          msg   = "busy";
          while( strcmp(msg, "busy") == 0 )
               msg = OMClientGetMat(id, &mtype, &nr, &nc, data);

          // make sure it was able to do so
          if( strcmp(msg, "ok") != 0 )
          {    printf("Matrix transfer failed: %s\n", msg);
               return 1;
          }

          if( mtype == UNDEF_mat )
          {    // O-Matrix puts a novalue matrix on link if it has
               // not yet executed the command that was sent to it.
               assert( OMSize(mtype) == 0 );
               OMClientGetMat(id, &mtype, &nr, &nc, &dummy); 
               assert( mtype == UNDEF_mat );
               printf("O-Matrix command not done executing\n");
          }
          else
          {    // allocate memory for the matrix
               data = malloc( nr * nc * OMSize(mtype) );

               // get the elements of the matrix
               OMClientGetMat(id, &mtype, &nr, &nc, data); 
          }
     }
     assert( mtype == INT_mat && nr == 3 && nc == 3 );

     // print the matrix
     printf("data =\n");
     for(i = 0; i < nr; i++)
     {    for(j = 0; j < 3; j++)
               printf("%5d", data[i+3*j]);
          printf("\n");
     }

     // free the memory allocated for the elements of the matrix
     free(data);

     // free the memory allocated for dde communication
     OMDdeUninitialize();

     return 0;
}

Reference
Invalid memory will be accessed if id is not equal to a previous return value of OMClientConnect. Invalid memory will also be accessed if data is not equal to NULL, and it does not point to enough space for the elements of the matrix.