C-sharp/.NET implementation notes

xsdb project page with download links
xFeedMe xsdb resources

C-sharp/.NET implementation notes

The C-sharp/.NET xsdbXML framework allows programs to use the XSDBxml framework in .NET enabled applications and also provides a number of useful related .NET applications. Please note that I'm a bit of a neophyte when it comes to distributing .NET/c-sharp modules -- any advice or comments the reader cares to offer would be appreciated.)

Running programs with the C-sharp implementation of the xsdbXML framework requires the installation of the .NET runtime environment 1.1 or higher or equivalent. Compiling and building the framework requires the installation of a .NET development environment equivalent to Visual Studio .NET 7.1 or better.

The .NET modules consist of the xsdbXMLcs class library and some applications which use the library. All of the components (xsdbXMLcs.dll and the *.exe's) are built using the xsdbXMLcs.sln solution file.

.NET applications

There are several applications associated with the framework.

APIdemo.exe is provided as a very simple demonstration of the applications programmer interface to the framework (described later in this document).
localtests.exe attempts to locate and run the self-test files for the distribution. This file should be run from its location in the distribution tree (the debug build builds in INSTALLDIR\xsdbXML\xsdbXMLcs\localtests\bin\Debug). With any luck it will automatically locate the default self-test files and run them.
runtests.exe is a console (MSDOS window) application which runs a test file or tests in a directory and its immediate descendants.
Query.exe is a console application which runs a query and sends the XML format string result of the query to the standard output.
To run these programs easily from any directory the programs and the associated *.dll files should be located in a directory which archives executable console applications such as "C:\WINDOWS\system32" on Windows/NT based systems systems (the debug build places these files in INSTALLDIR\xsdbXML\xsdbXMLcs\localtests\bin\Debug and INSTALLDIR\xsdbXML\xsdbXMLcs\Query\bin\Debug respectively).
runtests.exe may be run on test files such as those provided in the examples directory of the distribution. The following line runs the estimated tax test file.
```
[INSTALL DIRECTORY]\xsdb\xsdbXML\examples\EstimatedTax> runtests Est_tests.xsdb
```
The test execution generates a lot of standard output when it runs successfully. If the execution completes with no exception (no error output) then the test has succeeded, otherwise it has failed.
Query.exe may be run on test files such as those provided in the examples directory
```
[INSTALL DIRECTORY]\xsdb\xsdbXML\examples> Query yahoo_query.xsdb
```
xsdbQueryGUI is a graphical windows application primarily intended for testing and demonstration purposes. It is purposefully not hardened for any sort of "industrial" use. It may be run from its default location
```
[INSTALL DIRECTORY]\xsdb\xsdbXML\xsdbXMLcs\xsdbQueryGUI\bin\Debug\xsdbQueryGUI.exe
```
The very primative interface allows the user to load or create the text of a query and then execute the query. To load a query text use the "load query" query button and the open file dialogue it creates to identify a file to load. To edit a query, create or modify the query in the large text box. Once a query is loaded the primary window will look something like this:

To execute the query use the "run query" button. If everything is correct the query result will appear in a new dialogue looking something like this:

If there is a syntax error or other problem the program may quit or it may launch a dialogue box containing an error message (or it may launch a debugger if a development environment is present).

The C-Sharp/.NET Application programmers interface

The primary interface to the framework from an external program is mediated by the xsdbXMLcs.Query object defined in the xsdbXMLcs.dll library file. A .NET application that uses the module must identify the library file xsdbXMLcs.dll as a reference (in Visual Studio use the Project/Add Reference menu option or equivalent to identify xdbXMLcs.dll -- the debug build places this file in C:\xsdbSourceForge\xsdbXML\xsdbXMLcs\xsdbXMLcs\obj\Debug\xsdbXMLcs.dll).

Create a Query for a literal query text using the constructor

public Query(string text, string contextLocation, bool verbose)

Where text is the body of the query, contextLocation is a directory path used to resolve relative file system references and verbose boolean flag which when set true causes the framework to generate debugging output. The alternate constructors

public Query(System.IO.StreamReader stream, string contextLocation, bool verbose) 
public Query(string filename, bool verbose)

are similar, but these constructors get the query text from a stream or a file content respectively. The last constructor infers the contextLocation from the filename path.

A program may extract the result of a query as an XML string, an ArrayList of ArrayLists or as an ArrayList of Hashtables as explained below.

The result of a normal xsdb evaluation is a sequence of mappings from names to values. The Query.Dictionaries(...) method presents the result as a sequence of Hashtables where the keys for the table are the names and the values for the table are the values associated with each name. The Query.Tuples(...) method presents the result as a sequence of ArrayLists containing the values associated with the names. If the order of the names is specified in the query the values are provided in the order requested, otherwise the values are provided sorted alphabetically by the associated name. The Query.StringResult(...) method presents the result as an xml string similar to those generated by the query and test applications.

The signatures of these methods are

public ArrayList Dictionaries(bool strict) 
public ArrayList Tuples(bool strict)
public string StringResult(bool strict)

In each case the strict parameter will trigger an exception if the result of the query cannot be converted to a purely positive form.

The included APIDemo application provides a very simple demonstration of each of these methods. The Main method for the application is listed below

static void Main(string[] args) { // Initialize a query from a string literal string querytext = @" <query names=""salutation age"" sort=""age""> <or> <and> <s at=""salutation"">hello kind world</s> 0 </and> <and> <s at=""salutation"">goodbye cruel world</s> 99 </and> </or> </query> "; Console.WriteLine("query text = \n"+querytext); xsdbXMLcs.Query Q = new xsdbXMLcs.Query(querytext, "\\" ,false); Console.WriteLine("\n\n string result is\n"+Q.StringResult(false)); Console.WriteLine("\n\n hash table result"); ArrayList Hashes = Q.Dictionaries(false); foreach (object thing in Hashes) { Hashtable H = (Hashtable) thing; int age = (int)H["age"]; string salutation = (string)H["salutation"]; Console.WriteLine("age="+age+" salutation="+salutation); } Console.WriteLine("\n\n array list result"); ArrayList tuples = Q.Tuples(false); foreach (object thing in tuples) { ArrayList A = (ArrayList) thing; int age = (int)A[1]; string salutation = (string)A[0]; Console.WriteLine("age="+age+" salutation="+salutation); } }

This console application generates the following standard output
query text = <query names="salutation age" sort="age"> <or> <and> <s at="salutation">hello kind world</s> 0 </and> <and> <s at="salutation">goodbye cruel world</s> 99 </and> </or> </query> string result is <or> <and> <s at="salutation">hello kind world</s> 0 </and> <and> <s at="salutation">goodbye cruel world</s> 99 </and> </or> hash table result age=0 salutation=hello kind world age=99 salutation=goodbye cruel world array list result age=0 salutation=hello kind world age=99 salutation=goodbye cruel world

Arithmetic expressions

The arithmetic expressions used in the calc and cond predicates match the Python implementation except that certain arithmetic functions supported in Python are not yet supported in the .NET implementation. In particular the .NET implementation supports the following arithmetic functions within arithmetic expressions.

Signature	Summary
int(x), float(x), str(x)	Data type conversion.
round(x), floor(x), ceil(x) abs(x), sqrt(x), log(x) sin(x), cos(x), tan(x) asin(x), acos(x), atan(x) sinh(x), cosh(x), tanh(x)	Standard floating point functions.
e(), pi()	Function notation for floating point constants.
strip(s), upper(s), lower(s) find(inString, pattern [, start [,end]])	string functions.
max(x.y), min(x.y) count(x.y), avg(x.y), med(x.y)	Group aggregate operations.

These functions have the same semantics as in the Python implementation. End of C-sharp/.NET implementation notes return to index