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)

getLongArray1

long[] getLongArray1()
                     throws MathLinkException
Reads a list as a one-dimensional array of longs.

The expression being read must be a list or other depth-1 expression of integers. 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[1, 2] or Foo[1, 2]. 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 integers
See Also:
getArray(int, int)

getLongArray2

long[][] getLongArray2()
                       throws MathLinkException
Reads an array as a two-dimensional array of longs.

The expression being read must be a matrix of integers. 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[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 a depth-2 array of integers
See Also:
getArray(int, int)

getFloatArray1

float[] getFloatArray1()
                       throws MathLinkException
Reads a list or array as a one-dimensional array of floats.

The expression being read must be a list or deeper array of real numbers or 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 reals or integers
See Also:
getArray(int, int)

getFloatArray2

float[][] getFloatArray2()
                         throws MathLinkException
Reads an array as a two-dimensional array of floats.

The expression being read must be a matrix or deeper array of real numbers or 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 of array reals or integers
See Also:
getArray(int, int)

getDoubleArray1

double[] getDoubleArray1()
                         throws MathLinkException
Reads a list or array as a one-dimensional array of doubles.

The expression being read must be a list or deeper array of real numbers or 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 reals or integers
See Also:
getArray(int, int)

getDoubleArray2

double[][] getDoubleArray2()
                           throws MathLinkException
Reads an array as a two-dimensional array of doubles.

The expression being read must be a matrix or deeper array of real numbers or 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 reals or integers
See Also:
getArray(int, int)

getStringArray1

java.lang.String[] getStringArray1()
                                   throws MathLinkException
Reads a list as a one-dimensional array of strings.

The expression being read must be a list or other depth-1 expression of strings or symbols. 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["A", "B"] or Foo["A", "B"]. 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 strings or symbols
See Also:
getArray(int, int)

getStringArray2

java.lang.String[][] getStringArray2()
                                     throws MathLinkException
Reads an array as a two-dimensional array of strings.

The expression being read must be a matrix of strings or symbols. 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["A", "B"], List["C", D"]] or Foo[Bar["A", "B"], Bar["C", "D"]]. 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 matrix of strings or symbols
See Also:
getArray(int, int)

getComplexArray1

java.lang.Object[] getComplexArray1()
                                    throws MathLinkException
Reads a list as a one-dimensional array of complex numbers.

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

This method will read the expression, but return null, if no Java class has yet been established to use for complex numbers by calling setComplexClass.

The expression does not need to have head List. In other words, it could be List[1+I, 2-I] or Foo[1+I, 2-I]. 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, or null if no Java class has been declared for complex numbers via setComplexClass()
Throws:
MathLinkException - if the incoming expression is not a depth-1 array of Complex
See Also:
setComplexClass(Class), getArray(int, int)

getComplexArray2

java.lang.Object[][] getComplexArray2()
                                      throws MathLinkException
Reads a matrix as a two-dimensional array of complex numbers.

The expression being read must be a matrix of Complex. 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[1+I, 2-I], List[3+I, 4-I]] or Foo[Bar[1+I, 2-I], Bar[3+I, 4-I]]. 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, or null if no Java class has been declared for complex numbers via setComplexClass()
Throws:
MathLinkException - if the incoming expression is not a matrix of Complex
See Also:
setComplexClass(Class), getArray(int, int)

getArray

java.lang.Object getArray(int type,
                          int depth)
                          throws MathLinkException
Reads an array of the specified type and depth.

The getXXXArrayN methods are all just convenience methods that call this method. Use this method instead when you want to read an array of dimensionality deeper than 2. Cast the result of this method to the desired array type, as in:

     int[][][] result = (int[][][]) ml.getArray(TYPE_INT, 3); 
For the types TYPE_BYTE, TYPE_CHAR, TYPE_SHORT, TYPE_INT, TYPE_FLOAT, and TYPE_DOUBLE, if the expression has depth greater than depth, it will be flattened to a Java array of dimension depth. If the expression has a depth less than depth, a MathLinkException will be thrown.

The maximum depth supported is 5.

The expression does not need to have head List. It can have any heads, at any depth, and the heads do not have to agree at each depth, meaning that you could read the expression {foo[1, 2], bar[3, 4]} as an int[][]. The information about the heads is lost; if you need this information you can use the alternative signature getArray(int type, int depth, String[] heads), or read the expression as an Expr and examine it using the Expr methods.

Parameters:
type - The desired type for the returned array. Must be one of TYPE_BOOLEAN, TYPE_BYTE, TYPE_CHAR, TYPE_SHORT, TYPE_INT, TYPE_LONG, TYPE_FLOAT, TYPE_DOUBLE, TYPE_STRING, TYPE_BIGINTEGER, TYPE_BIGDECIMAL, TYPE_EXPR, or TYPE_COMPLEX.
depth - the depth of the returned array
Returns:
the array read, or null if type is TYPE_COMPLEX and no Java class has been declared for complex numbers via setComplexClass()
Throws:
MathLinkException - if the incoming expression is not an array of the requested type or is not as deep as requested
MathLinkException
See Also:
getArray(int, int, String[])

getArray

java.lang.Object getArray(int type,
                          int depth,
                          java.lang.String[] heads)
                          throws MathLinkException
Reads an array of the specified type and depth and records the heads at each level.

Identical to getArray(int type, int depth), except that this form fills a String array with the heads of the expression found at each level. To use this method, allocate a String array of length 'depth' and pass it in. For example:

 // Assume that the expression {foo[1, 2], foo[3, 4]} is waiting on the link.
 String[] heads = new String[2];
 int[][] intArray2D = (int[][]) ml.getArray(MathLink.TYPE_INT, 2, heads);
 // Now heads[0] is "List" and heads[1] is "foo".
This method does not enforce a requirement that the heads be identical across a level. If the expression looks like {foo[1, 2], bar[3, 4]} then the heads array would become {"List", "foo"}, ignoring the fact that foo was not the head of every subexpression at level 1. In other words, if heads[i] is "foo", then it is only guaranteed that some expression at level i had head foo, not that all of them did. If you want to be absolutely sure about the heads of every subpart, read the expression as an Expr and use the Expr methods to inspect it.

Parameters:
type - The desired type for the returned array. Must be one of TYPE_BOOLEAN, TYPE_BYTE, TYPE_CHAR, TYPE_SHORT, TYPE_INT, TYPE_LONG, TYPE_FLOAT, TYPE_DOUBLE, TYPE_STRING, TYPE_BIGINTEGER, TYPE_BIGDECIMAL, TYPE_EXPR, or TYPE_COMPLEX.
depth - the depth of the returned array
heads - an array of length 'depth' that will be filled with the heads at each level
Returns:
the array read, or null if type is TYPE_COMPLEX and no Java class has been declared for complex numbers via setComplexClass()
Throws:
MathLinkException - if the incoming expression is not an array of the requested type, or is not as deep as requested
Since:
2.0
See Also:
getArray(int, int)

getFunction

MLFunction getFunction()
                       throws MathLinkException
Reads a function name and argument count.

Returns:
an object describing the head and argument count of the function
Throws:
MathLinkException

putFunction

void putFunction(java.lang.String f,
                 int argCount)
                 throws MathLinkException
Sends a function name and argument count.

Follow this with calls to put the arguments.

Parameters:
f - the function name
argCount - the number of arguments to follow
Throws:
MathLinkException

checkFunction

int checkFunction(java.lang.String f)
                  throws MathLinkException
Reads a function name and argument count and compares the function name with f. If they do not match, a MathLinkException is thrown.

Similar to getFunction() in that it reads the name and argument count off the link. Use it in situations where you want an error to occur if the function is not what you expect.

Parameters:
f - the function name that you are expecting
Returns:
the argument count
Throws:
MathLinkException - if the current expression is not a function, or if it does not have the specified name
See Also:
checkFunctionWithArgCount(String, int)

checkFunctionWithArgCount

void checkFunctionWithArgCount(java.lang.String f,
                               int argCount)
                               throws MathLinkException
Reads a function name and argument count and compares the function name with f and the argument count with argCount. If they do not match, a MathLinkException is thrown.

Similar to getFunction() in that it reads the name and argument count off the link. Use it in situations where you want an error to occur if the function is not what you expect.

Parameters:
f - the function name that you are expecting
argCount - the argument count that you are expecting
Throws:
MathLinkException - if the current expression is not a function, or if it does not have the specified name
See Also:
checkFunction(String)

getComplex

java.lang.Object getComplex()
                            throws MathLinkException
Reads a complex number. This can be an integer, real, or a Mathematica expression with head Complex. You must first specify a Java class for complex numbers using setComplexClass().

This method will read the number, but return null, if no Java class has yet been established to use for complex numbers.

Returns:
an object of the class you have specified to map to Mathematica Complex numbers, or null if you have not specified any class (using setComplexClass()).
Throws:
MathLinkException - if the current expression is not an integer, real, or Mathematica Complex.
See Also:
setComplexClass(Class)

transferExpression

void transferExpression(MathLink source)
                        throws MathLinkException
Writes a complete expression from the link source to this link.

Parameters:
source - the link to read from
Throws:
MathLinkException
See Also:
transferToEndOfLoopbackLink(LoopbackLink)

transferToEndOfLoopbackLink

void transferToEndOfLoopbackLink(LoopbackLink source)
                                 throws MathLinkException
Writes the entire contents of the LoopbackLink source to this link.

Parameters:
source - the LoopbackLink to read from
Throws:
MathLinkException
See Also:
transferExpression(MathLink)

getExpr

Expr getExpr()
             throws MathLinkException
Reads an expression from the link and creates an Expr from it.

The returned Expr can be examined and manipulated later.

Returns:
the Expr read
Throws:
MathLinkException
See Also:
peekExpr()

peekExpr

Expr peekExpr()
              throws MathLinkException
Creates an Expr from the current expression, but does not drain it off the link.

Like getExpr(), but peekExpr() does not actually remove anything from the link. In other words, it leaves the link in the same state it was in before peekExpr() was called.

Returns:
the Expr read
Throws:
MathLinkException
See Also:
getExpr()

getMessage

int getMessage()
               throws MathLinkException
Deprecated. 

Reads a low-level MathLink message.

This method no longer functions in J/Link 2.0. You must use addMessageHandler() if you want to be able to receive messages from Mathematica.

Returns:
the message read; will most likely be one of MLINTERRUPTMESSAGE or MLABORTMESSAGE
Throws:
MathLinkException
See Also:
addMessageHandler(Class, Object, String)

putMessage

void putMessage(int msg)
                throws MathLinkException
Sends a low-level MathLink message.

To abort a Mathematica computation, use putMessage(MLABORTMESSAGE). If a computation is successfully aborted, it will return the symbol $Aborted.

Do not confuse this type of message, used mainly for communicating requests to interrupt or abort computations, with Mathematica warning messages, which are unrelated.

Parameters:
msg - the message to send; will be one of MLABORTMESSAGE or MLINTERRUPTMESSAGE. Most users will only be concerned with MLABORTMESSAGE.
Throws:
MathLinkException

messageReady

boolean messageReady()
                     throws MathLinkException
Deprecated. 

Tells whether a low-level MathLink message has arrived.

This method no longer functions in J/Link 2.0. You must use addMessageHandler() if you want to be able to receive messages from Mathematica.

Returns:
true if a message is waiting to be read with getMessage(); false otherwise
Throws:
MathLinkException
See Also:
addMessageHandler(Class, Object, String)

createMark

long createMark()
                throws MathLinkException
Creates a mark at the current point in the incoming MathLink data stream.

Marks can returned to later, to re-read data. A common use is to create a mark, call some method for reading data, and if a MathLinkException is thrown, seek back to the mark and try a different method of reading the data.

Make sure to always call destroyMark() on any marks you create. Failure to do so will cause a memory leak.

Some of the usefulness of marks in the C-language MathLink API is obviated by J/Link's Expr class.

Returns:
the mark. You cannot do anything with this value except use it in seekMark() or destroyMark(); it has no meaning as a number.
Throws:
MathLinkException
See Also:
seekMark(long), destroyMark(long)

seekMark

void seekMark(long mark)
Resets the current position in the incoming MathLink data stream to an earlier point.

Parameters:
mark - the mark, created by createMark(), that identifies the desired position to reset to
See Also:
createMark(), seekMark(long)

destroyMark

void destroyMark(long mark)
Destroys a mark. Always call destroyMark() on any marks you create with createMark().

Parameters:
mark - the mark to destroy

put

void put(java.lang.Object obj)
         throws MathLinkException
Sends an object, including strings and arrays.

Only a limited set of Java objects can be usefully sent across a link with this method. These are objects whose "values" have a meaningful representation in Mathematica:

 null: sent as the symbol Null.
 strings: sent as Mathematica strings
 arrays: sent as lists of the appropriate dimensions
 Expr: sent as expressions
 Wrapper classes (e.g., Boolean, Integer, Float, etc.): sent as their values
 BigDecimal and BigInteger: sent as their values
 complex numbers: sent as Complex
All other objects have no meaningful representation in Mathematica. For these objects, the relatively useless obj.toString() is sent. The put(Object) method in the KernelLink interface will put these objects "by reference".

Parameters:
obj - the object to put
Throws:
MathLinkException

put

void put(java.lang.Object obj,
         java.lang.String[] heads)
         throws MathLinkException
Sends an array object. Unlike put(Object), this method lets you specify the heads you want for each dimension.
     int[][] a = {{1,2},{3,4}};
     // The following are equivalent, sending to Mathematica the matrix: {{1,2},{3,4}}
     ml.put(a);
     ml.put(a, null);
     ml.put(a, new String[] {"List", "List"});

Parameters:
obj - must be an array
heads - the heads at each dimension
Throws:
MathLinkException

setComplexClass

boolean setComplexClass(java.lang.Class cls)
Specifies the class you want to map to Mathematica's Complex numbers.

After calling setComplexClass(), you can use getComplex() to read an incoming Complex and create an instance of your class, and you can use put() to send objects of your class to Mathematica as Complex.

To be suitable, your class must have a public constructor of the form MyComplex(double re, double im), and it must have two public methods double re() and double im().

Parameters:
cls - the class to map to Mathematica Complex numbers
Returns:
true, if the class is a suitable choice, false otherwise
See Also:
getComplexClass(), getComplex()

getComplexClass

java.lang.Class getComplexClass()
Gives the Java class that you have specified to map to Mathematica's Complex numbers.

You specify the class you want using setComplexClass().

Returns:
the class, or null if no class has yet been specified
See Also:
setComplexClass(Class)

setYieldFunction

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.

The method must be public and its signature must be (V)Z (e.g., public boolean foo()). You can pass null for cls if obj is provided. If the method is static, pass null as obj.

Yield functions are an advanced topic, and are discussed in greater detail in the User Guide. Few users will need to use one.

Parameters:
cls - the class in which the method resides
obj - the object on which the method should be invoked (use null if the method is static)
methName - the name of the method to invoke
Returns:
true, if the specified method is suitable (i.e., could be found, and has the correct signature); false otherwise

addMessageHandler

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.

Do not confuse this type of message, used mainly for communicating requests to interrupt or abort a computation, with Mathematica warning and error messages, which are unrelated.

The method you specify will be added to the set that are called whenever a MathLink message is received by your Java program. The method must be public and its signature must be (II)V (e.g., public void foo(int msgType, int ignore)). You can pass null for cls if obj is provided. If the method is static, pass null for obj. The first argument passed to your function when it is called is the integer code giving the message type (e.g., MLABORTMESSAGE, MLINTERRUPTMESSAGE, etc.) The second argument is undocumented and should be ignored.

Do not attempt to use the link from within your message handler function.

You can set more than one message handler, hence the name "addMessageHandler".

Message handlers are an advanced technique. Few programmers will need to use one.

Parameters:
cls - the class in which the method resides
obj - the object on which the method should be invoked (use null if the method is static)
methName - the name of the method to invoke
Returns:
true, if the specified method is suitable (i.e., could be found, and has the correct signature); false otherwise
See Also:
removeMessageHandler(String)

removeMessageHandler

boolean removeMessageHandler(java.lang.String methName)
Removes a message handler you previously set up with addMessageHandler.

Do not confuse this type of message, used mainly for communicating requests to interrupt or abort a computation, with Mathematica warning and error messages, which are unrelated.

Message handlers are an advanced topic, and are discussed in greater detail in the User Guide. Few users will need to use one.

Parameters:
methName - the name of the method to remove
Returns:
true, if the specified method was previously set as a message handler; false otherwise
See Also:
addMessageHandler(Class, Object, String)


J/Link is Copyright (c) 1999-2008, Wolfram Research, Inc. All rights reserved.