Library `informix`

Informix Library supporting a very limited subset of Informix operations

Summary ------- Informix supports both The Open Group Distributed Relational Database Architecture (DRDA) protocol, and their own. This library attempts to implement a basic subset of operations. It currently supports; o Authentication using plain-text usernames and passwords o Simple SELECT, INSERT and UPDATE queries, possible more ...

Overview -------- The library contains the following classes:

o Packet.* - The Packet classes contain specific packets and function to serialize them to strings that can be sent over the wire. Each class may also contain a function to parse the servers response.

o ColMetaData - A class holding the meta data for each column

o Comm - Implements a number of functions to handle communication over the the Socket class.

o Helper - A helper class that provides easy access to the rest of the library

o Socket - This is a copy of the DB2Socket class which provides fundamental buffering

In addition the library contains the following tables with decoder functions

o MetaDataDecoders - Contains functions to decode the column metadata per data type

o DataTypeDecoders - Contains function to decode each data-type in the query resultset

o MessageDecoders - Contains a decoder for each supported protocol message

Example ------- The following sample code illustrates how scripts can use the Helper class to interface the library:

	helper 	= informix.Helper:new( host, port, "on_demo" )
	status, err = helper:Connect()
	status, res = helper:Login("informix", "informix")
	status, err = helper:Close()

Additional information ---------------------- The implementation is based on analysis of packet dumps and has been tested against:

x IBM Informix Dynamic Server Express Edition v11.50 32-bit on Ubuntu x IBM Informix Dynamic Server xxx 32-bit on Windows 2003

Author:

"Patrik Karlsson <patrik@cqure.net>"

Source: http://nmap.org/svn/nselib/informix.lua

Functions

[Constants.Message.SQ_DBLIST] (socket)	Decodes a SQ_DBLIST response
[Constants.Message.SQ_DESCRIBE] (socket)	Decodes the metadata for a result set
[Constants.Message.SQ_DONE] (socket)	Decodes the SQ_DONE message
[Constants.Message.SQ_EOT] (socket)	Decodes the SQ_EOT message
[Constants.Message.SQ_ERR] (socket)	Decodes the SQ_ERR error message
[Constants.Message.SQ_PROTOCOLS] (socket)	Decodes the SQ_PROTOCOLS message
[Constants.Message.SQ_TUPLE] (socket, info)	Processes the result from a query
__tostring (self)	Converts the class to a string suitable to send over the socket
__tostring (self)	Converts the class to a string suitable to send over the socket
__tostring (self)	Converts the class to a string suitable to send over the socket
__tostring (self)	Converts the class to a string suitable to send over the socket
__tostring (self)	Converts the class to a string suitable to send over the socket
__tostring (self)	Converts the class to a string suitable to send over the socket
__tostring (self)	Converts the class to a string suitable to send over the socket
__tostring (self)	Converts the class to a string suitable to send over the socket
__tostring (self)	Converts the class to a string suitable to send over the socket
addDefaultParameters (self)	Adds the default set of parameters
addParameter (self, param, value)	Adds a parameter to the connection packet
close (self)	Closes an open connection.
Close (self)	Closes the connection to the server
Connect (self)	Connects to the Informix server
connect (self, hostid, port, protocol)	Establishes a connection.
exchIfxPacket (self, packet, info, packets)	Sends and packet and attempts to handle the response
formatTable (info)	Formats a table to suitable script output
GetDatabases (self)	Attempts to retrieve a list of available databases
getErrMsg (self)	Retrieves the Informix error message
getLength (self)	Gets the column length
getName (self)	Gets the column name
getOsError (self)	Retrieves the OS error code
getSvcError (self)	Retrieves the Informix service error
getType (self)	Gets the column type
Login (self, username, password, parameters, database, retry)	Attempts to login to the Informix database server The optional parameters parameter takes any informix specific parameters used to connect to the database. In case it's ommited a set of default parameters are set. Parameters should be past as key, value pairs inside of a table array as the following example:
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
new (self, host, port, instance)	Creates a new Helper instance
OpenDatabase (self, database)	Opens a database
padToEven (str, pad)	Pads a string to an even number of characters
padToOdd (str, pad)	Pads a string to an odd number of characters
paramToString (param, value)	Converts a connection parameter to string
readResponse (self, socket)	Reads and decodes the response to the connect packet from the server. The function will return true even if the response contains an Informix error. In order to verify if the connection was successful, check for OS or service errors using the getSvcError and getOsError methods.
recv (self, count)	Opposed to the `socket:receive_bytes` function, that returns at least x bytes, this function returns the amount of bytes requested.
send (self, data)	Sends data over the socket
setLength (self, len)	Sets the length
setName (self, name)	Sets the name
setType (self, typ)	Sets the datatype

Functions

[Constants.Message.SQ_DBLIST] (socket)

Decodes a SQ_DBLIST response

Parameters

socket: already connected to the Informix database server

Return values:

status true on success, false on failure
databases array of database names

[Constants.Message.SQ_DESCRIBE] (socket)

Decodes the metadata for a result set

Parameters

socket: already connected to the Informix database server

Return values:

status true on success, false on failure
column_meta table containing the metadata

[Constants.Message.SQ_DONE] (socket)

Decodes the SQ_DONE message

Parameters

socket: already connected to the Informix database server

Return values:

status true on success, false on failure
err error message if status is false

[Constants.Message.SQ_EOT] (socket)

Decodes the SQ_EOT message

Parameters

socket:

Return value:

status, always true

[Constants.Message.SQ_ERR] (socket)

Decodes the SQ_ERR error message

Parameters

socket: already connected to the Informix database server

Return values:

status true on success, false on failure
errmsg, Informix error message or decoding error message if status is false

[Constants.Message.SQ_PROTOCOLS] (socket)

Decodes the SQ_PROTOCOLS message

Parameters

socket: already connected to the Informix database server

Return values:

status true on success, false on failure
err error message if status is false

[Constants.Message.SQ_TUPLE] (socket, info)

Processes the result from a query

Parameters

socket: already connected to the Informix database server
info: table containing the following fields: metadata as recieved from SQ_DESCRIBE rows containing already retrieved rows id containing the statement id as sent to SQ_ID

Return values:

status true on success, false on failure
rows table containing the resulting columns and rows as: { { col, col2, col3 } } or error message if status is false

__tostring (self)

Converts the class to a string suitable to send over the socket

Parameters

self:

Return value:

string containing the packet data

__tostring (self)

Converts the class to a string suitable to send over the socket

Parameters

self:

Return value:

string containing the packet data

__tostring (self)

Converts the class to a string suitable to send over the socket

Parameters

self:

Return value:

string containing the packet data

__tostring (self)

Converts the class to a string suitable to send over the socket

Parameters

self:

Return value:

string containing the packet data

__tostring (self)

Converts the class to a string suitable to send over the socket

Parameters

self:

Return value:

string containing the packet data

__tostring (self)

Converts the class to a string suitable to send over the socket

Parameters

self:

Return value:

string containing the packet data

__tostring (self)

Converts the class to a string suitable to send over the socket

Parameters

self:

Return value:

string containing the packet data

__tostring (self)

Converts the class to a string suitable to send over the socket

Parameters

self:

Return value:

string containing the packet data

__tostring (self)

Converts the class to a string suitable to send over the socket

Parameters

self:

Return value:

string containing the packet data

addDefaultParameters (self)

Adds the default set of parameters

Parameters

self:

addParameter (self, param, value)

Adds a parameter to the connection packet

Parameters

self:
param: string containing the parameter name
value: string containing the parameter value

Return value:

status, always true

close (self)

Closes an open connection.

Parameters

self:

Return values:

Status (true or false).
Error code (if status is false).

Close (self)

Closes the connection to the server

Parameters

self:

Return value:

status true on success, false on failure

Connect (self)

Connects to the Informix server

Parameters

self:

Return values:

true on success, false on failure
err containing error message when status is false

connect (self, hostid, port, protocol)

Establishes a connection.

Parameters

self:
hostid: Hostname or IP address.
port: Port number.
protocol: "tcp", "udp", or

Return values:

Status (true or false).
Error code (if status is false).

exchIfxPacket (self, packet, info, packets)

Sends and packet and attempts to handle the response

Parameters

self:
packet:
info: any additional info to pass as the second parameter to the decoder
packets: an instance of a Packet.* class

Return values:

status true on success, false on failure
data returned from the ResponseDecoder

formatTable (info)

Formats a table to suitable script output

Parameters

info: as returned from ExecutePrepare

Return value:

table suitable for use by stdnse.format_output

GetDatabases (self)

Attempts to retrieve a list of available databases

Parameters

self:

Return values:

status true on success, false on failure
databases array of database names or err on failure

getErrMsg (self)

Retrieves the Informix error message

Parameters

self:

Return value:

errmsg string containing the "mapped" error message

getLength (self)

Gets the column length

Parameters

self:

Return value:

len the column length

getName (self)

Gets the column name

Parameters

self:

Return value:

name the column name

getOsError (self)

Retrieves the OS error code

Parameters

self:

Return value:

oserror number containing the OS error code

getSvcError (self)

Retrieves the Informix service error

Parameters

self:

Return value:

svcerror number containing the service error

getType (self)

Gets the column type

Parameters

self:

Return value:

typ the column type

Login (self, username, password, parameters, database, retry)

Attempts to login to the Informix database server The optional parameters parameter takes any informix specific parameters used to connect to the database. In case it's ommited a set of default parameters are set. Parameters should be past as key, value pairs inside of a table array as the following example:

local params = { [1] = { ["PARAM1"] = "VALUE1" }, [2] = { ["PARAM2"] = "VALUE2" }, }