Contents Previous Next Subchapters

Using DDE to Communicate with other Programs
Syntax omlink(option
omlink(
option,value)
omlink(
option,name)
See Also omclient , omserver , dll

Description
This function enables O-Matrix to be used in conjunction with other programs, or other copies of O-Matrix, either as a client or as a server. Initially, when O-Matrix starts, it is an OMLINK server named "O-Matrix". Commands sent by an OMLINK client for this server are automatically executed. The omlink function enables O-Matrix to change the server name, to become an OMLINK client, and to exchange data with other servers and clients.

Arguments
The first argument to the omlink function is a character row vector called option. It determines the nature of the call to omlink and whether the second argument is called name or value. If the second argument is called name, it is also a character row vector. If the second argument is called value it can be a logical, character, integer, real, double-precision or complex matrix.

Server Option
If option is equal to "server", any open OMLINK conversations are terminated and the OMLINK state is set to server with the reference name being name. The return value of the omlink function is true for success and false for failure. If the return value is false, the "error" option can be used to determine the nature of the failure.

Client Option
If option is equal to "client", any open OMLINK conversations are terminated and the OMLINK state is set to client with the reference name being name. This starts a conversation with this copy of O-Matrix as the client and the server that has its reference name equal to name. The return value of the omlink function is true for success and false for failure. If the return value is false, the "error" option can be used to determine the nature of the failure.

Get Option
If option is equal to "get" there is only one argument to omlink. If the current OMLINK state is server (client), the return value of the omlink function is the next matrix that was passed by a client (server) to this copy of O-Matrix. In either case if there is no such matrix, the return value has type equal to "novalue". The matrices are returned on a first in first out basis.

Put Option
If option is equal to "put" and the current OMLINK state is server (client), the matrix specified by value is sent to the client (server) currently connected to this copy of O-Matrix. If the return value of the omlink function is false, the matrix transfer failed for some reason. Otherwise the return value is true. If the return value is false, the "error" option can be used to determine the nature of the failure.

Command Option
If option is equal to "command" and the current OMLINK state is client, this call sends the commands in the character matrix value to the server that is connected to this copy of O-Matrix. If the return value of the omlink function is false, the command transfer failed for some reason, otherwise the return value is true. If the return value is false, the "error" option can be used to determine the nature of the failure.

Error Option
If option is equal to "error", there is only one argument to omlink. The return value is a character row vector containing a description of the most recent error. This error message corresponds to the most recent call to the omlink function in which the first argument was not equal to "error". If no error occurred during that call, the return value is equal to "".

Example
If you start two copies of O-Matrix and in the first copy enter the command
     omlink("client", "O-Matrix")
O-Matrix will respond
     T
This connects the first copy as the client to the second copy as the server. (The response T signals that the connection was successful.) If in the first copy of O-Matrix you then enter
     omlink("put", seq(5))
O-Matrix will respond
     T
If in the first copy of O-Matrix you then enter
     get = [DQUOTE, "get", DQUOTE]
     cmd = ["omlink(", get, ")"]
     print cmd
O-Matrix will respond
     omlink("get")
If you transfer this command to the second copy of O-Matrix by entering the command
     omlink("command", cmd)
O-Matrix will respond
     T
If you now look at the command window in the second copy of O-Matrix you will see
     {
     1
     2
     3
     4
     5
     }
which is the result of executing the command in the second copy of O-Matrix.

Linking to C
If you want to program your own OMLINK, you can use the C library routines described in the Omclient , and Omserver sections.

Mlmode
Commands sent to a copy of O-Matrix that is currently an OMLINK server are executed in O-Matrix mode (as apposed to Mlmode ).