Server

TreeGrid server component

v1.2 for TreeGrid v3.6

TreeGrid server is dynamic link library (.dll for Windows and .so for Linux).

It is written in C++ and is very fast and not memory consuming.

Works upon XML data and provides intrinsic functionality for server side paging, sorting, filtering, calculations and updates.

Input data are the same as in client application (XML with defaults, XML with grid layout and XML with data). DLL exports all functions needed to support server paging and updating TreeGrid.

TreeGrid server can be used in ASP.NET, Java servlets / JSP, PHP or any server script environment that supports using dynamic link libraries.

All input / output data are in XML Internal format.

TreeGrid server does not care about sharing data among clients. Every client must have own instance of server grid, because of their own sorting and filter settings. If you want to support write access for more clients, you must call Save method for all opened grid with the same data.

Using TreeGrid server

All functions are exported as extern "C" __declspec(dllexport) ... __stdcall (standard C++ exports).

All strings parameters are in unicode. For all string handled functions there are functions ends with “A” using UTF8 strings (CreateGrid => CreateGridA).

Input XML strings can be standard XML “<...></...>” or entity encoded “< ... ></...>”

ASP.NET C#

Declare all needed functions with DllImport attribute and static extern keywords:

DllImport("TreeGrid.dll", CharSet=CharSet.Unicode, CallingConvention=CallingConvention.StdCall)]

public static extern return_type function_name( ... parameters ...);

If you want to place TreeGrid.dll anywhere else then in Windows/System32 directory you need to load it by function LoadLibrary before any its method is called.

To use LoadLibrary you must declare it in the same manner as TreeGrid functions:

[DllImport("kernel32.dll", CharSet = CharSet.Auto)] static extern IntPtr LoadLibrary(string lpFileName);

Supported .NET 1.0, 1.1, 2.0, ...

Whole declaration:

[DllImport("kernel32.dll", CharSet = CharSet.Auto)]

static extern IntPtr LoadLibrary(string lpFileName);

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern int CreateGrid(string Data, string Layout, string Defaults, string Text, string Bonus, string Bonus2);

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern int UpdateGrid(int Index, string Bonus);

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern int FindGrid(string Cfg);

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern int DeleteGrid(int Index);

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern void Clear();

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern string GetBody(int Index, string Cfg);

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern string GetPage(int Index, string Cfg);

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern int Save(int Index, string Input);

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern int SaveToFile(int Index, string FileName, int Type);

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern string GetData(int Index);

[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]

public static extern string LastError( );

ASP.NET VB

Declare all needed functions:

Declare Unicode Function function_name Lib "TreeGrid.dll" (... parameters ...) As return_type

If you want to place TreeGrid.dll anywhere else then in Windows/System32 directory you need to load it by function LoadLibrary before any its method is called.

To use LoadLibrary you must declare it in the same manner as TreeGrid functions:

Declare Auto Function LoadLibrary Lib "kernel32.dll" (ByVal lpFileName As String) As IntPtr

Supported .NET 1.0, 1.1, 2.0, ...

Whole declaration:

Declare Auto Function LoadLibrary Lib "kernel32.dll" (ByVal lpFileName As String) As IntPtr

Declare Unicode Function CreateGrid Lib "TreeGrid.dll" (ByVal Data As String, ByVal Layout As String, ByVal Defaults As String, ByVal Text As String, ByVal Bonus As String, ByVal Bonus2 As String) As Integer

Declare Unicode Function UpdateGrid Lib "TreeGrid.dll" (ByVal Index As Integer, ByVal Bonus As String) As Integer

Declare Unicode Function FindGrid Lib "TreeGrid.dll" (ByVal Cfg As String) As Integer

Declare Unicode Function DeleteGrid Lib "TreeGrid.dll" (ByVal Index As Integer) As Integer

Declare Unicode Sub Clear Lib "TreeGrid.dll" ()

Declare Unicode Function GetBody Lib "TreeGrid.dll" (ByVal Index As Integer, ByVal Cfg As String) As String

Declare Unicode Function GetPage Lib "TreeGrid.dll" (ByVal Index As Integer, ByVal Cfg As String) As String

Declare Unicode Function Save Lib "TreeGrid.dll" (ByVal Index As Integer, ByVal Input As String) As Integer

Declare Unicode Function SaveToFile Lib "TreeGrid.dll" (ByVal Index As Integer, ByVal FileName As String, ByVal Type As Integer) As Integer

Declare Unicode Function Save Lib "TreeGrid.dll" (ByVal Index As Integer) As String

Declare Unicode Function LastError Lib "TreeGrid.dll" ( ) As String

In PHP you need to use FFI expansion (foreign functions interface).

Under Windows you can use php_ffi.dll provided in TreeGrid distribution (located in /Server/Php), just copy it to your PHP expansion directory.

Under Linux you have to download FFI sources from PECL (http://pecl.php.net) and install it by command “pecl install ffi”

In code you need to create FFI instance by

$TreeGrid = new ffi ("[lib='path/TreeGrid.dll'] return_type function_name1(... paramaeters ...); return_type function_name2(... parameters ...); ...”

and using functions as methods of this instance.

! Attention ! PHP does not use Unicode, thus you must use UTF8 versions of functions handle strings with prefix “A” (CreateGridA).

! Also all returned strings are allocated, thus to avoid memory leaks you have to use FreeString function to free them. On Windows system only!

! Remember, PHP on Windows is simple CGI application without any state memory, after finishing request unloads all resources including TreeGrid.dll. Therefore you must not store indexes between requests, but you must store whole data to file (by SaveToFile) or database (by GetData).

Supported any PHP version with FFI.

Whole declaration:

$TreeGrid = new ffi ("[lib='$Path/../Server/TreeGrid.dll']

int CreateGridA(char* Data, char* Layout, char* Defaults, char *Text, char* Bonus, char *Bonus2);

int UpdateGridA(int Index, char* Bonus);

int FindGridA(char *Cfg);

void DeleteGrid(int Index);

void Clear();

void FreeString(char *String);

char* GetBodyA(int Index, char* Cfg);

char* GetPageA(int Index, char* Cfg);

int SaveA(int Index, char* Input);

int SaveToFileA(int Index, char* FileName, int Type);

char* GetDataA(int Index);

char* LastError( );

");

In Java there is used JNI (Java Native Interface) in provided package TreeGrid, class Server. Therefore you need create an instance of the TreeGrid.Server and use its methods.

First copy TreeGrid.jar file (located in /Server/Jsp directory of your TreeGrid distribution) to your JRE installed optional packages, usually located at “<java-home>\lib\ext”.

You can copy TreeGrid.dll file (located in /Server directory of your TreeGrid distribution) to your JRE BIN directory, usually located at “<java-home>\bin” or “<java-home>\lib\ext\x86”. <java-home> is directory where JRE is installed or JDK/jre. To run TreeGrid examples it is not needed.

Now you can in your code create TreeGrid.Server instance by

TreeGrid.Server TS = TreeGrid.Server();

If you have not copied TreeGrid.dll to JRE BIN directory, you must specify its path and name as parameter:

TreeGrid.Server TS = TreeGrid.Server (“TreeGrid_distribution_path/Server/TreeGrid.dll”);

Now you can call any TreeGrid server function as method of the TS instance. int G = T.CreateGrid( ... );

You can test if DLL was successfully loaded by static TreeGrid.Server.Loaded property. DLL is loaded when creating the first instance of TreeGrid.Server. If DLL loading has failed, the static String TreeGrid.Server.DllError contains the exception’s message string.

Supported any Java version with JNI.

TreeGrid server concepts

You have stored your data somewhere on disk or in database. When first request to this data arrives, you need to read you data and convert it to the TreeGrid XML internal format if you are using another and create TreeGrid instance from this data.

And fulfill the request.

For next request you have to resolve the TreeGrid instance the request belongs (by URL, by some user parameter, by <IO Session> attribute or by any you custom way) and fulfill request by calling GetPage, GetBody or Save method of the instance.

After every Update request or sometimes or by your custom request you will save all data to your original data store.

It is very useful to separate data (rows) that can be changed and updated from layout (columns, other settings). Layout is usually in static XML file, which is regenerated only when data layout changes, for example a column is added. Remember, TreeGrid instance saves data only, not layout.

When any function fails, it returns negative value for int or NULL for string. Error message can be read by LastError function.

Creating instance

Create TreeGrid instance from data in files (CreateGrid) or in strings (CreateGridData). This data must contain all data for the session.

Instance is created in memory and you will get handle (Index) to it.

The instance stays in memory until you delete it by DeleteGrid or Clear function or until TreeGrid server is not unloaded. TreeGrid server is unloaded for example if the server side script is restarted. In this case you need to save data from memory to persistent storage (disk (by SaveToFile) or database (by GetData)) and re-create it when processing next request.

On some systems (for example in PHP on Windows) is TreeGrid server unloaded immediately after client’s request is fulfilled, so in this case you must always save changed data to persistent storage as disk or database and create grid again when processing next request.

Particular instances are independent on the others. You can have more instances of the same data or different data. Count of instances is restricted by available memory only. Remember, the memory consumed by instance is usually similar to input size of input XML data in ASCII or half if they are in unicode. But always depends on data structure.

Updating instance

If you have created instance and you only need to change some of its settings, you can use UpdateGrid function.

Processing client’s request

When you have an index to TreeGrid instance, you can use next functions.

You can response to three main client’s request – to get body, to get one page and to update data.

Request GetBody

Body is whole grid data. When used server paging, it does not contain content of any page – in this case contains only page descriptions, page names and fixed rows.

Client requests body when

a) document is loaded for first time

b) document is reloaded

c) used server paging and rows have been re-sorted

d) used server paging and filter has changed

To get body just return GetBody function result.

Request GetPage

Page is one page when used server paging. When used another page, this request does not occur.

Client request page when page is displayed and were not downloaded yet.

To get page just return GetPage function result.

Request Update

Save occurs when client changed some data and is sending them to server to update.

If there is only one instance of TreeGrid for the document, you can just call Save function to update data to document. It is good idea to also save whole data to persistent storage to avoid loosing changes.

If there is more instances of TreeGrid for the document (more client simultaneously reads the same document) is good idea to permit just only client to change data to avoid access violation and data inconsistency. When the one chosen client changes data, call Save for all opened instances of the grid. Don’t forget, if you save opened instances to persistent storage, you need to update changes also in these data.

If there are more clients with write access to one document, you need to implement your own semaphores or another technique to avoid access violation.

Saving data back

When data are changed by Update request or by you custom calling UpdateGrid function you will need save instance data back to you original storage.

You can use function SaveToFile to save data to disk or get data in string from function GetData and update it manually, for example to database.

Remember, the saved data are sorted by last used sorting and contains filter settings, but always all rows, not only filtered.

When to update the original data depends on your needs. You can do after every Update request, after some time, or you can call your own request procedure when data is needed.

Other way is to save all input data into grid instance and simultaneously to the original data store by parsing input XML string in Update request. See XML structure of Upload request.

Temporary saving

You can use functions SaveToFile and GetData to temporary save data to persistent storage when server service is restarted or to free memory. After data save you can delete the instance by DeleteGrid function. In next request you will to create the instance again. Pass saved data as first parameter to CreateGrid or CreateGridData.

Function reference

CreateGrid

C++ int CreateGrid (wchar_t *Data, wchar_t *Layout, wchar_t *Defaults, wchar_t *Text, wchar_t *Bonus, wchar_t *Bonus2);

C# public static extern int CreateGrid (string Data, string Layout, string Defaults, string Text, string Bonus, string Bonus2);

VB Function CreateGrid (ByVal Data As String, ByVal Layout As String, ByVal Defaults As String, ByVal Text As String, ByVal Bonus As String, ByVal Bonus2 As String) As Integer

PHP int CreateGridA(char* Data, char* Layout, char* Defaults, char *Text, char* Bonus, char *Bonus2);

Java int CreateGrid (String Data, String Layout, String Defaults, String Text, String Bonus, String Bonus2);

Creates new grid instance from XML data in given files or strings. Returns grid index, that can be used in other functions.

Input parameters can be XML string (first character must be ‘<’ or ‘&’) or XML file.

Returns <0 for error (-1 input file not found, -2 file cannot be read, -3 bad XML format)

Data – required – the XML data rows. This is only data that can be saved back.

Layout – can be NULL – grid layout (columns, definitions, configuration, ...)

Defaults – can be NULL – grid defaults, usually Defaults.xml. Remember, some default settings is always required.

Text – can be NULL – grid text, usually Text.xml. In actual version is not used.

Bonus, Bonus2 – can be NULL - XML data in string, to change some settings

Remember, if you pass XML file as parameter, you must give absolute path. Relative paths in this context are very problematic.

UpdateGrid

C++ int UpdateGrid (int Index, wchar_t *Bonus);

C# public static extern int UpdateGrid (int Index, string Bonus);

VB Function UpdateGrid (ByVal Index As Integer, ByVal Bonus As String) As Integer

PHP int UpdateGridA (int Index, char *Bonus);

Java int UpdateGrid (int Index, String Bonus);

Updates Grid settings by XML string Bonus.

Returns 0 OK, -1 grid not found, -3 bad input XML

FindGrid

C++ int FindGrid (wchar_t *Cfg);

C# public static extern int FindGrid (string Cfg);

VB Function FindGrid (ByVal Cfg As String) As Integer

PHP int FindGridA (char *Cfg);

Java int FindGrid (String Cfg);

Looks for grid with the same Session attribute (<Grid><IO Session=’???’/></Grid>) as in given Cfg string.

Session parameter can be set in functions CreateGrid, CreateGridData, UpdateGrid, GetBody, GetPage, Save.

If Session parameter is not set, is by default the grid index returned from CreateGrid/CreateGridData.

Returns grid index or -1 grid not found, -3 bad input XML

DeleteGrid

C++ int DeleteGrid (int Index);

C# public static extern int DeleteGrid (int Index);

VB Function DeleteGrid (ByVal Index As Integer) As Integer

PHP int DeleteGrid (int Index);

Java int DeleteGrid (int Index);

Deletes the grid. Frees all its resources.

Returns 0 OK, -1 grid not found

Clear

C++ void Clear ( );

C# void Clear ( );

VB Sub Clear ( )

PHP void Clear ( );

Java void Clear ( );

Deletes all grids. Frees all resources.

But remember, this does not unlock the dll file. To unlock it, you must call FreeLibrary ( ), but only if it was loaded dynamically (in ASP.NET or Java it is not possible).

FreeString

C++ void FreeString (wchar_t *Str);

PHP void FreeStringA (char *Str);

Frees allocated string if calling environment cannot do this itself. In .NET or Java you don’t need to (you must not) use this function.

GetBody

C++ wchar_t * GetBody (int Index, wchar_t *Cfg);

C# public static extern string GetBody (int Index, string Cfg);

VB Function GetBody (ByVal Index As Integer, ByVal Cfg As String) As String

PHP char * GetBodyA (int Index, char *Cfg);

Java String GetBody (int Index, String Cfg);

Returns main data for TreeGrid in XML string. If Paging==3, returns only pages (tags <B>) without any child tags <I>.

Cfg – required - XML string with TreeGrid configuration – sorting and filters.

In C++ and PHP it returns allocated string that must be freed by FreeString function.

Function also modifies main data.

GetPage

C++ wchar_t * GetPage (int Index, wchar_t *Cfg);

C# public static extern string GetPage (int Index, string Cfg);

VB Function GetPage (ByVal Index As Integer, ByVal Cfg As String) As String

PHP char * GetPageA (int Index, char *Cfg);

Java String GetPage (int Index, String Cfg);

Returns data for one page if Paging==3 or children of row if ChildPaging==3.

Cfg – required – XML string with requested page (identified by position) or row (identified by id) and with TreeGrid configuration – sorting and filters.

Cfg contains requested page or row identification. Both requests are set by <B> tag, page is identified by Pos attribute and row by id attribute.

Cfg also contains setting for sorting and filters. If these settings do not correspond to settings in last call GetBody, the GetPage returns NULL.

Returns NULL if no page or row is requested or the requested page or row is not found or configuration changed.

Does not return rows marked as Filtered. Returns all cells with values set.

In C++ and PHP it returns allocated string that must be freed by FreeString function.

Function does not modify main data (only if configuration changes).

Save

C++ int Save (int Index, wchar_t *Input);

C# public static extern int Save (int Index, string Input);

VB Function Save (ByVal Index As Integer, ByVal Input As String) As Integer

PHP int SaveA (int Index, char * Input);

Java int Save (int Index, String Input);

Saves changes to main data.

Input is XML string with changed rows. It contains rows that have been added, deleted, moved or changed. Function irreversibly modifies main data.

Returns 0 OK, -3 bad Input XML, >0 number of rows not successfully saved

SaveToFile

C++ int SaveToFile (int Index, wchar_t *FileName, int Type);

C# public static extern int SaveToFile (int Index, string FileName, int Type);

VB Function SaveToFile (ByVal Index As Integer, ByVal FileName As String, ByVal Type As Integer) As Integer

PHP int SaveToFileA (int Index, char * FileName, int Type);

Java int SaveToFile (int Index, String FileName, int Type);

Saves data to file. Saves all rows, include all attributes (such Filtered). Saves in last state (sorting, filters, calculations).

FileName – required – FileName with path to save to.

Type – required – data format – 0 – UTF8, 1 – Unicode.

Returns 0 OK, -1 file cannot be created, -2 file cannot be written, -3 corrupted data

GetData

C++ wchar_t * GetData (int Index);

C# public static extern string GetData (int Index);

VB Function GetBody (ByVal Index As Integer) As String

PHP char * GetBodyA (int Index);

Java String GetBody (int Index);

Returns all data in string. This is the same as function SaveToFile, but always returns unicode (or ...A UTF8) string.

In C++ and PHP it returns allocated string that must be freed by FreeString function.

LastError

C++ wchar_t * LastError ( );

C# public static extern string LastError ( );

VB Function LastError ( ) As String

PHP char * LastError A ( );

Java String LastError ( );

Returns last error string message if any function returned error code. The last error is always cleared by calling any TreeGrid function.

New in version 1.2.

Calculations

TreeGrid server is written in C++ and therefore you cannot use all JavaScript code in formulas calculated on server as you can do if formula is calculated on client.

All names and keywords are case-sensitive.

Operators (sorted by priority):

! (logical negation) ~ (binary negation) – (unary minus)

* (multiplication) / (division) % (modulo)

+ (addition, number + number = number, number + string = string) – (subtraction)

< (less then) <= (less or equal) > (greater then) >= (greater or equal)

== (equal) != (not equal)

& (binary AND)

^ (binary XOR)

| (binary OR)

&& (logical AND)

|| (logical OR)

?: (conditional ternary operator => a ? b : c => if(a) return b; else return c; )

, (comma, separates parameters in functions)

number (floating point number, always starts with digit ‘0’ – ‘9’)

string (any characters in quotes “ ” or apostrophes ‘ ‘, the string cannot contain enclosing quote or apostrophe)

Identifiers:

ident (any string without quotations, starting with letter (‘a’ – ‘z’, ‘A’ – ‘Z’) or underscore ‘_’, can contain these characters and letters ‘0’ – ‘9’)

This ident returns value from actual row from column named ident.

func (any ident followed by left parenthesis ‘(‘, comma separated parameters and right parenthesis ‘)’ ).

Parameters can contain expression, except aggregate functions in fixed rows and function Get, their parameters must be constants.

(Fixed rows are calculated in special way due paging and function Get is special function.)

This func returns value the function calculated.

Get (Parent, ”column”) Returns the cell from column from immediate parent node, Parent is keyword without quotations, column must be quoted constant.

Get (id, “column”) Returns the cell from column from row identified by id. id is an id attribute of row, without quotations, column must be quoted constant.

sum ( ) Calculates sum of all children cell values in actual column (column for the formulas is calculated). Sums values as numbers only.

sum (“column”) Calculates sum of all children cell values in given column. Sums values as numbers only.

count ( ) Returns count of all children

<I id = ‘i’ A = ‘5’>

<I id=’i1’ A=’10’ B=’5.5’ C=’yes’ D=’no’F = ‘formula’>

<I id=’i11’ F=’100’ B=’200’/>

<I id=’i12’ F=’200’/>

<I id=’i13’ F=’300’ B=’400’/>

</I>

<I id=’i2’ E=’0.5’/>

</I>

In these data let’s have formula in second row (id=’i1’) for cell ‘F’:

A+B = 10+5.5 = 15.5

A+B+C = 10 + 5.5 + “yes” = 15.5yes

A+(B+C)+D = 10 + (5.5 + “yes”) + “no” = 105.5yesno

A*B*C = 10 * 5.5 * 0 = 0

A > 3 && B+1 > 6 ? C : D = 10 > 3 && 5.5+1>6 ? “yes” : “no” = yes

(!A+2) * -(B&3) = (!10 +2) * -(5.5&3) = -2 (!10 = 0, 5.5&3=1)

“(“+C+”,”+D+”) = “(“+”yes”+”,”+”no”+”)” = (yes,no)

sum() = 100+200+300 = 600

count() >= 3 ? sum(“B”) : D = 3 >=3 ? 200+400 : “no” = 600

sum() * Get(i1,”E”) = (100+200+300) * 0.5 = 600

Get(Parent,”A”) == Get(i11,”F”) = 5 == 100 = 0