2.13.12 Manipulating Expressions in External ProgramsMathematica expressions provide a very general way to handle all kinds of data, and you may sometimes want to use such expressions inside your external programs. A language like C, however, offers no direct way to store general Mathematica expressions. But it is nevertheless possible to do this by using the loopback links provided by the MathLink library. A loopback link is a local MathLink connection inside your external program, to which you can write expressions that can later be read back.
MLINK MLLoopbackOpen(stdenv, long *errno)
| | open a loopback link | | void MLClose(MLINK link) | close a link |
int MLTransferExpression(MLINK dest, MLINK src)
| | get an expression from src and put it onto dest |
Functions for manipulating loopback links.
...
This opens a loopback link.
ml = MLLoopbackOpen(stdenv, &errno);
This puts the expression Power[x, 3] onto the loopback link.
MLPutFunction(ml, "Power", 2);
MLPutSymbol(ml, "x");
MLPutInteger(ml, 3);
...
This gets the expression back from the loopback link.
MLGetFunction(ml, &head, &n);
MLGetSymbol(ml, &sname);
MLGetInteger(ml, &k);
...
This closes the loopback link again.
MLClose(ml);
You can use MLTransferExpression() to take an expression that you get via stdlink from Mathematica, and save it in a local loopback link for later processing. You can also use MLTransferExpression() to take an expression that you have built up on a local loopback link, and transfer it back to Mathematica via stdlink.
...
This puts 21! onto a local loopback link.
MLPutFunction(ml, "Factorial", 1);
MLPutInteger(ml, 21);
This sends the head FactorInteger to Mathematica.
MLPutFunction(stdlink, "FactorInteger", 1);
This transfers the 21! from the loopback link to stdlink.
MLTransferExpression(stdlink, ml);
You can put any sequence of expressions onto a loopback link. Usually you get the expressions off the link in the same order as you put them on. And once you have got an expression off the link it is usually no longer saved. But by using MLCreateMark() you can mark a particular position in a sequence of expressions on a link, forcing MathLink to save every expression after the mark so that you can go back to it later.
| MLMARK MLCreateMark(MLINK link) | create a mark at the current position in a sequence of expressions on a link |
MLSeekMark(MLINK link, MLMARK mark, long n)
| | go back to a position n expressions after the specified mark on a link |
MLDestroyMark(MLINK link, MLMARK mark)
| | destroy a mark in a link |
Setting up marks in MathLink links.
...
This puts the integer 45 onto a loopback link.
MLPutInteger(ml, 45);
This puts 33 onto the link.
MLPutInteger(ml, 33);
And this puts 76.
MLPutInteger(ml, 76);
This will read 45 from the link. The 45 will no longer be saved.
MLGetInteger(ml, &i);
This creates a mark at the current position on the link.
mark = MLCreateMark(ml);
This will now read 33.
MLGetInteger(ml, &i);
And this will read 76.
MLGetInteger(ml, &i);
This goes back to the position of the mark.
MLSeekMark(ml, mark, 0);
Now this will read 33 again.
MLGetInteger(ml, &i);
It is important to destroy marks when you have finished with them, so no unnecessary expressions will be saved.
MLDestroyMark(ml, mark);
The way the MathLink library is implemented, it is very efficient to open and close loopback links, and to create and destroy marks in them. The only point to remember is that as soon as you create a mark on a particular link, MathLink will save subsequent expressions that are put on that link, and will go on doing this until the mark is destroyed.
| int MLGetNext(MLINK link) | find the type of the next object on a link |
int MLGetArgCount(MLINK link, long *n)
| | store in n the number of arguments for a function on a link |
int MLGetSymbol(MLINK link, char **name)
| | get the name of a symbol |
int MLGetInteger(MLINK link, int *i)
| | get a machine integer |
int MLGetReal(MLINK link, double *x)
| | get a machine floating-point number |
int MLGetString(MLINK link, char **string)
| | get a character string |
Functions for getting pieces of expressions from a link.
| MLTKFUNC | composite function--head and arguments | | MLTKSYM | Mathematica symbol | | MLTKINT | integer | | MLTKREAL | floating-point number | | MLTKSTR | character string |
Constants returned by MLGetNext().
switch(MLGetNext(ml)) {
This reads a composite function.
case MLTKFUNC:
MLGetArgCount(ml, &n);
recurse for head
for (i = 0; i < n; i++) 
recurse for each argument
...
This reads a single symbol.
case MLTKSYM:
MLGetSymbol(ml, &name);
...
This reads a machine integer.
case MLTKINT:
MLGetInteger(ml, &i);
...
}
By using MLGetNext() it is straightforward to write programs that can read any expression. The way MathLink works, the head and arguments of a function appear as successive expressions on the link, which you read one after another. Note that if you know that the head of a function will be a symbol, then you can use MLGetFunction() instead of MLGetNext(). In this case, however, you still need to call MLDisownSymbol() to disown the memory used to store the symbol name.
| int MLPutNext(MLINK link, int type) | prepare to put an object of the specified type on a link |
int MLPutArgCount(MLINK link, long n)
| | give the number of arguments for a composite function |
int MLPutSymbol(MLINK link, char *name)
| | put a symbol on the link | | int MLPutInteger(MLINK link, int i) | put a machine integer | | int MLPutReal(MLINK link, double x) | put a machine floating-point number |
int MLPutString(MLINK link, char *string)
| | put a character string |
Functions for putting pieces of expressions onto a link. MLPutNext() specifies types of expressions using constants such as MLTKFUNC from the mathlink.h header file--just like MLGetNext().
|
