External Functions

External functions are used to access xmCHART from FileMaker Pro and are listed in FileMaker’s Specify Calculation dialog box. By convention, the names of xmCHART’s external functions are prefixed by "xmCH_".

FileMaker Dialog Box External Functions

The following eight external functions are available:

Arguments userName Required. The user name is case-sensitive and has to be entered exactly as provided by X2max Software.
activationCode Required. The activation code is case-sensitive and has to be entered exactly as provided by X2max Software. Activation codes for xmCHART 4 are prefixed by "V4–".
maxNumOfUsers Optional. With the 3rd argument maxNumOfUsers it is possible for developers to control the display of the maximum number of users per company in the xmCHART plug-in window (under FileMaker Pro menu item: Preferences... > Plug-Ins). This can be advantageous should you wish to individually design licenses for your database solutions. Assuming you hold a xmCHART Developer License for a maximum of 25 users/company: one time you license one of your database solutions for a max. of 25 users per company, another time, for example, for a max. of 10 users. In the latter case you can adapt the display in the xmCHART plug-in window accordingly by entering:

xmCH_Activate(​yourUserName;​yourActivationCode;​10)

Of course, this is only an optical correction to "synchronize" the display in the xmCHART plug-in window with your own license terms. The flexible number of users per company is limited by the respective xmCHART Developer License and is ignored by other licenses.
Return Value xmCH_Activate() returns always an empty string, regardless of whether the activation was successful or not. It is important to assign xmCH_Activate() to a FileMaker Pro field or $Variable, otherwise xmCHART is not activated.
Examples

xmCH_Activate("John Q. Doe";"V4-2L-94CXc6U4T83-Qs2T45Klz8")

xmCH_Activate("John Doe Software";"V4-43sQ-kabt6-Wid9r1cc4A-jmRw98KvV3Css";10)

FileMaker Dialog Box StartUp Script
Notes Since neither the user name nor the activation code is saved in a Preferences file or Registry entry, it is recommended to perform the activation of xmCHART in a FileMaker Pro start-up script in each of your database projects. You can define a start-up script under FileMaker Pro menu item: File > File Options... > Script Triggers > Event: OnFirstWindowOpen.
FileMaker Dialog Box File Options
Arguments sourceScript Required. Contains a list of xmCHART functions arranged as a large string of text in the form:

 

"OpenDrawing(width;​height[;resolution])

...

list of xmCHART functions

...

CloseDrawing()"

fileName Optional. The entered filename is shown in FileMaker’s Export Field to File dialog box under FileMaker Pro menu item: Edit > Export Field Contents...
FileMaker Dialog Box Export
uuid Optional. An uuid works like a session ID and makes it possible to access internal charting values such as curve fitting coefficients in a FileMaker server environment. You can safely ignore the uuid or simply enter an empty string unless you want to use the external functions xmCH_GetErrorMessage() or xmCH_GetCFValue() on FileMaker Server.
errorFlags Optional. See external function xmCH_GetErrorMessage().
Return Value PNG bitmap image. The image quality can be controlled by using the argument resolution in function OpenDrawing().
Examples

xmCH_DrawChart("OpenDrawing(400;​300)

ChartData(2 4 5; 3 1 1; 5 4 2 2; 1 4 2 5; 7 6 1 4)

BarChart(shadow+label)

FillColorScheme(desert;​shaded)

BorderStyle(all;​none)

CloseDrawing()")

 

xmCH_DrawChart(sourceScript;​"gantt_chart";​"";​"003$$")

xmCH_DrawChart(sourceScript;​"MyDrawing";​$uuid)

xmCH_DrawChart(sourceScript;​"MyDrawing";​"";​"103")

Arguments chartIndex Required. Since several charts can be drawn at the same time within a drawing, it is necessary to specify the chart by using an index. The index corresponds to the order of chart definitions within OpenDrawing() and CloseDrawing(). If the drawing only consists of one chart, chartIndex is 1.
seriesIndex Required. The series index is used to determine which series the inquiry refers to. This is necessary as curve fittings for several series can be carried out simultaneously.
curveFittingID Required. The curve function index is used to define which curve function should be accessed. This is necessary as several curve fittings can be calculated simultaneously for one data series. The curve function index is identical to the argument type and has a value between -5 and 6. See Curve Fitting Constants.
valueID Required. The value index makes it possible to access individual coefficients. Value index 1 returns the correlation coefficient r², value index 2 the curve coefficient c₀, value index 3 the curve coefficient c₁, etc.
format Optional. As an option, the coefficient returned by the function xmCH_GetCFValue() can be formatted accordingly by using a format specifier. If no format specifier is defined, the default format specifier "|u|" is used. All format specifiers including numerous examples can be found in Output Numbers.
uuid Optional. An uuid is only required if xmCHART is installed on FileMaker Server. The uuid enables you to access the calculated curve fitting coefficients after calling xmCH_DrawChart(). The uuid must match the one you use in function xmCH_DrawChart(...;​...;​uuid;​​...)
Return Value Returns for curve fitting type -5 (pSpline) the coordinates of the p-spline and for curve fitting types between -4 and 6 a single curve fitting coefficient.
Examples

xmCH_GetCFValue(1;1;1;1) /* Returns correlation coefficient r² */

xmCH_GetCFValue(1;1;1;2) /* Returns coefficient c₀ */

xmCH_GetCFValue(1;1;1;3) /* Returns coefficient c₁ */

xmCH_GetCFValues(1;1;​-5;​1) /* Returns the x-coordinates of the P-spline. */

xmCH_GetCFValues(1;1;​-5;​2) /* Returns the y-coordinates of the P-spline. */

xmCH_GetCFValue(1;1;1;​3;​"|f6|";​$uuid)

 

The way in which the function xmCH_GetCFValue() works can be studied in Curve Fitting Example Databases. The files are unlocked and are available as a free download.

Arguments errorFlags Required.
errorFlags[1]: playAlertSound "0..1" (default: "0")
errorFlags[2]: showErrorCode "0..1" (default: "0")
errorFlags[3]: descriptionFlag "0..4" (default: "3")
 "0"...no description
 "1"...basic info
 "2"...basic info + location
 "3"...basic info + location + erroneous script part (default)
 "4"...for bug reports: same as "3" + error location in xmCHART source code.
errorFlags[4+]: messagePrefix (default: ""). A message prefix string is attached, only if showErrorCode is set to "1".
uuid Optional. An uuid is only required if xmCHART is installed on FileMaker Server. The uuid enables you to access information about the last error that occurred while trying to execute xmCH_DrawChart(). The uuid must match the one you use in function xmCH_DrawChart(...;​...;​uuid;​...).
Return Value Error message. If no error occurred, the function xmCH_GetErrorMessage() returns an empty string or "0" if showErrorCode is set (for example: "013").
Examples

xmCH_GetErrorMessage("003") /* Default in xmCHART 4. (Alert sound: off) */

xmCH_GetErrorMessage("103") /* Default in xmCHART 3. (Alert sound: on) */

xmCH_GetErrorMessage("110$$") /* Play alert sound and show error code, e.g. $$1180 */

xmCH_GetErrorMessage("003";​$uuid)

Notes Since xmCH_DrawChart() returns in case of an error already an error message, the external function xmCH_GetErrorMessage() is rarely needed.
Arguments resultFormat Required. resultFormat can be any text string with %1 and %2 as placeholders for the x and y coordinates.
Return Value Current mouse coordinates measured in pixels with the origin in the top-left corner of the FileMaker layout area. The returned coordinates do not include any horizontal or vertical scroll offsets.
Examples

xmCH_GetMouse("") /* Returns an empty string. */

xmCH_GetMouse("%1") /* Returns, for example: "241" */

xmCH_GetMouse("%1 %2") /* Returns, for example: "241 188" */

xmCH_GetMouse("y:%2") /* Returns, for example: "y:188" */

xmCH_GetMouse("(x=%1 y=%2)") /* Returns, for example: "(x=241 y=188)" */

Notes xmCH_GetMouse() is not supported in IWP/CWP, WebDirect and FileMaker Go.
Arguments versionFormat Required. Four formats are supported:
1 or "long"
2 or "short" (default)
3 or "autoupdate" (same as xmCH_Version­Auto­Update)
4 or "platform"
Return Value xmCHART version info.
Examples

xmCH_GetVersion("") /* Returns, for example: "4.0.7" */

xmCH_GetVersion("long") /* Returns, for example: "xmCHART 4.0.7" */

xmCH_GetVersion("short") /* Returns, for example: "4.0.7" */

xmCH_GetVersion("autoupdate") /* Returns, for example: "04000700" */

xmCH_GetVersion("platform") /* Returns "OS X" or "Windows" */

xmCH_GetVersion( 1 ) /* Same as xmCH_GetVersion("long") */

xmCH_GetVersion( 2 ) /* Same as xmCH_GetVersion("short") */

xmCH_GetVersion( 3 ) /* Same as xmCH_GetVersion("autoupdate") */

xmCH_GetVersion( 4 ) /* Same as xmCH_GetVersion("platform") */

Arguments languageID Required. Currently, the languages English and German are supported.
Language ID for English: 0 or "en"
Language ID for German: 1 or "de"
Return Value Language ID ("0" for English, "1" for German).
Examples

xmCH_SetLanguage("") /* English (default) */

xmCH_SetLanguage("en") /* English */

xmCH_SetLanguage("de") /* German */

xmCH_SetLanguage( 0 ) /* English */

xmCH_SetLanguage( 1 ) /* German */

Notes The language setting affects error messages and the default legend texts: "Series 1", "Series 2", ...
Arguments xmCH_VersionAutoUpdate has no arguments.  
Return Value xmCHART version info as an 8-character string in the format:
Major version (2 characters)
Minor version (2 characters)
Patch version (2 characters)
Build number (2 characters)
Example

xmCH_VersionAutoUpdate /* Returns, for example, for version 4.0.7: "04000700" */

Note xmCH_VersionAutoUpdate has been developed as a helper function for FileMaker’s AutoUpdate Plug-in. The AutoUpdate Plug-in is no longer supported as a valid way of updating plug-ins in FileMaker 13 and higher. Instead, insert xmCHART into a container field and use scripts and calculations to install and update xmCHART. For more information, please visit the FileMaker support page: Installing and updating plug-ins in FileMaker Pro
Scroll to Top
Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×