Installation


Install plugin in a standard way. On some modern operating system, you can have an error on the launch plugin. Use this recipe:

On the macOS:

Open terminal and type command like this (type correct path to DataBox.fmplugin file on your system)

Example:

sudo xattr -rd com.apple.quarantine /Users/YourUserName/Library/Application\ Support/FileMaker/FileMaker\ Pro/19.0/Extensions/DataBox.fmplugin

On the Windows:

  1. Click the right button and open file properties

  2. Found the certificate and import into The certificates to Trusted Root Certification folder


Understanding dataset


The DataBox main structure is a dataset. The dataset is a vector of some values or other vectors. The vector is a named list of values with a given type. Types of vectors can be numbers, texts, dates, times, timestamps or datasets.

The DataBox works with data types in the same way like the FileMaker does and it returns data in given type, not only in text format. For example, it returns the date in the format corresponding to the user locale. The dataset type vectors are a hierarchical structure containing a set of vectors with different nesting levels.

The DataBox store data in the memory of the computer. It is can be a user’s computer or FileMaker Server machine. Datasets in memory are independent of open databases in FileMaker. It’s mean if you close your FileMaker file your data will not delete and be accessible. It’s mean also, you can transfer data between databases uses DataBox.

After finishing work in the FileMaker and closing app, all datasets are deleted from memory automatically, but it’s always good to delete all created datasets after finishing work forcibly. It’s especially important when working on server, because datasets will be accumulated in server memory until the reboot of the FileMaker server.

When multi-users work with a plug-in on the server, one should remember to give unique names to datasets while using it in FileMaker scripts or calculations to avoid mess in one’s data, since datasets are stored in computer memory.


Create. Add. Delete


DB_NewDataSet

Creates a new object in plug-in memory as a vector from any string separated by the delimiter.

Format

DB_NewDataSet ( dataSetName ; dataType ; initValues ; delimiter ; replaceSign { ; datetimeMask } )

Parameters

dataSetName - the dataset name will be created

dataType - the type of new dataset

initValues - the string with values

delimiter - the delimiter in values string

replaceSign - if the dataset with dataSetName already exists, it will be replaced when replaceSign = 1

datetimeMask - optional. The format string for correct parsing Date/Time/Timestamp values. Details about datetimeMask.

Note: When datatype is equal to “dataset”, parameters “initValues” and “delimiter” are ignored, use "".

Result

“OK” - if successful

“Object already exists” - if the dataset with dataSetName already exists and replaceSign = 0

Error description - on error

Examples

DB_NewDataSet( "num1" ; "number" ; "1 2 3 4 5 6" ; " " ; 0 ) ;

New numeric dataset will be created in memory with name “num1” and values 1,2,3,4,5,6

DB_NewDataSet( "txt1" ; "text" ; "Scarlet Keira Charlize" ; " " ; 1 );

New text dataset will be created in memory with name “txt1” and values Scarlet, Keira, Charlize. The previous dataset “txt1” will be deleted.

DB_NewDataSet( "date1" ; "date" ; "2020-11-30 2020-12-17 2020-11-02" ; " " ; 0 ; "YYYY-MM-DD" );

New date dataset will be created in memory with name “date1” and values 2020-11-30,2020-12-17,2020-11-02.

DB_NewDataSet( "ds1" ; "dataset" ; "" ; "" ; 0 ) ;

New empty dataset will be created in memory with type “dataset” and name “ds1”.


DB_NewDataSetAsTable

Creates a new object in plug-in memory as a table. You should define name and type for each column.

Format

DB_NewDataSetAsTable ( dataSetName ; columnNames ; columnTypes ; replaceSign )

Parameters

dataSetName - the dataset name that will be created

columnNames - the column names are given via semicolon without spaces

columnTypes - the column types are given via semicolon without space in the same order with column names

replaceSign - if the dataset with dataSetName already exists, it will be replaced when replaceSign = 1

Result

“OK” - if successful

“Object already exist” if the dataset with dataSetName already exists and replaceSign = 0

Error description - on error

Examples

DB_NewDataSetAsTable ( "SimpleTable" ; "num;fname;sname;product;date" ; "number;text;text;text;date" ; 1 )

New dataset as empty table will be created in memory with the columns “num”, “fname”, “sname”, “product”, “date”, as in the following example:

[1]num

[2]fname

[3]sname

[4]product

[5]date


DB_AddValues

Adds values to dataset from separated text by delimiter.

Format

DB_AddValues ( dataSetName ; values ; delimiter {; datetimeMask } )

Parameters

dataSetName - the name of existing dataset

values - the values are separated by delimiter

delimiter - the delimiter in values string

datetimeMask - optional. The string format for correct parsing Date/Time/Timestamp values. Details about datetimeMask.

Result

Number of elements in dataset - if successful

“Object already exist” - if the dataset with dataSetName already exists and replaceSign = 0

Error description - on error

Examples

DB_AddValues ("num1" ; "6 7 8 9" ; " ")

Values 6, 7, 8, 9 will be added to existing dataset “num1”

DB_AddValues ("date1" ; "2020-06-19 2020-11-17 2020-01-30" ; " " ; "YYYY-MM-DD" )

Values 2020-06-19 2020-11-17 2020-01-30 will be added to existing dataset “date1”


DB_AddRows

Adds rows to table from separated text by delimiter.

Format

DB_AddRows ( dataSetName ; tabletext ; row_delimiter ; cell_delimiter {; skipFirstRowSign; datetimeMask ; } )

Parameters

dataSetName - the name of existing dataset

tabletext - the text separated by row_delimiter and cell_delimiter

row_delimiter - the delimiter in tabletext for rows

cell_delimiter - the delimiter in tabletext for cells

skipFirstRowSign - optional. If this parameter is 1, the first row will be ignored

datetimeMask - optional. The string format for correct parsing Date/Time/Timestamp values. Details about datetimeMask.

Result

Number of elements in dataset - if successful

“Object already exist” if the dataset with dataSetName already exists and replaceSign = 0

Error description - on error

Examples

DB_AddRows ( "SimpleTable" ; "1 Iren Collin 2021-02-01@2 Jhon Devis 2021-01-01" ; "@" ; " " ; 0 ; "YYYY-MM-DD" )

The SimpleTable will be filled with new data, as in the following example:

[1]num

1 2

[2]fname

Iren Jhon

[3]sname

Smith Trew

[4]date

2021-02-01 2021-01-01


DB_MoveDataSet

Moves existing dataset to the end of the other existing dataset vector with type “dataset”. The moved dataset no longer exist in the source place.

Format

DB_MoveDataSet ( dataSetNameSource ; dataSetNameTarget ; replaceSign )

Parameters

dataSetNameSource - the name of existing dataset will be move to target dataset

dataSetNameTarget - the name of existing dataset, where source dataset will be moved. The dataset should have “dataset” type

replaceSign - if the vector with name of dataSetNameSource already exists, it will be replaced when replaceSign = 1

Result

“OK” - if successful

Error description - on error

Examples

DB_NewDataSet ( "num1" ; "number" ; "1 2 3 4 5" ; " " ; 1 )

The dataset with name “num1” and values 1,2,3,4,5 will be created in memory

DB_NewDataSet ( "DS1" ; "dataset" ; "" ; "" ; 1 )

The empty dataset “DS1” will be created in memory

DB_MoveDataSet ( "num1" ; "DS1" ; 1 )

The dataset “num1” will be moved to dataset “DS1”


DB_SetValue

Sets the value to dataset element by path.

Format

DB_SetValue ( dataSetValuePath ; value )

Parameters

dataSetValuePath - the path to element needs to be set. The path is formed from the names of the nodes specified through the symbol $ and indicating the number of element in [ ]. E.g.: DS1$num1[1]

value - the new value will be set

Result

“OK” - if successful

Error description - on error

Examples

DB_SetValue ( "DS1$num1[1]" ; "55" )

For the first element in node num1 will be set value 55


DB_Seq

Creates dataset as sequence of numbers, dates, time, timestamps from start position to end position with some step.

Format

DB_Seq ( dataSetName ; dataType ; start ; end {; step } )

Parameters

dataSetName - the dataset name will be created

dataType - the type of new dataset. It can be: num, date, time and timestamp.

dataSetValuePath - the path to element needs to be set

start - the start value. For dataset in date format it’s better to use FM function Date() or use values from fields in date format. The same rule is used for timestamp.

end - the end value. For dataset in date format it’s better to use FM function Date() or use values from fields in date format. The same rule is used for timestamp.

step - the step of increasing or decreasing sequence, by default 1.

Result

“OK” - if successful

Error description - on error

Examples

DB_Seq ( "num" ; "number" ; 1 ; 5 ; 1 )

DB_Seq ( "num" ; "number" ; 1 ; 5 ; -1 )

DB_Seq ( "num" ; "number" ; 0 ; 0,9 ; 0,1 )

DB_Seq ( "date" ; "date" ; Date ( 12 ; 25 ; 2021 ) ; Date ( 01 ; 10 ; 2022 ) ; 1 )

DB_Seq ( "time" ; "time" ; Time ( 08 ; 15 ; 00 ) ; Time ( 08 ; 16 ; 00 ) ; 1 )

DB_Seq ( "timestamp" ; "timestamp" ; Timestamp ( Date (02 ; 01 ; 2021 ) ; Time ( 08 ; 15 ; 00 ) ) ; Timestamp ( Date (02 ; 01 ; 2021 ) ; Time ( 08 ; 16 ; 00 ) ) ; 1 )


DB_Delete

Deletes dataset or value by index or name.

Format

DB_Delete ( dataSetName )

Parameters

dataSetName - The dataset name or path to the value will be deleted. The path to value is formed from the names of the nodes specified through the symbol $ and indicating the number of element in [ ]. E.g.: DS1$num1[1]

Result

“OK” - if successful

Error description - on error

Examples

DB_Delete ( "DS1" )

DB_Delete ( "DS1$num1[1]")


Getting


DB_GetValue

Returns value from dataset element by path. The name of child elements is returned for ‘dataset’ type.

Format

DB_GetValue ( dataSetValuePath )

Parameters

dataSetValuePath - the path to element needs to be gotten. The path to value is formed from the names of the nodes specified through the symbol $ and indicating the number of element in [ ]. E.g.: DS1$num1[1]

Result

Required value - if successful

“Index is out of range” - if there is no value with given index in dataset

Error description - on error

Examples

DB_GetValue ( "SimpleTable1$num1[1]" )


DB_GetIndexByValue

Returns index of the first founded element by value.

Format

DB_GetIndexByValue ( dataSetName ; value { ; startIndex } )

Parameters

dataSetName - the name of existing dataset or path to child node of dataset

value - the value needs to be found. FFor dataset in date format it’s better to use FM function Date() or use values from fields in date format. The same rule is used for timestamp

startIndex - optional. The number of element from where the search will be started

Result

Index of element - if successful

0 - if value wasn’t found by given path

Error description - on error

Examples

DB_GetIndexByValue ("num1" ; 23 )

DB_GetIndexByValue ("date" ; Date (02 ; 01 ; 2021 ) ; 6 )

DB_GetIndexByValue ("SimpleTable1$txt2" ; "Bell")


DB_Agregate

Returns aggregated value like minimum, maximum, sum or average for dataset or for given range of dataset.

Format

DB_Agregate ( dataSetName ; action {; start; end } )

Parameters

dataSetName - the name of existing dataset or path to node of dataset

action - the function will be applied for data

start - optional. The starting element number

end - optional. The ending element number

Result

Aggregated value - if successful

0 - if value wasn’t found by given path

Error description - on error

Examples

DB_Agregate ( "date1" ; "min" )

DB_Agregate ( "num1" ; "sum" ; 3 ; 5 )


DB_GetDataSet

Displays dataset as a list with named child elements or a list of dataset child elements values.

Format

DB_GetDataSet ( dataSetName )

Parameters

dataSetName - the name of existing dataset or path to child element of dataset

Result

Content of dataset - if successful

Error description - on error

Examples

DB_GetDataSet ( "SimpleTable1" )

Returns the following structure:

[1]num1 1 2 3 4 5

[2]txt1 Iren Jack Rolf Mark Ben

[3]txt2 Johnson Davis Brown Wilson Bell

[4]date1 2020-11-30 2020-12-17 2020-11-02 2020-11-09 2020-12-31

DB_GetDataSet("SimpleTable1$txt1")

Returns the following structure:

Iren Jack Rolf Mark Ben


DB_GetDataSetAsJSON

Returns dataset in JSON format.

Format

DB_GetDataSetAsJSON ( dataSetName { ; aloneElemenAsArray ; pretty } )

Parameters

dataSetName - the name of existing dataset or path to child element of dataset.

aloneElemenAsArray - optional. 1 or 0. If it equals 1, single value will be given in square brackets, if it equals 0 - the value will be given without brackets. 0 is by default.

pretty - optional. 1 or 0. It’s 1 by default, and it means that strings of JSON will be separated by line break. Otherwise all text will be written in one line.

Result

Content of dataset - if successful

Error description - on error

Examples

DB_GetDataSetAsJSON ( "SimpleTable1" )

Returns the following structure:

{

"num1": [ 1, 2, 3, 4, 5 ],

"txt1": [ "Iren", "Jack", "Rolf", "Mark", "Ben" ],

"txt2": [ "Johnson", "Davis", "Brown", "Wilson", "Bell" ],

"date1": [ "2020-11-30", "2020-12-17", "2020-11-02", "2020-11-09", "2020-12-31" ]

}

DB_GetDataSetAsJSON ( "SimpleTable2" ; 1 )

Returns the following structure:

{ "num1": 1,

"txt1": [ "Iren", "Jack", "Rolf", "Mark", "Ben" ],

"txt2": [ "Johnson", "Davis", "Brown", "Wilson", "Bell" ],

"date1": [ "2020-11-30", "2020-12-17", "2020-11-02", "2020-11-09", "2020-12-31" ]

}

DB_GetDataSetAsJSON ( "SimpleTable2$txt2" )

Returns the following structure:

[ "Johnson", "Davis", "Brown", "Wilson", "Bell" ]


DB_GetDataSetAsTextTable

Returns dataset as a separated text by delimiter.

Format

DB_GetDataSetAsTextTable ( dataSetName { ; row_delimiter ; cell_delimiter; headerOn ; columnsOrder ; start ; end; } )

Parameters

dataSetName - the name of existing dataset or path to child element of dataset

row_delimiter - optional.The delimiter in text for rows, line break - Char (10) - by default

cell_delimiter - optional.The delimiter in text for cells, space by default

headerOn - optional. Column header is off by default ( 0 ). Set the value to 1 to enable the header

columnsOrder - optional. The list of column names to be displayed in the desired order. If empty, then all columns are displayed

start - optional. The starting dataset element number

end - optional. The ending dataset element number.

Result

Content of dataset - if successful

Error description - on error

Examples

DB_GetDataSetAsTextTable ( "SimpleTable1" )

Returns the following structure:

1 Iren Johnson 2020-11-30

2 Jack Davis 2020-12-17

3 Rolf Brown 2020-11-02

4 Mark Wilson 2020-11-09

5 Ben Bell 2020-12-31

DB_GetDataSetAsTextTable ( "SimpleTable1" ; "@" ; "#" )

Returns the following structure:

1#Iren#Johnson#2020-11-30@2#Jack#Davis#2020-12-17@3#Rolf#Brown#2020-11-02@4#Mark#Wilson#2020-11-09@5#Ben#Bell#2020-12-31@###

DB_GetDataSetAsTextTable ( "SimpleTable1" ; Char(13) ; " " ; 1 )

Returns the following structure:

num1 txt1 txt2 date1

1 Iren Johnson 2020-11-30

2 Jack Davis 2020-12-17

3 Rolf Brown 2020-11-02

4 Mark Wilson 2020-11-09

5 Ben Bell 2020-12-31

DB_GetDataSetAsTextTable ( "SimpleTable1" ; Char(13) ; " " ; 1 ; "txt2;num1" ; 2; 4 )

Returns the following structure:

txt2 num1

Davis 2

Brown 3

Wilson 4


DB_GetDataSetAsHTMLTable

Returns dataset as HTML table.

Format

DB_GetDataSetAsHTMLtTable ( dataSetName ; tableParameters { ; start ; end ; customJS ; datasetWHtmlPart } )

Parameters

dataSetName - the name of existing dataset or path to child element of dataset

tableParameters - The set of parameters for HTML table formatting

start - optional. The starting dataset element number

end - optional. The ending dataset element number

customJS - optional. Any JavaScript, usually functions for processing data in table is used in “cond_function” in table description

datasetWHtmlPart - optional. Name of the new dataset which will be created and consist of separate parts HTML page. The dataset will be have four variables: CSS, JSBeforeBody, JSAfterBody and Body.

Result

Content of dataset - if successful

Error description - on error

Description

Format of HTML table is set by description of columns and a few common parameters.

The following parameters can be set via sign equal:

header - show or hide table header, it can be ‘on’ or ‘off’

header_class - the style of header in css

header_lock - lock table header, it can be ‘on’ or ‘off’. By default is off.

inlineChildTable - show or hide nested tables, it can be ‘on’ or ‘off’

container_height - height of table container. If height not specified height equal height of document

container_class - the style of container in css

row_onclick_script - name of the FileMaker script is applied by a click on row

row_onclick_script_column_as_parameter - the parameter for script from “row_onclick_script” parameter

row_class_odd - the style of odd table rows in css

row_class_even - the style of even table rows in css

row_class_hover - the style of hover table rows in css

columns.n - the name of column from dataset, n - the number of column in html-table

columns.n.prettyname - the name of column in table will be shown in header

columns.n.width - the width of column can be set in % and px

columns.n.format - dysplaing format of numeric values (C lang printf() style) and date, time and timestamp values (like mask, ex. YYYY-MM-DD hh:mm:ss)

columns.n.class - the style of column data in css

columns.n.class_header - the style of column header in css

columns.n.class_hover - the style of hover column in css

columns.n.onclick_script - name of the FileMaker script will be applied by a click on cell

columns.n.cond_function - the function for processing data can be used for example for indicating data or for changing format of data. The function body is set in “customJS” parameter

Examples

DB_GetDataSetAsHTMLtTable ( "SimpleTable1" ; " " )

Returns the following table:

DB_GetDataSetAsHTMLtTable ( "SimpleTable1" ;

`"

header = 'on';

row_onclick_script = 'script1';

row_class_odd = ' background-color: white; color: black; ';

row_class_even = ' background-color: lightgrey; color: black; ';

row_class_hover = ' background-color: green ; color: white; cursor:pointer;';

columns.1 = 'num1';

columns.1.prettyname = '#';

columns.1.width = '5%';

columns.1.class = 'color: red; font-size: 16pt;';

columns.1.onclick_script = 'script2';

columns.2 = 'txt1';

columns.2.prettyname = 'First Name';

columns.2.width = '15%';

columns.3 = 'txt2';

columns.3.prettyname = 'Second Name';

columns.3.width = '20%';

" ;

1 ; 4 ;

)

Returns the following table:


Manipulating


DB_sApply

Applies expression for each element of dataset. Stores results to the new dataset or updates source dataset.

Format

DB_sApply ( dataSetName ; expression { ; newDataSet ; newDataSetType} )

Parameters

dataSetName - the name of existing dataset or path to child element of dataset

expression - the calculation is applied for dataset elements

newDataSet - the name of new dataset will be created based on modified data. It’s optional, if the parameter is not set the data is updated in source dataset.

newDataSetType - the type of new dataset. It’s optional

Result

Modified data in source dataset or in new dataset - if successful

Error description - on error

Description

sApply can be considered as a loop from the first element of dataset to the last element. The expression is the body of loop and it will be evaluated for each loop iteration. For each iteration you can use two key words elemidx and elemvalue.

elemidx - is the number of the iteration in loop, like counter in loop.

elemvalue - is value of element of the iteration.

These keywords are a fast way to use element in expression without functions like DB_GetValue(). From another side, you can think about expressions like lambda-function from other programming languages (ex. C++).

The expression ids evaluated like FileMaker’s calculation, so you can use any FileMaker’s functions, including ‘Let()’ to create complex expressions.
As the expression is the text, one should set it in quotes. For convinience, one can use apostrophe signs instead of quotes inside the expression. DB_sApply replaces all apostrophe signs with quotes before evaluation.

Examples

DB_sApply ( "SimpleTable1$num1" ; "_elemidx_ &' ' &_elemvalue_ * 10 " ; "result" ; "text" )

DB_GetDataSetAsJSON ("result") returns:

[ "1 10", "2 20", "3 30", "4 40", "5 10" ]


DB_Uniq

Creates a new dataset with unique values from source dataset. It can be applied for all vector types except for dataset type.

Format

DB_Uniq ( dataSetFrom ; dataSetTo )

Parameters

dataSetFrom - the name of source dataset

dataSetTo - the name of target dataset

Result

The number of unique values - if successful

Error description - on error

Examples

DB_Uniq ( "SimpleTable1$num1" ; "Uniq_num" )


DB_Sort

Sorts data in dataset. It can be applied for all vector types except fordataset type. If dataset has dataset type, it sorts data only in direct column, not in all dataset.

Format

DB_Sort ( dataSetName { ; direction })

Parameters

dataSetName - the name of existing dataset or path to child element of dataset

direction - the order of sorting, 1 for ascending, 0 for descending. 1 is by default

Result

The number of sorted values - if successful

Error description - on error

Examples

DB_Sort( "txt1" )

DB_Sort( "SimpleTable1$txt1" ; 0 )


DB_Group

Groups dataset by one column and saves results to the new dataset. The new dataset has special structure: the first element is vector named by source column with grouped values, the second element is named Details, it includes vectors named R[index] - by number of grouped values. There are vectors containing grouped data inside vectors R.

Format

DB_Group ( dataSetName ; columnName ; newDataSetName )

Parameters

dataSetName - the name of existing dataset

columnName - the name of column for groupping

newDataSetName - the name of target dataset

Result

The number of grouped values - if successful

Error description - on error

Examples

For this dataset named SimpleTable3:

[1]num1

1 2 3 4 1

[2]txt1

Iren Jack Rolf Mark Ben

DB_Group ( "SimpleTable3" ; "num1" ; "SimpleTable4" )

returns:

[1]num1 1 2 3 4

[2]Details

[1]R1

[1]num1 1 1 [2]txt1 Iren Ben

[2]R2

[1]num1 2 [2]txt1 Jack

[3]R3

[1]num1 3 [2]txt1 Rolf

[4]R4

[1]num1 4 [2]txt1 Mark


Miscellaneous

DB_Version

Returns number of the verison of DataBox plug-In.

Format

DB_Version

Parameters

No parameters

Result

The number of verison - if successful

Error description - on error

Examples

DB_Version returns 1.0.1012


DB_Lenght

Returns objects number in dataset.

Format

DB_Lenght ( dataSetName )

Parameters

dataSetName - the name of existing dataset

Result

Objects number - if successful

Error description - on error

Examples

DB_Lenght ("SimpleTable1") returns 4

DB_Lenght ("SimpleTable1$num1") returns 5


DB_IsExist

Returns 1 if dataset exists in plug-in memory, otherwise 0.

Format

DB_IsExist ( dataSetName )

Parameters

dataSetName - the name of dataset

Result

1 or 0 - if successful

Error description - on error

Examples

DB_IsExist( "SimpleTable1" ) returns 1


DB_EnviromentInfo

Returns the list of datasets stored in plugin memory, with types and lengths.

Format

DB_EnviromentInfo

Parameters

No parameters

Result

The list - if successful

Error description - on error

Examples

DB_EnviromentInfo

returns

SimpleTable1; Type = dataset; Length = 4

Uniq_num; Type = number; Length = 4

Format of datetimeMask


YY or YYYY for years value

MM for months value

DD for days value

hh for hours value

mm for minutes value

ss for seconds value

Examples:

“YYYY-MM-DD” - for format like “2020-11-02”

“YY-MM-DD” - for format like “20-11-02”

“DD.MM.YYYY” - for format like “23.02.2020”

“MM.DD.YYYY” - for format like “02.23.2020”

“hh:mm:ss” - for format like “23:15:10”

“YYYY-MM-DD hh:mm:ss” - if you use format like “2020-11-02 23:15:10”

Note 1: We strongly recommend using leading zero for values. “02.23.2020” - is correct. “2.23.2020” - can be incorrect

Note 2: The time is always used in 24h format. The 12PM/AM format is not supported