bBox Functions

Version 0.99 and 1.00

See bBox Wiki page for information on error handling, parameters, etc.

See Installation for system requirements.

FileMaker Script Step List

These work much like their function based counterparts, and often call the exact same code internally. However, some simplification may be required for them to work as script steps, so for more complex scenarios also check for an equivalent function.

bBox Applescript
bBox Bash
bBox Curl (version 0.98+)
bBox Perform Script
bBox Execute SQL
bBox File Read
bBox File Status
bBox Get Character Style
bBox GraphicsMagick (version 0.98+)
bBox Grep
bBox File Symlink
bBox File Write
bBox JavaScript
bBox Mac Notification
bBox Pasteboard Flavors
bBox Pasteboard Get
bBox Pasteboard Set
bBox Python3 Run (version 0.96+)
bBox Sips (version 0.98+)
bBox Select Menu Item
bBox Version
bBox WebView Evaluate JS
bBox WebView Load HTML
bBox Zsh

bBox_Applescript (mode; script {; handler; param1; param2} )

bBox_Bash ( mode; text {; param1; …; param5} )

bBox_Curl ( param1 {; param2; …; param5} )

bBox_CurrentTime ( {format} )

bBox_DoScript (filename; scriptname ( {parameter} )

bBox_EvaluateList (values; expression {; delimiter} )

bBox_ExecuteSQL (filename; sqlQuery {; columnSeparator; rowSeparator; arguments…} )

bBox_FileRead ( path; type {; offset; filename} )

bBox_FileStatus (path {; parameter} )

bBox_FileSymLink (sourcePath; destinationPath {; useHardLink} )

bBox_FileWrite (data; path {; append} )

bBox_GetCharacterStyle ( text; position )

bBox_GraphicsMagick( mode; param1; param2 {; param3; …} )

bBox_Grep ( mode; text; param1 {; param2; param3}; )

bBox_JavaScript ( expression {; delimiter; …}; )

bBox_JavaScriptNode ( mode; text; script {; param1; …}; )

bBox_JQ ( mode; text; param1 {; …} )

bBox_LastError ( reference )

bBox_MimeTypeForPath( path )

bBox_PasteboardFlavors ( {item} )

bBox_PasteboardGet ( mode; item; flavor )

bBox_PasteboardSet ( mode; flavor )

bBox_PerformKeystrokes ( text {; …} )

bBox_Python3Run( mode; script {; text; param1; ...} )

bBox_PythonCompile ( mode; script )

bBox_PythonEval( reference; expression )

bBox_PythonExecute ( mode )

bBox_PythonFinalize

bBox_PythonGetVar ( name )

bBox_PythonSetVar ( name; value {; type} )

bBox_ReferenceInfo( reference )

bBox_Ruby( mode; text; param1 {; param2; …; param5} )

bBox_Scp( param1; param2 {; ...} )

bBox_SessionInfo

bBox_SetEnvironmentVariable( name; value )

bBox_Shell (mode; script)

bBox_Sips (mode; param1{; param2; …} )

bBox_Sort (mode; input, param1 {; param2; param3} )

bBox_SplitText( text; position; length; skipRepeats; seperator1; seperator2; delimitor )

bBox_SQLiteClose ( reference )

bBox_SQLiteExec ( reference; statement; {parameters…} )

bBox_SQLiteOpen ( path; {; options} )

bBox_SQLiteOptions ( reference; columnSeparator; rowSeparator )

bBox_StackBacktrace

bBox_SysCtl ( {mib} )

bBox Syslog ( path; {; options} )

bBox_ThreadInfo

bBox_URLHandlerInfo ( scheme )

bBox_Version ( { versionFormat } )

bBox_WebViewEstimatedProgress( window; webviewer )

bBox_WebViewEvaluateJavaScript( window; webviewer; script {; handlerFileName; handlerScriptName} )

bBox_WebViewIsLoading( window; webviewer )

bBox_WebViewLoadFile( window; webviewer; path )

bBox_WebViewLoadHTML( window; webviewer; HTML {; baseurl} )

bBox_WebViewTitle( window; webviewer )

bBox_XPathEvaluate( expression {; delimiter} )

bBox_XPathFinalize

bBox_XPathInitializeFromText( mode; text {; options; namespaceValues} )

bBox_Zsh( mode; text {; …} )

JavaScript Functions

While still using JavaScript, the fm class gives access to data in FileMaker within your JavaScript script. These are only available with the bBox Javascript script step or the bBox_JavaScrip function.

fm.evaluate (expression)

Evaluate a FileMaker expression, returning any results as a JavaScript string. Since FileMaker globals can be set with this (eg., $$myGlobalName = "text" ), it can be used both to set and get values from FileMaker.

fm.executesql (expression)

This JavaScript method calls back to the FileMaker DB engine and a newline and tab-delimited list of results (future versions will use an array). The SQL expression is evaluated by the FileMaker database engine, and the results are returned as a Python list object.

fm.run (filename, scriptname, {parameter})

Runs a FileMaker script with given script & file name. An optional parameter may be passed in.

To get the script’s result, use:

fm.evaluate ("Get (ScriptResult)")

Python Functions

These functions give Python scripts access to data in FileMaker.

fm.evaluate (expression)

Evaluate a FileMaker expression, returning any results as a Python object. Since FileMaker globals can be set with this (eg., $$myGlobalName = "text" ), it can be used both to set and get values from FileMaker.

fm.executesql (expression, values=None)

This Python function calls back to the FileMaker engine to evaluate your SQL expression, and returns a Python list object with the results.

For example, we can execute this in Python:

r = fm.executesql ("SELECT id,name FROM EXAMPLE")

and get back a result like this:

((95.0, u'last went to sleep'), (90.0, u'calendar for year'))

The optional values parameter is a list of one or values that will be used as SQL parameters. Here we’ll create a new record in the SCRATCH table with the values from the Python variables id and filename:

fm.executesql ('INSERT INTO "SCRATCH" (text_1, text_2) VALUES (?,?)', [id, filename])

fm.run (filename, scriptname, {parameter})

Runs a FileMaker script with given script & file name. An optional parameter may be passed in.

To get the script’s result, use:

fm.evaluate ("Get (ScriptResult)")

Appendix

A Note About Line Endings

Many of the commands accept a mode parameter. For the most part, this is used to specify optional line ending conversions. This may be required because of FileMaker’s convention of using return (CR) delimited line endings, whereas the unix commands used by many of the bBox functions use a newline character.

When passing literals with return delimited values, in some situations the FileMaker calculation will strip off carriage returns. Instead, store text, scripts, etc. in a field so that only a field reference is used. Or, use a Insert Text script step to set a variable or field to the needed value.

Usage with PSoS (Perform Script on Server) and Server Schedules

Although many functions are compatible when run server-side, there are certain limitations to be aware of.

First, any functions interacting with windows or applications are problematic. Even if a user was logged in on the server, that session is largely inaccessible to any scripts running via FMS . This, for instance, rules out quite a bit of AppleScript functionality, since you have no way of launching an application or communicating with one that has already started.

Additionally, the FMS script engine is more conservative about its environment, and it is possible to hit limits imposed by this. For instance, the sample file includes a Python based prime number generator that uses the itertools module. For each iteration created, some data is pushed onto the stack for the process. If the upper range in the example is raised above 55,000 you are likely to hit a limit on the stack size, causing the FMS script engine to crash.

Another limitation to watch for is how much data can be used in your PSoS parameters returned as a result. FileMaker 14 limits this to 1,000,000 characters. Attempts to return more then this will cause the client to hang.

Usage within Calculation Fields

For some functions (Shell, Bash, Python, Ruby), functions will not work as expected if used in a stored calculation field. Use unstored calculations instead.

back