DOCUMENTATION CENTER SEARCH

com.wolfram.jlink
Interface MathLink

All Known Subinterfaces:

KernelLink, LoopbackLink

public interface MathLink

MathLink is the low-level interface that is the root of all link objects in J/Link. The methods in MathLink correspond roughly to a subset of those in the C-language MathLink API. Most programmers will deal instead with objects of type KernelLink, a higher-level interface that extends MathLink and incorporates the assumption that the program on the other side of the link is a Mathematica kernel.

You create objects of type MathLink via the MathLinkFactory.createLink() method. Again, though, most programmers will use KernelLink instead of MathLink.

Most MathLink methods throw a MathLinkException if a link-related error occurs. Examples would be calling endPacket() before sending a complete expression, or calling getFunction() when an integer is waiting on the link.

For additional information about these methods, see the J/Link User Guide, and also the MathLink documentation in the Mathematica book. Most of these methods are substantially similar, if not identical, to their C counterparts as documented in the book.

See Also:

KernelLink, MathLinkFactory

Field Summary

static int	BEGINDLGPKT Constant returned by nextPacket.
static int	CALLPKT Constant returned by nextPacket.
static int	DISPLAYENDPKT Constant returned by nextPacket.
static int	DISPLAYPKT Constant returned by nextPacket.
static int	ENDDLGPKT Constant returned by nextPacket.
static int	ENTEREXPRPKT Constant returned by nextPacket.
static int	ENTERTEXTPKT Constant returned by nextPacket.
static int	EVALUATEPKT Constant returned by nextPacket.
static int	EXPRESSIONPKT
static int	FEPKT
static int	FIRSTUSERPKT
static int	ILLEGALPKT
static int	INPUTNAMEPKT Constant returned by nextPacket.
static int	INPUTPKT Constant returned by nextPacket.
static int	INPUTSTRPKT Constant returned by nextPacket.
static int	LASTUSERPKT
static int	MENUPKT Constant returned by nextPacket.
static int	MESSAGEPKT Constant returned by nextPacket.
static int	MLABORTMESSAGE Used in putMessage() to cause the current Mathematica evaluation to be aborted.
static int	MLE_ARRAY_TOO_SHALLOW
static int	MLE_BAD_COMPLEX
static int	MLE_CONNECT_TIMEOUT
static int	MLE_CREATION_FAILED
static int	MLE_FIRST_USER_EXCEPTION
static int	MLE_LINK_IS_NULL
static int	MLE_NON_ML_ERROR
static int	MLE_OUT_OF_MEMORY
static int	MLE_WRAPPED_EXCEPTION
static int	MLEOK
static int	MLEUSER
static int	MLINTERRUPTMESSAGE
static int	MLTERMINATEMESSAGE
static int	MLTKERR
static int	MLTKFUNC Constant for use in putNext() or returned by getNext() and getType().
static int	MLTKINT Constant for use in putNext() or returned by getNext() and getType().
static int	MLTKREAL Constant for use in putNext() or returned by getNext() and getType().
static int	MLTKSTR Constant for use in putNext() or returned by getNext() and getType().
static int	MLTKSYM Constant for use in putNext() or returned by getNext() and getType().
static int	OUTPUTNAMEPKT Constant returned by nextPacket.
static int	RESUMEPKT Constant returned by nextPacket.
static int	RETURNEXPRPKT Constant returned by nextPacket.
static int	RETURNPKT Constant returned by nextPacket.
static int	RETURNTEXTPKT Constant returned by nextPacket.
static int	SUSPENDPKT Constant returned by nextPacket.
static int	SYNTAXPKT Constant returned by nextPacket.
static int	TEXTPKT Constant returned by nextPacket.
static int	TYPE_BIGDECIMAL Constant for use in getArray().
static int	TYPE_BIGINTEGER Constant for use in getArray().
static int	TYPE_BOOLEAN Constant for use in getArray().
static int	TYPE_BYTE Constant for use in getArray().
static int	TYPE_CHAR Constant for use in getArray().
static int	TYPE_COMPLEX Constant for use in getArray().
static int	TYPE_DOUBLE Constant for use in getArray().
static int	TYPE_EXPR Constant for use in getArray().
static int	TYPE_FLOAT Constant for use in getArray().
static int	TYPE_INT Constant for use in getArray().
static int	TYPE_LONG Constant for use in getArray().
static int	TYPE_SHORT Constant for use in getArray().
static int	TYPE_STRING Constant for use in getArray().

Method Summary

void	activate() Same as connect().
boolean	addMessageHandler(java.lang.Class cls, java.lang.Object obj, java.lang.String methName) Specifies the Java method you want called as a message handler.
int	bytesToGet() Returns the number of bytes that remain to be read in the element that is currently being read in textual form.
int	bytesToPut() Gives the number of bytes that remain to be sent in the element that is currently being sent in textual form.
int	checkFunction(java.lang.String f) Reads a function name and argument count and compares the function name with f.
void	checkFunctionWithArgCount(java.lang.String f, int argCount) Reads a function name and argument count and compares the function name with f and the argument count with argCount.
boolean	clearError() Clears the link error condition, if possible.
void	close() Closes the link.
void	connect() Connects the link, if it has not already been connected.
void	connect(long timeoutMillis) Connects the link, but waits at most timeoutMillis for a response from the other side.
long	createMark() Creates a mark at the current point in the incoming MathLink data stream.
void	destroyMark(long mark) Destroys a mark.
void	endPacket() Call it when you are finished writing the contents of a single packet.
int	error() Gives the code corresponding to the current error state of the link.
java.lang.String	errorMessage() Gives a textual message describing the current error.
void	flush() Immediately transmits any data buffered for sending over the link.
int	getArgCount() Reads the argument count of an expression being read manually.
java.lang.Object	getArray(int type, int depth) Reads an array of the specified type and depth.
java.lang.Object	getArray(int type, int depth, java.lang.String[] heads) Reads an array of the specified type and depth and records the heads at each level.
boolean	getBoolean() Reads the Mathematica symbols True or False as a boolean.
boolean[]	getBooleanArray1() Reads a list as a one-dimensional array of booleans.
boolean[][]	getBooleanArray2() Reads an array as a two-dimensional array of booleans.
byte[]	getByteArray1() Reads a list or array as a one-dimensional array of bytes.
byte[][]	getByteArray2() Reads an array as a two-dimensional array of bytes.
byte[]	getByteString(int missing) Reads a Mathematica string as an array of bytes.
char[]	getCharArray1() Reads a list or array as a one-dimensional array of chars.
char[][]	getCharArray2() Reads an array as a two-dimensional array of chars.
java.lang.Object	getComplex() Reads a complex number.
java.lang.Object[]	getComplexArray1() Reads a list as a one-dimensional array of complex numbers.
java.lang.Object[][]	getComplexArray2() Reads a matrix as a two-dimensional array of complex numbers.
java.lang.Class	getComplexClass() Gives the Java class that you have specified to map to Mathematica's Complex numbers.
byte[]	getData(int len) Gets a specified number of bytes in the textual form of the expression currently being read.
double	getDouble() Reads a Mathematica real number or integer as a double.
double[]	getDoubleArray1() Reads a list or array as a one-dimensional array of doubles.
double[][]	getDoubleArray2() Reads an array as a two-dimensional array of doubles.
Expr	getExpr() Reads an expression from the link and creates an Expr from it.
float[]	getFloatArray1() Reads a list or array as a one-dimensional array of floats.
float[][]	getFloatArray2() Reads an array as a two-dimensional array of floats.
MLFunction	getFunction() Reads a function name and argument count.
int[]	getIntArray1() Reads a list or array as a one-dimensional array of ints.
int[][]	getIntArray2() Reads an array as a two-dimensional array of ints.
int	getInteger() Reads a Mathematica integer as an int.
long[]	getLongArray1() Reads a list as a one-dimensional array of longs.
long[][]	getLongArray2() Reads an array as a two-dimensional array of longs.
long	getLongInteger() Reads a Mathematica integer as a long.
int	getMessage() Deprecated.
int	getNext() Gives the type of the next element in the expression currently being read.
short[]	getShortArray1() Reads a list or array as a one-dimensional array of shorts.
short[][]	getShortArray2() Reads an array as a two-dimensional array of shorts.
java.lang.String	getString() Reads a Mathematica character string.
java.lang.String[]	getStringArray1() Reads a list as a one-dimensional array of strings.
java.lang.String[][]	getStringArray2() Reads an array as a two-dimensional array of strings.
java.lang.String	getSymbol() Reads a Mathematica symbol as a string.
int	getType() Gives the type of the current element in the expression currently being read.
boolean	messageReady() Deprecated.
java.lang.String	name() Gives the name of the link.
void	newPacket() Discards the current packet, if it has been partially read.
int	nextPacket() "Opens" the next packet arriving on the link.
Expr	peekExpr() Creates an Expr from the current expression, but does not drain it off the link.
void	put(boolean b) Sends the boolean value as the Mathematica symbol True or False.
void	put(double d) Sends a double value.
void	put(int i) Sends an integer value.
void	put(long i) Sends a long value.
void	put(java.lang.Object obj) Sends an object, including strings and arrays.
void	put(java.lang.Object obj, java.lang.String[] heads) Sends an array object.
void	putArgCount(int argCount) Specifies the argument count for a composite expression being sent manually.
void	putByteString(byte[] data) Sends an array of bytes to Mathematica as a string.
void	putData(byte[] data) Used for sending elements in textual form.
void	putData(byte[] data, int len) An alternative form of putData() that lets you specify how many bytes from the array should be sent, rather than just sending the whole thing.
void	putFunction(java.lang.String f, int argCount) Sends a function name and argument count.
void	putMessage(int msg) Sends a low-level MathLink message.
void	putNext(int type) Identifies the type of data element that is to be sent.
void	putSize(int size) Specifies the size in bytes of an element being sent in textual form.
void	putSymbol(java.lang.String s) Sends a symbol name.
boolean	ready() Indicates whether the link has data waiting to be read.
boolean	removeMessageHandler(java.lang.String methName) Removes a message handler you previously set up with addMessageHandler.
void	seekMark(long mark) Resets the current position in the incoming MathLink data stream to an earlier point.
boolean	setComplexClass(java.lang.Class cls) Specifies the class you want to map to Mathematica's Complex numbers.
void	setError(int err) Sets the link's error state to the specified value.
boolean	setYieldFunction(java.lang.Class cls, java.lang.Object obj, java.lang.String methName) Sets the Java method you want called as a yield function.
void	transferExpression(MathLink source) Writes a complete expression from the link source to this link.
void	transferToEndOfLoopbackLink(LoopbackLink source) Writes the entire contents of the LoopbackLink source to this link.

Field Detail

ILLEGALPKT

static final int ILLEGALPKT

See Also:

Constant Field Values

CALLPKT

static final int CALLPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

EVALUATEPKT

static final int EVALUATEPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

RETURNPKT

static final int RETURNPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

INPUTNAMEPKT

static final int INPUTNAMEPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

ENTERTEXTPKT

static final int ENTERTEXTPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

ENTEREXPRPKT

static final int ENTEREXPRPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

OUTPUTNAMEPKT

static final int OUTPUTNAMEPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

RETURNTEXTPKT

static final int RETURNTEXTPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

RETURNEXPRPKT

static final int RETURNEXPRPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

DISPLAYPKT

static final int DISPLAYPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

DISPLAYENDPKT

static final int DISPLAYENDPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

MESSAGEPKT

static final int MESSAGEPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

TEXTPKT

static final int TEXTPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

INPUTPKT

static final int INPUTPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

INPUTSTRPKT

static final int INPUTSTRPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

MENUPKT

static final int MENUPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

SYNTAXPKT

static final int SYNTAXPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

SUSPENDPKT

static final int SUSPENDPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

RESUMEPKT

static final int RESUMEPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

BEGINDLGPKT

static final int BEGINDLGPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

ENDDLGPKT

static final int ENDDLGPKT

Constant returned by nextPacket.

See Also:

Constant Field Values

FIRSTUSERPKT

static final int FIRSTUSERPKT

See Also:

Constant Field Values

LASTUSERPKT

static final int LASTUSERPKT

See Also:

Constant Field Values

FEPKT

static final int FEPKT

See Also:

Constant Field Values

EXPRESSIONPKT

static final int EXPRESSIONPKT

See Also:

Constant Field Values

MLTERMINATEMESSAGE

static final int MLTERMINATEMESSAGE

See Also:

Constant Field Values

MLINTERRUPTMESSAGE

static final int MLINTERRUPTMESSAGE

See Also:

Constant Field Values

MLABORTMESSAGE

static final int MLABORTMESSAGE

Used in putMessage() to cause the current Mathematica evaluation to be aborted.

See Also:

Constant Field Values

MLTKFUNC

static final int MLTKFUNC

Constant for use in putNext() or returned by getNext() and getType().

See Also:

Constant Field Values

MLTKSTR

static final int MLTKSTR

Constant for use in putNext() or returned by getNext() and getType().

See Also:

Constant Field Values

MLTKSYM

static final int MLTKSYM

Constant for use in putNext() or returned by getNext() and getType().

See Also:

Constant Field Values

MLTKREAL

static final int MLTKREAL

Constant for use in putNext() or returned by getNext() and getType().

See Also:

Constant Field Values

MLTKINT

static final int MLTKINT

Constant for use in putNext() or returned by getNext() and getType().

See Also:

Constant Field Values

MLTKERR

static final int MLTKERR

See Also:

Constant Field Values

MLEOK

static final int MLEOK

See Also:

Constant Field Values

MLEUSER

static final int MLEUSER

See Also:

Constant Field Values

MLE_NON_ML_ERROR

static final int MLE_NON_ML_ERROR

See Also:

Constant Field Values

MLE_LINK_IS_NULL

static final int MLE_LINK_IS_NULL

See Also:

Constant Field Values

MLE_OUT_OF_MEMORY

static final int MLE_OUT_OF_MEMORY

See Also:

Constant Field Values

MLE_ARRAY_TOO_SHALLOW

static final int MLE_ARRAY_TOO_SHALLOW

See Also:

Constant Field Values

MLE_BAD_COMPLEX

static final int MLE_BAD_COMPLEX

See Also:

Constant Field Values

MLE_CREATION_FAILED

static final int MLE_CREATION_FAILED

See Also:

Constant Field Values

MLE_CONNECT_TIMEOUT

static final int MLE_CONNECT_TIMEOUT

See Also:

Constant Field Values

MLE_WRAPPED_EXCEPTION

static final int MLE_WRAPPED_EXCEPTION

See Also:

Constant Field Values

MLE_FIRST_USER_EXCEPTION

static final int MLE_FIRST_USER_EXCEPTION

See Also:

Constant Field Values

TYPE_BOOLEAN

static final int TYPE_BOOLEAN

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_BYTE

static final int TYPE_BYTE

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_CHAR

static final int TYPE_CHAR

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_SHORT

static final int TYPE_SHORT

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_INT

static final int TYPE_INT

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_LONG

static final int TYPE_LONG

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_FLOAT

static final int TYPE_FLOAT

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_DOUBLE

static final int TYPE_DOUBLE

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_STRING

static final int TYPE_STRING

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_BIGINTEGER

static final int TYPE_BIGINTEGER

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_BIGDECIMAL

static final int TYPE_BIGDECIMAL

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_EXPR

static final int TYPE_EXPR

Constant for use in getArray().

See Also:

Constant Field Values

TYPE_COMPLEX

static final int TYPE_COMPLEX

Constant for use in getArray().

See Also:

Constant Field Values

Method Detail

close

void close()

Closes the link. Always call close() on every link when you are done using it.

connect

void connect()
             throws MathLinkException

Connects the link, if it has not already been connected. There is a difference between opening a link (which is what the MathLinkFactory methods createLink() and createKernelLink() do) and connecting it, which verifies that it is alive and ready for data transfer.

All the methods that read from the link will connect it if necessary. The connect() method lets you deliberately control the point in the program where the connection occurs, without having to read anything.

Throws:

MathLinkException

connect

void connect(long timeoutMillis)
             throws MathLinkException

Connects the link, but waits at most timeoutMillis for a response from the other side. If the timeout passes, a MathLinkException is thrown. This is a handy way to prevent your thread from hanging indefinitely if there is a problem in connecting. Such problems are not hard to generate--for example, if the user launches a process other than a Mathematica kernel in their arguments to MathLinkFactory.createKernelLink(), the Java side will likely hang at the stage of connecting. If the timeout passes and an exception is thrown, the link cannot be salvaged and should be closed. Make sure you give adequate time for the kernel to launch.

Parameters:

timeoutMillis - the number of milliseconds to wait

Throws:

MathLinkException

See Also:

connect()

activate

void activate()
              throws MathLinkException

Same as connect().

Throws:

MathLinkException

See Also:

connect()

name

java.lang.String name()
                      throws MathLinkException

Gives the name of the link. For typical links, the name of a listen-mode link can be used by the other side to connect to.

Throws:

MathLinkException

newPacket

void newPacket()

Discards the current packet, if it has been partially read. Has no effect if the previous packet was fully read.

This is a useful cleanup function. You can call it when you are finished examining the contents of a packet that was opened with nextPacket() or waitForAnswer(), whether you have read the entire packet contents or not. You can be sure that the link is then in a state where you are ready to read the next packet.

It is also frequently used in a catch block for a MathLinkException, to clear off any unread data in a packet before returning to the normal program flow.

See Also:

nextPacket()

nextPacket

int nextPacket()
               throws MathLinkException

"Opens" the next packet arriving on the link. It is an error to call nextPacket() while the current packet has unread data; use newPacket() to discard the current packet first.

Most programmers will use this method rarely, if ever. J/Link provides higher-level functions in the KernelLink interface that hide these low-level details of the packet loop.

Returns:

the packet type (e.g., RETURNPKT, TEXTPKT).

Throws:

MathLinkException

See Also:

newPacket()

endPacket

void endPacket()
               throws MathLinkException

Call it when you are finished writing the contents of a single packet.

Calling endPacket() is not strictly necessary, but it is good style, and it allows J/Link to immediately generate a MathLinkException if you are not actually finished with writing the data you promised to send.

Throws:

MathLinkException

error

int error()

Gives the code corresponding to the current error state of the link.

Returns:

the error code; will be MLEOK if no error.

See Also:

errorMessage(), clearError()

clearError

boolean clearError()

Clears the link error condition, if possible. After an error has occurred, and a MathLinkException has been caught, you must call clearError() before doing anything else with the link.

Returns:

true, if the error state was cleared; false, if the error could not be cleared. If false, you must close the link.

errorMessage

java.lang.String errorMessage()

Gives a textual message describing the current error.

Returns:

the error message

See Also:

error()

setError

void setError(int err)

Sets the link's error state to the specified value. Afterwards, error() will return this value. Very few programmers will have any need for this method.

Parameters:

err - the error code

ready

boolean ready()
              throws MathLinkException

Indicates whether the link has data waiting to be read. In other words, it tells whether the next call that reads data will block or not.

Returns:

true, if data is waiting; false otherwise

Throws:

MathLinkException

flush

void flush()
           throws MathLinkException

Immediately transmits any data buffered for sending over the link.

Any calls that read from the link will flush it, so you only need to call flush() manually if you want to make sure data is sent right away even though you are not reading from the link immediately. Calls to ready() will not flush the link, so if you are sending something and then polling ready() waiting for the result to arrive (as opposed to just calling nextPacket() or waitForAnswer()), you must call flush to ensure that the data is sent.

Throws:

MathLinkException

getNext

int getNext()
            throws MathLinkException

Gives the type of the next element in the expression currently being read.

To check the type of a partially read element without advancing to the next element, use getType().

Returns:

one of MLTKINT, MLTKREAL, MLTKSTR, MLTKSYM, MLTKFUNC

Throws:

MathLinkException

getType

int getType()
            throws MathLinkException

Gives the type of the current element in the expression currently being read.

Unlike getNext(), getType() will not advance to the next element if the current element has only been partially read.

Returns:

one of MLTKINT, MLTKREAL, MLTKSTR, MLTKSYM, MLTKFUNC

Throws:

MathLinkException

See Also:

getNext()

putNext

void putNext(int type)
             throws MathLinkException

Identifies the type of data element that is to be sent.

putNext() is rarely needed. The two most likely uses are to put expressions whose heads are not mere symbols (e.g., Derivative[2][f]) or to put data in textual form. Calls to putNext() must be followed by putSize() and putData(), or by putArgCount() for the MLTKFUNC type. Here is how you could send Derivative[2][f]:

 ml.putNext(MathLink.MLTKFUNC);  // The func we are putting has head Derivative[2], arg f
 ml.putArgCount(1);  // this 1 is for the 'f'
 ml.putNext(MathLink.MLTKFUNC);  // The func we are putting has head Derivative, arg 2
 ml.putArgCount(1);  // this 1 is for the '2'
 ml.putSymbol("Derivative");
 ml.put(2);
 ml.putSymbol("f");

Parameters:

type - one of MLTKINT, MLTKREAL, MLTKSTR, MLTKSYM, MLTKFUNC

Throws:

MathLinkException

See Also:

putSize(int), putData(byte[]), putArgCount(int)

getArgCount

int getArgCount()
                throws MathLinkException

Reads the argument count of an expression being read manually.

This method can be used after getNext() or getType() returns the value MLTKFUNC. The argument count is always followed by the head of the expression. The head is followed by the arguments; the argument count tells how many there will be.

Returns:

the number of arguments in the expression being read

Throws:

MathLinkException

See Also:

getNext(), getType()

putArgCount

void putArgCount(int argCount)
                 throws MathLinkException

Specifies the argument count for a composite expression being sent manually.

Use it after a call to putNext() with the MLTKFUNC type.

Parameters:

argCount - the number of aruments in the expression being sent

Throws:

MathLinkException

See Also:

putNext(int)

putSize

void putSize(int size)
             throws MathLinkException

Specifies the size in bytes of an element being sent in textual form.

A typical sequence would be putNext(), followed by putSize(), then putData().

Parameters:

size - the size of the data, in bytes, that will be written with the following putData()

Throws:

MathLinkException

See Also:

putData(byte[]), putNext(int)

bytesToPut

int bytesToPut()
               throws MathLinkException

Gives the number of bytes that remain to be sent in the element that is currently being sent in textual form.

After you have called putSize(), the link knows how many bytes you have promised to send. This method lets you determine how many you still need to send, in the unlikely event that you lose track after a series of putData() calls.

Returns:

the number of bytes that remain to be sent

Throws:

MathLinkException

See Also:

putSize(int), putData(byte[])

bytesToGet

int bytesToGet()
               throws MathLinkException

Returns the number of bytes that remain to be read in the element that is currently being read in textual form.

Lets you keep track of your progress reading an element through a series of getData() calls.

Returns:

the number of bytes that remain to be read in the current element

Throws:

MathLinkException

MathLinkException

See Also:

getData(int)

putData

void putData(byte[] data)
             throws MathLinkException

Used for sending elements in textual form. After calling putNext() and putSize(), a series of putData() calls are used to send the actual data.

The so-called "textual" means of sending data is rarely used. Its main use is to allow a very large string to be sent, where the string data is not held in a single String object. The most important use of this technique in the C-language MathLink API was to send integers and reals that were too large to fit into an int or double. This use is unnecessary in J/Link, since Java has BigInteger and BigDecimal classes, and these objects can be sent directly with put().

Parameters:

data - the textual representation of the data

Throws:

MathLinkException

See Also:

putNext(int), putSize(int)

putData

void putData(byte[] data,
             int len)
             throws MathLinkException

An alternative form of putData() that lets you specify how many bytes from the array should be sent, rather than just sending the whole thing.

Parameters:

data -

len -

Throws:

MathLinkException

See Also:

putData(byte[])

getData

byte[] getData(int len)
               throws MathLinkException

Gets a specified number of bytes in the textual form of the expression currently being read. The returned array will have a length of at most len.

You can use bytesToGet() to determine if more getData() calls are needed to completely read the element.

Parameters:

len - the maximum number of bytes to read

Returns:

the data read

Throws:

MathLinkException

See Also:

bytesToGet(), getNext(), getType()

getString

java.lang.String getString()
                           throws MathLinkException

Reads a Mathematica character string.

Because both Java and Mathematica strings are in Unicode, the read string is an exact match to its Mathematica representation.

Returns:

the string that was read

Throws:

MathLinkException

getByteString

byte[] getByteString(int missing)
                     throws MathLinkException

Reads a Mathematica string as an array of bytes.

In contrast with getString(), this method strips the incoming (16-bit Unicode) character data into single-byte representation. Characters that cannot be represented faithfully in single-byte form are replaced by the byte specified by the missing parameter. This method is primarily useful if you know the incoming data contains only ASCII characters and you want the data in the form of a byte array.

Parameters:

missing - the byte to replace non-ASCII characters with

Returns:

the data that was read

Throws:

MathLinkException

See Also:

getString()

putByteString

void putByteString(byte[] data)
                   throws MathLinkException

Sends an array of bytes to Mathematica as a string.

Use this instead of put() if you have string data in the form of a byte array. In the C-language MathLink API, MLPutByteString was useful because the more obviously-named MLPutString required a specially-encoded string. Because Java strings and Mathematica strings are both Unicode, put() works in J/Link without requiring special encoding. Thus, putByteString() has little use.

Parameters:

data - the string data to send

Throws:

MathLinkException

See Also:

put(Object)

getSymbol

java.lang.String getSymbol()
                           throws MathLinkException

Reads a Mathematica symbol as a string.

Because Java strings and Mathematica symbols are in Unicode, the read string is an exact match to its Mathematica representation.

Returns:

the symbol

Throws:

MathLinkException

See Also:

getString()

putSymbol

void putSymbol(java.lang.String s)
               throws MathLinkException

Sends a symbol name.

Both Java strings and Mathematica symbols are in Unicode, so you can send symbols with the full Unicode character set.

Parameters:

s - the symbol name

Throws:

MathLinkException

getBoolean

boolean getBoolean()
                   throws MathLinkException

Reads the Mathematica symbols True or False as a boolean. More precisely, it returns true if the symbol True is read, and false if False (or any other non-True symbol) is read. If you want to make sure that either True or False is on the link, don't use getBoolean(); instead, read the symbol with getSymbol() and test its value yourself.

Returns:

the boolean read

Throws:

MathLinkException

put

void put(boolean b)
         throws MathLinkException

Sends the boolean value as the Mathematica symbol True or False.

Parameters:

b - the value to send

Throws:

MathLinkException

getInteger

int getInteger()
               throws MathLinkException

Reads a Mathematica integer as an int.

Returns:

the integer read

Throws:

MathLinkException

put

void put(int i)
         throws MathLinkException

Sends an integer value.

Parameters:

i - the int to send

Throws:

MathLinkException

getLongInteger

long getLongInteger()
                    throws MathLinkException

Reads a Mathematica integer as a long.

Returns:

the long that was read

Throws:

MathLinkException

put

void put(long i)
         throws MathLinkException

Sends a long value.

Parameters:

i - the value to send

Throws:

MathLinkException

getDouble

double getDouble()
                 throws MathLinkException

Reads a Mathematica real number or integer as a double.

Returns:

the double value read

Throws:

MathLinkException

put

void put(double d)
         throws MathLinkException

Sends a double value.

Parameters:

d - the double to send

Throws:

MathLinkException

getBooleanArray1

boolean[] getBooleanArray1()
                           throws MathLinkException

Reads a list as a one-dimensional array of booleans.

The expression being read must be a list or other depth-1 expression of the symbols True and False. The "1" suffix in the method name indicates that the returned array has depth 1.

The expression does not need to have head List. In other words, it could be List[False, True] or Foo[True, True]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

Returns:

the array read

Throws:

MathLinkException - if the incoming expression is not a depth-1 array of True and False

See Also:

getArray(int, int)

getBooleanArray2

boolean[][] getBooleanArray2()
                             throws MathLinkException

Reads an array as a two-dimensional array of booleans.

The expression being read must be a matrix of the symbols True and False. The "2" suffix in the method name indicates that the returned array has depth 2.

The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[True, False], List[True, True]] or Foo[Bar[True, False], Bar[True, True]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

Returns:

the array read

Throws:

MathLinkException - if the incoming expression is not a 2-deep array of True and False

See Also:

getArray(int, int)

getByteArray1

byte[] getByteArray1()
                     throws MathLinkException

Reads a list or array as a one-dimensional array of bytes.

The expression being read must be a list or deeper array of integers. Values outside the range of a byte are converted via casting. The "1" suffix in the method name indicates that the returned array has depth 1. If the arriving expression has depth greater than 1 (e.g., it is a matrix), it will be flattened to a 1-dimensional array.

The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

Returns:

the array read

Throws:

MathLinkException - if the incoming expression is not an array of integers

See Also:

getArray(int, int)

getByteArray2

byte[][] getByteArray2()
                       throws MathLinkException

Reads an array as a two-dimensional array of bytes.

The expression being read must be a matrix or deeper array of integers. Values outside the range of a byte are converted via casting. The "2" suffix in the method name indicates that the returned array has depth 2. If the arriving expression has depth greater than 2, it will be flattened to a 2-dimensional array. If the arriving expression has a depth less than 2 (i.e., it is a flat list), a MathLinkException will be thrown.

The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

Returns:

the array read

Throws:

MathLinkException - if the incoming expression is not an array of integers

See Also:

getArray(int, int)

getCharArray1

char[] getCharArray1()
                     throws MathLinkException

Reads a list or array as a one-dimensional array of chars.

The expression being read must be a list or deeper array of integers. Values outside the range of a char are converted via casting. The "1" suffix in the method name indicates that the returned array has depth 1. If the arriving expression has depth greater than 1 (e.g., it is a matrix), it will be flattened to a 1-dimensional array.

The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

Returns:

the array read

Throws:

MathLinkException - if the incoming expression is not an array of integers

See Also:

getArray(int, int)

getCharArray2

char[][] getCharArray2()
                       throws MathLinkException

Reads an array as a two-dimensional array of chars.

The expression being read must be a matrix or deeper array of integers. Values outside the range of a char are converted via casting. The "2" suffix in the method name indicates that the returned array has depth 2. If the arriving expression has depth greater than 2, it will be flattened to a 2-dimensional array. If the arriving expression has a depth less than 2 (i.e., it is a flat list), a MathLinkException will be thrown.

The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

Returns:

the array read

Throws:

MathLinkException - if the incoming expression is not an array of integers

See Also:

getArray(int, int)

getShortArray1

short[] getShortArray1()
                       throws MathLinkException

Reads a list or array as a one-dimensional array of shorts.

The expression being read must be a list or deeper array of integers. Values outside the range of a short are converted via casting. The "1" suffix in the method name indicates that the returned array has depth 1. If the arriving expression has depth greater than 1 (e.g., it is a matrix), it will be flattened to a 1-dimensional array.

The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

Returns:

the array read

Throws:

MathLinkException - if the incoming expression is not an array of integers

See Also:

getArray(int, int)

getShortArray2

short[][] getShortArray2()
                         throws MathLinkException

Reads an array as a two-dimensional array of shorts.

The expression being read must be a matrix or deeper array of integers. Values outside the range of a short are converted via casting. The "2" suffix in the method name indicates that the returned array has depth 2. If the arriving expression has depth greater than 2, it will be flattened to a 2-dimensional array. If the arriving expression has a depth less than 2 (i.e., it is a flat list), a MathLinkException will be thrown.

The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

Returns:

the array read

Throws:

MathLinkException - if the incoming expression is not an array of integers

See Also:

getArray(int, int)

getIntArray1

int[] getIntArray1()
                   throws MathLinkException

Reads a list or array as a one-dimensional array of ints.

The expression being read must be a list or deeper array of integers. The "1" suffix in the method name indicates that the returned array has depth 1. If the arriving expression has depth greater than 1 (e.g., it is a matrix), it will be flattened to a 1-dimensional array.

The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

Returns:

the array read

Throws:

MathLinkException - if the incoming expression is not an array of integers

See Also:

getArray(int, int)

getIntArray2

int[][] getIntArray2()
                     throws MathLinkException

Reads an array as a two-dimensional array of ints.

The expression being read must be a matrix or deeper array of integers. The "2" suffix in the method name indicates that the returned array has depth 2. If the arriving expression has depth greater than 2, it will be flattened to a 2-dimensional array. If the arriving expression has a depth less than 2 (i.e., it is a flat list), a MathLinkException will be thrown.

The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

Returns:

the array read

Throws:

MathLinkException - if the incoming expression is not an array of integers

See Also:

getArray(int, int)