MatlabManager

com.apamax.matlab
Event MatlabManager

This MATLAB plug-in allows the user to connect to and use the MATLAB Engine.

Note to user: There are some functions/toolkits that MATLAB does not support integration with C or fortran, or on some operating platforms. So check with MATLAB documentation before using the plug-in.

There a 2 ways to use the MATLAB plug-in:- The first (legacy) way is to route the *Request() events and setup listeners for the *Response() events. If you are only using the plug-in from the main context, injecting MatlabService.mon will setup all the required listeners for the *Request() events which call through to the plug-in. If you wish to use the plug-in from another context, you will have to instantiate a MatlabManager variable and call #initialize() on it after the spawn to the new context. This will set up the required listeners in the current (non-main) context, and the *Response() events will be routed to this context. The second way is to use the MatlabManager event itself, and call the relevant action and supply a callback. This way saves routing the request event as the call goes directly to the plug-in. However, the *Response() events are still routed from the plug-in to the calling context. The request actions automatically set-up a listener for the *Response() event which will call the supplied callback. You can supply the relevant doesNothing*Callback() from MatlabManager if you are not interested in the results of the callback. If you use the MatlabManager actions you do not need to call #initialize().

The MATLAB plug-in is asynchronous (except the OpenSession requests) so the processing of the input queue, or calling the request actions, does not block.

It is also multi-context aware, the *Response() events are routed to the calling context.

Routes:: com.apamax.matlab.CloseSessionResponse -; com.apamax.matlab.EvaluateResponse -; com.apamax.matlab.GetFloatResponse -; com.apamax.matlab.GetFloatSequenceResponse -; com.apamax.matlab.GetMatrixResponse -; com.apamax.matlab.GetVisibleResponse -; com.apamax.matlab.OpenSessionResponse -; com.apamax.matlab.PutFloatResponse -; com.apamax.matlab.PutFloatSequenceResponse -; com.apamax.matlab.PutMatrixResponse -; com.apamax.matlab.SetVisibleResponse -

Listens:: com.apamax.matlab.CloseSessionRequest -; com.apamax.matlab.CloseSessionResponse -; com.apamax.matlab.EvaluateRequest -; com.apamax.matlab.EvaluateResponse -; com.apamax.matlab.GetFloatRequest -; com.apamax.matlab.GetFloatResponse -; com.apamax.matlab.GetFloatSequenceRequest -; com.apamax.matlab.GetFloatSequenceResponse -; com.apamax.matlab.GetMatrixRequest -; com.apamax.matlab.GetMatrixResponse -; com.apamax.matlab.GetVisibleRequest -; com.apamax.matlab.GetVisibleResponse -; com.apamax.matlab.MatlabServiceConfig -; com.apamax.matlab.OpenSessionRequest -; com.apamax.matlab.PutFloatRequest -; com.apamax.matlab.PutFloatResponse -; com.apamax.matlab.PutFloatSequenceRequest -; com.apamax.matlab.PutFloatSequenceResponse -; com.apamax.matlab.PutMatrixRequest -; com.apamax.matlab.PutMatrixResponse -; com.apamax.matlab.SetVisibleRequest -; com.apamax.matlab.SetVisibleResponse -

Import summary
`MatlabPlugin`	`MatlabPlugin` Load MatlabPlugin

Action summary
`void`	`closeSession(string sessionID, string messageID, action<string, string, boolean, string> callback)` Close a MATLAB Session. Uses MATLAB API function engClose.
`void`	`doesNothingCallback(string sessionID, string messageID, boolean success, string error)` Does nothing callback.
`void`	`doesNothingEvaluateCallback(string sessionID, string messageID, string output, sequence<string> outputLines, boolean success, string error)` Does nothing Evaluate callback.
`void`	`doesNothingGetFloatCallback(string sessionID, string messageID, float value, boolean success, string error)` Does nothing GetFloat callback.
`void`	`doesNothingGetFloatSequenceCallback(string sessionID, string messageID, sequence<float> values, boolean success, string error)` Does nothing GetFloatSequence callback.
`void`	`doesNothingGetMatrixCallback(string sessionID, string messageID, sequence<sequence<float>> values, boolean success, string error)` Does nothing GetMatrix callback.
`void`	`doesNothingGetVisibleCallback(string sessionID, string messageID, boolean value, boolean success, string error)` Does nothing GetVisible callback.
`void`	`evaluate(string sessionID, string messageID, string expression, integer outputSize, action<string, string, string, sequence<string>, boolean, string> callback)` Evaluates an expression for the MATLAB engine session and returns textual output from evaluating the expression (including possible error messages). Uses MATLAB API function engEvalString.
`void`	`getFloat(string sessionID, string messageID, string name, action<string, string, float, boolean, string> callback)` Gets a float variable from MATLAB engine workspace. Uses MATLAB API function engGetVariable.
`void`	`getFloatMatrix(string sessionID, string messageID, string name, action<string, string, sequence<sequence<float>>, boolean, string> callback)` Gets a two-dimensional matrix variable from MATLAB engine workspace. Uses MATLAB API function engGetVariable.
`void`	`getFloatSequence(string sessionID, string messageID, string name, action<string, string, sequence<float>, boolean, string> callback)` Gets a float sequence variable from MATLAB engine workspace. Uses MATLAB API function engGetVariable.
`void`	`getVisible(string sessionID, string messageID, action<string, string, boolean, boolean, string> callback)` Returns the current visibility setting for MATLAB engine session. Uses MATLAB API function engGetVisible.
`void`	`initialize()` This action must be called when trying to use MATLAB via routed events in a context other than main.
`void`	`openSession(string sessionID, string messageID, boolean singleUse, integer precision, action<string, string, boolean, string> callback)` Starts a MATLAB process for the purpose of using MATLAB as a computational engine. Uses MATLAB API function engOpen if singleUse = false and engOpenSingleUse if singleUse = true. Single Use is unavailable on Linux.
`void`	`putFloat(string sessionID, string messageID, string name, float value, action<string, string, boolean, string> callback)` Puts a float variable into MATLAB engine workspace. Uses MATLAB API function engPutVariable.
`void`	`putFloatMatrix(string sessionID, string messageID, string name, sequence<sequence<float>> values, action<string, string, boolean, string> callback)` Puts a two-dimensional matrix variable into MATLAB engine workspace. Uses MATLAB API function engEval.
`void`	`putFloatSequence(string sessionID, string messageID, string name, sequence<float> values, action<string, string, boolean, string> callback)` Puts a float sequence variable into MATLAB engine workspace. Uses MATLAB API function engPutVariable.
`void`	`setVisible(string sessionID, string messageID, boolean value, action<string, string, boolean, string> callback)` Makes the window for the MATLAB engine session either visible or invisible on the Windows desktop. Uses MATLAB API function engSetVisible.

Import detail

MatlabPlugin

MatlabPlugin MatlabPlugin

Load MatlabPlugin

Action detail

closeSession

void closeSession(string sessionID, string messageID, action<string, string, boolean, string> callback)

Close a MATLAB Session. Uses MATLAB API function engClose.

The response to this action call will be a routed CloseSessionResponse event to the calling context from the plug-in and the supplied callback will be invoked.

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; callback - The callback for the response. Can be #doesNothingCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.CloseSessionResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.CloseSessionResponse -

Listens:: com.apamax.matlab.CloseSessionResponse -

doesNothingCallback

void doesNothingCallback(string sessionID, string messageID, boolean success, string error)

Does nothing callback.

Parameters:: sessionID; messageID; success; error

doesNothingEvaluateCallback

void doesNothingEvaluateCallback(string sessionID, string messageID, string output, sequence<string> outputLines, boolean success, string error)

Does nothing Evaluate callback.

Parameters:: sessionID; messageID; output; outputLines; success; error

doesNothingGetFloatCallback

void doesNothingGetFloatCallback(string sessionID, string messageID, float value, boolean success, string error)

Does nothing GetFloat callback.

Parameters:: sessionID; messageID; value; success; error

doesNothingGetFloatSequenceCallback

void doesNothingGetFloatSequenceCallback(string sessionID, string messageID, sequence<float> values, boolean success, string error)

Does nothing GetFloatSequence callback.

Parameters:: sessionID; messageID; values; success; error

doesNothingGetMatrixCallback

void doesNothingGetMatrixCallback(string sessionID, string messageID, sequence<sequence<float>> values, boolean success, string error)

Does nothing GetMatrix callback.

Parameters:: sessionID; messageID; values; success; error

doesNothingGetVisibleCallback

void doesNothingGetVisibleCallback(string sessionID, string messageID, boolean value, boolean success, string error)

Does nothing GetVisible callback.

Parameters:: sessionID; messageID; value; success; error

evaluate

void evaluate(string sessionID, string messageID, string expression, integer outputSize, action<string, string, string, sequence<string>, boolean, string> callback)

Evaluates an expression for the MATLAB engine session and returns textual output from evaluating the expression (including possible error messages). Uses MATLAB API function engEvalString.

The response to this action call will be a routed EvaluateResponse event to the calling context from the plug-in and the supplied callback will be invoked.

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; expression - The expression to evaluate. e.g. "z=x+y".; outputSize - The amount of expected textual output from the expression (in characters). If outputSize <= 0 then the output string will be empty. If the amount of actual output exceeds the outputSize, then only the first outputSize characters will be returned.; callback - The callback for the response. Can be #doesNothingEvaluateCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.EvaluateResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingEvaluateCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.EvaluateResponse -

Listens:: com.apamax.matlab.EvaluateResponse -

getFloat

void getFloat(string sessionID, string messageID, string name, action<string, string, float, boolean, string> callback)

Gets a float variable from MATLAB engine workspace. Uses MATLAB API function engGetVariable.

The response to this action call will be a routed GetFloatResponse event to the calling context from the plug-in and the supplied callback will be invoked.

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; name - The name of the float variable to get. Maximum name is currently 256 characters.; callback - The callback for the response. Can be #doesNothingGetFloatCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.GetFloatResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingGetFloatCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.GetFloatResponse -

Listens:: com.apamax.matlab.GetFloatResponse -

getFloatMatrix

void getFloatMatrix(string sessionID, string messageID, string name, action<string, string, sequence<sequence<float>>, boolean, string> callback)

Gets a two-dimensional matrix variable from MATLAB engine workspace. Uses MATLAB API function engGetVariable.

The response to this action call will be a routed GetMatrixResponse event to the calling context from the plug-in and the supplied callback will be invoked.

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; name - The name of the matrix variable to get. Maximum name is currently 256 characters.; callback - The callback for the response. Can be #doesNothingGetMatrixCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.GetMatrixResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingGetMatrixCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.GetMatrixResponse -

Listens:: com.apamax.matlab.GetMatrixResponse -

getFloatSequence

void getFloatSequence(string sessionID, string messageID, string name, action<string, string, sequence<float>, boolean, string> callback)

Gets a float sequence variable from MATLAB engine workspace. Uses MATLAB API function engGetVariable.

The response to this action call will be a routed GetFloatSequenceResponse event to the calling context from the plug-in and the supplied callback will be invoked.

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; name - The name of the sequence variable to get. Maximum name is currently 256 characters.; callback - The callback for the response. Can be #doesNothingGetFloatSequenceCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.GetFloatSequenceResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingGetFloatSequenceCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.GetFloatSequenceResponse -

Listens:: com.apamax.matlab.GetFloatSequenceResponse -

getVisible

void getVisible(string sessionID, string messageID, action<string, string, boolean, boolean, string> callback)

Returns the current visibility setting for MATLAB engine session. Uses MATLAB API function engGetVisible.

The response to this action call will be a routed GetVisibleResponse event to the calling context from the plug-in and the supplied callback will be invoked.

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; callback - The callback for the response. Can be #doesNothingGetVisibleCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.GetVisibleResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingGetVisibleCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.GetVisibleResponse -

Listens:: com.apamax.matlab.GetVisibleResponse -

initialize

void initialize()

This action must be called when trying to use MATLAB via routed events in a context other than main.

It must be called after the spawn to setup all the relevant listeners in the current context. It does not need to be called if using the action calls.

Listens:: com.apamax.matlab.MatlabServiceConfig -

openSession

void openSession(string sessionID, string messageID, boolean singleUse, integer precision, action<string, string, boolean, string> callback)

Starts a MATLAB process for the purpose of using MATLAB as a computational engine. Uses MATLAB API function engOpen if singleUse = false and engOpenSingleUse if singleUse = true. Single Use is unavailable on Linux.

The response to this action call will be a routed OpenSessionResponse event to the calling context and the supplied callback will be invoked.

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; singleUse - If true, creates a new MATLAB session with its own variable space. Otherwise, connects to the main session. Multiple "non-single-use" sessions will share variable space (event across contexts) and can be open at the same time. Must be false on Linux.; precision - The float precision returned in getFloat* requests (getFloat, getFloatSequence, getFloatMatrix). Suggested value is 6.; callback - The callback for the response. Can be #doesNothingCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.OpenSessionResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.OpenSessionResponse -

putFloat

void putFloat(string sessionID, string messageID, string name, float value, action<string, string, boolean, string> callback)

Puts a float variable into MATLAB engine workspace. Uses MATLAB API function engPutVariable.

The response to this action call will be a routed PutFloatResponse event to the calling context from the plug-in and the supplied callback will be invoked.

NOTE: By default this event create a local variable in the MATLAB session. If you need the variable to have a global scope, precede the putFloat() call with an evaluate() in which you declare the variable as being global (e.g. "global x");

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; name - The name to give this variable. Maximum name is currently 256 characters.; value - The value of this float variable.; callback - The callback for the response. Can be #doesNothingCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.PutFloatResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.PutFloatResponse -

Listens:: com.apamax.matlab.PutFloatResponse -

putFloatMatrix

void putFloatMatrix(string sessionID, string messageID, string name, sequence<sequence<float>> values, action<string, string, boolean, string> callback)

Puts a two-dimensional matrix variable into MATLAB engine workspace. Uses MATLAB API function engEval.

The response to this action call will be a routed PutMatrixResponse event to the calling context from the plug-in and the supplied callback will be invoked.

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; name - The name to give this variable. Maximum name is currently 256 characters.; values - The value of this matrix variable.; callback - The callback for the response. Can be #doesNothingCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.PutMatrixResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.PutMatrixResponse -

Listens:: com.apamax.matlab.PutMatrixResponse -

putFloatSequence

void putFloatSequence(string sessionID, string messageID, string name, sequence<float> values, action<string, string, boolean, string> callback)

Puts a float sequence variable into MATLAB engine workspace. Uses MATLAB API function engPutVariable.

The response to this action call will be a routed PutFloatSequenceResponse event to the calling context from the plug-in and the supplied callback will be invoked.

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; name - The name to give this variable. Maximum name is currently 256 characters.; values - The value of this sequence variable.; callback - The callback for the response. Can be #doesNothingCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.PutFloatSequenceResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.PutFloatSequenceResponse -

Listens:: com.apamax.matlab.PutFloatSequenceResponse -

setVisible

void setVisible(string sessionID, string messageID, boolean value, action<string, string, boolean, string> callback)

Makes the window for the MATLAB engine session either visible or invisible on the Windows desktop. Uses MATLAB API function engSetVisible.

The response to this action call will be a routed SetVisibleResponse event to the calling context from the plug-in and the supplied callback will be invoked.

Parameters:: sessionID - The session id to identify the opened MATLAB session.; messageID - The unique message id to identify the response event to this request.; value - Whether the MATLAB window should be visible.; callback - The callback for the response. Can be #doesNothingCallback() if result not needed or setting up own listeners.

See Also:: com.apamax.matlab.SetVisibleResponse - The response to this action; com.apamax.matlab.MatlabManager.doesNothingCallback() - Possible callback if result not needed or setting up own listeners.

Routes:: com.apamax.matlab.SetVisibleResponse -

Listens:: com.apamax.matlab.SetVisibleResponse -

com.apamax.matlabEvent MatlabManager