Appendix E — Built-In Method Library
This appendix lists all of the built-in methods available in the Method Editor, except for methods that operate on the model object and the application object. For detailed information on using the built-in methods and for full information on the syntax used, see the Application Programming Guide and the Programming Reference Manual.
As an alternative method of learning the syntax of these methods, you can use code completion by typing the name of the method and then use Ctrl+Space. A window will open with information on the syntax and method signature.
Model Utility Methods
The model utility methods make it possible to load the model object part of an MPH-file into a method for further processing.
Name
Description
clearModel
Clears the model object contents.
createModel
Creates a new model with a given tag.
removeModel
Removes a model. The embedded model cannot be removed.
modelTags
Returns an array of model tags for all loaded models, including the embedded model.
uniqueModeltag
Returns a model tag that is not in use.
getModel
Returns a model with a specified tag.
loadModel
Loads a model with a specified tag from a file or, using a model location URI, from a Model Manager database.
loadProtectedModel
Loads a password protected model with a specified tag from a file.
loadRecoveryModel
Loads a model from a recovery directory/folder structure.
saveModel
Saves a model to a file. The filename can be a file scheme path or, if allowed by security settings, a server file path.
getComsolVersion
Returns the current software version as a string.
File Methods
The file methods support, in addition to reading and writing to data files on the file system, reading and writing of data files stored in a Model Manager database by accepting a file location URI.
Name
Description
readFile
Returns the contents in a given file as a string.
openFileStreamReader
Returns a CsReader object that can be used to read line-by-line or character-by-character from a given file name.
openBinaryFileStreamReader
Returns a CsBinaryReader object that can be used to read from a given file byte-by-byte.
readMatrixFromFile
Reads the contents of the given file into a double matrix. The file has the same spreadsheet-type format as available in the model tree Export node.
readStringMatrixFromFile
Reads the contents of the given file into a string matrix. The file has the same spreadsheet-type format as available in the model tree Export node.
readCSVFile
Reads a file with comma-separated values (CSV file) into a string matrix. By default, it expects the file to use the RFC 4180 format for CSV. However, by providing an additional input argument a user-defined delimiter can be used.
writeFile
Writes array data to a given file. If the spreadsheet format is used, then the data can be read by readMatrixFromFile or readStringMatrixFromFile.
openFileStreamWriter
Returns a CsWriter object that can write to a given file.
openBinaryFileStreamWriter
Returns a CsBinaryWriter object that can be used to write to a given file byte-by-byte.
writeCSVFile
Writes a given double or string array to a CSV file. The RFC 4180 format is used for the CSV.
exists
Tests whether a file with a given name exists.
deleteFile
Deletes a file with a given name if it exists. The file is deleted on the server.
copyFile
Copies a file on the server. Both the source and target names can use file scheme paths.
importFile
Displays a file browser dialog and uploads the selected file to the file declaration with the given name. Alternatively, it uploads the selected file to the Filename text field in a given model object entity.
writeExcelFile
Writes the given string array data starting from a specified cell in a specified sheet of an Excel file.
readExcelFile
Reads a specified sheet of an Excel file, starting from a specified cell, into a 2D string array.
getFilePath
Returns the absolute server file path of the server proxy file corresponding to a certain file scheme path, or null if the server proxy file for the given path does not exist.
This method can be used to pass the path to, for example, a file using the temp:/// scheme to external code or an application.
getClientFileName
Returns the original name of an uploaded file on the client file system (or null if there is no uploaded file matching the given file scheme path).
This method is only useful for providing user interface feedback; for example, to get information on which uploaded file is being used. There is no guarantee that the original file would still exist on the client or even that the current client would be the same as the original client.
getClientFilePath
Returns the original path of an uploaded file on the client file system (or null if there is no uploaded file matching the given file scheme path).
This method is only useful for providing user interface feedback; for example, to get information on which uploaded file is being used. There is no guarantee that the original file would still exist on the client or even that the current client would be the same as the original client.
Operating System Methods
Name
Description
executeOSCommand
Executes the OS command with a given command (full path) and parameters. When applicable, the command is run server side.
fileOpen
Opens a file with the associated program on the client. See also the section “File Methods”.
getUser
Returns the username of the user that is running the application. If the application is not run from COMSOL Server, then the value of the preference setting General > Username > Name is returned.
openURL
Opens a URL in the default browser on the client.
playSound
Plays a sounds on the client.
Email Methods
Name
Description
emailFromAddress
Returns the email from address from the COMSOL Server or preferences setting.
sendEmail
Sends an email to the specified recipient(s) with the specified subject, body text, and zero or more attachments created from Report, Export, and Table nodes in the embedded model.
userEmailAddress
Returns the user email address(es) corresponding to the currently logged in user, or an empty string if the user has not configured an email address.
Email Class Methods
The class EmailMessage can be used to create custom email messages.
Name
Description
EmailMessage
Creates a new EmailMessage object.
EmailMessage.setServer
Sets the email (SMTP) server host and port to use for this email message.
EmailMessage.setUser
Sets the username and password to use for email (SMTP) server authentication. This method must be called after the setServer method.
EmailMessage.setSecurity
Sets the connection security type for email (SMTP) server communication.
EmailMessage.setFrom
Sets the from address.
EmailMessage.setTo
Sets the to addresses.
EmailMessage.setCc
Sets the cc addresses.
EmailMessage.setBcc
Sets the bcc addresses.
EmailMessage.setSubject
Sets the email subject line. Note that newline characters are not allowed.
EmailMessage.setBodyText
Sets the email body as plain text. An email can contain both a text and an HTML body.
EmailMessage.setBodyHtml
Sets the email body as HTML text. An email can contain both a text and an HTML body.
EmailMessage.attachFile
Adds an attachment from a file. The attachment MIME type is determined by the file name extension.
EmailMessage.attachFile
Adds an attachment from a file with a specified MIME type.
EmailMessage.attachFromModel
Adds an attachment created from a report, export, or table feature in the model.
EmailMessage.attachText
Adds a text attachment with a specified sub-MIME type, such as plain or HTML.
EmailMessage.attachBinary
Adds an attachment from a byte array with a specified MIME type.
EmailMessage.send
Sends the email to the email (SMTP) server. An email object can only be sent once.
Email Preferences
To set preferences for an outgoing email (SMTP) server, open the Email page of the Preferences window, as shown in the figure below.
COMSOL Server provides a similar set of email preferences.
GUI-Related Methods
Name
Description
Call a method directly
Call a method from the Methods list by using its name; for example, method1(), method2().
callMethod
Alternate way to call a method from the Methods list; used internally and in cases of name collisions.
useGraphics
Plots a given entity (Plot Group, Geometry, Mesh, or Explicit Selection) in the graphics form object given by a name or name path in the second argument.
openForm
Shows the form with the given name in the current main window. In a single window application, the form replaces the current one. In an application with subwindows, the form must exist in the main window layout. If not, it will not be opened. Showing a form that is already open will only activate the form.
closeForm
Closes the form with the given name. Closing forms is only possible in applications using subwindows. This method is not applicable for single window applications.
closeDialog
Closes the form, shown as a dialog, with a given name.
dialog
Shows the form with a given name as a dialog. Equivalent to the dialog method of a Form object; see below.
alert
Stops execution and displays an alert message with a given text.
alert
Stops execution and displays an alert message with a given text and title.
confirm
Stops execution and displays a confirmation dialog with a given text and title. It also displays two or three buttons, such as “Yes”, “No”, and “Cancel”.
error
Stops execution and opens an error dialog with a given message.
request
Stops execution and displays a dialog with a text field, requesting input from the user.
message
Sends a message to the message log.
clearLog
Clears the log window.
clearMessageLog
Clears the message log window.
evaluateToResultsTable
Evaluates a given entity, a Derived Value, in the table object given by the name or name path in the second argument, which will then be the default target for the evaluations of the Derived Value. If the third argument is true, the table is cleared before adding the new data. Otherwise, the data is appended.
evaluateToDoubleArray2D
Evaluates the given entity, a Derived Value, and returns the nonparameter column part of the real table that is produced as a double matrix. All settings in the numerical feature are respected but those in the current table connected to the numerical feature are ignored.
evaluateToIntegerArray2D
Evaluates the given entity, a Derived Value, and returns the nonparameter column part of the real table that is produced as an integer matrix. All settings in the numerical feature are respected, but those in the current table connected to the numerical feature are ignored.
evaluateToStringArray2D
Evaluates the given entity, a Derived Value, and returns the nonparameter column part of the potentially complex valued table that is produced as a string matrix. All settings in the numerical feature are respected, but those in the current table connected to the numerical feature are ignored.
useResultsTable
Shows the values from the tableFeature in the resultsTable form object.
getChoiceList
Returns an object of the type ChoiceList, representing a choice list node under the declarations branch. The type ChoiceList has associated methods that make it easy to change values and display names, see the Application Programming Guide.
setFormObjectEnabled
Sets the enable state for the form object specified by the name or name path.
setFormObjectVisible
Sets the visible state for the form object specified by the name or name path.
setFormObjectText
Sets the text for the form object specified by the name or name path in the second argument. This method throws an error if it is impossible to set a text for the specified form object.
setFormObjectEditable
Sets the editable state for the form object specified by the name or name path. This functionality is only available for text field objects.
setMenuBarItemEnabled
Sets the enable state for the menu bar item specified by the name or name path (from the menu bar) in the first argument.
setMainToolbarItemEnabled
Sets the enable state for the main toolbar item specified by the name or name path (from the main toolbar) in the first argument.
setFileMenuItemEnabled
Sets the enable state for the file menu item specified by the name or name path (from the file menu) in the first argument.
setRibbonItemEnabled
Sets the enable state for the ribbon item specified by the name or name path (from the main window) in the first argument.
setToolbarItemEnabled
Sets the enable state for the toolbar form object item specified by the name or name path in the first argument.
useView
Applies a view to the graphics contents given by the name or name path in the second argument.
resetView
Resets the view to its initial state in the graphics contents given by the name or name path in the second argument.
getView
Returns the view currently used by the graphics contents given by the name or name path in the second argument.
goToView
Goes to one of the “xy”, “xz“, “yx“, “yz“, “zx“, or “zy” views in the main graphics window or in the graphics window of a form object.
setWebPageSource
Sets the source for the form object specified by the name or name path in the first argument.
getScreenHeight
Returns the height in pixels of the primary screen on the client system, or of the browser window if Web Client is used.
getScreenWidth
Returns the width in pixels of the primary screen on the client system, or of the browser window if Web Client is used.
GUI Command Methods
Name
Description
clearAllMeshes
Clears all meshes.
clearAllSolutions
Clears all solutions.
clearSelection
Clears the selection in the given graphics object.
environmentReflections
Adds environment reflections to graphics
exit
Exits the application.
fileOpen
Opens a file with the associated program on the client.
fileSaveAs
Downloads a file to the client. See also the section “File Methods”.
printGraphics
Prints the given graphics object.
rotateEnvironment
Rotate the environment used for reflections
saveApplication
Saves the application.
saveApplicationAs
Saves the application under a different name (or as an MPH-file).
saveApplicationCopyAs
Saves a copy of the application.
scenelight
Toggles scene light in the given graphics object.
selectAll
Selects all objects in the given graphics object.
skyBox
Shows skybox in graphics
transparency
Toggles transparency in the given graphics object.
zoomExtents
Makes the entire model visible in the given graphics object.
zoomToSelection
Zooms to the current selection.
Debug Methods
Name
Description
clearDebugLog
Clears the Debug Log window.
debugLog
Prints the value of an input argument to the Debug Log window. The input argument can be a scalar, 1D array, or 2D array of the types string, double, integer, or Boolean.
Methods for External C Libraries
External Method
Name
Description
external
Returns an interface to an external C (native) library given by the name of the library feature. The External class uses the Java Native Interface (JNI) framework. For more information, see the Application Programming Guide.
Methods Returned by the External Method
The external method returns an object of type External with the following methods:
Name
Description
invoke
Invokes a named native method in the library with the supplied arguments.
invokeWideString
Invokes the named native method in the library with the supplied arguments.
close
Releases the library and frees resources. If you do not call this method, it is automatically invoked when the external library is no longer needed.
Progress Methods
Name
Description
setProgressInterval
Sets a progress interval to use for the top-level progress and display message at that level.
Calling this method implicitly resets any manual progress previously set by calls to setProgress().
setProgress
Sets a value for the user-controlled progress level.
resetProgress
Removes all progress levels and resets progress to 0 and the message to an empty string.
showIndeterminateProgress
Shows a progress dialog with an indeterminate progress bar, given message, and an optional cancel button.
showProgress
Shows a progress dialog with an optional cancel button, optional model progress, and one or two levels of progress information.
closeProgress
Closes the currently shown progress dialog.
startProgress
Resets the value of a given progress bar form object name to 0.
setProgressBar
Sets the value of a given progress bar form object name in the range 0 –100 and the associated progress message.
Date and Time Methods
Name
Description
currentDate
Returns the current date as a string (formatted according to the server's defaults) for the current date.
currentTime
Returns the current time as a string (not including date and formatted according to the server's defaults).
formattedDateTime
Returns a formatted time given in milliseconds since the epoch to a readable date and time.
formattedTime
Returns a formatted time using the given format. The format can either be a time unit or text describing a longer format.
sleep
Sleep for a specified number of milliseconds.
timeStamp
Current time in milliseconds since midnight, January 1, 1970 UTC.
getExpectedComputationTime
Returns a string describing the approximate computation time of the application. The string can be altered by the method setExpectedComputationTime.
setLastComputationTime
Set the last computation time, overwriting the automatically generated time.
You can use the timeStamp method to record time differences and then set the measured time in ms (a long integer).
getLastComputationTime
Returns the last computation time in the given format. The format can either be a time unit or text describing a longer format. This format is localized and the output is translated to the current language setting.
License Methods
Name
Description
checkoutLicense
Checks out one license for each specified product.
checkoutLicenseForFile
Checks out one license for each product required to open an MPH-file.
checkoutLicenseForFileOnServer
Checks out one license for each product required to open an MPH-file.
getLicenseNumber
Returns a string with the license number for the current session. Example: licensenumber=getLicenseNumber()
hasProduct
Returns true if the COMSOL installation contains the software components required for running the specified products.
hasProductForFile
Returns true if the COMSOL installation contains the software components required for running the specified MPH-file.
hasProductForFileOnServer
Returns true if the COMSOL installation contains the software components required for running the specified MPH-file.
Conversion Methods
Name
Description
toBoolean
Converts strings and string arrays to Booleans. ('true' returns true, all other strings return false).
toDouble
Converts floats, float arrays, strings, and string arrays to doubles.
toInt
Converts strings and string arrays to integers.
toString
Converts Booleans, integers, and doubles, including arrays, to strings.
Array Methods
Name
Description
getColumn
Returns a string, double, integer, or Boolean array for a specified column in a 2D array (matrix). This is, for example, useful when values have been read from a file and only certain columns should be shown in a table.
getSubMatrix
Returns a rectangular submatrix of an input matrix. Available for string, double, integer, or Boolean 2D arrays.
insert
Inserts one or more elements in an array and returns the expanded array. Available for string, double, integer, or Boolean arrays.
append
Adds one or more elements to the end of an array and returns the expanded array. Available for string, double, integer, or Boolean arrays.
remove
Removes one or more elements from an array and returns the shortened array. Available for string, double, integer, or Boolean arrays.
insertRow
Inserts one or more rows into a rectangular 2D array and returns the expanded array. Available for string, double, integer, or Boolean arrays.
appendRow
Adds one or more rows to the end of a rectangular 2D array and returns the expanded array. Available for string, double, integer, or Boolean arrays.
removeRow
Removes one or more rows from a 2D array and returns the reduced array. Available for string, double, integer, or Boolean arrays.
replaceRow
Replaces one or more rows in a rectangular 2D array and returns the array. Available for string, double, integer, or Boolean arrays.
insertColumn
Adds one or more columns into a rectangular 2D array and returns the expanded array. Available for string, double, integer, or Boolean arrays.
appendColumn
Adds one or more columns at the end of a rectangular 2D array and returns the expanded array. Available for string, double, integer, or Boolean arrays.
removeColumn
Removes one or more columns from a rectangular 2D array and returns the smaller array. Available for string, double, integer, or Boolean arrays.
replaceColumn
Replaces one or more columns in a rectangular 2D array and returns the array. Available for string, double, integer, or Boolean arrays.
matrixSize
Returns the number of rows and columns of a matrix as an integer array of length 2. Available for string, double, integer, or Boolean arrays.
String Methods
Name
Description
concat
Concatenates a given array or matrix of strings into a single string using the given separators.
contains
Returns true if a given string array contains a given string.
find
Returns an array with the indices to all occurrences of a string in a string array.
findIn
Returns the index to the first occurrence of a string in a string array or the first occurrence of a substring in a string.
length
Returns the length of a string.
replace
Returns a string where a string has been replaced with another string.
split
Returns an array of strings by splitting the given string at a given separator.
substring
Returns a substring with the given length starting at the given position.
unique
Returns an array of strings with the unique values in the given array of strings.
Collection Methods
Name
Description
copy
Returns a copy of the given array or matrix. Available for string, double, integer, or Boolean arrays.
equals
Returns true if all elements in the given array are equal and they have the same number of elements. Available for string, double, integer, or Boolean arrays. For doubles, comparisons are made using a relative tolerance.
sort
Sorts the given array. Note: The array is sorted in place. Available for string, double, or integer arrays. If the array is two-dimensional (a matrix), the columns are sorted by their row values from top to bottom.
merge
Returns an array with all of the elements merged from the given arrays. Available for string, double, or integer arrays.
With, Get, and Set Methods
Name
Description
with
Used to make code more compact.
endwith
The ending of a with statement.
set
Sets a Boolean, integer, double, or string property value. Allows for a scalar, array, or matrix property.
setIndex
Sets a string, double, or integer property value for a matrix or vector at a given index.
getIntArray
Gets an integer vector property.
getIntMatrix
Gets an integer matrix property.
getBoolean
Gets a Boolean property.
getBooleanArray
Gets a Boolean vector property.
getBooleanMatrix
Gets a Boolean matrix property.
getDouble
Gets a double property.
getString
Gets a string scalar, vector, or matrix property.
getDoubleArray
Gets a double vector property or parameter.
getDoubleMatrix
Gets a double matrix property or parameter.
getStringArray
Gets a string vector property or parameter.
getStringMatrix
Gets a string matrix property or parameter.
getDblStringArray
Returns the value as a matrix of strings.
getInt
Gets an integer property.
get
Returns a variable expression.
descr
Returns a variable description.
Model Builder Methods for Use in Add-ins
For writing add-in method code that operates on the current component, current mesh, current physics, and so on, use the methods in the table below.
Name
Description
getCurrentComponent
Returns an object of the type ModelNode for the current component.
getCurrentPhysics
Returns an object of the type Physics for the current physics interface.
getCurrentMesh
Returns an object of the type MeshSequence for the current mesh.
getCurrentStudy
Returns an object of the type Study for the current component.
getCurrentPlotGroup
Returns an object of the type ResultFeature for the current component.
getCurrentNode
Returns an object of the type ModelEntity for the current component.
selectNode
Select a particular model tree node.
These methods return the corresponding entity such that the method code in an add-in can operate on it. When called from an application a method in this category returns null. Also, null is returned if no entity of the corresponding type exists such that nothing is current.