This is documentation for Mathematica 5, which was
based on an earlier version of the Wolfram Language.
View current documentation (Version 11.1)

Documentation / Mathematica / The Mathematica Book / Principles of Mathematica / MathLink and External Program Communication /

2.13.7 Calling Subsidiary Mathematica Processes

Connecting to a subsidiary program via MathLink.

This starts a subsidiary Mathematica process on the computer system used here.

In[1]:=link = LinkLaunch["math -mathlink"]

Out[1]=LinkObject[math -mathlink, 4, 4]

Here is a packet representing the first input prompt from the subsidiary Mathematica process.

In[2]:= LinkRead[link]

Out[2]=InputNamePacket[In[1]:= ]

This writes a packet representing text to enter in the subsidiary Mathematica process.

In[3]:= LinkWrite[link, EnterTextPacket["10!"]]

Here is a packet representing the output prompt from the subsidiary Mathematica process.

In[4]:= LinkRead[link]

Out[4]=OutputNamePacket[Out[1]= ]

And here is the actual result from the computation.

In[5]:= LinkRead[link]

Out[5]=ReturnTextPacket[3628800]

The basic way that the various different objects involved in a Mathematica session are kept organized is by using MathLink packets. A MathLink packet is simply an expression with a definite head that indicates its role or meaning.

Basic packets used in Mathematica sessions.

The fact that LinkRead returns an InputNamePacket indicates that the subsidiary Mathematica is now ready for new input.

In[6]:= LinkRead[link]

Out[6]=InputNamePacket[In[2]:= ]

This enters two Print commands as input.

In[7]:= LinkWrite[link, EnterTextPacket["Print[a]; Print[b];"]]

Here is the text from the first Print.

In[8]:= LinkRead[link]

Out[8]=TextPacket[a
]

And here is the text from the second Print.

In[9]:= LinkRead[link]

Out[9]=TextPacket[b
]

No output line is generated, so the new packet is an InputNamePacket.

In[10]:= LinkRead[link]

Out[10]=InputNamePacket[In[3]:= ]

Some additional packets generated in Mathematica sessions.

If you enter input to Mathematica using EnterTextPacket["input"], then Mathematica will automatically generate a string version of your output, and will respond with ReturnTextPacket["output"]. But if you instead enter input using EnterExpressionPacket[expr] then Mathematica will respond with ReturnExpressionPacket[expr] and will not turn your output into a string.

Packets for representing input and output lines using expressions.

This enters an expression into the subsidiary Mathematica session without evaluating it.

In[11]:= LinkWrite[link, Unevaluated[EnterExpressionPacket[
Factor[x^6 - 1]]]]

Here are the next 3 packets that come back from the subsidiary Mathematica session.

In[12]:= Table[LinkRead[link], {3}]

Out[12]=

InputNamePacket and OutputNamePacket packets are often convenient for making it possible totell the current state of a subsidiary Mathematica session. But you can suppress the generation of these packets by calling the subsidiary Mathematica session with a string such as "math -mathlink -batchoutput".

Even if you suppress the explicit generation of InputNamePacket and OutputNamePacket packets, Mathematica will still process any input that you give with EnterTextPacket or EnterExpressionPacket as if you were entering an input line. This means for example that Mathematica will call $Pre and $Post, and will assign values to In[$Line] and Out[$Line].

Evaluating expressions without explicit input and output lines.

This sends an EvaluatePacket. The Unevaluated prevents evaluation before the packet is sent.

In[13]:= LinkWrite[link, Unevaluated[EvaluatePacket[10!]]]

The result is a pure ReturnPacket.

In[14]:= LinkRead[link]

Out[14]=

This sends an EvaluatePacket requesting evaluation of Print[x].

In[15]:= LinkWrite[link, Unevaluated[EvaluatePacket[Print[x]]]]

The first packet to come back is a TextPacket representing text generated by the Print.

In[16]:= LinkRead[link]

Out[16]=TextPacket[x
]

After that, the actual result of the Print is returned.

In[17]:= LinkRead[link]

Out[17]=ReturnPacket[Null]

In most cases, it is reasonable to assume that sending an EvaluatePacket to Mathematica will simply cause Mathematica to do a computation and to return various other packets, ending with a ReturnPacket. However, if the computation involves a function like Input, then Mathematica will have to request additional input before it can proceed with the computation.

This sends a packet whose evaluation involves an Input function.

In[18]:= LinkWrite[link,
Unevaluated[EvaluatePacket[2 + Input["data ="]]]]

What comes back is an InputPacket which indicates that further input is required.

In[19]:= LinkRead[link]

Out[19]=InputPacket[data =]

There is nothing more to be read on the link at this point.

In[20]:= LinkReadyQ[link]

Out[20]=False

This enters more input.

In[21]:= LinkWrite[link, EnterTextPacket["x + y"]]

Now the Input function can be evaluated, and a ReturnPacket is generated.

In[22]:= LinkRead[link]

Out[22]=ReturnPacket[2 + x + y]

Interrupting a MathLink-compatible program.

This sends a very time-consuming calculation to the subsidiary process.

In[23]:= LinkWrite[link,
EnterTextPacket["FactorInteger[2^777-1]"]]

The calculation is still going on.

In[24]:= LinkReadyQ[link]

Out[24]=False

This sends an interrupt.

In[25]:= LinkInterrupt[link]

Now the subsidiary process has stopped, and is sending back an interrupt menu.

In[26]:= LinkRead[link]

Out[26]=MenuPacket[1, Interrupt> ]