Sunday, 31 August 2008

New libraries in the Inguma Framework


The, currently in development, new version of Inguma will include modules for Informix and IBM DB2 databases. Right now, for IBM DB2 databases we don't have many things, just a discover module (at the moment) but I'm working in a Python module for the DRDA protocol.

Also, and it's almost finished, I'm working in a pure Python Informix library. This library just "works". It generates valid packets for login, queries and various other Informix commands (such as DBList, etc...). It wasn't a hard job! I will explain a bit how the Informix communication protocol works:

The 1st packet the client sends to the database server is a pure ASCII packet with the following format:
buf = "sq"
buf += base64.b64encode("the total size of the packet").strip("==")
buf += "BPQAAsqlexec"

data  = ' %s -p%s %s %s -d%s -f%s DBPATH=%s DBMONEY=%s CLIENT_LOCALE=%s'
data += ' SINGLELEVEL=%s '
data  = data % (self.username, self.password, self.version, self.serialNumber,
self.databaseName,, self.databasePath, self.databaseMoney,
self.singleLevel, self.lkNotify, self.lockDown, 

When the server receives this packet validates the username and the password (which is, BTW, sent in plain text) and, also, the database name if it was passed. Regardless of whether the username and password are valid, the server will always answer with interesting data to the client, such as the install path, complete version, etc... (BTW, there is a working module to gather information from an Informix Database in the private version of Inguma and will be released in the next release).

The response sent from the server to the client will have the following format:

"0x00 0x05 0x02 0x00*12 ieee name banner serial dbpath protocol hostname terminal installpath"

The first byte (0x00 or 0x01) is the "isValidUser" byte. If the username and password are OK, the server will answer with a value of 0x01. Otherwise, the value will be 0x0. The 2nd and 3rd bytes indicates if the database selected exists and the user has privilege to connect to. A normal answer (if the database exists and, also, the username & password are both valid) is 0x05 0x02. All the rest of the data are C strings.

After this, if both username and password are valid, the user may start sending commands in a new (binary) protocol format. The protocol will have the following structure (not 100% accurate...):

0x00 OPCODE 0x00 0x00 0x00 STRING_DATA 0x00 0x00 0x16 0x00 0x31 0x00 0x0c

The first byte is static and the second one is the OPCODE. The opcode is an index to an internal function pointers array. In example, the OPCODE 0x01 is for executing SQL commands, the OPCODE chr(26) will list all the databases in the server, etc.. These function pointers are stored in the global array "jmpsql".

Well, I hope that we will release a new version in about 1 month or so with modules for DB2 and Informix.

Joxean Koret

First post!

This is the Inguma project's development blog. In the near future (we hope) we will update the blog with information about the new libraries, modules, etc... added to the Inguma framework.