The bBox FileMaker plug-in is a toolbox of functions freely available to all developers. Use it with your Mac OS X-based FileMaker solutions to call programs, scripts, code libraries, and OS functions that are not available within FileMaker:

  • Python
  • Ruby
  • JavaScript
  • AppleScript
  • Shell scripts (sh, Bash)
  • SQLite3
  • curl HTTP (for SOAP or REST calls)
  • XPath

Offering dozens of powerful functions, bBox extends the reach of FileMaker’s existing commands. This makes it easier to get your projects done, and without the need for ugly workarounds to provide functionality that should be simple.

Some common uses are:

  • integration with Python-based libraries
  • Parse XML/XPath or JSON
  • AppleScripts that easily return results to FileMaker
  • accessing WSDL (SOAP) services
  • ad-hoc searches for layout elements using XML in clipboard
  • output formatted PDF or Excel files
  • shell access to manipulate file system
  • parsing text with regular expressions
  • transforming images with SIPS or ImageMagick
  • customized SMTP email

 

FileMaker Function List

See the function documentation page for detailed usage information.

Many functions are also available as script steps. However, the function based versions often have fewer restrictions on parameters.

 

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 return their errors with the bBox_LastError function. 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).

 

bBox Modes

Many functions and script steps accept a mode parameter. These are bit flags that enable features or behaviors.

mode flags
   +1: skip conversion of carriage returns to line feeds on input
   +2: skip conversion of line feeds to carriage returns on output
   +4: run asynchronously (don't wait for output)
   +8: skip finalization (keep context)
   +16: use alternate path for command (/usr/local/bin/ instead of /usr/bin)
   +32: combine stdout & stderr (often to get error output that does not go to stdout)

Add the values together to combine options. For instance, use a mode of 20 to run asynchronously AND using an alternate command path.

Most functions will only support a subset of the available modes.

 

bBox Parameters

In most cases, any function or script parameters will be use their text equivalent, e.g. a numeric value 1234 will be returned as the string “1234”.

For functions or script steps expecting a path, these will always be in POSIX format. So if using the path from Get (DocumentsFolder) you’ll need to convert that into its POSIX equivalent before passing in to the function or script step.

If you need to pass container or return a file as a result, the bBox_FileWrite or bBox_FileRead functions may be helpful.

However, starting with version 0.97, a number of functions have shortcuts that allow you to use container references. These are:

bBox_Bash function & script step
   bBox_Bash function & script step
   bBox_Curl function
   bBox_GraphicsMagick function
   bBox_Grep function & script step
   bBox_JQ function
   bBox Python3 Run script step
   bBox_Ruby function
   bBox_Sips function
   bBox_Zsh function & script step

When a container reference is passed in, the container’s file will be written out to /tmp using a name in the form of /private/tmp/bBox_posix_XXXXXXXXX.bin, where XXXXXXXXX is replaced with randomized characters, and will never conflict with an existing file. The file path is then used as a replacement for the parameter. In the example below, the container field reference will be written out, and Bash will receive the file path as its first parameter. The stat command will then be executed by Bash, and stat’s output will be returned:

bBox_Bash(0; "stat $1"; "-s"; RESOURCE::file)

A few things to note here. First, all files written out this way will have a .bin extension, regardless of their file type or original name. If the file container was stored with the compressed option, there will also be an intermediate .zip file created. Finally, these files are typically purged by the OS after three days, or the next reboot. If working with larger files you may want to purge them periodically before then, possibly by running a command like:

bBox_Bash(0; "rm /tmp/bBox_posix_*")

If server-side, only run this when there aren’t any other scripts running and might be expecting files there.

 

FileMaker, Line Endings, and Character Encoding

FileMaker has several conventions that are very likely to cause issues with functions expecting New Line (ASCII 10) line breaks.

First and foremost, FileMaker will strip out line breaks completely with string literals. Because of this, always store scripts or other line delimited text in database text fields, use the Insert Text script step, or possible store it in a container field.

Even in cases where line endings are preserved by FileMaker, it defaults to using a Carriage Return for all line breaks. Any text going to or from a bBox function expecting POSIX formatted text will often not handle this correctly. Here however bBox typically defaults to translating the line endings for you. If needed, you may be able to override this translation by setting the necessary flag in a function’s mode parameter. See the function documentation page for details.

Finally, many POSIX commands expect UTF-8 encoded text. If you are using text that requires 16 or 32 bit Unicode characters they may not translate into a UTF-8 equivalent, and will be stripped out of the text when it is converted.

 

Python & JavaScript Functions

When bBox instantiates a JavaScript or Python VM, it adds in a custom class to its environment. The class functions implement callbacks to FileMaker, allowing your Python or JavaScript script to query FileMaker, update tables, or run scripts. For Python, you will need to add the following to your script:

import fm

Except for the executesql function, the parameters are identical for Python & JavaScript. In a future bBox version the JavaScript executesql parameters will be identical.

The functions are:

  • fm.evaluate (expression)
    • expression: text containing a valid FileMaker calculation
    • result: a Python value based on result of expression
  • fm.executesql (expression) [JAVASCRIPT]
    • expression: a FileMaker SQL expression
    • result: a string result from the SQL query (or ?)
  • fm.executesql (expression {, values} ) [PYTHON]
    • expression: a FileMaker SQL expression
    • values: one or more SQL parameters to be used in the SQL expression
    • result: a string result from the SQL query (or ?)
  • fm.run (filename, scriptname {, parameter} )
    • filename: FileMaker file name
    • scriptname: FileMaker script name to run
    • parameter: passed to FileMaker script

The evaluate function may seem to be mainly about pulling data out of FileMaker into Python, but you can also push data out by setting FileMaker variables within the evaluate statement.

executesql can naturally work in both directions using a SELECT statement to pull data in, or an UPDATE or INSERT to push data out to FileMaker. Rows and columns are returned as a non-mutable Python list (tuple), so there is no need to specify characters to delimit these like you would with FileMaker’s ExecuteSQL function.

 

Session and Re-entrancy/Thread-safe

It is possible with re-entrant calls or with server-side scripts that two calls to a function (or set of related functions) could occur at the same time.

We will use the term “session safe” if multiple PSOS or server script schedules can use the same function. If a function can (for instance) be used re-entrantly, then we will say that it is “thread safe”.

Most functions are thread-safe, but there are some exceptions to be aware of:

bBox_LastError: result is session safe for most cases; for SQLite it is also thread safe
bBox_ShellExitStatus: Not session or thread safe; use bBox_LastError instead
bBox_JavaScript: session and thread safe, but bBox_LastError(-5) is only session safe
bBox_Python: these functions are not thread safe (use the bBox Python3 Run script step instead)
bBox_SQLite: SQLite functions are session and thread-safe
bBox_XPath: session safe

 

Function Documentation by Version

 

Examples

The bBox Plug-in Demo file has 200 examples of the various functions, and is included with the bBox disk image.

 

Product Information

 

Related Blog Posts

Current Version

As of June 20, 2021 the current version is 0.98.