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 1.3.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.
Attempts to unlock (register) your copy of 24U Toolbox Plug-In with the specified code.
| validSerialNumber | The valid code to unlock the full version of the plug-in. This parameter is optional in Filemaker Server for server registration - it tries to register with available serial numbers. |
If the code is valid, 24U Toolbox Plug-In gets unlocked and stays in this state until you quit the FileMaker Pro application, deactivate the plug-in, or the registration code expires. While unlocked, 24U Toolbox Plug-In is fully functional and does not bother the user with a shareware reminder.
It returns 0 if the plug-in was successfully registered. Status code 57005 means the plug-in expired and 52973 means the license number for the specified code has been exceeded. Without parameters function checks plug-in registration and reloads serial numbers from the 24UServerReg.txt on server. It returns registration warning as Toolbox_Get( "registrationWarning" ).
Toolbox_Register( "TBX10J-CM244H-U4UGBN" )
This function will register the plug-in with serial number TBX10J-CM244H-U4UGBN. This method is useful when you register the plug-in with developer license but it can be used for end-user licenses as well.
Note: All serial numbers here are only for demonstration purposes. They will not work in real 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 MAX OS X. |
| "PHP" | PHP script | The scriptText is a PHP Script. Available on MAX 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.
| 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_SetScriptEvent( "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_SetScriptEvent( "ctrl alt F1" ; "" )
This removes all installed scripts for shortcut "ctrl+alt+F1".
Toolbox_SetScriptEvent( "" ; "" )
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.
It will lock all active windows or all windows with title defined in windowList.
| windowList | This optional parameter strictly define which windows should be locked. Use value list delimited by a line break. |
This command tries to lock all active windows or all windows with title defined in windowList.
Locked windows cannot be focused by keyboard or mouse action. Focused windows will remain its focus even if FileMaker tries to change it.
All new FileMaker windows (created by script for example) are locked automatically if windowList is not defined. Otherwise the plug-in will not lock any other window than defined ones.
Dialog windows of Script Maker, Script Debugger, Data Viewer etc. are not locked.
The function returns 0 if it managed to lock down all defined FileMaker windows. In the case of error, the function returns negative error code. In FileMaker Pro 11 and newer the function does nothing and returns status code -4 (not implemented).
This command is useful only on Mac OS X on FileMaker Pro 8.5 - 10. Previous or next FileMaker Pro versions are not supported. It prevents from switching focus and it is an expert feature. Use it on your own risk!
Toolbox_LockWindows
Start effects described in description and returns 0.
Unlocks windows previously locked by Toolbox_LockWindows or all locked windows with title defined in windowList.
| windowList | This optional parameter strictly define which windows should be unlocked. Use value list delimited by a line break. |
Unlock windows previously locked by Toolbox_LockDown. If no window is locked it does nothing.
The function returns 0 if it managed to unlock all defined FileMaker windows. In the case of error, the function returns negative error code. It always attempt to unlock the windows even in the case of error. If the function is not supported it returns error -4 (not implemented).
This command is useful only on Mac OS X on FileMaker Pro 8.5 - 10. Previous or next FileMaker versions are not supported. Use it on your own risk!
Toolbox_UnlockWindows
Unlocks FileMaker windows. You can click to them, change focus and work normally.
This function returns Toolbox Plug-In internal parameters.
| selector | What parameter to get. |
| selector | Description |
|---|---|
| "isLocked" | If the Plug-in locked FileMaker windows it returns 1, otherwise 0. |
| "lastError" | Returns the Plug-In last error. |
| "lastErrorMessage" | Returns the Plug-In last error message. |
| "registrationWarning" | Check registration status and returns number which means: 0 - Plug-In registered and fully operational, 1 - Plug-In in Demo mode, 2 - License number exceeded, 3 - Plug-In expired. |
| "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.".