This is documentation for Mathematica 3, which was
based on an earlier version of the Wolfram Language.
View current documentation (Version 11.2)
 Documentation / Mathematica / The Mathematica Book / Principles of Mathematica / MathLink and External Program Communication  /

2.12.14 Running Mathematica from Within an External Program

To run Mathematica from within an external program requires making use of many general features of MathLink. The first issue is how to establish a MathLink connection to Mathematica.
When you use MathLink templates to create external programs that can be called from Mathematica, source code to establish a MathLink connection is automatically generated, and all you have to do in your external program is to call MLMain(argc,argv). But in general you need to call several functions to establish a MathLink connection.


Opening and closing MathLink connections.


  • Include the standard MathLink header file.
  • #include "mathlink.h"

    int main(int argc, char *argv[]) {

    MLENV env;
    MLINK link;
    long errno;

  • This initializes MathLink library functions.
  • env = MLInitialize(0);

  • This opens a MathLink connection, using the same arguments as were passed to the main program.
  • link = MLOpenArgv(env, argv, argv+argc, &errno);

  • This activates the connection, waiting for the other program to respond.
  • MLActivate(link);

    ...
    }


    Often the argv that you pass to MLOpenArgv() will come directly from the argv that is passed to main() when your whole program is started. Note that MLOpenArgv() takes pointers to the beginning and end of the argv array. By not using argc directly it avoids having to know the size of an int.
    The elements in the argv array are character strings which mirror the arguments and options used in the Mathematica functions LinkLaunch, LinkCreate and LinkConnect.


    Possible elements of the argv array passed to MLOpenArgv().

    As an alternative to MLOpenArgv() you can use MLOpenString(), which takes parameters concatenated into a single character string with spaces in between.
    Once you have successfully opened a MathLink connection to the Mathematica kernel, you can then use standard MathLink functions to exchange data with it.


    Functions often used in communicating with the Mathematica kernel.

    Once you have sent all the pieces of a packet using MLPutFunction() etc., MathLink requires you to call MLEndPacket() to ensure synchronization and consistency.
    One of the main issues in writing an external program which communicates directly with the Mathematica kernel is handling all the various kinds of packets that the kernel can generate.
    The function MLNextPacket() finds the head of the next packet that comes from the kernel, and returns a constant that indicates the type of the packet.


    Some packets recognized by MLNextPacket().


  • This keeps on reading data from a link, discarding it until an error or a ReturnPacket is found.
  • while ((p = MLNextPacket(link)) && p != RETURNPKT)
    MLNewPacket(link);


    If you want to write a complete front end to Mathematica, you will need to handle all of the possible types of packets that the kernel can generate. Typically you can do this by setting up an appropriate switch on the value returned by MLNextPacket().
    The MathLink Developer's Kit contains sample source code for several simple but complete front ends.


    Flow of data on links.

    One feature of more sophisticated external programs such as front ends is that they may need to perform operations while they are waiting for data to be sent to them by Mathematica. When you call a standard MathLink library function such as MLNextPacket() your program will normally block until all the data needed by this function is available.
    You can avoid blocking by repeatedly calling MLReady(), and only calling functions like MLNextPacket() when MLReady() no longer returns 0. MLReady() is the analog of the Mathematica function LinkReadyQ.
    Note that MathLink sometimes buffers the data that you tell it to send. To make sure that all necessary data has been sent you should call MLFlush(). Only after doing this does it make sense to call MLReady() and wait for data to be sent back.