TreeGrid server library
v3.1 for TreeGrid v5.9
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 v5.6 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).
Only base types (Bool, Int, Float, Date, Enum, Radio, Text, Lines) are sorted and filtered as expected.
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.
Enum type should be set as integer not string and EnumKeys attribute is ignored.
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.
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)]
[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);
}
[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 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( );
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 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
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 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" ()
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.0 – 5.2.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
$grid = TGCreateGrid($DataFile,$LayoutsFile,$TextFile,$DefaultsFile,””,””);
! 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”.
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.
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.
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.
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.
How to find instance that the request belongs to?
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);
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.
If you have created instance and you only need to change some of its configuration settings (but not columns), 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. And two support requests to get exported data and to get changes.
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
e) used server paging and grouping has changed
f) used server paging and search has been done – search feature is not supported by current version of TreeGrid server library.
To get body just return GetBody function result.
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.
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.
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")
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.
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.
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++ 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.
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.
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.
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.
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.
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.
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.
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
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).
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.
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.
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).
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
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.
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++ 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 is 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.
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.
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:
1.bit (&1) - data format – 0 – UTF8, 1 – Unicode.
2.bit (&2) – reserved
3.bit (&4) – save session (<IO Session> attribute)
4.bit (&8) – save configuration (sorting, grouping, search, filters)
5.bit (&16) – save <Body> tag
6.bit (&32) – save <Head> and <Foot> tags
7.bit (&64) – save all other tags than <Body>, <Head>, <Foot>. It saves also configuration and session.
Returns 0 OK, -1 file cannot be created, -2 file cannot be written, -3 corrupted data
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.
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.
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
C++ int LockLibrary (wchar_t *LibName);
C++ int LockLibraryA (char *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.
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).
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.
1. bit (&1) – last error is stored and can be accessed by LastError function
2. bit (&2) – every global function called is logged with all its input parameters to file FileNameG_Index.log,
where FileName is given FileName, Index is grid instance index, for functions without index is Index set as ‘xxxx’
3. bit (&4) – many information is logged to file FileNameT_Id.log,
where FileName is given FileName, Id is global thread id that called the function
! Setting this bit can slow down the library and sometimes also crash it.
4. bit (&8) – logs all the global called functions (by 2.bit) the one file with Index set as ‘xxxx’.
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.
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.
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):
! (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 (fixed rows are calculated in special way due paging).
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 (“column”) Sums all values in column or in actual column if called without parameter
sumsq (“column”) Sums all squares of values in column or in actual column if called without parameter
count ( ) Returns count of rows
counta (“column”) Counts all non blank values in the column or in actual column if called without parameter
countblank (“column”) Counts all blank values in the column or in actual column if called without parameter
product (“column”) Multiplies all values in column or in actual column if called without parameter
max (“column”) Returns maximum value from the column or from actual column if called without parameter
min (“column”) Returns minimum value from the column or from actual column if called without parameter
<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
Added Compatibility section
Added GetLastId function
Added FindGrids function
Added SaveEx and GetChanges functions
Added LockLibrary and UnlockLibrary
Rewritten PHP section
Added SetDebug function
LastError function moved to newly created section Debugging functions
Updated SaveToFile, parameter Type
Added critical section function EnterRead,LeaveRead,EnterWrite,LeaveWrite
Added SetGridLocale function
Rewritten PHP section
Added GetSession and GetGridSession functions
Added functions sumsq, counta, countblank, product, max, min
Rewritten section TreeGrid server concepts
Added compatibility with Range attribute for filters
Added <Cfg Precision/> to set rounding precision of digits