Global functions

Global functions to evaluate expressions, execute SQL, run FileMaker scripts, and use idle time.

Overview#Back to top

The evaluate and execute_sql functions are same as the corresponding methods of the Context class; behind the scenes they read the current context and call its methods. If you need to make multiple evaluate or execute_sql calls and are concerned about speed, create a new Context and call its methods; this way you'll save some time on each call.

Functions#Back to top

api_version()#Back to top

Return FileMaker API version:

api_version() -> API_7, API_8, API_11

Result and side effect

The function returns a numeric code representing the version of the API. There are three versions: v7, v8, and v11. The corresponding constants are defined in the filemaker module: API_7, API_8, API_11. Note that the value of the constant doesn't match the version number or something like that; e.g. the numeric equivalent of API_7 is 50.

The function has no side effects.

Discussion

The current FileMaker plug-in API was introduced with v7 and underwent a couple of changes over the years: v8 added special functions to work with FNAM and SIZE container streams and v11 exposed an enhanced SQL function (execute_sql_2()) and supporting code.

The PyFM plug-in will work in older versions, but, of course, won't be able to call functions that are not there and will raise an exception instead.

Example

  >>> from filemaker import api_version, API_11
  >>> api_version()
  52
  >>> api_version() == API_11
  True

This code will work on v11 and v12.

application()#Back to top

Return FileMaker API version:

filemaker.application() -> PRO, ADVANCED, RUNTIME, SERVER, WEB
Parameters

The function takes no parameters

Result and side effect

The function returns a numeric constant representing the current application type. The corresponding constants are defined in the filemaker module: PRO, ADVANCED, RUNTIME, SERVER, and WEB. For example, PRO is 1. The function has no side effects.

Example
>>> import filemaker
>>> filemaker.application() == filemaker.ADVANCED
True

The code above will work in PyFM console if you run it in FileMaker Pro Advanced.

evaluate()#Back to top

Evaluate a FileMaker calculation expression:

evaluate(expression) -> any FileMaker type
Arguments
expression

A text value that will be evaluated as a FileMaker expression. The expression can vary from a mere field name to a call to a custom function or even another external function.

Result and side effects

The function returns one of FileMaker data types with the result of the expression. The result is read-only, but not volatile. The function may raise the following exceptions:

  • TypeError if expression is not a text type.

  • One of FileMaker errors if the expression failed to evaluate.

The function has the same side effects as the expression. For example, you can use it to set a variable or to call another plug-in function.

Examples

To read a value of a field that can be reached from the current context, evaluate its name:

>>> import filemaker
>>> result = filemaker.evaluate('Test::Global Text')

This will set result to the contents of the Global Text field in the Test table.

To see an example of an error:

>>> result = filemaker.evaluate('Test::No Such Field')
Traceback (most recent call last)
   ...
MissingFieldError: Field is missing.
Sample code

See the Zip sample that uses evaluate() to collect containers from a found set or a related table.

execute_sql()#Back to top

Execute SQL against the current FileMaker database and return the result in a single string:

execute_sql(sql[, rowsep, colsep])
Parameters
sql

The SQL to execute. This can be any kind of FileMaker SQL.

rowsep

A single Unicode character to use to separate rows. The default is the ASCII Record Separator character (0x1E) defined in the filemaker module as the ROW_SEP constant.

colsep

A single Unicode characters to use to separate columns. The default is the ASCII Unit Separator character (0x1F) defined in the filemaker module as the COL_SEP constant.

Result and side effects

The function returns a FileMaker Text instance with the data. If the SQL statement doesn't return any data, the string will be empty. The data are separated with the specified rowsep and colsep characters: the colsep character separates individual fields and the rowsep character separates records.

The SQL expression can can create, update, or delete records in the current file. The SQL expression can also manipulate tables or indices, but such expressions cannot be evaluated from within a function call; if you need this, you'll need to do this during idle time.

Discussion

The default ROW_SEP and COL_SEP characters are intentionally set to normally unused part of the ASCII table so they won't mix with tabs or carriage returns.

execute_sql_2()#Back to top

Execute SQL against the specified or the current file using native FileMaker types and receive the result as a (virtual) table with native types:

execute_sql_2(file, sql[, bindings])
execute_sql_2(file, sql[, *bindings])
file

The name of the file to execute the SQL against. To execute SQL against the current file, use an empty string.

sql

The SQL to execute. The statement can use question marks as binding placeholders; see the bindings parameter.

bindings

Values to insert at the placeholders. The argument can be a single iterable like a list, tuple, or filemaker.Row or you can just list the arguments themselves. I.e. the following are equivalent:

execute_sql('', 'INSERT INTO a (b, c) VALUES (?, ?)', (1, 2))
execute_sql('', 'INSERT INTO a (b, c) VALUES (?, ?)', 1, 2)
Result and side effects

The function returns an instance of a RowSet that consists of Rows. You can iterate over the set or get a row by index; once you have a row, you can also iterate over it or get it a value by index. The values retain their FileMaker types, so you can read container data this way. All the results are read-only, but not volatile.

Discussion

If you're after speed, pass file name and the expression as filemaker.Text. For the parameters the fastest way would be to pass them in the simplest way possible; if you get them as a tuple, pass them as a tuple then. Technically the native type is filemaker.Row and all other parameters are converted into it, so if you pass a Row, it will go straight to the SQL engine. But this doesn't necessarily matter you should use Rows, because you have to construct them, right? And constructing a Row in Python is definitely going to be slower than just passing the data you parameters and have them packed by the C code.

run_script#Back to top

Run a FileMaker script:

run_script(file, name[, parameter=None, control=PAUSE])
file

The name of the file. Use an empty string to run a script in the current file.

name

The name of the script.

parameter

The script parameter. This can be any data type, including Container.

control

A code that specifies what to do with the current script. The possible codes are defined in the filemaker module as PAUSE, RESUME, EXIT, and HALT.

Result and side effects

The function adds the specified script to the top of the current script stack and returns without waiting for the script to actually run. The function returns no results.

run_when_idle#Back to top

Schedule a function or a generator to run during idle time:

run_when_idle(agility, generator)
run_when_idle(agility, callable[, *args, **kwds])
level

A numeric constant that specifies the minimal duration of the pause the function is waiting for. The possible values are defined in the filemaker module:

USER_IDLE  USER_NOT_IDLE  SCRIPT_PAUSED  SCRIPT_RUNNING  UNSAFE

The USER_IDLE even occurs when the user is idle for 30 or more seconds; other levels describe the smaller and smaller bits of time until the UNSAFE, which should not be used at all if you plan to do something slow, like writing to disk.

Functions written in Python should probably stick to the first two levels.

generator

A generator that will be called when exhausted or until the system quits.

callable

A callable that will be called once with the specified arguments.

args and kwds

Positional and keyword arguments to use with the callable parameter.

Result and side effects

The function adds the passed parameter into an internal queue and will call it as soon as FileMaker notifies the plug-in of a pause that is equal to or greater than the specified level. The function returns no results.

Discussion

To run a function when idle once pass it to run_when_idle() along with the arguments. Note that the function result or whatever exception it might raise will be ignored and will only appear in the log.

To run something repeatedly you need to write a generator. run_when_idle() will add it to the queue and then the plug-in will call the generator's next() method on each pause that passes the level filter and then move it to the end of the queue. If the generators yields any values, they will be ignored. If calling next() raises an exception other than StopIteration, the plug-in will write it into the log and delete the generator. If the exception is StopIteration, the plug-in will simply delete the generator.

On shutdown the plug-in deletes all pending callables without calling them and throws the GeneratorExit exception into generators so they can quit.

version#Back to top

Return the FileMaker version as a three-element tuple:

version() -> (major, minor, micro)
Parameters

The function takes no parameters.

Result and side effects

The function returns a tuple of three numbers that specify major, minor, and micro version of FileMaker. The function has no side effects.

Example

In v11.0v3 calling version will produce the following:

>>> import filemaker
>>> filemaker.version()
(11, 0, 3)