One may use the MuPAD kernel application mupkern.exe as a stand-alone DDE server. For this purpose the MuPAD kernel supports a simple DDE protocol, which is described in this document. This purely text-oriented protocol allows to send command strings to the kernel to be executed and to receive the corresponding results.
The MuPAD kernel also supports a second, more complex DDE protocol for communication with it's user interface front end. But this second protocol may not be used by foreign applications and is not documented herin.
Each running instance of the MuPAD kernel allows for a single connection to a client at a time. If a client holds a connection to a kernel instance no other client may connect to that kernel.
If a client releases its connection the kernel is free for the next client. Note that the kernel is implicitly reset (using the MuPAD command reset()) if a client releases its connection.
If there is no free MuPAD kernel instance available a client will try to start a new kernel and to connect to it.
The name of the MuPAD kernel service is mupkern. The topic identfying the text protocol described herin is cmd. The kernel supports the following DDE transactions:
· connect mupkern cmd: Connects to the kernel. The connection is only accepted if no other client currently is connected to the kernel.
· disconnect: Closes the connection to the kernel. The kernel is reset (using the MuPAD command reset()).
· execute cmd <string>: Execute the command given by <string>, which must be a valid MuPAD command. The <string> must be a zero-terminated ASCII string. Note that the command must be followed by a colon (:) or semicolon (;) as usual. The kernel asynchronously starts computing the result, i.e. the execute transaction returns immediately. If an execute transaction is started while the kernel is still busy computing a command given before, the kernel discards this transaction and returns DDE_FBUSY.
· poke cmd <item> <string>: Execute the command given by <string>, the <item> does not matter. This transaction is handled exactly like an execute transaction.
· request cmd result: This transaction returns the output of the last result computed by the kernel as long as no new execute- or poke-transaction is started. The format of the result requested must be CF_TEXT. The result may be queried more than once. A zero-terminated ASCII text string containing the output is returned. The result string may not be longer than approx. 32 kB. Longer results are shortened and the string "<<discarded>>" is appended to them. If the output is not yet available because the kernel is still executing, the request is handled asynchronously (i.e. the transaction is blocked until the result is available). A client should handle requests asynchronously if possible.
· request cmd length: This transaction returns a string which contains the string length of the output of the last result computed. This request is useful if the output may be very large and one wants to be sure not to overflow the client. In any other respect this request is handled like the one before.
· request cmd file: This transaction returns a string which contains the full path name of a temporary file. The file in turn contains the output of the last result computed. This request is useful if one wants to handle very large output. The file is closed at the time when the request returns. Please note that the file is re-used again later on by the kernel. One may open the file for reading only and must close it before the next transaction is started, one must not delete the file. Please note further that the output is only flushed to the file after a request file transaction is issued (even though the name of the temporary file does not change).
· request cmd stop: This transaction stops any computation which is actually executed by the kernel. The transaction has no affect if the kernel is idle.
· request cmd quit: This request transaction stops the actual computation and then causes the kernel to quit.
· advise cmd result: This transaction starts a DDE advise loop: Each time when the execution of a command produces an output, this output is sent to the client; there is no need for the client to request the data explicitly. (Commands are issued by execute- or poke-transactions as usual.) The data sent to the client is of the same format as with the request result transaction.
· advise cmd length: This transaction also starts a DDE advise loop, but instead of sending the output to the client the string length of the output is sent. The client may then fetch the output from the kernel using the request result or the request file transaction, depending on the length of the output.
· advise cmd file: This transaction starts a DDE advise loop like above, with the difference that the name of a temporary file from which to read the output is sent to the server.
· unadvise cmd <item>: This transaction stops the corresponding advise loop, the client is no longer informed when new output is ready. Valid items are result, length and file.
In the description given above mupkern is the name of the kernels DDE service; cmd is the DDE topic identifying the protocol described herin; result, length, file, stop and quit are DDE items.
If a client wants to connect to a MuPAD kernel and no one currently is up and running or free for a new client, the client may wish to start a new kernel.
Please note that the kernel will need some time to start up and initialize before it is able to execute commands. Requests which are made before the initialization is finished are blocked; execute or poke transactions are rejected.
After starting the kernel the client may simply state a request if it does not want to idle loop and try to execute the first command. The transaction will be blocked until the kernel is ready.