Calling Subsidiary Wolfram System Processes—Wolfram Documentation

WOLFRAM

Wolfram Language & System Documentation Center
Calling Subsidiary Wolfram System Processes

Calling Subsidiary Wolfram System Processes

Connecting to a subsidiary program via WSTP.
This starts a subsidiary Wolfram System process on the computer system used here:
Wolfram Language code: link = LinkLaunch["math -mathlink"]
Here is a packet representing the first input prompt from the subsidiary Wolfram System process:
Wolfram Language code: LinkRead[link]
This writes a packet representing text to enter in the subsidiary process:
Wolfram Language code: LinkWrite[link, EnterTextPacket["10!"]]
Here is a packet representing the output prompt from the subsidiary process:
Wolfram Language code: LinkRead[link]
And here is the actual result from the computation:
Wolfram Language code: LinkRead[link]
The basic way that the various different objects involved in a Wolfram System session are kept organized is by using Wolfram Symbolic Transfer Protocol (WSTP) packets. A WSTP packet is simply an expression with a definite head that indicates its role or meaning.
EnterTextPacket["input"]
text to enter corresponding to an input line
ReturnTextPacket["output"]
text returned corresponding to an output line
InputNamePacket["name"]
text returned for the name of an input line
OutputNamePacket["name"]
text returned for the name of an output line
Basic packets used in Wolfram System sessions.
The fact that LinkRead returns an InputNamePacket indicates that the subsidiary Wolfram System is now ready for new input:
Wolfram Language code: LinkRead[link]
This enters two Print commands as input:
Wolfram Language code: LinkWrite[link, EnterTextPacket["Print[a]; Print[b];"]]
Here is the text from the first Print:
Wolfram Language code: LinkRead[link]
And here is the text from the second Print:
Wolfram Language code: LinkRead[link]
No output line is generated, so the new packet is an InputNamePacket:
Wolfram Language code: LinkRead[link]
TextPacket["string"]
text from Print etc.
MessagePacket[symb,"tag"]
a message name
DisplayPacket["string"]
parts of PostScript graphics
DisplayEndPacket["string"]
the end of PostScript graphics
Some additional packets generated in Wolfram System sessions.
If you enter input to the Wolfram Language using EnterTextPacket["input"], then the Wolfram Language 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 the Wolfram Language will respond with ReturnExpressionPacket[expr] and will not turn your output into a string.
EnterExpressionPacket[expr]
an expression to enter corresponding to an input line
ReturnExpressionPacket[expr]
an expression returned corresponding to an output line
Packets for representing input and output lines using expressions.
This enters an expression into the subsidiary Wolfram System session without evaluating it:
Wolfram Language code: LinkWrite[link, Unevaluated[EnterExpressionPacket[Factor[x ^ 6 - 1]]]]
Here are the next 3 packets that come back from the subsidiary Wolfram System session:
Wolfram Language code: Table[LinkRead[link], {3}]
InputNamePacket and OutputNamePacket packets are often convenient for making it possible to tell the current state of a subsidiary Wolfram System session. But you can suppress the generation of these packets by calling the subsidiary Wolfram System session with a string such as "math -mathlink -batchoutput".
Even if you suppress the explicit generation of InputNamePacket and OutputNamePacket packets, the Wolfram System 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 the Wolfram Language will call $Pre and $Post, and will assign values to In[$Line] and Out[$Line].
EvaluatePacket[expr]
an expression to be sent purely for evaluation
ReturnPacket[expr]
an expression returned from an evaluation
Evaluating expressions without explicit input and output lines.
This sends an EvaluatePacket. The Unevaluated prevents evaluation before the packet is sent:
Wolfram Language code: LinkWrite[link, Unevaluated[EvaluatePacket[10!]]]
The result is a pure ReturnPacket:
Wolfram Language code: LinkRead[link]
This sends an EvaluatePacket requesting evaluation of Print[x]:
Wolfram Language code: LinkWrite[link, Unevaluated[EvaluatePacket[Print[x]]]]
The first packet to come back is a TextPacket representing text generated by the Print:
Wolfram Language code: LinkRead[link]
After that, the actual result of the Print is returned:
Wolfram Language code: LinkRead[link]
In most cases, it is reasonable to assume that sending an EvaluatePacket to the Wolfram System will simply cause the Wolfram System to do a computation and to return various other packets, ending with a ReturnPacket. However, if the computation involves a function like Input, then the Wolfram System will have to request additional input before it can proceed with the computation.
This sends a packet whose evaluation involves an Input function:
Wolfram Language code: LinkWrite[link, Unevaluated[EvaluatePacket[2 + Input["data ="]]]]
What comes back is an InputPacket, which indicates that further input is required:
Wolfram Language code: LinkRead[link]
There is nothing more to be read on the link at this point:
Wolfram Language code: LinkReadyQ[link]
This enters more input:
Wolfram Language code: LinkWrite[link, EnterTextPacket["x + y"]]
Now the Input function can be evaluated, and a ReturnPacket is generated:
Wolfram Language code: LinkRead[link]
Interrupting a WSTP-compatible program.
This sends a very time‐consuming calculation to the subsidiary process:
Wolfram Language code: LinkWrite[link, EnterTextPacket["FactorInteger[2^777-1]"]]
The calculation is still going on:
Wolfram Language code: LinkReadyQ[link]
This sends an interrupt:
Wolfram Language code: LinkInterrupt[link]
Now the subsidiary process has stopped and is sending back an interrupt menu:
Wolfram Language code: LinkRead[link]
This closes the link:
Wolfram Language code: LinkClose[link]