Creates and returns a new dbmgr_cs object, which manages all interaction with a database. The database must be ODBC compliant.

Note. This function is currently only available for Netica running on Microsoft Windows. For support on other platforms, please contact Norsys.

Connection String

The connect_str defines an ODBC data source that this database manager will communicate with. The connect_str is the standard ODBC resource definition string passed directly to the standard SQLDriverConnect ODBC command. The general syntactic form of a connection string is "param=value;param=value;...", where 'param' is not case sensitive. Here are some sample connection strings for some common types of database configuration:

Data Source		Connection String
A Microsoft Access database located on your hard disk at C:\MyProjectDir\myAccessDB.mdb		"driver={Microsoft Access Driver (*.mdb)}; dbq=C:\\MyProjectDir\\myAccessDB.mdb; UID=myUserAccount;PWD=myPassword"
A Microsoft Excel spreadsheet located on your hard disk at C:\MyProjectDir\myData.xls		"driver={Microsoft Excel Driver (*.xls)}; dbq=C:\\MyProjectDir\\myData.xls"
An arbitrary data source named "myDataSource" that is registered with the Windows ODBC Data Source Administrator1		"DSN=myDataSource;UID=myUserAccount;PWD=myPassword"
An ORACLE 8i data server running locally with database name "OraInstanceName"		"DRIVER={Microsoft ODBC for Oracle}; SERVER=OraInstanceName; UID=OraUser;PWD=OraPswd;"
A MySQL database called "myDB" running on a machine whose domain name address is "db1.abc.com" communicating via port 5432		"Driver={MySQL};Server=db1.abc.com; Port=5432;Option=131072;Stmt=;Database=myDB; Uid=myUsername;Pwd=myPassword"
A Microsoft SQL Server database called "myDB" running on a machine called "DB_server" on your Microsoft Network LAN		"Driver={SQL Server};Server=DB_server;DataBase=myDB"
A text file2 located on your hard disk at C:\MyProjectDir\myFile.csv		"Driver={Microsoft Text Driver (*.txt; *.csv)}; Dbq=C:\MyProjectDir\;Extensions=asc,csv,tab,txt"

1 To access the Windows ODBC Data Source Administrator, from the Start menu, select "Settings" then "Control Panel". Then for Windows 2000/XP, double-click on "Administrative Tools" and then "Data Sources (ODBC)", and for Windows 95/98/NT, double-click on "ODBC Sources".

2 For text files, your SQL statements must use the file name as the TABLE name. For example: "SELECT * FROM myFile.csv". Furthermore, the first line of the text file is assumed to give the COLUMN names. If you prefer other options than these, then use the Windows ODBC Data Source Administrator1 which has an excellent wizard for text-file databases.

If the database does not have user accounts, then you do not need to specify a UID and PWD.

There are a great many parameters that can be specified within connect_str. Some are generic and apply to all database vendors, like "DSN" and "UID", while others are vendor specific. See your database vendor's documentation and the documentation for SQLDriverConnect to see what other parameters may be available. A good on-line source of documentation for ODBC is available at http://www.microsoft.com/data/odbc/.

Hint: If you are having difficulty getting your connection string to work, then use the Windows ODBC Data Source Administrator to connect to the database, give it a data source name (DSN), "myName", and then use "DSN=myName" as the simplified connection string. The Administrator has powerful wizards to facilitate both finding the database and defining precisely how you wish to access it.

WARNING: Because the connection string may contain a UserID and Password to your database, it represents a security risk. You may want to take extra precautions by securing your source code, dynamically fetching the password from the user, or asking your database administrator to place extra restrictions on the database user account.

Connection Pooling

The ODBC 3.0 standard allows for the caching of database connections, also known as "connection pooling". Every ODBC call involves requesting a connection and releasing it when done. Making a connection is expensive and can often take longer than an actual query to the database. For this reason, you will typically want to enable connection pooling so that your connections are opened only once, and thereafter are taken from and released back to the pool, rather than being really fully initialized and released with each ODBC call. You may wish to disable connection pooling if there are only a limited number of connections available and your process must be a good citizen and share its database connectivity with other processes.

Pass "pooling" for options to enable connection pooling. Pass "no_pooling" to disable it. Other control parameters may be added in future.

Connections in the pool may expire after a time. Adjustments to this time limit and to other properties of the connection pool can be made sometimes via the connection string (see above), and sometimes via the ODBC Data Source Administrator control panel, depending on the ODBC driver that is available.

When the dbmgr_cs object is deleted (see DeleteDBManager_cs), any connections it may have are released.