TreeGrid server library
v2.0 for TreeGrid v5.0
TreeGrid server is helper library for very large grids to use server side paging or child paging. You can, but you need not use it for server paging.
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 (in group) with the same changes.
Compatibility with TreeGrid component
TreeGrid server library is compatible with TreeGrid component v5.0 except:
It supports only Internal format of XML input / output data. You must set <treegrid *_Format=’Internal’>, where * is Data, Page, Upload, Export, Check.
It supports only some formulas syntax and few functions, see Calculations section.
It does not support advanced CalcOrder - it does not support wildcards in CalcOrder attribute and CalcOrderX attributes and also <Cfg CalcOrder> attribute (uses only <I CalcOrder).
It sorts and filters data according to native types of values – integer, float and string and does not use cell Type attribute.
Bool, Int, Enum, Radio and Date are integers, Float are floats and other types are strings.
To sort or filter extended types like Link, you should use cell attributes SortValue, SortDescValue and FilterValue.
The filter rows (<Filter>) must have set id attribute.
It uses only basic row identification by unique id, so extended id attributes IdNames, FullId, AppendId, IdCompare must not be used.
It uses date time values as integers (number of millisecond since 1/1/1970 00:00:00) for input and output. You also must not use attribute <Cfg DateStrings>.
Attribute SortSpan is ignored.
Localized sorting and filtering is not supported, the values of &2 of SortType and FilterType.
Grouping is not supported yet.
Export is not supported yet.
Search and advanced filters are not supported yet.
Solid space rows with cells are not supported yet.
Aggregate function on toolbar is supported only if there is also some fixed row where the same function is calculated too.
All functions are exported as extern "C" __declspec(dllexport) ... __stdcall (standard C++ exports).
All strings parameters are in unicode. For all string handling functions there are functions ends with “A” using UTF8 strings (CreateGrid => CreateGridA).
Input XML strings can be standard XML “<...></...>” or entity encoded “< ... ></...>”
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 SaveEx(int Index, string Input, int Type);
[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();
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern string GetLastId(int Index);
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern string GetChanges(int Index, int Type);
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern int FindGrids(IntPtr Indexes, int Max, string Cfg, int Seconds, int Type);
public static int FindGrids(ref int []Indexes, int Max, string Cfg, int Seconds, int Type){
return FindGrids(GCHandle.Alloc(Indexes,GCHandleType.Pinned).AddrOfPinnedObject(),Max,Cfg,Seconds,Type);
}
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 SaveEx Lib "TreeGrid.dll" (ByVal Index As Integer, ByVal Input As String, ByVal Type As Integer) 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 GetLastId Lib "TreeGrid.dll" (ByVal Index As Integer) As String
Declare Unicode Function LastError Lib "TreeGrid.dll" () As String
Declare Unicode Function GetChanges Lib "TreeGrid.dll" (ByVal Index As Integer, ByVal Type As Integer) As String
Declare Unicode Function FindGrids Lib "TreeGrid.dll" (ByVal Indexes As IntPtr, ByVal Max As Integer, ByVal Cfg As String, ByVal Seconds As Integer,
ByVal Type As Integer) As Integer
Public Function FindGrids(ByVal Indexes() As Integer, ByVal Max As Integer, ByVal Cfg As String, ByVal Seconds As Integer, ByVal Type As Integer) As Integer
Return FindGrids(GCHandle.Alloc(Indexes, GCHandleType.Pinned).AddrOfPinnedObject(), Max, Cfg, Seconds, Type)
End Function
In PHP you need to use FFI expansion (foreign functions interface).
To preserve DLL in memory, you need to lock library in memory by LockLibrary function. After all grid instances are deleted, you should unlock the library by UnlockLibrary function. You cannot lock library if you use PHP as CGI application, see bellow.
Windows
You should add to your php.ini to main [PHP] section the line extension=php_ffi.dll.
Copy php_ffi.dll provided in TreeGrid distribution (located in /Server/Php) to your PHP expansions directory.
You should choose the correct file for your PHP version. The files 5.1 and 5.2 require .NET framework 1.1. If you don’t have it, just download file msvcr71.dll and place it to your PHP directory. Latest PHP builds, extensions and msvcr71.dll can be downloaded from http://kromann.info/php.php.
The TreeGrid.dll library is intended to be persistently placed in memory. Therefore you should run the PHP engine as ISAPI service and not CGI application.
If you installed PHP by windows installer, the PHP is configured by default to run as CGI application. Check Install.txt file in your PHP directory how to change PHP to run as ISAPI service. For example WinXP and IIS - just open IIS configuration, choose your virtual web server directory, select Properties->Virtual Directory->Configuration->Mappings, select .php Extension and click Edit button and browse for Executable php5isapi.dll.
TreeGrid.dll will work also with PHP as CGI application, but after every page processing the DLL is unloaded from memory and all grid instances are deleted, so in this case you need to always save all grid instances to disk and load them when processing new command.
Remember, if PHP runs as ISAPI service and you do some changes in php.ini, you usually need to restart whole web server service, for example for IIS you need often to restart IIS Admin service from services dialog. Also remember, that PHP running as ISAPI can have another relative path, so you should set in php.ini the extension_dir to absolute path where to search PHP extensions.
Linux
You should add to your php.ini to main [PHP] section the line extension=ffi.so.
Copy ffi.so provided in TreeGrid distribution (located in /Server/Php) to your PHP expansions directory.
TreeGrid distribution contains ffi source. You can compile and install them by yourself. Just go to the /Server/Php/ffi-0.3src-modif/ directory and run:
pear install package.xml
OR
pear5 install package.xml
OR
phpize
./configure
make install
Or you can download and build sources from http://pecl.php.net/package/ffi. Or you can try command “pear install ffi”.
Just try the command which will work to you.
Yes, Linux is system for people who don't know what to do with their leisure time.
Using
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!
! Functions returning string in case of error return empty string (and not null), that must not be freed.
! Remember, if 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 FreeStringA(char *String);
char* GetBodyA(int Index, char* Cfg);
char* GetPageA(int Index, char* Cfg);
int SaveA(int Index, char* Input);
int SaveExA(int Index, char* Input, int Type);
int SaveToFileA(int Index, char* FileName, int Type);
char* GetDataA(int Index);
char* LastErrorA();
char* GetLastIdA(int Index);
char* GetChangesA(int Index, int Type);
int FindGridsA(int* Indexes, int Max, char* Cfg, int Seconds, int Type);
char* FindGridsStrA(int Max, char* Cfg, int Seconds, int Type);
int LockLibraryA(char *LibName);
int UnlockLibrary();
");
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 = new 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 = new 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.
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.
Create TreeGrid instance from data in files or in strings (CreateGrid). 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.
If you have created instance and you only need to change some of its settings, you can use UpdateGrid function.
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.
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.
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.
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.
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.
Or you can use GetChanges function to get all Update requests (if you used SaveEx function with Type==1) and parse and update them manually 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.
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.
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.
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.
Use this function to modify some grid settings, not to saving changes to data. For saving changes use Save or SaveEx function.
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 attribute can be set in functions CreateGrid, UpdateGrid, GetBody, GetPage, Save.
If Session attribute is not set, it is by default the grid index returned from CreateGrid.
By Session should be the grid instance fully identified. The Session attribute (if set) is returned in every TreeGrid request.
Returns grid index or -1 grid not found, -3 bad input XML.
C++ int FindGrids (int *Indexes, int Max, wchar_t *Cfg, int Seconds, int Type);
C# public static extern int FindGrids (IntPtr Indexes, int Max, string Cfg, int Seconds, int Type);
VB Function FindGrids (ByVal Indexes As IntPtr, ByVal Max As Integer, ByVal Cfg As String, ByVal Seconds As Integer, ByVal Type As Integer) As Integer
PHP int FindGridsA (int *Indexes, int Max, char *Cfg, int Seconds, int Type);
Java int FindGrids (int[] Indexes, int Max, string Cfg, int Seconds, int Type);
Looks for grids with the same attribute values in <Cfg> tag as in Cfg parameter. So you should fill to Cfg parameter only those attributes according to you want to search.
Indexes is array of integers filled by found indexes. Indexes can be null to get only count of grids.
Max is maximum count of indexes to fill to Indexes array.
Cfg is full Grids XML data with <Cfg> tag like “<Grid><Cfg MyAttr=’xy’/></Grid>” to search grids according to.
If Seconds is not 0 the function returns only grids older this count of seconds – the last access to grids was before this count of seconds.
Type is reserved and should be 0.
Returns count of found grids (count of indexes in Indexes) or -3 for bad XML in Cfg.
Use this function to get indexes from some group of grids marked by some (usually custom) attribute in <Cfg> tag.
Or use this function to get old (probably not used) grid instances to backup or delete them.
New in version 2.0.
PHP char* FindGridsStrA (int Max, char *Cfg, int Seconds, int Type);
The same as FindGrids, but returns Indexes as comma separated string.
New in version 2.0.
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
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).
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.
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.
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).
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. The same as SaveEx function with Type = 0.
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
C++ int Save (int Index, wchar_t *Input, int Type);
C# public static extern int Save (int Index, string Input, int Type);
VB Function Save (ByVal Index As Integer, ByVal Input As String, ByVal Type As Integer) As Integer
PHP int SaveA (int Index, char * Input, int Type);
Java int Save (int Index, String Input, int Type);
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.
If Type = 1 it remembers the changes to be got by GetChanges function. More changes are merged together.
Type = 1 is usually set for all other grid instances except the grid instance the changes are coming from.
If Type = 2 it remembers the id modifications if new id collided with some id stored in data.
Type = 2 is usually set for the grid instance the changes are coming from.
This setting has sense only when more users have rights to add new rows that can cause id colliding.
Returns 0 OK, -3 bad Input XML, >0 number of rows not successfully saved.
New in version 2.0.
C++ wchar_t * GetChanges (int Index, int Type);
C# public static extern string GetChanges (int Index, int Type);
VB Function GetChanges (ByVal Index As Integer, ByVal Type As Integer) As String
PHP char * GetChangesA (int Index, int Type);
Java String GetChanges (int Index, int Type);
Returns all changes done by SaveEx function with Type=1.
If Type=1, it clears all returned changes, so you will not get them in next call of GetChanges. Remember, it never modifies the data.
You can use this function to get changes and return them to client when checking for updates function is used or you can get and parse them and store changes to database instead of use GetData function.
In C++ and PHP it returns allocated string that must be freed by FreeString function.
New in version 2.0.
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
C++ wchar_t * GetData (int Index);
C# public static extern string GetData (int Index);
VB Function GetData (ByVal Index As Integer) As String
PHP char * GetDataA (int Index);
Java String GetData (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.
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.
In C++ and PHP it returns allocated string that must be freed by FreeString function.
New in version 1.2.
C++ wchar_t * GetLastId (int Index);
C# public static extern string GetLastId (int Index);
VB Function GetLastId (ByVal Index As Integer) As String
PHP char * GetLastIdA (int Index);
Java String GetLastId (int Index);
Returns last (highest) id in grid. Use this function to get the last id after saving changes by Save function when copying collapsed rows with children is permitted.
You should return this last id in <Cfg LastId=’...’/> back to grid after successful save to update LastId property on client.
Copying collapsed rows means that user can copy rows with not loaded children => copying is done only on server by Copy attribute.
In C++ and PHP it returns allocated string that must be freed by FreeString function.
New in version 2.0.
C++ int LockLibrary (wchar_t *LibName);
PHP int LockLibraryA (char *LibName);
Locks library in memory to not be unloaded after the server script frees its handle. Use for PHP.
LibName is full path to TreeGrid.dll. It is the same string you passed to ffi in PHP.
The function can be called more times, it locks library only once.
Returns 1 – success, 0 – error, -1 library already locked
New in version 2.0.
UnlockLibrary
C++ int UnlockLibrary ( );
PHP int UnlockLibrary ( );
Unlocks library previously locked by LockLibrary function. Use for PHP.
Returns 1 – success, 0 – error, -1 library is not locked
New in version 2.0.
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)
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
Updates
2.0
Added Compatibility section
Added GetLastId function
Added FindGrids function
Added SaveEx and GetChanges functions
Added LockLibrary and UnlockLibrary
Rewritten PHP section