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

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:

 

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 a function might return “?” as its result, as this is the default for FileMaker when the function has a serious error, or the plug-in is missing.

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
 +32: combine stdout & stderr (often to get error output that does not go to stdout)
 +64: unzip container references

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.

Unzipping of parameter references only available since version 0.99.7.

 

bBox Parameters

In most cases, any function or script parameters will 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. Paths from FileMaker functions like Get (DocumentsFolder) will need to be converted into its POSIX equivalent using the ConvertFromFileMakerPath function before passing in to the bBox function or script step.

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

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

When a container reference is passed in, the container’s file will be written out to the system's /tmp directory using a name in the form of 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 file in the container field reference will be written out to the file system, and Bash will receive the path as its parameter instead. 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 a .zip file, and the unzip mode is set, a directory will be created instead. 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 using the files there.

FileMaker, Line Endings, and Character Encoding

FileMaker has several conventions that are 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 store text 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 using the "Core" based JavaScript function, and Python functions without the "Run" suffix, bBox adds in a custom fm class to its environment. This class implement callbacks to FileMaker, allowing your Python or JavaScript script to easily 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:

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.

/tmp files

On busy systems processing lots of data using certain functions, space consumption in the /tmp directory may get fairly large. To clear these out more quickly, run the following command on a regular basis to purge any that are at least 3 hours old:

find /tmp -type f -mmin +180 -name 'bBox_posix_*' -delete # Ubuntu versionfind /private/tmp -type f -mmin +180 -name 'bBox_posix_*' -delete # macOS version

You do not want to delete any temp files that are in use, which is why we wait the 180 minutes.

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 August 9, 2024 the current version is 1.04.4 for macOS, and 1.04.3 for Ubuntu.

Version 1.05 planned for Aug 2024 release.