Version 0.88
See Installation for system requirements.
This version is superseded by version 0.9×.
bBox Errors
Nearly all functions may return some sort of error result. For a few functions, different types of errors can be returned in different ways.
Although avoided, it’s possible for most functions to return “?” as their result, but is the default for FileMaker when the function had a serious error, or the plug-in is missing. A difficult case is if there is any chance your function call would normally return “?” as its result, so it may not make sense the check for this particular issue.
Most functions are moving towards using the bBox_LastError function to return their error results. It accepts a session ID, which is either a value returned from a previous function call (eg, to bBox_SQLiteOpen), or a fixed value (e.g., -3 for Python).
A number of function call types still have their own specific functions for returning errors. For example, AppleScript uses bBox_AppleScriptLastError. These will be phased out in later versions to use bBox_LastError instead.
bBox Functions
bBox_Applescript (mode; script {; handler; param1; param2} )
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
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::input_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.
When getting a numeric result you’ll need to wrap the AppleScript call in a GetAsNumber function to get the expected result, like so:
GetAsNumber (bBox_Applescript( 0; "(1+1)" )) = 2Use bBox_LastError (-6) to get error results. If there are any errors, you will the error number as first value, and an error message (if any) as the second value.
bBox_ApplescriptLastError
Get the error code returned from the last executed Applescript script.
parameters
none
result
error number returned from execution of last Applescript scriptThis function will be removed in the future. You should use bBox_LastError (-6) instead.
bBox_Bash ( mode; text {; param1; …; param5} )
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
3 = don't translate input or output line endings
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)
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.
Scripts and their commands will be limited to 600 seconds of sustained CPU usage and 2 GB of memory. Use bBox_LastError (-1) to get the exit status (error number) from your script.
bBox_Curl ( param1 {; param2; …; param5} )
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)
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, the example above 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 parameter, so the same request becomes:
bBox_Curl ("--output", "/var/tmp/www.beezwax.net.html"; "http://beezwax.net")
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
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.
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…} )
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
UPDATE, INSERT, and TRUNCATE (FileMaker 15+ only) operations are supported. However, CREATE, DROP, or ALTER statements are not supported at this time and will cause the client to hang. Also, INSERT operations can be slower than expected if over a WAN connection.
An example of a simple expression is below. Note that this can be run from any layout, as it is not based on the context from FileMaker other than the current file. 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") ]
To get the last ExecuteSQL error use the special reference ID:
Set Variable [ $lastError; "bBox_LastError (-2)" ]
This returns two return delimited values: the error number, followed by the error message. The error result is global to all PSoS instances, so if more than one PSoS is running there is a small chance you could get the result from a different ExecuteSQL call. The value does not get cleared if there was a successful call. This will change in the next release.
bBox_FileRead ( path; type {; 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
result
container reference in chosen format
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.
bBox_FileStatus (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.
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)
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.
bBox_FileWrite (data; path {; append} )
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)
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. Check the bBox_ShellExitStatus function for any OS errors codes.
The file path is a literal value; do not escape characters or enclose in quotes.
bBox_GetCharacterStyle ( 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_Grep ( mode; text; param1 {; param2; param3}; )
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; …}; )
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 grep as text
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.
Use bBox_LastError (-5) to retrieve any errors.
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: use -1
- bBox_ExecuteSQL: use -2
- bBox_Python: use -3
- bBox_XPathInitializeFromText: use -4
- bBox_JavaScript: use -5
- 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.
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 ( 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.
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_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.
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
script: text to be compiled into bytecode
result
reference number, or 0 on error
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.
If there are compile errors, use bBox_LastError (reference), where reference is the number returned by bBox_Compile. At this time, reference number is always -3. You should 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.
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
text = input text to be processed
param1: Ruby option (optional)
…
param5: Ruby option (optional)
result
output (stdout) from Ruby script
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 64 MB)
Also see the the bBox_Bash function, which has better performance with large amounts of output and has 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_ShellExitStatus
Returns the exit status from the last shell command to complete. This function is not thread safe, and may return indeterminate results if more than one bBox function is in use at the same time. Use bBox_LastError instead.
parameters
none
result
exit status returned from execution of last shell script
The result codes vary, as the result is from the last command or function executed. However, a non-zero result is almost always indicative of an error. With server-side scripts in particular, concurrent calls to functions like bBox_Shell could give the result for a different process if it completed just before your call to bBox_ShellExitStatus.
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 commandSee 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_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
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.
Check with bBox_LastError (-4) for any errors.
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
Check with bBox_LastError (-4) for any errors tokenizing the XML. First value in error output will be the error number, followed by any error messages. 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_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"
"long": plug-in name + version, as in "bBox 0.51"
"platform": returns "Mac OS X"
"short": just the plug-in version, as in "0.51" (default)
result
version string
JavaScript Functions
While still using JavaScript, the fm class gives access to data in FileMaker within your JavaScript script.
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 is a Python function for calling back to the FileMaker engine, and returns a list object with the results. The SQL expression is evaluated by the FileMaker database engine, and the results are returned as a Python list object.
The optional values parameter is a list of one or values that will be used as SQL parameters.
For example, we wanted to create a new record in the SCRATCH table with the values from the 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.
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. Use unstored calculations instead.