Hello, :WOMB:


First of all, you have to define your data model. For this tutorial we will be using the well-known 'employees' case where you are going to store information about your company's employees.
Data models are defined using very simple XML files in :WOMB:.

Our xml file will look like this:

<object name="Employee" table="Employees" namespace="Tutorial">
    <col name="id" type="serial" />
    <col name="surname" type="string" notnull="true" />
    <col name="name" type="string" />
    <col name="birthdate" type="date" />
</object>


Download: Employee.xml


You must at the very least specify the object's name, the table where it will be stored, and a column to get a valid data model. In this case, our employee records will be called, unsurprisingly, Employee and we'll store them into a table called (yes!) Employees in the PostgreSQL server.

We need to generate both SQL code to create the storage in the server and C# code to create the stub classes to manipulate data within our application. Wxml is the tool which does the job for us, thus:

$ wxml --sql Employee.xml > Employee.sql
$ wxml --body Employee.xml > Employee.cs


To create the SQL side storage, use psql or your favorite tool. For this tutorial, we'll be using a database called WombTutorial. Refer to PostgreSQL documentation for more information on creating databases.

$ sudo -u postgres createdb WombTutorial
CREATE DATABASE
$ sudo -u postgres psql WombTutorial < Employee.sql
NOTICE:  CREATE TABLE will create implicit sequence "employees_aid_seq" for "serial" column "employees.aid"
NOTICE:  CREATE TABLE will create implicit sequence "employees_id_seq" for "serial" column "employees.id"
NOTICE:  CREATE TABLE / UNIQUE will create implicit index "employees_aid_key" for table "employees"
CREATE TABLE
CREATE INDEX

You can ignore all that information PostgreSQL is giving you, unless you see ERROR somewhere. Next thing you should do is give yourself privileges to access the table. Assuming your username is 'bob':

$ sudo -u postgres psql WombTutorial
Welcome to psql 7.4.8, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help on internal slash commands
       \g or terminate with semicolon to execute query
       \q to quit

WombTutorial=# CREATE USER bob;
CREATE USER
WombTutorial=# GRANT ALL on Employees, Employees_aid_seq, Employees_id_seq TO BOB;
GRANT
WombTutorial=# \q

We must manually give permission to modify the sequences. All tables have a <atom_name>_aid_seq that is used internally by :WOMB:, and one _seq for every 'serial' or 'bigserial' column you define in your atom. This will be  done automatically in the future.

That's all for the SQL side of things. As for the C# part, you now have a source file that contains an Employee class you can use to manipulate rows in this table.

Let's do the most basic operation: connect to the database, create a row with some data and write it.

using System;
using Womb;
using Tutorial;

public class TutorialClass
{
    public static void Main (string [] args)
    {
        DB       db;      // Our connection to the database
        Employee emp;     // An employee atom

        // Connect to the database. This assumes postgresql server is
        // running on the local computer and listening on TCP port 5432,
        // adjust to your own settings.

        db = new DB ();

        db.Connect ("localhost", 5432, "WombTutorial", "bob", "");

        // We are connected. Create an empty employee.

        emp = new Employee (db);

        // Set some data in the employee.

        emp.surname   = "Doe";
        emp.name      = "John";
        emp.birthdate = DateTime.Today;

        // Write our employee record to the database

        emp.Write ();

        db.Disconnect ();

        return;
    }
}




Download: Tutorial1.cs


Build the app. Note that you must use gmcs and not mcs because :WOMB: uses some .NET 2.0 features, like nullable types.

$ cp /usr/local/lib/Womb/Womb.dll .
$ gmcs -target:exe -out:Tutorial1.exe Tutorial1.cs Employee.cs -r:Womb.dll
$ mono ./Tutorial1.exe

That's it, you have just written your first employee to the database. Now we'll select, update and delete rows:


using System;
using System.Collections;
using Womb;
using Tutorial;
public class TutorialClass
{
    public static void Main (string [] args)
    {
        DB         db;     
        ArrayList  emp_list;       
        
        db = new DB ();

        db.Connect ("localhost", 5432, "WombTutorial", "bob", "");

        // We are connected. Loop and add a few dummy employees
        for (int i = 0; i < 10; i++)
        {
            Employee emp = new Employee (db);
          
            emp.surname = "Dummy employee #" + i;
          
            emp.Write ();
        }

        // Now get all employees from the table
       

        Selector selector = db.GetSelector (typeof (Employee));

        emp_list = selector.Select (); // equivalent to "SELECT *"

        if (emp_list != null)
        {
            Console.WriteLine ("***** RESULT: we have " + emp_list.Count + " employees");

            // We can loop the result list to get the atoms

            foreach (Employee e in emp_list)
            {
                Console.WriteLine ("[" + e.id + "] : " + e.surname);

                // Update the atoms : set a name

                e.name = "Alfred";
                e.Write ();

            }
        }
              
        // Examples of selects:

        // Select matching a criteria
        // Example: select employee with id 2 using Select1 (column, value)

        Employee emp_2 = (Employee) selector.Select1 ("id", (int?)2);
              
        // Delete the employee, if found
      
        if (emp_2 != null)
            emp_2.Delete ();

        // Select all employees with id > 4, and sort by birthdate in descending order
        // using Select (constraint)
        ArrayList biggerThan4 = selector.Select ("WHERE id > 4 ORDER BY birthdate DESC");


        db.Disconnect ();

        return;
    }
}



Download: Tutorial2.cs

$ gmcs -target:exe -out:Tutorial2.exe Tutorial2.cs Employee.cs -r:Womb.dll
$ mono ./Tutorial2.exe
***** RESULT: we have 11 employees
[1] : Doe
[2] : Dummy employee #0
[3] : Dummy employee #1
[4] : Dummy employee #2
[5] : Dummy employee #3
[6] : Dummy employee #4
[7] : Dummy employee #5
[8] : Dummy employee #6
[9] : Dummy employee #7
[10] : Dummy employee #8
[11] : Dummy employee #9






bla