24U Toolbox Plug-In 1.0 Syntax

This file describes syntax of 24U Toolbox Plug-In's functions.

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

shortTo get just the version number. Default value.
longTo get the plug-in name followed by its version number.
platformTo get the platform of the code currently running.

Description

This function is very important and it has the same output format 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 "?" than the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.

Examples

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

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

Toolbox_Register ( originalSerialNumber { & " " & upgradeSerialNumber... } )

Attempts to unlock (register) your copy of 24U Toolbox Plug-In with the specified code.

Parameters

originalSerialNumberThe original (non upgrade) code to unlock the full version of the plug-in.
upgradeSerialNumberThe upgrade code to unlock the full version of the plug-in.

Description

If the code(s) 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.

Result

Returns a non-zero error code when the serial numbers are wrong if the numbers cannot be used. Returns 0 if the plug-in was successfully registered.

Examples

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.

Toolbox_Register( "TBX10J-CM244H-U4UGBN TBX12J-BTPDSK-D3AJ9C" )
Use combination of serial numbers delimited by empty space to register using upgrade code. The first code must be the original one, all other codes should be upgrade codes.

Toolbox_Register( "TBX10J-CM244H-U4UGBN TBX20J-BTPDSK-D3AJ9C TBX30J-5B4J7Z-W9KFNS" )
The example of using one original number and two upgrade numbers. The original is for version 1.0 and upgrades are for 2.0 and 3.0.

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

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

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

Parameters are:

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

Description

This command will try 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

Function returns the result of the SQL Command. In the case of error, the function will return negative error code.

Toolbox_DoSystemScript ( scriptText ; scriptInterpreter )

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

Parameters are:

scriptTextThe text of the script which should be run.
scriptInterpreterThe interpreter which 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.
"BAT"Bat scriptThe scriptText is a bat textfile. Available on Windows.
"VBS"Visual Basic scriptThe scriptText is a Visual Basic Script. Available on Windows.

Description

This command will try launch the specified script in the system shell. All higher mentioned script languages can be used.

Result

Function returns 0 if the system script was sucessfully started. In the case of error, the function will return negative error code. If entered scriptInterpreter is not supported by your system, function will return an error -1000.

Examples

Toolbox_DoSystemScript( "DIR C:" ; "BAT" )
This will execute specified bat script, which should list all directories and files in the root directory of disk C: to the shell window.

Toolbox_DoSystemScript( "Echo HELLO" ; "BASH" )
This will execute specified bash script, which should write "HELLO" to the shell window.

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

Tell the plug-in to launch the FileMaker script.

Parameters are:

scriptNameThe name of script which should be executed. If the name is not valid,the function will return an error -50.
scriptParameterAny data which should be sent to the script as parameter. The default is nothing, so no parameter.
delayOrTimeThe time interval after which 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. In the second case use FileMaker TimeStamp value. If time to execute is longer than 1 day, a warning -1001 is generated but the script will be sheduled.

Description

This command will try to shedule or launch the FileMaker script. If delayOrTime parameter is not specified, the script should run immediatelly, otherwise after specified delay or at specified TimeStamp value.

Result

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

Attention

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

Examples

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

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

Toolbox_DoFileMakerScript( "Default Script" ; "230" ; 10.5 )
This will try to shedule the script named "Default Script". The script will receive a parameter with value 230. The script will be executed 10.5 seconds after this command.

Toolbox_DoFileMakerScript( "Default Script" ; "50" ; GetAsTimestamp( "3/10/2009 11:30 AM" ))
This will try to shedule the script named "Default Script". The script will receive a parameter with value 50. The script will be executed 30/8/2008 at 11:30.

Toolbox_GetNameForIP ( hostIP )

Gets host name for the given IP.

Parameters are:

hostIPIP adress for which to find host name.

Description

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

Result

Function returns host name. In the case of error, the function will return negative error code.

Toolbox_GetIPforName ( hostName )

Gets IP for the given nost name.

Parameters are:

hostNameThe name of host for which to find IP.

Description

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

Result

Function returns host IP. In the case of error, the function will return negative error code.

Toolbox_GetClientPublicIPAddress

Gets your public ip address in the Internet.

Description

This command will try to get your public ip address in the Internet. 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

Function returns your public ip address. In the case of error, the function will return negative error code.

Attention

When 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_GetSpecialWindows

Gets list of the opened special FileMaker windows.

Description

This command will try to get list of the special FileMaker windows like "Data Viewer" and "Script Debugger" etc.

Result

Function returns the value list of the special FileMaker windows delimited by the line break.

Toolbox_GetPrinterNames

Gets list of installed printers.

Description

This command will try to get list of of printers currently installed in the system.

Result

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

Toolbox_GetDefaultPrinter

Gets the default printer.

Description

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

Result

Function returns the name of default printer.

Toolbox_SetDefaultPrinter ( printerName )

Sets specified printer as a default printer.

Parameters are:

printerNameThe correct printer description.

Description

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

Result

Function returns the name of the printer which was actually set. In the case of error, the function will return negative error code.

Attention

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

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

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

Parameters are:

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

Function returns 0 if event is sucessfully installed or uninstalled. In case of error the function will return negative error code.

Attention

Keys "F9" - "F13" are reserved by system on Mac OS X. Therefore they can't be used in shortcuts on Mac OS X.

Examples

Toolbox_SetScriptEvent( "ctrl alt F1" ; "Default Script" )
This will install 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 will remove all installed scripts for shortcut "ctrl+alt+F1".

Toolbox_SetScriptEvent( "" ; "" )
This will remove 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 occureces.

Parameters are:

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 occureces. Text in "searchPattern" parameter can be styled. If so the function will become style sensitive.

Result

The function return the number of occureces found. In the the case of error, the function will return negative error code.

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

Finds and replaces pattern in specified text.

Parameters are:

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 will return negative error code.

Toolbox_MergeText ( text )

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

Parameters are:

textText which should be searched and merged. All <> 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 case of error, the function will return negative error code.

Toolbox_LockWindows ( { windowList } )

It will lock all active windows or all windows with title defined in windowList.

Parameters are:

windowListThis optional parameter scrictly define which windows should be locked. Use value list delimited by a line break.

Description

This command will try to lock all active windows or all windows with title defined in windowList.
Locked windows cannot be focused by keyboard or mouse action. The current focused FileMaker window cannot be switched to other FileMaker window using mouse or keyboard.
All new windows are locked automaticaly if windowList is not defined. Otherwise the plug-in will not lock any other windows than defined ones.
Dialog windows with Script Maker, Script Debuger, Data Viewer etc. are not locked.

Result

The function will return 0 if it managed to lock down all FileMaker windows. In the case of error, the function will return negative error code.

Attention

This command is usefull only on Mac OS X on FileMaker Pro 8.5 - 9. 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_UnlockWindows ( { windowList } )

Ulocks windows previously locked by Toolbox_LockWindows or all locked windows with title defined in windowList.

Parameters are:

windowListThis optional parameter scrictly define which windows should be ulocked. Use value list delimited by a line break.

Description

Ulock windows previously locked by Toolbox_LockDown. If no window is locked it does nothing.

Result

The function will return 0 if it managed to unlock all defined FileMaker windows. In the case of error, the function will return negative error code. It allways attempt to ulock the windows even in the case of error.

Attention

This command is usefull only on Mac OS X on FileMaker Pro 8.5 - 9. Previous or next FileMaker versions are not supported. Use it on your own risk!

Toolbox_Get ( selector )

This function returns Toolbox Plug-In internal parameters.

Parameters are:

selectorWhat parameter to get.

Possible values for selector

selectorDescription
"isLocked"If the Plug-in locked FileMaker windows it returns 1, otherwise 0.
"lastError"Returns Plug-In last error.

Description

This function returns Toolbox Plug-In internal parameters.

Result

The function will return state of required parameter. In the case of error, the function will return negative error code.