Returns version string of the active 24U Toolbox Plug-In, formatted as requested by the parameter.
| versionFormat | Defines the format of the returned version. |
| "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. |
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.
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.
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.
Provides special functionality to operate with plugin serial numbers.
| SerialNumber | Register given SerialNumber and return an error code. |
| EmailAddress | Tries 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. |
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.
Returns zero or error code depending on the selector.
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.
Tells the plug-in to execute SQL command and returns the result.
| SQLCommand | The SQL command which should be executed. |
| fieldSeparator | Optional field separator. Only the first character is used. The default field separator is a "Tab". |
| recordSeparator | Optional record separator. Only the first character is used. The default record separator is a line break. |
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.
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.
Tells the plug-in to launch the specified script in the system shell.
| scriptText | The text of the script that should be run. |
| scriptInterpreter | The interpreter that should run the script. |
| scriptInterpreter | Script type | Description and platform |
|---|---|---|
| "APPLE" | Apple script | The scriptText is an AppleScript. Available on MAC OS X. |
| "BASH" | Bash script | The scriptText is a Bash Script. Available on MAC OS X. |
| "PHP" | PHP script | The scriptText is a PHP Script. Available on MAC OS X. |
| "BAT" | Bat script | The scriptText is a bat text file. Available on Windows. |
| "VBS" | Visual Basic script | The scriptText is a Visual Basic Script. Available on Windows. |
The function starts the script and waits until it finishes. Then it returns the text that has been printed on the standard output.
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.
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).
Tells the plug-in to launch the FileMaker script. Note: FileMaker scripts cannot be performed on FileMaker Server.
| scriptName | The name of the script that should be executed. If the name is not valid, the function returns an error -50. |
| scriptParameter | Any data that should be sent to the script as a parameter. No parameter is default. |
| delayOrTime | The 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. |
This command tries to schedule or launch the FileMaker script. If delayOrTime parameter is not specified, the script should run immediately.
The function returns 0 if it managed to execute or schedule the script. In the case of error, the function returns negative error code.
The Toolbox plug-in cannot remember scheduled scripts if FileMaker is restarted.
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.
Gets hostname for the given IP.
| hostIP | The source IP address. |
Uses DNS service of the operating system to obtain the name for the given IP.
The function returns a hostname. In the case of error, the function returns negative error code.
Toolbox_GetNameForIP( "209.85.149.99" )
Returns DNS record for IP Address 209.85.149.99.
Gets IP for the given hostname.
| hostName | The source hostname. |
Uses DNS service of the operating system to obtain the IP for the given name.
The function returns host IP. In the case of error, the function returns negative error code.
Toolbox_GetIPforName( "www.24u.cz" )
Returns an IP Address for hostname "www.24u.cz".
Gets your public ip address.
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.
The function returns your public ip address. In the case of error, the function returns negative error code.
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.
Toolbox_GetClientPublicIPAddress
Returns your public ip address.
Gets a list of opened special FileMaker windows.
This command tries to get a list of special FileMaker windows such as "Data Viewer" and "Script Debugger" etc.
This command is disabled on server.
The function returns a value list of the special FileMaker windows delimited by the line break.
Toolbox_GetSpecialWindows
Returns "Data viewer" if it is opened.
Gets a list of installed printers.
This command tries to get a list of printers currently installed in the system.
The function returns the list of printers currently installed in the system. The printer names are delimited by line break.
Toolbox_GetPrinterNames
Returns the list of printers currently installed in the system.
Gets the default printer.
This command gets the name of default printer currently used in the system.
The function returns the name of default printer of the current session. If no printer is set as default, the function returns "".
Toolbox_GetDefaultPrinter
Returns the name of default printer of the current session.
Sets specified printer as a default printer.
| printerName | The identifier of the printer which should be set as default. |
This command sets the printer described in printerName parameter as a default printer in the system.
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.
Use Toolbox_GetPrinterNames to obtain the list of printers and choose one line as a parameter for this function.
Toolbox_SetDefaultPrinter( "HP710" )
Sets a "HP710" as a new default printer for the system or returns "?" if "HP710" cannot be the default one.
Assigns a keyboard shortcut for script. All keyboard shortcuts are forgotten when FileMaker quits.
| key | The 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. |
| scriptName | The name of script which should be triggered. |
| scriptParameter | The optional script parameter. |
| scriptControl | This 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". |
Assigns a keyboard shortcut for script. All keyboard shortcuts are forgotten when FileMaker quits.
The function returns 0 if event is successfully installed or uninstalled. In case of error the function returns negative error code.
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.
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.
Finds a defined regular expression pattern in the text and returns the number of occurrences.
| text | The source text where to perform find. |
| searchPattern | Regular expression defining what to find. |
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.
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.
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.
Finds and replaces pattern in specified text.
| text | The source text where to perform find & replace. |
| searchPattern | Regular expression defining what to find. |
| replaceString1 | Text 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. |
This function finds and replaces found text. Text in "searchPattern" parameter can be styled. If so the function will become style sensitive.
The function returns text with replaced patterns. In the the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code.
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.".
This function finds values in the FileMaker text and replaces them by their values.
| text | Text 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. |
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.
The function returns merged text. In the the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code.
Toolbox_MergeText( "There are <<NumberField>> records." )
If the field named NumberField contains number 5 it returns "There are 5 records.".
This function returns the type of its parameter.
| value | FileMaker value which type you want to obtain. |
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.
The function always return FileMaker text and never fails. It can return "Text", "Number", "Date", "Time", "Timestamp", "Container" or "" for unknown type.
Toolbox_ValueType( "There are 5 records." )
Returns "Text" because input value type is FM text.
This function returns Toolbox Plug-In internal parameters.
| selector | What parameter to get. |
| selector | Description |
|---|---|
| "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. |
Generic function to get various plug-in parameters.
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.
Toolbox_Get( "lastError" )
Returns last function error code or 0 if last function was performed properly.
This function sets Toolbox Plug-In internal parameters.
| selector | What parameter to set. |
| selector | Description |
|---|---|
| "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. |
Generic function to get various plug-in parameters.
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.
Toolbox_Set( "globalDieInterval" ; 9.5 )
Sets parameter "globalDieInterval" to 9.5 seconds.
Stores global value which can be read on any database.
| key | Unique key to the dictionary of values. This key should be unique across all opened databases. |
| value | FileMaker field or variable. Field / variable type is also stored. |
| moreOptions | Options to specify some special behavior for previous key-value combination. |
| value | description |
|---|---|
| "dieOnClose" | The current key-value combination will be erased when you close the current database. |
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( "" ; "" ).
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.
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.
Loads global value previously stored by Toolbox_SetGlobal.
| key | Unique key to the dictionary of values. This key should be unique across all opened databases. |
Use this function to load global value previously stored by Toolbox_SetGlobal.
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.
Toolbox_GetGlobal( "g_UserContext" )
The function returns actual value of global key "g_UserContext".
Basic function for time measurement.
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.
FileMaker Timestamp with current time.
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).
The function for text encoding.
| encoding | The encoding of the input text and the encoding of the result. |
| text | The input text to be encoded. |
| encoding | Description |
|---|---|
| "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. |
This function encodes given input text to specified encoding. For decoding see Toolbox_Decode.
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.
Toolbox_Encode("UTF-8 to Base64" ; "Text to be encoded.")
Returns "VGV4dCB0byBiZSBlbmNvZGVkLg==".
Toolbox_Encode("UTF-8 to Base64" ; "")
Returns "".
The function for text decoding.
| encoding | The encoding of the input text and the encoding of the result. |
| text | The input text to be decoded. |
| encoding | Description |
|---|---|
| "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. |
This function decodes given input text to specified encoding. For encoding see Toolbox_Encode.
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.
Toolbox_Decode("Base64 to UTF-8" ; "QmFzZTY0IGVuY29kZWQgdGV4dC4=")
Returns "Base64 encoded text.".
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.
| Code | Description | |
|---|---|---|
| 0 | No error. | All requested actions were successfull. |
| -4 | Not 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. |
| -50 | Parameter error. | Wrong number, type, value or order of parameter(s). Please check parameters against the documantation again. |
| 2400 | Unknown error. | Unexpected (probably system related) error occured. |
| 24001 | Demo mode expired. | If you want to keep using the plug-in, you must register it or buy it for particular environment. |
| 24002 | Product expired. | Trial period is over. If you want to keep using the product, you must buy it for particular environment. |
| 24003 | SN limit was met. | The serial number is already registered on too many computers. |
| 24004 | Product is dead. | The product expired and cannot be used any more. Please download the new version from 24U Software. |
| 24005 | Invalid serial number. | Serial number you entered is not valid. |
| 24006 | Activation failed. | Activation failed probably due to some network error. Please, check your connection to the internet and try again later. |
| 24007 | Deactivation failed. | Deactivation failed probably due to some network error. Please, check your connection to the internet and try again later. |
| 24008 | Unknown 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. |
| 24009 | Blacklisted serial number. | The given serial number has been blacklisted and cannot be used anymore. Please, contact 24U Support if you need more information. |
| 24010 | eSellerate 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. |