TreeGrid server library v3.6

TreeGrid documentation

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, grouping, 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 is thread safe.
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.
Default rounding precision of all numbers in TreeGrid server is 4 digits. It can be changed by <Cfg Precision=''/>, available values are 0 - 9.

Compatibility with TreeGrid component

TreeGrid server library is compatible with TreeGrid component v6.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).
Up to three sort columns are supported.
Attributes LocaleCompare, CaseSensitive, WhiteChars, CharCodes and GroupSole, GroupSingle, GroupEmpty are supported only in <C> tag.
Other default cols <D> than <D Name="C"/> are ignored.
Only base types (Bool, Int, Float, Date, Enum, Radio, Text, Lines) are sorted and filtered as expected.
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 milliseconds since 1/1/1970 00:00:00) for input and output. You also must not use attribute <Cfg DateStrings>. See also GMT attribute.
Attribute SortSpan is ignored.
Attribute Range is used only in filter rows. In all other cells is the value treated as simple string.
Search and advanced filters are not supported yet.
The filter rows (<Filter>) must have set id attribute if there are more filter rows.

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 handling functions there are functions ends with "A" using UTF8 strings (CreateGrid => CreateGridA).
Input XML strings can be standard XML "<...>" or entity encoded "&lt; ... &gt;&lt;/...&gt;"

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)]
[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){
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern string GetSession(string Cfg);
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern string GetGridSession(int Index);
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 string GetExport(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 string GetCells (int Index, string Row, string Col, int Type, string Param);
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern int SetDebug(int Index, string FileName);
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern int SetGridLocale(int Index, string Locale);
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern void EnterRead( );
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern void LeaveRead( );
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern void EnterWrite( );
[DllImport("TreeGrid.dll", CharSet = CharSet.Unicode, CallingConvention = CallingConvention.StdCall)]
public static extern void LeaveWrite( );

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, _
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 FindGrids Lib "TreeGrid.dll" (ByVal Indexes As IntPtr, ByVal Max As Integer, ByVal Cfg As String, ByVal Seconds 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
End Function
Declare Unicode Function GetSession Lib "TreeGrid.dll" (ByVal Cfg As String) As String
Declare Unicode Function GetGridSession Lib "TreeGrid.dll" (ByVal Index As Integer) As String
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 GetExport 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 GetData Lib "TreeGrid.dll" (ByVal Index As Integer) As String
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 GetCells Lib "TreeGrid.dll" (ByVal Index As Integer, ByVal Row As String, ByVal Col As String, ByVal Type As Integer, _
Declare Unicode Function SetDebug Lib "TreeGrid.dll" (ByVal Index As Integer, ByVal FileName As String) As Integer
Declare Unicode Function SetGridLocale Lib "TreeGrid.dll" (ByVal Index As Integer, ByVal Locale As String) As Integer
Declare Unicode Sub EnterRead Lib "TreeGrid.dll" ()
Declare Unicode Sub LeaveRead Lib "TreeGrid.dll" ()
Declare Unicode Sub EnterWrite Lib "TreeGrid.dll" ()
Declare Unicode Sub LeaveWrite Lib "TreeGrid.dll" ()

PHP

In PHP TreeGrid.dll/so works as PHP extension.
Copy it to you PHP extensions directory and add to your php.ini to main [PHP] section the line extension=TreeGrid.dll on Windows or extension=TreeGrid.so on Linux.
! TreeGrid.dll/so must not be the first PHP extension loaded! So ensure that in php.ini is at least one active line extension=xxx before the extension=TreeGrid.dll/so.

TreeGrid.dll/so PHP extension is compatible with PHP versions 5.0 - 5.5. Both PHP thread-safe / thread-unsafe versions. Only PHP non-debug version.
It should work also in future releases, but because of pure amateurism of PHP authors there is no insurance that it will do. We sometimes check and update the extension to be compatible with new PHP releases. If you encounter that TreeGrid.dll/so does not work in PHP release other that listed above let us know to update the TreeGrid.dll/so.

Windows
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 always to save all grid instances to disk and load them when processing new command. It can slow down using TreeGrid.dll/so.

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.

Using
Call TreeGrid function like other PHP functions, for example
! PHP does not use Unicode, thus you must all strings encode in UTF8. But call TreeGrid functions without prefix "A" (CreateGrid).
! 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).
! All TreeGrid function names in PHP starts with prefix "TG".

Whole declaration:
There is no need for external declaration of TreeGrid functions in PHP.
But remember all function names start with prefix "TG".

JSP Java

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
If you have not copied TreeGrid.dll to JRE BIN directory, you must specify its path and name as parameter:
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.

Whole declaration: There is no need for external declaration of TreeGrid functions in Java - it is already declared in TreeGrid.jar in object TreeGrid.Server.

TreeGrid server concepts

Basics

a) You have stored your data somewhere on disk or in database.

b) When first request to this data arrives, you need to read all you data and convert it to the TreeGrid XML internal format and create TreeGrid instance from this data by calling CreateGrid. And fulfill the request by calling GetPage, GetBody, Save or GetExport method of the created instance.
This means that every client has its own grid instance on server, because every client can have its own individual state of sorting, filtering or grouping.

c) For next requests 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, see FindGrid and FindGrids function) and fulfill the request by calling GetPage, GetBody, Save or GetExport method of the found instance.

d) After every Update request you will save data changes to grid instance by Save method as mentioned in c).
But you need to save changes also your original data store (database, file, etc.) by parsing the request XML and updating to your original store. See XML structure - upload.

The <IO Session> can be modified by CreateGrid, UpdateGrid and GetBody if the sent xml contains this attribute set.

For use TreeGrid server you have 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, GetBody returns data only, not layout.

Creating instance

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 as CGI 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 2/3 if they are in unicode. But always depends on data structure.
You should also know that grouping data can allocate significantly more memory, depending on count of groups, but it can double or even triple memory allocation when many groups are generated.

Finding instance

How to find instance that the request belongs to?

Session

The easiest way is to use TreeGrid built-in Session concept. When grid instance is created on server, it gets its unique Session attribute. This Session attribute is sent to client in GetBody request. And client in every future request will send this Session attribute within the request. You can control how client will store its Session by <Cfg SaveSession/> attribute. To get grid instance with appropriate Session call FindGrid with the whole request XML.
When you get request with Session no longer exist on server (FindGrid returned -1) you have to create new instance (for GetBody request) or return error for other request.

More instances by custom attribute

When you want to permit write access to the grid data and read access for more clients, you will need, when saving, to get all grid instances with appropriate table and save changes to them all. To get some instances you need to mark them when creating by setting some your custom attribute in <Cfg> tag and when needed call FindGrids to get all the instances according to the custom attribute. For example:
Create grids like: index = CreateGrid("...","...","...","...","...","<Grid><Cfg Ident='MyGridX1'/></Grid>");
And get all the instances of MyGridX1 by: count = FindGrids(array, 100, "<Grid><Cfg Ident='MyGridX1'/></Grid>",0,0);

Custom way

You can also identify the grid by any your custom way, for example according to some user name and password or IP address and provide your own method to find the appropritate grid for the request.

Updating instance

If you have created instance and you only need to change some of its configuration settings (but not columns), 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. And two support requests to get exported data and to get changes.

a) 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
To get body just return GetBody function result.

b) Request GetPage

Page is one page when used server paging. When used client paging, this request does not occur.
Page is also children of parent row or group when used server child paging. When used client child paging, this request does not occur.
Client request a page when page is displayed or parent row was expanded, and it was not downloaded yet.
To get page just return GetPage function result.

c) Request Update

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

Call Save function to update data to the instance.
But you need to save changes also your original data store (database, file, etc.) by parsing the request XML and updating to your original store. See XML structure - upload.

If there are more instances of TreeGrid for the table (more clients simultaneously read the same table) 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. To get all the instances for update, call FindGrids, see also Finding instance.
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.

d) Request GetExport

This is request for all data to be exported in XLS file to download and open in Excel. It is sent, when user clicks to Export button on TreeGrid toolbar.
To get exported data just return GetExport function result.
When exporting data to Excel, do not forget to set in HTTP response ContentType to "application/vnd.ms-excel" and Content-Disposition to "attachment; filename="export_file.xls")

e) Request GetChanges

When you set in your grid to check for updates feature (<treegrid Check_>), the grid periodically sends this request to server to find, if there is some update to the data.
The changes can be marked by using SaveEx method instead of Save. This feature can be used, when database is frequently changing or if any other visitor(s) have write access to the data.
To get chanegs just return GetChanges function result.

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.
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.
Or you can just parse XML got in Update request and provide changes.
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.

Special XML attributes

TreeGrid library accepts these attributes in input XML data:
<Cfg Precision> [4] - Rounding precision of all numbers in TreeGrid server, available values are 0 - 9.
<Cfg MaxChildrenOffline> [3] - In server child paging the children are served with the parent if their count is less or equal to this value.
<Cfg ShowFocused> [0] - If set to 1, it serves in body response all parents (expanded) of <Cfg Focused> row.
<Cfg ChangedParents> [0] - If set to 1, GetChanges returns also all changed parents and root page of changed rows. Useful for updating aggregate calculation results on client.
<Changes Reload="1"> - It is filled to GetChanges response if client should reload data to get all the newest data.

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++	int CreateGridA (char *Data, char *Layout, char *Defaults, char *Text, char *Bonus, char *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 TGCreateGrid (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++	int UpdateGridA (int Index, char *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 TGUpdateGrid (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.

FindGrid

C++	int FindGrid (wchar_t *Cfg);
C++	int FindGridA (char *Cfg);
C#	public static extern int FindGrid (string Cfg);
VB	Function FindGrid (ByVal Cfg As String) As Integer
PHP	int TGFindGrid (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, -2 no <IO> Session attribute set in Cfg or no grid found for the Session, -3 bad input XML.
The -2 is returned if the grid instance was already freed from memory. It happens especially in PHP when used as CGI.

FindGrids

C++	int FindGrids (int *Indexes, int Max, wchar_t *Cfg, int Seconds, int Type);
C++	int FindGridsA (int *Indexes, int Max, char *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	use FindGridsStr instead
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.

FindGridsStr

C++	char* FindGridsStrA (int Max, char *Cfg, int Seconds, int Type);
PHP	char* TGFindGridsStr (int Max, char *Cfg, int Seconds, int Type);

The same as FindGrids, but returns Indexes as comma separated string. If no index found, returns null.
New in version 2.0.

GetSession

C++	wchar_t* GetSession (wchar_t *Cfg);
C++	char* GetSession A (char *Cfg);
C#	public static extern string GetSession (string Cfg);
VB	Function GetSession (ByVal Cfg As String) As String
PHP	char* TGGetSession (char *Cfg);
Java	String GetSession (String Cfg);

Returns value of <IO Session> attribute from given XML string. If no session found returns null.
Useful when the grid data are unloaded from memory and saved to disk or database according to Session id.
New in version 3.0.

GetGridSession

C++	wchar_t* GetGridSession (int Index);
C++	char* GetGridSessionA (int Index);
C#	public static extern string GetGridSession (int Index);
VB	Function GetGridSession (ByVal Index As Integer) As String
PHP	char* TGGetGridSession (int Index);
Java	String GetGridSession (int Index);

Returns actual value of <IO Session> attribute in given grid instance. If no session found returns null.
Useful when the grid data are unloaded from memory and saved to disk or database according to Session id.
New in version 3.0.

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 TGDeleteGrid (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 TGClear ( );
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).

GetBody

C++	wchar_t * GetBody (int Index, wchar_t *Cfg);
C++	char * GetBodyA (int Index, char *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 * TGGetBody (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>. For error returns null.
Cfg - required - XML string with TreeGrid configuration - sorting and filters.
Function also modifies main data.

GetPage

C++	wchar_t * GetPage (int Index, wchar_t *Cfg);
C++	char * GetPageA (int Index, char *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 * TGGetPage (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 optionally with Pos attribute for particular child part.
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.
Does not return rows marked as Filtered. Returns all cells with values set.
Function does not modify main data (only if configuration changes).

Save

C++	int Save (int Index, wchar_t *Input);
C++	int SaveA (int Index, char * 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 TGSave (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.

SaveEx

C++	int SaveEx (int Index, wchar_t *Input, int Type);
C++	int SaveExA (int Index, char * Input, int Type);
C#	public static extern int SaveEx (int Index, string Input, int Type);
VB	Function SaveEx (ByVal Index As Integer, ByVal Input As String, ByVal Type As Integer) As Integer
PHP	int TGSaveEx (int Index, char * Input, int Type);
Java	int SaveEx (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.
If Type = 2 it remembers the id modifications if new id collided with some id stored in data.
Returns 0 OK, -3 bad Input XML, >0 number of rows not successfully saved.
New in version 2.0.

GetChanges

C++	wchar_t * GetChanges (int Index, int Type);
C++	char * GetChangesA (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 * TGGetChanges (int Index, int Type);
Java	String GetChanges (int Index, int Type);

Returns all changes done by SaveEx function with Type=1. Returns only <Changes> tag without parent <Grid> tag. Returns null if there are no pending changes.
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.
New in version 2.0.

GetCells

C++	wchar_t * GetCells (int Index, wchar_t *Row, wchar_t *Col, int Type, wchar_t *Param);
C++	char * GetCellsA (int Index, char *Row, char *Col, int Type, char *Param);
C#	public static extern string GetCells (int Index, string Row, string Col, int Type, string Param);
VB	Function GetCells (ByVal Index As Integer, ByVal Row As String, ByVal Col As String, ByVal Type As Integer, ByVal Param As String) As String
PHP	char * TGGetCells (int Index, char *Row, char *Col, int Type, char *Param);
Java	String GetCells (int Index, String Row, String Col, int Type, String Param);

Returns values from selected cells. Returns all data in one string, separated by the first character in Param.
Row - a row id, can be null, see Type
Col - required - from this column will be the cells returned. In fact the Col can be any row or cell attribute name.
Type - required - which cells will be returned for the given Row and other options
Param - its first character is used to separate the values in the returned string. If it is empty, the '|' is used.
For example GetCells(0,"123","A",1,"!Visible!1") returns all siblings of the row with id "123", only visible rows, values from column 'A'.
The result can be for example "!45!2.4!66!12" (it is separated by the '!', because it was set as the first character in Param).
It can be used especially to get string for Defaults list.
New in version 3.4.

GetExport

C++	wchar_t * GetExport (int Index, wchar_t *Cfg);
C++	char * GetExportA (int Index, char *Cfg);
C#	public static extern string GetExport (int Index, string Cfg);
VB	Function GetExport (ByVal Index As Integer, ByVal Cfg As String) As String
PHP	char * TGGetExport (int Index, char *Cfg);
Java	String GetExport (int Index, String Cfg);

Returns data exported to MS Excel. It returns data in HTML with specific formatting for Excel. Returns null for error.
Cfg - required - XML string with list all columns with position, width and visibility.
New in version 3.0.

SaveToFile

C++	int SaveToFile (int Index, wchar_t *FileName, int Type);
C++	int SaveToFileA (int Index, char * 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 TGSaveToFile (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 (default = 28 = UTF8 + session + cfg + body) - bit array:
Returns 0 OK, -1 file cannot be created, -2 file cannot be written, -3 corrupted data

GetData

C++	wchar_t * GetData (int Index);
C++	char * GetDataA (int Index);
C#	public static extern string GetData (int Index);
VB	Function GetData (ByVal Index As Integer) As String
PHP	char * TGGetData (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. Returns null for error.

GetLastId

C++	wchar_t * GetLastId (int Index);
C++	char * GetLastIdA (int Index);
C#	public static extern string GetLastId (int Index);
VB	Function GetLastId (ByVal Index As Integer) As String
PHP	char * TGGetLastId (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.
Returns null for error.
New in version 2.0.

SetGridLocale

C++	int SetGridLocale (int Index, wchar_t *Locale);
C++	int SetGridLocaleA (int Index, char * Locale);
C#	public static extern int SetGridLocale (int Index, string Locale);
VB	Function SetGridLocale (ByVal Index As Integer, ByVal Locale As String) As Integer
PHP	int TGSetGridLocale (int Index, char * Locale);
Java	int SetGridLocale (int Index, String Locale);

Chooses language for internationalization when comparing strings for sorting, filtering and grouping.
Index is index of given grid. Every grid instance can have its own locale settings.
Locale is name of language like "french", "german", "czech". For name reference see http://msdn2.microsoft.com/en-us/library/39cwe7zf(VS.80).aspx.
Locale can also specify regional sub language if different, in this schema: "lang[_territory[.code_page]]",
where lang is ISO 639 language code, territory is an ISO 3166 country code, and code_page is a character set or encoding identifier like ISO-8859-1 or UTF-8.
For standard English language don't call this function, it slows down strings comparing.
Strings are compared according to given locale only if SortType / GroupType / FilterType has set second bit (&2) for locale comparing.
! Attention, the locale comparing is always case insensitive !
New in version 3.0.

EnterRead, LeaveRead, EnterWrite, LeaveWrite

C++	void EnterRead ( ); void LeaveRead ( ); void EnterWrite ( ); void LeaveWrite ( );
C#	void EnterRead ( ); void LeaveRead ( ); void EnterWrite ( ); void LeaveWrite ( );
VB	Sub EnterRead ( ) : Sub LeaveRead ( ) : Sub EnterWrite ( ) : Sub LeaveWrite ( );
PHP	void TGEnterRead ( ); void TGLeaveRead ( ); void TGEnterWrite ( ); void TGLeaveWrite ( );
Java	void EnterRead ( ); void LeaveRead ( ); void EnterWrite ( ); void LeaveWrite ( );

Critical section
Use critical sections if you need to call more than one function without interference with other threads.
All TreeGrid functions itself are thread safe and you don't need to use critical section for them.
This critical section is usual Multi read exclusive write synchronizer. It is not reentrant - you cannot call EnterWrite twice from one thread.
For every EnterRead you must call LeaveRead and for every EnterWrite you must call LeaveWrite.
EnterWrite waits for all threads to finish reading or writing. There can be only one thread that writes at a time.
EnterRead waits for all threads to finish writing. There can be more threads that read at a time.
These functions are in fact independent on grids and can be used everywhere.
New in version 3.0.

Other function

LockLibrary

C++	int LockLibrary (wchar_t *LibName);
C++	int LockLibrary (wchar_t *LibName);

Locks library in memory to not be unloaded after the server script frees its handle. Use only in non-standard server script environment.
LibName is full path to TreeGrid.dll.
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 ( );

Unlocks library previously locked by LockLibrary function.
Returns 1 - success, 0 - error, -1 library is not locked
New in version 2.0.

FreeString

C++	void FreeString (wchar_t *Str);
C++	void FreeStringA (char *Str);

Frees allocated string if calling environment cannot do this itself. Use it for all strings you got by TreeGrid functions.
In standard server side environments like .NET, Java or PHP you don't need to (you must not) use this function.

Debugging functions

! These functions are available only in debug version of TreeGrid.dll/so (TreeGridDbg.dll / TreeGridDbg.so).

SetDebug

C++	int SetDebug (int Level, wchar_t *FileName);
C++	int SetDebugA (int Level, char * FileName);
C#	public static extern int SetDebug (int Level, string FileName);
VB	Function SetDebug (ByVal Level As Integer, ByVal FileName As String) As Integer
PHP	int TGSetDebug (int Level, char * FileName);
Java	int SetDebug (int Level, String FileName);

Sets debugging path and level of logs.
Level is binary array and controls what will be logged: Default is 3.
FileName is only partial file name without extension. It can be also only directory path, but with ending '\' or '/'.
Default FileName value is "c:\\treegrid\\log_" on Windows and "/tmp/treegrid/log_" on Linux.
! The web server process must have rights to write to the directory where FileName resides and must have rights to create new files here.
Returns 0 OK, -1 Called in non debug DLL/SO, -2 to file cannot be written
New in version 3.0.

LastError

C++	wchar_t * LastError ( );
C++	char * LastErrorA ( );
C#	public static extern string LastError ( );
VB	Function LastError ( ) As String
PHP	char * TGLastError ( );
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.
In version 3.0 moved to debug version. In non-debug version returns always null.

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.
Default rounding precision of all numbers in TreeGrid server is 4 digits. It can be changed by <Cfg Precision=''/>, available values are 0 - 9.

Operators (sorted by priority):

Constants:

Identifiers:

Function:

Examples:

<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