Sedna Logo Background
 
Home  |  Getting Started  |  Documentation  |  Demo  |  Download  |  Support  

Getting Started with C API

Sedna provides API for different programming languages (C, Java, Python, Scheme, PHP, Omnimark). Here we show how to write simple C programs that work with Sedna via its C API, how to compile and run these programs.

Contents:

See also:

Download and Install Sedna

Download a copy of the prebuilt binaries for your machine, or get a copy of the sources and compile them yourself (download page).

Installing Sedna from binaries is easy, you just need to unzip archive (on Windows) or run self-extracting script (on *nix). For more information on installation see README in your Sedna package.

Run Sedna

Start Sedna server: go to SEDNA_DIR/bin and run:

se_gov

create and run a database named testdb:

se_cdb testdb
se_sm testdb

Write Programs That Use Sedna

C/C++ program that works with Sedna must include libsedna.h and link with libsedna.a under Linux, FreeBSD, Mac OS and Solaris operating systems (hereinafter Unix-like operating systems are abbreviated as [nix:]). Under Windows (hereinafter abbreviated as [win:]) three versions of Sedna library are available:

  1. libsednamt.lib - multithreaded, static link, application is built with /MT[d] compiler option
  2. libsednamd.lib - multithreaded, static link, application is built with /MD[d] compiler option
  3. sednamt.lib (import library for sednamt.dll) - multithreaded, dynamic link, application will have a dependency on sednamt.dll

Library files are located at the SEDNA_DIR/driver/c folder, where SEDNA_DIR is the directory Sedna is installed in.

Examples discussed in this document can be found in SEDNA_DIR/examples/api/c.

Depending on your operating system use one of the following commands to build examples:

[win:] cl /MT /I SEDNA_DIR\driver\c sample.c SEDNA_DIR\driver\c\libsednamt.lib
[nix:] gcc -ISEDNA_DIR/driver/c -osample sample.c SEDNA_DIR/driver/c/libsedna.a

where sample.c is the name of the example application that you want to try.

 

Open a session to a database

To start working with Sedna you must first initialize SednaConnection structure: To open a session call SEconnect: To close session call SEclose:

The complete source of this example is 01_connect.c (SEDNA_DIR/examples/api/c/01_connect.c).

 

Load XML document

You can load XML document into a Sedna database as a stand alone, or into a collection of documents. To load XML document as a stand alone you should execute a query:
LOAD "path-to-XML-document-on-file-system" "name-of-the-document-in-database"

The complete source of this example is 02_load.c (SEDNA_DIR/examples/api/c/02_load.c).

Make sure that path to XML document categories.xml (SEDNA_DIR/examples/api/data/categories.xml) is correct when you run 02_load.

 

Load a set of XML documents into a collection

If you have a set of XML documents with similar (not necessarily the same) structure, it is recommended to load them into a collection.

You must first create an empty collection:

CREATE COLLECTION "collection-name"
then load each document with the query:
LOAD "path-to-XML-document-on-file-system" "name-of-the-document-in-collection" "collection-name"
In our example we load a set of Wikipedia articles (presented as XML documents) into a collection 'wikidb'.

The complete source of this example is 03_load_coll.c (SEDNA_DIR/examples/api/c/03_load_coll.c).

A set of XML documents wikidb.zip (SEDNA_DIR/examples/api/data/page*.xml), make sure that 'data' directory is accessible when you run 03_load_coll.

 

Query data

To execute a query use SEexecute function:

The result of an XQuery query is a sequence of XML nodes, where each node is represented as a string.

To retrieve the result data use SEnext - to iterate over the result items, and SEgetData - to retrieve the item:

The complete source of this example is 04_query.c (SEDNA_DIR/examples/api/c/04_query.c).

 

Manage transactions

By default, session is in autocommit mode, that is you don't need to begin and commit transactions explicitly. But if you want to, you can turn autocommit mode off: and then begin transaction explicitly: and commit when needed:

The complete source of this example is 05_trans.c (SEDNA_DIR/examples/api/c/05_trans.c).

 

Using value index

To speed up your queries you can create value index on data stored in database with CREATE INDEX:
CREATE INDEX "index-name"
ON xpath-to-indexed-nodes
BY relative-xpath-to-keys
AS xml-schema-atomic-type
Here is how to build value index on 'page' nodes by category of the page: To query data using index use index-scan XQuery function:

The complete source of this example is 06_value_index.c (SEDNA_DIR/examples/api/c/06_value_index.c).

 

Using full-text search index

Sedna provides full-text search support using dtSearch. By default, full-text search support in Sedna is turned off. If you want to use Sedna with full-text search contact us sedna@ispras.ru.

To create full-text index use CREATE FULL-TEXT INDEX:

CREATE FULL-TEXT INDEX "index-name"
ON xpath-to-indexed-data
TYPE type

Where type is on of the "xml", "string-value", "delimited-value" or "customized-value". See section 'Managing Full-Text Indices' in Sedna Programmer's Guide for the explanation of type parameter.

To create full-text index on 'page' nodes in collection 'wikidb'. Type "xml" means that the indexed nodes are considered as XML nodes.

To use full-text index use ftindex-scan XQuery function. Here we retrieve those pages that contain the word "science" and do not contain the word "computer". Retrieving the result of this full-text query is as usual (see Query data example).

The complete source of this example is 07_fts_index.c (SEDNA_DIR/examples/api/c/07_fts_index.c).

 

Update data

Sedna supports Update language based on XQuery. For details on Update language see Sedna Programmer's Guide.

Here we demonstrate how to insert, delete and replace data stored in the database.

The following update deletes all 'comment' nodes in collection 'wikidb':

Here is how to replace 'link' nodes that refer to the page that does not exist in collection 'wikidb' on to 'i' node:

Here is how to insert current date/time and contributor name 'sedna-user' in the beginning of page 'NASA':

The complete source of this example is 08_update.c (SEDNA_DIR/examples/api/c/08_update.c).

 

Using triggers

Sedna supports fine-grained triggers based on XQuery. That means that you can set a trigger on any nodes of an XML document stored in the database, and the trigger will automatically execute XQuery queries and updates specified in its body, when these nodes are updated.

Triggers can do a lot of useful and flexible things. You can use triggers to: support for integrity constraints; enrich inserted data with additional information, watch for the specific data changes, and more.

Using triggers at first can appear to be tricky and difficult. So, please read section "XQuery Triggers" in Sedna Programmer's Guide and have a look at these examples.

We create triggers for Wikipedia pages loaded into collection "wikidb" and document "categories". Trigger "trigger-on-insert-link" watches if the inserted links are valid. On insertion of 'link' node into page 'summary', trigger checks if there is a page that link refers. If there is no such a page, trigger changes 'link' node that is being inserted onto 'i' node with the same content.

Trigger "trigger-on-delete-category" watches that category list in document 'categories' is valid. On deletion of category from the 'categories' document, the trigger deletes all references to this category in Wikipedia pages.

The complete source of this example is 09_trigger.c (SEDNA_DIR/examples/api/c/09_trigger.c).

 

Using XQuery modules

XQuery allows putting functions in library modules, so that they can be shared and imported by any query. Before a library module could be imported from an query, it is to be loaded into the database.

To load a module, use the following statement:

LOAD MODULE "path-to-file", ..., "path-to-file"
Here is the example of XQuery module math.xqlib: To load this module: To use loaded module:

The complete source of this example is 10_module.c, math.xqlib (SEDNA_DIR/examples/api/c/10_module.c, SEDNA_DIR/examples/api/c/math.xqlib.c).