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 seven external functions are available in xmCHART 5:

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. All activation codes for xmCHART 5 are prefixed by "V5–..." (xmCHART 4: all activation codes 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 Returns "1" if the activation has been successful, otherwise "0" is returned.

Activating xmCHART 4:
Please note that xmCH_Activate() returns in xmCHART 4 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 4 is not activated.


Examples

xmCH_Activate("John Q. Doe";"V5-j29-spTi77xT-dz8fnbwzt-3lbn29j")

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

FileMaker Dialog Box Activate Script
Notes Important: Since neither the user name nor the activation code is saved in a Preferences file or Registry entry, one of the following options for activating xmCHART is recommended:
OPTION 1: 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
OPTION 2: Perform the activation right before calling xmCH_DrawChart() by using FileMaker’s built-in Let( ) function. This guarantees that xmCHART is always properly activated when calling xmCH_DrawChart(). For example:

 

Let([activate = xmCH_Activate("John Q. Doe";"V5-j29-spTi77xT-dz8fnbwzt-3lbn29j")];

xmCH_DrawChart("OpenDrawing()...CloseDrawing()"))

See Also Script Step: Activate[]
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 macOS: PDF vector image, Windows and Linux (FileMaker Cloud): 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")

See Also Script Step: Draw Chart[]
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_GetCFValue(1;1;​-5;​1) /* Returns the x-coordinates of the P-spline. */

xmCH_GetCFValue(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.

See Also Script Step: Get Curve Fitting Value[]
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.
See Also Script Step: Get Error Message[]
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 on FileMaker Server, FileMaker Cloud, FileMaker Go and in FileMaker WebDirect.
See Also Script Step: Get Mouse[]
Arguments Format Required. Three formats are supported:
1 or "Long"
2 or "Short" (default)
3 or "Norm"
Return Value xmCHART version info. Format "Norm" returns the normalized 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)
Examples

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

xmCH_GetVersion("Long") /* Returns, for example: "xmCHART 5.0.1" */

xmCH_GetVersion("Short") /* Returns, for example: "5.0.1" */

xmCH_GetVersion("Norm") /* Returns, for example: "05000100" */

See Also Script Step: Get Version[]
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 Deprecated. The language setting affects error messages and the legend default texts: "Series 1", "Series 2", ...
See Also
Scroll to Top
Your browser is out-of-date!

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

×