data_base (nst man page)

NAME

data_base -- ODBC NST class container

PROTOTYPE

unitptr data_base( char *pcHost, char *pcUser, char *pcPasswd, char *pcDBname, unitptr uHost)

ARGUMENTS

char *pcHost: hostname of ODBC capable database server
char *pcUser: username
char *pcPasswd: password
char *pcDBname: name of data source on server
unitptr uHost: host unit

RETURN VALUE:

A pointer to the created unit or NULL in the case of an error.

DESCRIPTION:

This class container provides the basic functionality to connect to an ODBC capable database server (Oracle, Informix, mySQL, etc). In general vendors of database servers provide different APIs to connect to and to retreive and store results from databases. A common way to gain server independant access to databases is to use the ODBC standard (Open DataBase Connectivity), of which many database servers are capable. The general philosophy of ODBC is as follows: The application calls all database services via standardized ODBC functions. These function calls are handled by a so called "ODBC Driver Manager" which dynamically loads the desired ODBC driver (which is generally provided by the database vendor). This driver then maps the ODBC function calls to native, server dependent function calls. Therefore, the application does not need to know from which database server it actually requests the information. ODBC also allows multiple connections to different servers. Hence, it can retreive information from server A and B, and store it into a database handled by server C. To address a specific data source, the driver manager needs the following information: - Host name of the database server - Username of user who requests service - Password of this user - Name of the data source (specifies name of database on server) Note, that the data_base container only provides mechanisms to connect to databases and to submit queries. (See below for a detailed description of each method). Retrieval and storage of actual data can be performed using the virtual methods of the result container class.

NEO CREATION:

When creating the unit, the following parameters have to be specified: -Database host -Database user -Password -Database Note, that for the first three parameters a environment variable substitution may be choosen. If, for example the entry for Password is "MYSQL_PWD" then the value of the corresponding environment variable is taken.

NEO INTERFACE:

The unit has no Input/Output fields.

EXECUTION:

Execution of the created unit does nothing. However, execution of any of its named subunits (via a use_named unit) invokes the corresponding C++ class method. The interface of each named subunit provides inputs and outputs for the corresponding method.

NEO INTERFACE AND DESCRIPTION OF NAMED SUBUNITS:

query:
Input field 0:: (string) The SQL query string
Output field 0:: (float 1) The number of columns in the result set (-1 in case of an error)

Execution allocates necessary statement handles and connects to the database server. The query string is then submitted via SQLExecute and must therefore be a valid SQL statement. (Note that different database servers often speak different SQL accents. Usually ANSI SQL is a safe bet.) For each query (=connection) the corresponding statement handles are stored in a hashtable indexed by the query string. A connection is kept up as long as its resources are not dropped by one of the drop methods described below.

drop_query:
Input field 0:: (string) The SQL query string

Execution closes connection to the database server and frees all resources allocated by the corresponding query string.

drop_all:: no Input/Output

Execution closes all open connections to the database server and frees all allocated resouces.

squery:
Input field 0:: (string) The SQL query string
Output field 0:: (float 1) The number of columns in result set (-1 in case of an error)

Execution connects to database server and commits SQL statement via SQLExecute. Then immediately closes the connection and frees allocated resources. (This method is intended for the submission of queries where one is not especially interested in any result data set, e.g. creation of new tables etc.)

col_names:
Input field 0:: (string) The SQL query string
Output field 0:: (string) Comma separated list of column names in result set corresponding to input query

FILE

nst_database.cc