24U Toolbox Plug-In 2.0 Syntax

Toolbox_Version( { versionFormat } )

Returns version string of the active 24U Toolbox Plug-In, formatted as requested by the parameter.

Parameters

versionFormatDefines the format of the returned version.

Parameter values for versionFormat

"short"To get just the version number. Default value.
"long"To get the plug-in name followed by its version number.
"platform"To get the platform the code is currently running on.
"autoupdate"To get autoupdate compatible (comparable) version number.

Description

This function is very important and its output format is uniform in all 24U Plug-Ins. You should call this function every time you need to check if the plug-in is properly installed to the FileMaker Pro. Even if the plug-in is not registered (or badly registered) this function should work. Calling this function in the startup script of your solution is recommended.

Result

Returns requested version format or platform. If this function returns "?" then the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.

Examples

Toolbox_Version( "long" )
This returns the plug-in name and its version. In this case it is "24U Toolbox Plug-In 2.0".

Toolbox_Version( "platform" )
Returns "Mac OS X" or "Windows" depending on the platform the plug-in is currently running.

Toolbox_Version( "autoupdate" )
Returns "01010300" for the plug-in version 1.1.3.

Toolbox_Register ( selector )

Provides special functionality to operate with plugin serial numbers.

Parameter values for selector

SerialNumberRegister given SerialNumber and return an error code.
EmailAddressTries to activate with given email address and return an error code.
"Registration window"Show the "Registration window" and return 0.
"About window"Show the "About window" and return 0.
"Status"Return the actual registration state of the plugin: "Demo", "Demo expired", "Trial", "Trial Expired", "Registered" or "Dead".
It may return different values in client solutions and server side scripts, depending on the types of licenses the product is registered with.
"Unregister"Unregister all serial numbers related to the product and return an error code.

Description

Use this function to register or unregister 24U Toolbox Plug-In, to get information about current registration state, or to invoke GUI providing basic registration information and purchase capabilities.

Result

Returns zero or error code depending on the selector.

Examples

Toolbox_Register( "TBX25C016-BXMW-VNW7-L8AJ-3KGX-VWG8" )
This function will register the plug-in with client serial number TBX25C016-BXMW-VNW7-L8AJ-3KGX-VWG8 for 16 users.

Toolbox_Register( "user@mail.com" )
In case you do not have a serial number but you want to try the plug-in out, use the string with your email address as selector.

Toolbox_Register( "unregister" )
This function will unregister every serial number related to 24U Toolbox Plug-In.

Toolbox_Register( "About window" )
Similar to opening FileMaker preferences, navigating to the Plug-Ins tab and double-clicking on 24U Toolbox Plug-In.

Note: All serial numbers here are only for demonstration purposes. They will not work in the plug-in.

Toolbox_ExecuteSQL( SQLCommand { ; fieldSeparator { ; recordSeparator } } )

Tells the plug-in to execute SQL command and returns the result.

Parameters

SQLCommandThe SQL command which should be executed.
fieldSeparatorOptional field separator. Only the first character is used. The default field separator is a "Tab".
recordSeparatorOptional record separator. Only the first character is used. The default record separator is a line break.

Description

This command tries to execute SQL command and returns the result. If an array of multiple records is a result of the command, it is returned as tab delimited text with records separated by returns, unless custom separators are specified.

Result

The function returns the result of the SQL Command. In the case of error, the function returns negative error code.

Toolbox_ExecuteSQL( "select * from FileMaker_Tables" )
Returns a list of FileMaker tables.

Toolbox_DoSystemScript( scriptText ; scriptInterpreter )

Tells the plug-in to launch the specified script in the system shell.

Parameters

scriptTextThe text of the script that should be run.
scriptInterpreterThe interpreter that should run the script.

Possible values for scriptInterpreter

scriptInterpreterScript typeDescription and platform
"APPLE"Apple scriptThe scriptText is an AppleScript. Available on MAC OS X.
"BASH"Bash scriptThe scriptText is a Bash Script. Available on MAX OS X.
"PHP"PHP scriptThe scriptText is a PHP Script. Available on MAX OS X.
"BAT"Bat scriptThe scriptText is a bat text file. Available on Windows.
"VBS"Visual Basic scriptThe scriptText is a Visual Basic Script. Available on Windows.

Description

The function starts the script and waits until it finishes. Then it returns the text that has been printed on the standard output.

Result

Result of the script. It is usually the text that is printed by the script into the standard output. In the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain the error code.

Examples

Toolbox_DoSystemScript( "DIR C:" ; "BAT" )
This executes specified BAT script that should list all directories and files in the root directory of disk C: on Windows.

Toolbox_DoSystemScript( "echo HELLO" ; "BASH" )
This executes specified BASH script that should write "HELLO" to the standard output. The function should return "HELLO".

Toolbox_DoSystemScript( "php C:\php.php" ; "BAT" )
This executes BAT script that runs PHP script on Windows (only if PHP is correctly installed in system).

Toolbox_DoFileMakerScript( scriptName { ; scriptParameter } { ; delayOrTime } )

Tells the plug-in to launch the FileMaker script.

Parameters

scriptNameThe name of the script that should be executed. If the name is not valid, the function returns an error -50.
scriptParameterAny data that should be sent to the script as a parameter. No parameter is default.
delayOrTimeThe time interval after that the script should be executed, or TimeStamp value. In the first case use FileMaker number i.e. 1.8. Time is in [s]. Time must be a positive number. If the time delay for execution is longer than 1 day, a warning -1001 is generated, and the script is scheduled anyway. In the second case use FileMaker TimeStamp value.

Description

This command tries to schedule or launch the FileMaker script. If delayOrTime parameter is not specified, the script should run immediately.

Result

The function returns 0 if it managed to execute or schedule the script. In the case of error, the function returns negative error code.

Attention

The Toolbox plug-in cannot remember scheduled scripts if FileMaker is restarted.

Examples

Toolbox_DoFileMakerScript( "Default Script" )
This tries to execute the script named "Default Script" instantly.

Toolbox_DoFileMakerScript( "Default Script" ; "105" )
This tries to execute the script named "Default Script" instantly. The script receives a parameter with value 105.

Toolbox_DoFileMakerScript( "Default Script" ; "230" ; 10.5 )
This tries to schedule the script named "Default Script". The script receives a parameter with value 230. The script will be executed 10.5 seconds after this command being executed.

Toolbox_DoFileMakerScript( "Default Script" ; "50" ; GetAsTimestamp( "3/10/2012 11:30 AM" ))
This tries to schedule the script named "Default Script". The script receives a parameter with value 50. The script will be executed 3/10/2012 at 11:30 AM.

Toolbox_GetNameForIP( hostIP )

Gets hostname for the given IP.

Parameters

hostIPThe source IP address.

Description

Uses DNS service of the operating system to obtain the name for the given IP.

Result

The function returns a hostname. In the case of error, the function returns negative error code.

Examples

Toolbox_GetNameForIP( "209.85.149.99" )
Returns DNS record for IP Address 209.85.149.99.

Toolbox_GetIPforName( hostName )

Gets IP for the given hostname.

Parameters

hostNameThe source hostname.

Description

Uses DNS service of the operating system to obtain the IP for the given name.

Result

The function returns host IP. In the case of error, the function returns negative error code.

Examples

Toolbox_GetIPforName( "www.24u.cz" )
Returns an IP Address for hostname "www.24u.cz".

Toolbox_GetClientPublicIPAddress

Gets your public ip address.

Description

This command tries to get your internet public ip address. If you are not behind NAT the returned address is the same as the address from your network interface. Otherwise it returns the address of frontmost NAT in your network.

Result

The function returns your public ip address. In the case of error, the function returns negative error code.

Attention

If this command does not work in your system it may be due wrong firewall setting. Please enable two way communication for your FileMaker Pro in your firewall setting to get this command to work.

Examples

Toolbox_GetClientPublicIPAddress
Returns your public ip address.

Toolbox_GetSpecialWindows

Gets a list of opened special FileMaker windows.

Description

This command tries to get a list of special FileMaker windows such as "Data Viewer" and "Script Debugger" etc.

Attention

This command is disabled on server.

Result

The function returns a value list of the special FileMaker windows delimited by the line break.

Examples

Toolbox_GetSpecialWindows
Returns "Data viewer" if it is opened.

Toolbox_GetPrinterNames

Gets a list of installed printers.

Description

This command tries to get a list of printers currently installed in the system.

Result

The function returns the list of printers currently installed in the system. The printer names are delimited by line break.

Examples

Toolbox_GetPrinterNames
Returns the list of printers currently installed in the system.

Toolbox_GetDefaultPrinter

Gets the default printer.

Description

This command gets the name of default printer currently used in the system.

Result

The function returns the name of default printer of the current session. If no printer is set as default, the function returns "".

Examples

Toolbox_GetDefaultPrinter
Returns the name of default printer of the current session.

Toolbox_SetDefaultPrinter( printerName )

Sets specified printer as a default printer.

Parameters

printerNameThe identifier of the printer which should be set as default.

Description

This command sets the printer described in printerName parameter as a default printer in the system.

Result

The function returns the name of the printer which was actually set. In the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code.

Note

Use Toolbox_GetPrinterNames to obtain the list of printers and choose one line as a parameter for this function.

Examples

Toolbox_SetDefaultPrinter( "HP710" )
Sets a "HP710" as a new default printer for the system or returns "?" if "HP710" cannot be the default one.

Toolbox_SetScriptShortcut( key ; scriptName { ; scriptParameter } { ; scriptControl } )

Assigns a keyboard shortcut for script. All keyboard shortcuts are forgotten when FileMaker quits.

Parameters

keyThe keyboard shortcut in format Modifier & " " & rawKey. Modifier can be: "", "shift", "ctrl", "alt", "super" or their combination like "shift alt" or "ctrl alt". The "super" key means Apple key on Mac or Windows key on Windows. RawKey can be any key from keyboard + some special keys: "F1" - "F13", "enter", "esc", "pageup", "pagedown", "up", "down", "left", "right", "delete", "backspace", "space", "tab". RawKey parameter is case insenstive.
scriptNameThe name of script which should be triggered.
scriptParameterThe optional script parameter.
scriptControlThis optional parameter tells FileMaker how to handle another runing scripts,when script specified in this command is triggered. Possible values are: "Halt", "Exit", "Resume", "Pause".

Description

Assigns a keyboard shortcut for script. All keyboard shortcuts are forgotten when FileMaker quits.

Result

The function returns 0 if event is successfully installed or uninstalled. In case of error the function returns negative error code.

Attention

Keys "F8" - "F13" are usually reserved for system functions on Mac OS X. Shortcuts will interfere with these functions.

This command is disabled on server.

Examples

Toolbox_SetScriptShortcut( "ctrl alt F1" ; "Default Script" )
This installs the script named "Default Script" for shortcut "ctrl+alt+F1". When this shortcut is pressed, the script will be triggered.

Toolbox_SetScriptShortcut( "ctrl alt F1" ; "" )
This removes all installed scripts for shortcut "ctrl+alt+F1".

Toolbox_SetScriptShortcut( "" ; "" )
This removes all installed scripts for all previously inserted shortcuts.

Toolbox_RegExp_PatternCount( text ; searchPattern )

Finds a defined regular expression pattern in the text and returns the number of occurrences.

Parameters

textThe source text where to perform find.
searchPatternRegular expression defining what to find.

Description

This function will find a defined regular expression pattern in the text and returns the number of occurrences. Text in "searchPattern" parameter can be styled. If so the function will become style sensitive.

Result

The function return the number of occurrences found. In the the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code.

Examples

Toolbox_RegExp_PatternCount( "I was born in USA 12/02/1973." ; "([0-9]{1,2})[./-]([0-9]{1,2})[./-]([0-9]{2}|[0-9]{4})" )
Returns 1 because there is one date in the string.

Toolbox_RegExp_Substitute( text ; searchPattern ; replaceString1 { ; replaceString2 ... } )

Finds and replaces pattern in specified text.

Parameters

textThe source text where to perform find & replace.
searchPatternRegular expression defining what to find.
replaceString1Text which will replace found string.
replaceString2 ...The next text to replace found string. The number of strings should be the same as the regular expression needs.

Description

This function finds and replaces found text. Text in "searchPattern" parameter can be styled. If so the function will become style sensitive.

Result

The function returns text with replaced patterns. In the the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code.

Examples

Toolbox_RegExp_Substitute( "I was born in USA 12/02/1973." ; "([0-9]{1,2})[./-]([0-9]{1,2})[./-]([0-9]{2}|[0-9]{4})" ; "10" ; "12" ; "2008" )
Returns "I was born in USA 10/12/2008.".

Toolbox_MergeText( text )

This function finds values in the FileMaker text and replaces them by their values.

Parameters

textText which should be searched and merged. All <<fieldname>> parts are substituted by the real value of the fieldname. All <<$variable_name>> parts will be substituted by the real value of the variable.

Description

This function finds values in the FileMaker text and replaces them by their values. All values are calculated only once. If the value contains the style this style is used. Otherwise the original style is preserved.

Result

The function returns merged text. In the the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code.

Examples

Toolbox_MergeText( "There are <<NumberField>> records." )
If the field named NumberField contains number 5 it returns "There are 5 records.".

Toolbox_ValueType( value )

This function returns the type of its parameter.

Parameters

valueFileMaker value which type you want to obtain.

Description

The function determines the type of its parameter. It can be FileMaker Text, Number, Date, Time, Timestamp or Container. This can be useful when you need precisely control script or custom function which is dependent on parameter type.

Result

The function always return FileMaker text and never fails. It can return "Text", "Number", "Date", "Time", "Timestamp", "Container" or "" for unknown type.

Examples

Toolbox_ValueType( "There are 5 records." )
Returns "Text" because input value type is FM text.

Toolbox_Get( selector )

This function returns Toolbox Plug-In internal parameters.

Parameters

selectorWhat parameter to get.

Possible values for selector

selectorDescription
"lastError"Returns the Plug-In last error.
"lastErrorMessage"Returns the Plug-In last error message.
"registrationWarning"The selector has been deprecated in favor of Toolbox_Register("Status").
"stderr"Returns standard error output of the last executed script. Supported are Bash and PHP.

Description

Generic function to get various plug-in parameters.

Result

The function returns state of required parameter. In the the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code. Toolbox_Get( "lastError" ) never fails.

Examples

Toolbox_Get( "lastError" )
Returns last function error code or 0 if last function was performed properly.

Toolbox_Set( selector ; newValue )

This function sets Toolbox Plug-In internal parameters.

Parameters

selectorWhat parameter to set.

Possible values for selector

selectorDescription
"globalDieInterval"Global variable can be set to be automatically erased when their parent database file is closed. The plug-in uses polling mechanism to determine if the file has been closed (evaluating function DatabaseNames). This interval specifies how often is should check the file is closed. The default value is 60 seconds and you can specify even fraction of seconds to be perfectly accurate. However try to keep it as long as possible (ones of seconds at least). The polling requires system resources and calling this often will slow down the FileMaker Pro application.

Description

Generic function to get various plug-in parameters.

Result

The function returns state of required parameter. In the the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code. Toolbox_Get( "lastError" ) never fails.

Examples

Toolbox_Set( "globalDieInterval" ; 9.5 )
Sets parameter "globalDieInterval" to 9.5 seconds.

Toolbox_SetGlobal( key ; value { ; moreOptions } )

Stores global value which can be read on any database.

Parameters

keyUnique key to the dictionary of values. This key should be unique across all opened databases.
valueFileMaker field or variable. Field / variable type is also stored.
moreOptionsOptions to specify some special behavior for previous key-value combination.

Possible values for moreOptions parameter.

valuedescription
"dieOnClose"The current key-value combination will be erased when you close the current database.

Description

Use this function to store global value which can be obtained by Toolbox_GetGlobal( key ) in any opened database. If "dieOnClose" is not specified the key-value combination will live until the FileMaker application is closed. Specifying the "dieOnClose" parameter will cause the plug-in will periodically check if the database file is opened (the plug-in will use Get( FileName ) and DatabaseNames functions from FileMaker calculation engine) and erase key-value combination if the database has been closed. The plug-in is not able to distinguish between two different databases with the same name.

To manually delete value stored under a key call Toolbox_SetGlobal( key ; "" ). To manually delete all global values call Toolbox_SetGlobal( "" ; "" ).

Result

The function returns the actual value which has been set under the key. In the the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain the error code.

Examples

Toolbox_SetGlobal( "g_UserContext" ; "user-defined-context-1" )
This will set value "user-defined-context-1" under the key "g_UserContext". It can be read by calling Toolbox_GetGlobal( "g_UserContext" ) in any opened solution.

Toolbox_SetGlobal( "g_UserContext" ; "user-defined-context-1" ; "dieOnClose" )
This will set value "user-defined-context-1" under the key "g_UserContext". It can be read by calling Toolbox_GetGlobal( "g_UserContext" ) in any opened solution. If the database file, where Toolbox_SetGlobal has been called, is closed, the value "user-defined-context-1" will be reset to "". There is the maximum time interval between file closing and value erasing. This interval can be set by Toolbox_Set( "globalDieInterval" ; newInterval ) and by default it is set to 60 seconds.

Toolbox_SetGlobal( "g_Picture" ; PictureField )
The plug-in will store content of PictureField into into the global dictionary under the key "g_Picture". This container can be loaded any time from any opened solution until the FileMaker application is closed or value reset.

Toolbox_GetGlobal( key )

Loads global value previously stored by Toolbox_SetGlobal.

Parameters

keyUnique key to the dictionary of values. This key should be unique across all opened databases.

Description

Use this function to load global value previously stored by Toolbox_SetGlobal.

Result

The function returns the actual value for key. If the key has not been specified the function returns "". In the the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain the error code.

Examples

Toolbox_GetGlobal( "g_UserContext" )
The function returns actual value of global key "g_UserContext".

Toolbox_GetTimestamp

Basic function for time measurement.

Description

This function uses most precise functions of the operating system to obtain current time (now). It creates a FileMaker timestamp which contains fractions of seconds so it can be used to measure time with more accuracy than one second. The function is also very fast: its execution time is approx. 30 µs long.

Result

FileMaker Timestamp with current time.

Examples

Toolbox_GetTimestamp
Returns most accurate timestamp. In the time of writing this manual it was: 27.5.2011 17:27:03,873641 (the timestamp is formatted using current, Czech locale).

Toolbox_Encode( encoding ; text )

The function for text encoding.

Parameters

encodingThe encoding of the input text and the encoding of the result.
textThe input text to be encoded.

Possible values for encoding

encodingDescription
"UTF-8 to Base64"The encoding of the input text is assumed to be UTF-8 and the encoding of the result will be Base64.

Description

This function encodes given input text to specified encoding. For decoding see Toolbox_Decode.

Result

The function returns encoded input text. In the case of an error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain the error code. Also note, that empty input text may not be well defined for various encodings.

Examples

Toolbox_Encode("UTF-8 to Base64" ; "Text to be encoded.")
Returns "VGV4dCB0byBiZSBlbmNvZGVkLg==".

Toolbox_Encode("UTF-8 to Base64" ; "")
Returns "".

Toolbox_Decode( encoding ; text )

The function for text decoding.

Parameters

encodingThe encoding of the input text and the encoding of the result.
textThe input text to be decoded.

Possible values for encoding

encodingDescription
"Base64 to UTF-8"The encoding of the input text is assumed to be Base64 and the encoding of the result will be UTF-8.

Description

This function decodes given input text to specified encoding. For encoding see Toolbox_Encode.

Result

The function returns decoded input text. In the case of an error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain the error code. Also note, that empty input text may not be well defined for various encodings.

Examples

Toolbox_Decode("Base64 to UTF-8" ; "QmFzZTY0IGVuY29kZWQgdGV4dC4=")
Returns "Base64 encoded text.".

Error Codes Table

Here is the list of all error codes which can be returned from the plug-in. The error codes are derived from MacErrors.h header file from Mac OS. If function fails it either returns "?" signaling error or it directly returns the error code. If it returns "?" you can use Toolbox_Get( "lastError" ) to obtain the code.

CodeDescription
0No error.All requested actions were successfull.
-4Not implemented.If you see this error please report the error and steps to reproduce it to 24U Support. This error should never be invoked in the release version of the plug-in.
-50Parameter error.Wrong number, type, value or order of parameter(s). Please check parameters against the documantation again.
2400Unknown error.Unexpected (probably system related) error occured.
24001Demo mode expired.If you want to keep using the plug-in, you must register it or buy it for particular environment.
24002Product expired.Trial period is over. If you want to keep using the product, you must buy it for particular environment.
24003SN limit was met.The serial number is already registered on too many computers.
24004Product is dead.The product expired and cannot be used any more. Please download the new version from 24U Software.
24005Invalid serial number.Serial number you entered is not valid.
24006Activation failed.Activation failed probably due to some network error. Please, check your connection to the internet and try again later.
24007Deactivation failed.Deactivation failed probably due to some network error. Please, check your connection to the internet and try again later.
24008Unknown serial number.The given serial number cannot be used for the current product. It has been stored so that other product can try to use it.
24009Blacklisted serial number.The given serial number has been blacklisted and cannot be used anymore. Please, contact 24U Support if you need more information.
24010eSellerate engine not installed.This product uses eSellerate to validate user registration and purchases, but its installation failed. Please, reboot the computer or try again later.