Version 0.97 – 0.99
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 Functions
bBox_Applescript (mode; script {; handler; param1; param2} )
script step: bBox Applescript [ Script; Handler ]
Compile and run an AppleScript script, using the script’s return value as the function’s result. If no return value is given then a “?” is the result.
parameters
mode: currently not used
script: a string that will evaluate to a valid AppleScript script
handler: subroutine name that should be called (optional)
param1: first parameter to pass to handler (optional)
param2: second parameter to pass to handler (optional)
result: string representation of data returned by the Applescript script
error: bBox_LastError (-6)
You can specify the first optional parameter and not specify the second. In other words:
Set Field [
DEMO::output_gt;
bBox_Applescript (
DEMO::mode_gn;
DEMO::script_gt;
"my_handler";
"1st and only parameter to subroutine my_handler"
)
]
Text given in parameters with AppleScript will be encoded using UTF -8 character encoding, which may be a problem in a few cases when passing text whose language requires the use of 16-bit characters. However, script text and output use UTF -16.
If using this function as part of a server-side script (including with Perform Script on Server) many commands requiring a UI will not work. This is because there is no window manager or Finder to “tell”, and you will not be able to launch or activate applications, unless you can be certain that the same user account running the FileMaker script is also logged in. However, this is not recommended.
String results will be enclosed in double quotes. If expecting a numeric result, wrap the AppleScript call in a GetAsNumber function to get the expected result, like so:
GetAsNumber (bBox_Applescript( 0; "(1+1)" )) = 2
bBox_Bash ( mode; text {; param1; …; param5} )
script step: bBox Bash [ Script; $1; $2; $3; $4 ]
Execute commands using the Bash shell. This is a superset of what the bBox_Shell function does, since command line options can be supplied to the interpreter, and you can use commands and functions specific to Bash that aren’t in sh.
parameters
mode:
0 = convert both input and output line endings, wait for output
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
2 = skip translation of new lines in shell output to carriage returns
4 = don't wait for completion
text: input text to be processed
param1: Bash option or parameter (optional)
…
param5: Bash option or parameter (optional)
result: stdout from Bash execution (truncated to a maximum of 160 MB)
error: bBox_LastError (-1)
You can use Bash’s -s option to help send parameters directly to commands you are executing.
Watch out for character encoding issues! By default, Bash will be using “c” for its character encoding, which only handles ASCII characters. This will cause problems with any high-bit or multibyte UTF -8 characters.
This function supports container field references. Scripts and their commands will be limited to 2 GB of memory. macOS now defaults to using Zsh, so you may want to use bBox_Zsh instead.
bBox_Curl ( param1 {; param2; …; param5} )
script step: bBox Curl [ Param1; Param2; Param3; Param4; Param5; Param6; Param7 ]
Return the results of the curl command with the given parameters. Each FileMaker parameter is equivalent to one curl parameter.
parameters
param1: first curl parameter (required)
param2: curl parameter (optional)
…
param5: curl parameter (optional)
result: curl output (from stdout)
error: bBox_LastError (-7)
Certain output, e.g., download progress information, will end up in the system log (/var/log/system.log) so you may want to suppress this with the “-s” option. Also, -v output is sent to stderr (not stdout) by Curl, so use one of Curl’s --trace options to direct output to a file instead.
The curl command is sensitive to spaces after an option. For instance, you might do the following in a shell script:
curl -o /var/tmp/www.beezwax.net.html http://beezwax.net
However, with the bBox_Curl function there is no shell to strip out extra spaces, so the above example would be written as:
bBox_Curl ("-o/var/tmp/www.beezwax.net.html"; "http://beezwax.net")
If using the longer form of the option name, the option name must be in its own FileMaker parameter, so the same request becomes:
bBox_Curl ("--output", "/var/tmp/www.beezwax.net.html"; "http://beezwax.net")
This function supports container field references.
bBox_CurrentTime ( {format} )
Return the current time as a string, with up to a millisecond of precision.
parameters
format = optional printf format string. The default format string is "%d:%02d:%02d.%06d"
result
the formatted time as text
The default format will return time with microseconds in a format that FileMaker will accept, so this will generate a Timestamp result with microseconds in FileMaker:
GetAsTime (bBox_CurrentTime)
bBox_DoScript (filename; scriptname ( {parameter} )
Run the given FileMaker script by name.
parameters
filename: FileMaker file containing the script, typically @Get (FileName)@
scriptname: name of script to run
parameter: text to pass to script (optional)
result
none
This function is not server-side compatible. The named script will run asynchronously from the calling script, so it is not possible to get its result with Get (ScriptResult). If the file has more than one script with the same name it is undefined which script will be used. If the filename is different from the current file, the file must already be open.
If a script with that name can not be found a “?” is returned for the function result.
bBox_EvaluateList (values; expression {; delimiter} )
Apply the expression once for each value in values.
parameters
values: delimited list of string values
expression: an expression in same form as FileMaker's native Evaluate function
delimiter: string to use as a delimiter, defaulting to carriage return
There are two variables that will be preset when the expression is evaluated. $i will be set to the current iteration number, starting at 1, and incrementing for every value. $v will be set to the current value in list (similar to the statement $values [$i], where $values is an array of strings). For this to work there is some special handling of quote characters, but this will be invisible to your expression.
There is a special case for the delimiter value. If you pass a null string (i.e., ""), each character in the values parameter will be treated as a separate value. This expression would strip all upper-case characters from the values parameter:
If (Code ($v) < Code ("A") or Code ($v) > Code ("Z"); $v; "")
bBox_ExecuteSQL (filename; sqlQuery {; columnSeparator; rowSeparator; arguments…} )
script step: bBox Execute SQL [ Expression; Field Separator; Row Separator; Parameter 1; Parameter 2; Parameter 3; Parameter 4 ]
Execute a SQL expression on the current file.
parameters
filename: name of the database file, or "" for current file
sqlQuery: a valid SQL expression
columnSeparator: delimiter to use for columns in output (defaults to tab character)
rowSeparator: delimiter to use for rows (defaults to newline)
arguments: zero or more SQL parameters
result: text result of the SQL expression, or "?" if there was an error
error: bBox_LastError (-2)
UPDATE , INSERT , and TRUNCATE (FileMaker 15+ only) operations are supported. However, CREATE , DROP , or ALTER statements are not supported at this time and may cause the client to hang. Also, INSERT operations can be slower than expected if over a WAN connection.
Note that this can be run from any layout, and even target another (previously opened) file. An example of a simple expression is below. Since only a SQL expression is expected, we don’t add a semicolon to the end of statement.
Set Variable [ ""; $result; "bBox_ExecuteSQL ("SELECT category,name from EXAMPLE") ]
bBox_FileRead ( path; type {; offset; filename} )
script step: bBox File Read [ POSIX Path; Offset ]
Reads the file from path, returning a result of the given type.
parameters
path: text containing POSIX file path (e.g., "/var/log/system.log")
type: desired result type
"F" = raw (binary) file
"O" = make best guess based on file signature, returned as FILE or image
"s" = UTF-8 result to be returned as text
"U" = UTF-16 result to be returned as text
offset: index to start reading at (optional)
filename: file name to use instead of source name (for binary results only)
result: container reference in chosen format
error: bBox_LastError (-1) (
This function can be used to read in a file to a variable or field. For the text data types, you’ll need to know the character encoding used, but typically these are UTF -8. As a safety measure, any input will be truncated at 2 GB.
The file path is a literal value; do not escape characters or enclose in quotes.
The optional filename parameter can be used for things like normalizing file names imported into the system.
bBox_FileStatus (path {; parameter} )
script step: bBox File Status [ POSIX Path; Parameter ]
Get information on or check for presence of a file or folder.
parameters
filepath: POSIX file or directory path
parameter: stat command parameters (defaults to -x)
result: file size, type, POSIX permissions, and access information as given by the command stat.
error: bBox_LastError (-1)
See man stat in Terminal for all possible options. The file path is a literal value; do not escape characters or enclose in quotes.
bBox_FileSymLink (sourcePath; destinationPath {; useHardLink} )
script step: bBox File Symlink [ POSIX Source Path; POSIX Destination Path; Parameter ]
Create a symbolic link at the destination path to the source path of a file or folder. This is equivalent to ln -s in the Terminal.
If useHardLink is True, creates a hard link instead. This is only possible when the source is a file, and the source & destination are on the same volume.
bBox_FileWrite (data; path {; append} )
script step: bBox File Write [ Data; POSIX Path ]
Write out the contents of the container or text to a file. If the optional append flag is true, add the contents to the end of the current file.
parameters
data: reference to a container or text value
path: POSIX file path
result: number of bytes written (negative on error)
error: bBox_LastError (-1)
Be sure that any needed folders already exist. For text, the number of bytes written is often the same as the number of characters in text, but any non- ASCII characters may require more than one byte per character.
The file path is a literal value; do not escape characters or enclose in quotes.
bBox_GetCharacterStyle ( text; position )
script step: bBox Get Character Style [ Text; Position ]
Returns the typeface and color information for character at given position in text.
parameters
text to be examined
position of character to return style information for
result
a return delimited list of values, in this sequence:
font name
font id (specific to each instance of the FileMaker client application)
font size
typeface style (as text, comma delimited)
RGB color + alpha (as text, comma delimited)
A position value of -1 gives the default text style.
If you want the style information for an entire run of text you might want to use the built-in function GetAsCSS instead.
bBox_GraphicsMagick( mode; param1; param2 {; param3; …} )
Execute a gm command to manipulate, compare, or describe image files.
parameters
mode:
0 = wait for output
4 = run command asynchronously (no wait)
32 = combine stderr & stdout output
param1 - 16: options to be sent to the gm command
result
any text output returned by gm command
Typically, each option, value, or switch is a separate FileMaker parameter.
The version bundled with the macOS version of the bBox plugin currently supports the following file types, encodings, or features:
- large files (<32 bit)
- BZIP
- JBIG
- JPEG
- LCMS
- PNG
- TIFF
- ZLIB
For details on the gm command see GraphicsMagick GM Utility . Although testing may be the quickest way to determine which image formats are supported, for details on supported formats see GraphicsMagick Supported Formats . Also see bBox_Sips , which may provide better performance and can work with a few image types not supported by GraphicsMagick.
This function supports container field references. See details under the bBox Parameters .
First appeared in version 0.98
bBox_Grep ( mode; text; param1 {; param2; param3}; )
script step: bBox Grep [ Text; Option 1; Option 2; Option 3; Option 4 ]
Execute a grep command to search text for one or more patterns. Patterns may be in a form similar to Unix glob patterns (basic regular expressions), or using extended regular expressions.
parameters
mode:
0 = convert both input and output line endings, wait for output
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
2 = skip translation of new lines in shell output to carriage returns
3 = don't translate input or ouput line endings
text: input text to be processed (this may be set to "" if passing a file path as one of the parameters)
param1: normally the search string, but can also contain command option(s) or file path
param2: optional command option(s) or file path
param3: optional command option(s) or file path
result
output returned by grep as text
bBox_JavaScript ( expression {; delimiter; …}; )
script step: bBox JavaScript [ Expression ]
Evaluate one or more JavaScript expressions or statements. These may be complete scripts, or a simple calculated result.
parameters
expression: the first JavaScript statement or expression
delimiter: demarcates results for each expression, or a null string
param3…param16: additional JavaScript expressions using same context
result: output returned by JavaScript as text
error: bBox_LastError (-5)
If multiple expressions are given and the delimiter parameter is a null string, only the result from the last expression is returned. Each expression has access to the global objects created by the previous expressions.
See the main page for information on the built-in FileMaker functions for JavaScript. This function is session and thread safe.
bBox_JavaScriptNode ( mode; text; script {; param1; …}; )
NOTE: parameters may change in a future version
Execute the script file, either provided as a container reference or a POSIX file path, using FMS' NodeJS environment.
parameters
mode:
4 = run asynchronously (don't wait for output)
16 = use alternate installation path for node executable (version 0.99.8+)
64 = expand .zip files, passing the path to the directory instead (should not be used for the main
script
parameter)
text: sent to NodeJS' stdin
script: path or container reference of the main script text
param1…param13: additional parameters for the
node
command.
result: output returned by JavaScript as text
error: bBox_LastError (-1)
Typically server-side only. However, may be used locally if both FileMaker Pro and Server are installed on the system, or the Alternate Path mode is set and NodeJS is installed at /usr/local/bin (macOS) or /usr/bin (Ubuntu). This function is session and thread safe.
See Node.js v14.19.1 documentation for information on node parameters.
When debugging it may be useful to use a mode of +32 to catch output to stderr.
bBox_JQ ( mode; text; param1 {; …} )
Evaluate the given JSON text using a jq statement.
parameters
mode:
0 = convert both input and output line endings
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
2 = skip translation of new lines in shell output to carriage returns
3 = don't translate input or ouput line endings
text: JSON text to be parsed
param1: first jq option or expression
param3…param16: additional jq options or expression
result: output returned by jq as text
error: bBox_LastError(-1)
for details on jq operators see the jq Manual .
bBox_LastError ( reference )
Get information on the last error that occurred with a given session reference ID.
parameters
reference: the session reference ID
result
a return-delimited value containing the error number and the error message (if any)
This function is used for the following:
- bBox_Bash, bBox_Shell,bBox_Zsh, bBox_File*, bBox_JQ: use -1
- bBox_ExecuteSQL: use -2
- bBox_Python: use -3
- bBox_XPathInitializeFromText: use -4
- bBox_JavaScript: use -5
- bBox_Applescript: use -6
- bBox_Curl: use -7
- bBox_SQLite: use reference number returned after open, exec, or close functions (this will be a positive number)
Results from this function are “session safe”, so it will reliably work when there are multiple server-side PSoS or scheduled scripts are running. However, except with SQLite functions, they are not thread safe, so certain scenarios such as recursion could result in the wrong error result being returned. Error codes are not cleared by this call, so it may be called multiple times.
Often, it will be POSIX error codes that are returned. For macOS, many of these are listed here: Mac OS X Man Pages
bBox_MacNotification ( queue; delay; titleList; {; buttonList; scriptSpecifier} )
script step: Mac Notification [ Queue; Delay; Title List; Button List; Script Specifier ]
Create a macOS notification. These may be displayed with optional alerts or buttons. A user click can be used to trigger a FileMaker script, which is called by file name and script name reference.
parameters
queue: this is an arbitrary string used by the Notification Center to group notifications
delay: negative number to immediately display a 0 to display alert
titleList: return delimited values for title, subtitle, and descriptive text
buttonList: return delimited values for Action, Close, and placeholder text (optional)
scriptSpecifier: FileMaker file and script name to run if notification is clicked (optional)
result
none
Although the function itself does not return a result, the FileMaker script called will get at least one value in a return delimited script result. The possible values for the first value item are:
- Button – the action button was clicked
- Content – click inside alert but not in action or Reply button
- Reply – click on Reply button
The second value in list will be the Reply text, if any.
Due to how the Notification Center works, users will only have a short period of time to click the Reply button if present. Later clicks in the macOS Notification Center will return Content clicks only.
Currently, there is no support for custom sounds or images. This may be added in a future version.
bBox_PasteboardFlavors ( {item} )
Get current types of data in the clipboard.
parameters
item: optional index, used when more than one item is in clipboard
result
UTI codes for the available flavors. See System-Declared Uniform Type Identifiers for some commonly used codes.
bBox_PasteboardGet ( mode; item; flavor )
Get data from the clipboard as text.
parameters
mode:
3 = use UTF8 character encoding, don't translate input or ouput line endings
4 = expect 2 byte characters in output (UTF16)
item: item index, usually 1
flavor: UTI code for one of the flavors currently in clipboard
result
the given item and flavor is returned as a text value, or ? if the flavor does not exist
Generally when some data is saved in the clipboard it is saved in a number of different formats. Rather than let FileMaker decide which format you get, the PasteboardGet function allows you to choose the format. However, since the result must be returned as text this function may not give useful results for all flavors. One unexpected use for this is to get an XML version of FileMaker objects that are in the clipboard.
If a value for the item index does not exist an empty string is returned. If requesting a non-existent flavor, "?" is returned.
bBox_PasteboardSet ( mode; flavor )
Set the contents of the clipboard to the given text data and flavor.
parameters
mode:
3 = use UTF8 character encoding, don't translate input or ouput line endings
4 = use 2 byte characters in output (UTF16)
flavor: UTI code for one of the flavors currently in clipboard
result
0 or the Pasteboard error code
The current implementation of this function always clears the previous contents of the clipboard, so it is not possible to have more than one flavor in the clipboard.
bBox_PerformKeystrokes ( text {; …} )
Key in the text parameters as if typed by user. This includes escape codes to enter modifiers such as Command and Shift key.
parameters
text: one or more text parameters with characters to key in
result
none
To use a command key combination, the first character in the parameter must be an “@” (at symbol). After that, one or more key modifiers are then used. These are:
- ^ – Control
- _ – Option
- $ – Shift
- ~ – 0.5 second pause
bBox Python3 Run [ Mode: Script: Input: Param1: Param2: Param3: ]
Execute a Python script using the python3 command.
parameters
mode:
0 = convert both input and output line endings, wait for output
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
2 = skip translation of new lines in shell output to carriage returns
3 = don't translate input or ouput line endings
4 = run asynchronously (don't wait for output)
16 = use /usr/local/bin/python3
32 = combine Python stdout and stderr output
script: text to be compiled into bytecode
result
text sent to stdout
Normally uses the python3 command installed at /usr/bin. On macOS, this requires the installation of Python Foundation's version of Python, on Ubuntu use apt-get to install it. To use alternate version, you may need to create a symlink in /usr/local/bin to your desired binary and add 16 to the mode.
Python modules installed on Linux may not be in the default path. If needed, add the following before you import statement:
import sys
sys.path.append('/usr/local/lib/python3.8/dist-packages')
Use bBoxy_LastError (-3) to get error result. While testing, using a mode of 32 is recommended. This will cause stderr output from Python to be returned as the script step/function result. Otherwise, messages about things like Python syntax errors will be lost, and you will only have the error message returned by bBox_LastError.
These calls are thread safe, so you can safely have multiple Python 3 scripts running at the same time. The script step does not support the Python fm module however — for fm methods you’ll need to use the bBox_PythonExecute or bBox_PythonEval functions.
bBox_PythonCompile ( mode; script )
Initializes the Python environment and script compiles the script into bytcode. If there was a previously created Python environment, it will be released by a call to Py_Finalize (but see mode options).
This function’s result will change in a future version. Instead of returning any compiler messages, a session reference ID will be returned. Compiler messages will be returned by bBox_LastError.
parameters
mode:
0 = convert both input and output line endings
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
8 = keep any previous globals
9 = skip conversion, keep previous globals
script: text to be compiled into bytecode
result: reference number, or 0 if major error
error: bBox_LastError (reference)
Currently, only one script can be compiled and in use at a time as the bytecode is stored in a global variable. Once a script has been successfully compiled, execute it one or more times with the bBox_PythonExecute function.
You can use the bBox_PythonSetVar function to supply data to your script via Python globals. For instance:
Set Variable [ $python_body; "print 'x =', x" ]
Set Variable [ $compile_msgs; bBox_PythonCompile ( 0; $python_body )
Set Variable [ $ig; bBox_PythonSetVar ("x"; 5 * 100; "i") ]
Set Variable [ $result; bBox_PythonExecute ]
Set Variable [ $ig; bBox_PythonFinalize ]
After execution with bBox_PythonExecute you should get the string “500” as a result.
When storing lengthier Python scripts in FileMaker your best option is to enter them into a field directly, instead of using a calculation. This way you won’t have to worry about escaping double-quote characters in FileMaker. However, be sure to turn off Smart Quotes in the FileMaker file’s Text Preferences.
At this time, reference number is always -3. If you get an error result from bBox_LastError, you may need to call bBox_Finalize to clear the error condition.
bBox_PythonEval( reference; expression )
Evaluates an expression, returning its result. bBox_PythonCompile must be called before using.
parameters
reference: currently, this will always be -3
expression: one or more Python calculations or function calls
result
The result of the evaluated statement, or "?" if there was an error.
This function is intended as a way to execute named functions in Python. In particular, this may be useful when you want to execute some functions out of a library, but the parameters or the functions may vary.
This function differs from bBox_PythonExecute in that the value returned is the result of the evaluated expression, not the output sent to stdout.
bBox_PythonExecute ( mode )
Executes the currently cached (compiled) Python bytecode and returns the result of its output. A future version of this function will require the session reference ID returned by bBox_PythonCompile.
parameters
mode:
0 = convert both input and output line endings
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
2 = skip translation of new lines in shell output to carriage returns
3 = don't translate input or ouput line endings
asType: not currently used
result
The output (stdout) from the Python script executed, or "?" if there was an error.
This routine executes the Python bytecode compiled by the last call to bBox_PythonCompile., which must of been called at least once before this function is used. Your script can either send its output to stdout (e.g., a print statement), or you can retrieve needed values with bBox_PythonGetVar.
When done with the Python environment, call bBox_PythonFinalize.
If there are exceptions during the execution they are typically logged in /var/log/system.log. Output is capped at 64 MB.
bBox_PythonFinalize
A future version of this function will require the session reference ID returned by bBox_PythonCompile.
Releases the current Python environment from memory.
parameters
none
result
none
IMPORTANT NOTE : There is only one shared Python VM with server-side processes. If you are running PSoS and/or script schedules that may overlap you’ll need to have a way of locking access to prevent conflicts. CWP scripts have their own separate copy.
bBox_PythonGetVar ( name )
A future version of this function will require the session reference ID returned by bBox_PythonCompile.
Return the value of a named Python global variable. Defaults to using string as type, but this can be specified to avoid (for instance) converting a Python numeric value to a string.
parameters
name: Python variable name to return value of
result
date, numeric, or text value from variable
Python’s global variables are released when bBox_PythonFinalize is called, so you should extract any global values first. If passed the name of a non-existent Python variable an empty string is returned.
bBox_PythonSetVar ( name; value {; type} )
A future version of this function will require the session reference ID returned by bBox_PythonCompile.
Creates or replaces a python global variable of a given name and value.
parameters
name: Python variable name
value: container, numeric or string value to store in Python variable
type: optional value that determines the Python variable's type
b = Python Bool
d = Python Date
f = Python Float
F = Python bytearray (File data from container, or text)
i = Python Integer
m = Python DateTime
s = Python String (default) with UTF-16 encoding
result
none
You should call this routine after bBox_PythonCompile but before bBox_PythonExecute to set the inputs for that particular run of the script (since you could call bBox_PythonExecute more than once). The Python functions do not support sending data to the Python script via stdout, so this function is the preferred method of supplying the input to scripts.
bBox_Ruby( mode; text; param1 {; param2; …; param5} )
Execute commands using Ruby interpreter.
parameters
mode:
0 = convert both input and output line endings
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
2 = skip translation of new lines in shell output to carriage returns
3 = don't translate input or output line endings
4 = run asynchronously (don't wait for output) (requires version 0.96+)
16 = use alternate path at /usr/local/bin (requires version 0.96+)
text = input text to be processed
param1: Ruby option (optional)
…
param5: Ruby option (optional)
result: output (stdout) from Ruby script
error: bBox_LastError (-1)
bBox_SessionInfo
FileMaker, OS, and process related values for the current context.
parameters
None
result
Line delimited list of function calls
Primarily useful for debugging, but could be used to determine what triggered the calculation (script, data viewer, etc.).
bBox_Shell (mode; script)
Execute the given script text with the Unix shell.
parameters
mode:
0 = convert both input and output line endings
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
2 = skip translation of new lines in shell output to carriage returns
3 = don't translate input or ouput line endings
script: string to be evaluated by the shell
result: string returned after executing the shell command (maximum of 2 GB)
error: bBox_LastError (-1)
Also see the the bBox_Bash and bBox_Zsh functions, which have better performance with large amounts of output and additional parameter passing options.
Unlike bBox_Bash , there are no CPU or memory limits, so you’ll need to be careful to not exceed any reasonable limits.
As with the AppleScript function, if running scripts server-side it is recommended that you avoid trying to run any scripts that might launch applications or put up any kind of UI on the server.
bBox_Sips (mode; param1{; param2; …} )
The Scriptable image processing system (sips) is used to query or modify raster image files ( JPG / GIF / PNG ) and ColorSync ICC profiles. Image processing options include flip, rotate, change image format/width/height.
parameters
mode:
0 = wait for output
4 = run command asynchronously (no wait)
32 = combine stderr & stdout output
param1 - 16: options to be sent to the sips command
result
output returned by sips command as text
result
any text output from the command
Due to the number of parameters required, there aren’t currently any examples in the demo file. However, a text version of an example looks like this:
bBox_Sips (
32;
"-s"; "format"; "heic";
"/System/Library/Templates/Data/Library/User Pictures/Nature/Earth.png";
"--out" "/tmp/Earth.heic"
)
Notice in the above example that it requires each item to be a separate parameter, so the above example requires 7 parameters.
Only supported on macOS. See bBox_GraphicsMagick for a Linux compatible alternative, However GraphicsMagick is less likely to leverage available hardware ( GPU , AltiVec, etc.).
First appeared in version 0.98
bBox_Sort (mode; input, param1 {; param2; param3} )
Sort the newline (\n) delimited values using the sort command.
parameters
mode:
0 = convert both input and output line endings
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
2 = skip translation of new lines in shell output to carriage returns
3 = don't translate input or ouput line endings
4 = don't wait for completion
param1: sort command option or file path, or ""
param2: 2nd sort parameter or file path (optional)
param3: 3rd sort parameter or file path (optional)
result
string returned after executing command
See man sort in the Terminal for all sort options.
bBox_SQLiteClose ( reference )
Closes a SQLite3 session created with bBox_SQLiteOpen. Once closed, the reference will be invalid.
parameters
reference: the SQLite session reference
result
0 or SQLite3 error code
If you have used in-memory storage, all SQLite3 data will also be dumped.
bBox_SQLiteExec ( reference; statement; {parameters…} )
Execute the SQLite3 statement, using zero or more SQL parameters.
parameters
reference: session ID created by bBox_SQLiteOpen
statement: text containing one or more SQLite3 statements
parameters: zero or more values to be used in the SQLite3 statement(s)
result
result as text
There can be only one SQLite3 statement per call. At this time, container data will always be converted to its GetAsText equivalent.
bBox_SQLiteOpen ( path; {; options} )
Creates a new SQLite3 session at the given SQLite3 path for later use with bBox_SQLiteExec.
parameters
path:
use ":memory" for in-memory storage without a file
POSIX path can be used to specify a file system location (eg, /tmp/mysqlite.db)
use "" (empty string) to use a temporary, private file for storage
options: space delimited list of zero or more SQLITE_OPEN options
result
positive number indicates success, and is the session ID
The default options are READWRITE + CREATE . Otherwise, either READWRITE or READONLY are typical. These correlate to the constants as defined in the SQLite3 C++ interface that begin with SQLITE_OPEN_.
You need to save the returned reference number on success, since you’ll need to pass this session ID for your later calls to bBox_SQLiteExec and bBox_SQLiteClose.
The SQLite3 library used is compiled with the SQLITE_CONFIG_MULTITHREAD option set. This means that each PSoS script may open its own files, or even the same file already in use by another PSoS instance (check for temporary write locks if updating), but it should not share references across PSoS instances unless you can guarantee that each PSoS instance will not use the same connection at the same time.
bBox_SQLiteOptions ( reference; columnSeparator; rowSeparator )
The column & row separators are the text values used to delimit the rows and columns returned by bBox_SQLiteExec. These default to tabs for columns and CRs for rows.
bBox_StackBacktrace
Returns the function call history leading up to the execution of the function in the current context.
parameters
None
result
Line delimited list of function calls
Primarily useful for debugging, but could be used to determine what triggered the calculation (script, data viewer, etc.).
bBox_SysCtl ( {mib} )
Returns all, or optionally, just one, of the OS kernel values on the system executing the function.
parameters
mib (optional): MIB (Management Information Base) key for the value you want
result
key/value pairs, return delimited
Use to get information on the configuration of the OS. If a MIB is specified, only the value is returned. Also see the bBox_SessionInfo function for other process and OS related values.
First appeared in version 0.99.11
bBox Syslog ( path; {; options} )
Script step to send messages to the system's Syslog server. On macOS that typically means messages will be written to its "unified log", whereas Ubuntu will send its messages to the file at /var/log/syslog.
parameters
priority:
"Emergency"
"Alert"
"Critical"
"Error"
"Warning"
"Notice"
"Info"
"Debug"
message: text for content portion of logged message
result
none
First appeared in version 0.99.10
bBox_Version ( { versionFormat } )
Returns the plug-in version as string, using a convention maintained by a number of other plug-ins.
parameters
versionFormat: (optional)
"autoupdate": zero padded format of version, as in "00050100"
"extended": includes build number and build date, as in "bBox 0.97.05 Nov 21 2020" (requires 0.97+)
"long": plug-in name + version, as in "bBox 0.51"
"platform": returns "Mac OS X" or "Linux"
"short": just the plug-in version, as in "0.91" (default)
result
version string
The extended format returns the version number in a form that matches what Get (InstalledFMPlugins) returns.
The default options are READWRITE + CREATE . Otherwise, either READWRITE or READONLYare typical. These correlate to the constants as defined in the SQLite3 C++ interface that begin with SQLITE_OPEN_.
You need to save the returned reference number on success, since you’ll need to pass this session ID for your later calls to bBox_SQLiteExec and bBox_SQLiteClose.
The SQLite3 library used is compiled with the SQLITE_CONFIG_MULTITHREAD option set. This means that each PSoS script may open its own files, or even the same file already in use by another PSoS instance (check for temporary write locks if updating), but it should not share references across PSoS instances unless you can guarantee that each PSoS instance will not use the same connection at the same time.
bBox_WebViewEstimatedProgress ( window; webviewer )
Return the current estimate of how close the web viewer is done with loading content, where 1.0 indicates the web view is done loading.
bBox_WebViewIsLoading ( window; webviewer )
Returns True if the web viewer has finished loading content in the window and web viewer at the given z-index.
bBox_WebViewHistory( window; webviewer; path )
bBox_WebViewHistory ( window; webviewer )
Returns the navigation history for a given Web Viewer. The window and web viewer layout object are referenced by their z order (depth) in window and layout object hiearchy. Result is returned as an array of JSON objects.
bBox_WebViewLoadFile ( window; webviewer; path )
Loads the file into web viewer. Path is given in POSIX format, and the file’s parent folder is made the base URL .
bBox_WebViewTitle ( window; webviewer )
Return the page title for the Web Viewer in the specified window and web viewer layout object.
bBox_XPathEvaluate (expression {; delimiter} )
Applies the given XPath expression against the XML source that was previously processed by a call to bBox_XPathInitialize.
parameters
expression: XPath expression
delimiter: string to use as delimiter between nodes of result
result: string returned by XPath expression
error: bBox_LastError (-4)
At this time, it is not possible to specify the name space to be used for XPath expressions. This might be an issue for some XPath functions or expressions.
bBox_XPathInitializeFromText (mode; source {; options; namespaceValues} )
Initialize the XPath environment and process the XML source. This is usually followed by a call to bBox_XPathEvaluate and bBox_XPathFinalize .
This function’s result value has changed since version 0.81.
parameters
mode:
0 = translate carriage returns in source to new lines (equivalent to mode 2)
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
2 = skip translation of new lines in shell output to carriage returns
3 = don't translate input or ouput line endings
source: the XML source to be processed (tokenized)
options: named libxml2 parser options to be passed to XPath parser (optional)
namespaceValues: these must be pairs of return-delimited values:
namespace prefix that will be used in XPath expression
namespace URI, e.g. "http://www.w3.org/2005/Atom"
result: -4, or an error message
error: bBox_LastError (-4)
Check with bBox_LastError (-4) for any errors tokenizing the XML . If there are no errors, use the bBox_XPathEvaluate function to get the results of your XPath queries. if the RECOVER option is used, you may get error messages with an error number of 0.
Consider converting the line endings of the XML source from FileMaker’s default of carriage returns to use new lines (e.g,, use a mode value of 2). Otherwise, the error is will always be reported as occurring on line 1.
bBox uses the Gnome libxml2 library, version 2.9.5. XInclude substitution and external DTD support is enabled by default, but you can use the options parameter to change this. Options consist of a string of named options, delimited by comma or space. Pass "" as the option if you don’t want to use any parser options, otherwise the options preceeded by a bullet will be used.
BIG_LINES : Store big lines numbers in text PSVI field
COMPACT : compact small text nodes; no modification of the tree allowed afterwards (may crash if you try to modify the tree)
•DTDATTR : default DTD attributes
DTDLOAD : load the external subset
DTDVALID : validate with the DTD
HUGE : relax any hardcoded limit from the parser (may exhaust available memory)
IGNORE_ENC : ignore internal document encoding hint
NOBASEFIX : do not fixup XINCLUDE xml:base uris
NOBLANKS : remove blank nodes
NOCDATA : merge CDATA as text nodes
NODICT : Do not reuse the context dictionnary
NOENT : substitute entities
NOERROR : suppress error reports
NONET : Forbid network access
NOWARNING : suppress warning reports
NOXINCNODE : do not generate XINCLUDE START / END nodes
NSCLEAN : remove redundant namespaces declarations
OLD10 : parse using XML -1.0 before update 5
OLDSAX : parse using SAX2 interface before 2.7.0
•PEDANTIC : pedantic error reporting
•RECOVER : recover on errors
SAX1 : use the SAX1 interface internally
•XINCLUDE : Implement XInclude substitition
Your source text should not contain content that can’t be converted to the UTF -8 character encoding. Even so, at least two UTF -8 characters seem to be problematic when in the XML content:
- right single quotation mark
- non-breaking space
If the RECOVER option is used (one of the defaults) it is possible your call may generate errors, but will still succesfully parse the XML tree.
bBox_XPathFinalize
Releases the current XPath environment.
parameters
none
result
none
bBox_Zsh ( mode; text {; param1; …; param5} )
script step: bBox Zsh [ Script; $1; $2; $3; $4 ]
Execute commands using the Zsh shell, the default shell interpreter starting with Catalina. This function is a superset of what the bBox_Shell function does, since command line options can be supplied to the interpreter, and you can use commands and functions specific to Zsh that aren’t in sh.
parameters
mode:
0 = convert both input and output line endings, wait for output
1 = skip conversion of carriage returns (the FileMaker end-of-line marker) to new lines
2 = skip translation of new lines in shell output to carriage returns
3 = don't translate input or output line endings
4 = don't wait for completion
text: input text to be processed
param1: Zsh option or parameter (optional)
…
param5: Zsh option or parameter (optional)
result: stdout from Zsh execution (truncated to a maximum of 160 MB)
error: bBox_LastError (-1)
You can use Zsh’s -s option to help send parameters directly to commands you are executing.
Watch out for character encoding issues! By default, Bash will be using “c” for its character encoding, which only handles ASCII characters. This will cause problems with any high-bit or multibyte UTF -8 characters.
Scripts and their commands will be limited to 600 seconds of sustained CPU usage and 2 GB of memory. Use to get the exit status (error number) from your script.
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.