| Application Development | |
Before your application can access data stored in your database, you must connect to an initialized database engine. Database initialization tells Panther which database driver and which support routine to use to access the database engine.
There are two types of initialization:
This chapter describes how to implement both initialization types as well as how to initialize one or more database engines.
For information about connecting to a database once it is initialized, refer to Chapter 8, "Connecting to Databases."
Initializing One or More Engines |  |
A database engine is a DBMS (Database Management System) product. It is identified by a specific vendor and version. For example, SYBASE 10, ORACLE 6.0, and ORACLE 7.0 are three distinct engines. A Panther database driver is a C library or DLL that handles all communication between Panther and the DBMS. A Panther support routine is the name of the main entry point, or function, in a Panther database driver.
By default, Panther is distributed with a driver for Panther's database engine, JDB, and for additional database engines. On request, drivers are available for other database engines.
Refer to "Database Drivers" for specific information about each Panther database driver.
A Panther application can access zero or more database engines. The application must have a driver for each engine, and it must initialize the engine before declaring a connection.
As a part of initialization, Panther calls the support routine for information on the particular DBMS. The information provides:
In addition, Panther sets up some structures at initialization, including structures for tracking the number and names of all connections to an engine.
An application with two or more initialized engines sets the default engine with the command:
or sets the current engine for a statement by including the Setting the Default Engine
DBMS ENGINE
engineNameWITH ENGINE clause. If an application initializes more than one engine, it must set the default or current engine when declaring connections to different engines. Once a connection is declared, the default connection determines the default engine.
Initializing the Database via the Executable | |
In static initialization, an application identifies the support routines it will use at compile time, and it links with both the Panther database driver libraries and the DBMS interface libraries.
A list of the support routines available for your application is included in the module dbiinit.c, which is automatically created from settings found in the makevars file for your database when you build Panther executables. When you run Panther, the function dm_init is called for each support routine listed in dbiinit.c.
When initialization is successful, the support routine returns zero. If the support routine rejects the initialization and returns an error code, it might be because there is insufficient memory, the engine might not be installed, or the application might have initialized the same support routine more than once. If such an error occurs when executing the Panther initialization routines, jmain or jxmain, an error message is displayed and Panther terminates.
If necessary, you can create a new version of dbiinit.c. For more information on building a new executable and changing static initialization, refer to "Changing Static Initialization."
The file dbiinit.c contains:
vendor_list.
pfuncs.
A sample vendor_list structure appears as follows:
static vendor_t vendor_list[] =
{
/* {"engineName", supportRoutine, caseFlag, (char *) 0}, */
{"jdb", dm_jdbsup, DM_DEFAULT_CASE, (char *) 0},
{ 0 }
};
engineName
engineName specification tells Panther which database engine to use. Most of the examples in this guide use a vendor name as the engineName mnemonic, for example sybase or oracle.
supportRoutine
dm_vendorCodesup where vendorCode is an abbreviated vendor name. For example:
dm_orasup for ORACLE
caseFlag
SQL SELECT statements. Variables can be widgets on the screen, JPL variables, or LDB variables. Using the case setting lets you create all your Panther variables in a particular case and Panther does the conversion to the desired case for you. caseFlag values are described in Table 7-1.
ORACLE, for example, returns column names in upper case.
DM_PRESERVE_CASE, the application needs Panther variables with upper case names.
char
(char *)0, is provided for future use.
When you compile a new executable, the mkinit command is executed which creates a new version of dbiinit.c, if one does not already exist.
makevars.dbs file (where dbs is a three-letter abbreviation for your database). Provide the appropriate arguments:
dbs_INIT={ d | n | l | u | p }
You need to enter one of the command flags. Refer to "Database Drivers" to find the correct dbs abbreviation string; an invalid abbreviation results in an unresolved external error when you try to link.
make (or nmake in Windows).For details on creating new executables, refer to Chapter 42, "Building Application Executables."
Most of the command flags deal with the case conversion for column names. When a query retrieves a column value, Panther looks for a Panther variable with the same name as the column name and places the value in that variable. However, some database engines only create column names in a specific case or allow mixed cases. Using the case setting, you can create all your Panther variables in a particular case and Panther handles the conversion for you.
d
n
dbiinit.c.
l
u
p
dbs
jdb is for JDB and syb for SYBASE.
Refer to "Database Drivers" to find the abbreviation for a particular database engine.
Dynamic Database Initialization | |
In dynamic initialization, the application identifies the desired support routines at runtime. No compilation is needed to change the initialization.
Under Windows, you have two methods of initializing a database engine. One method is to compile the database into the executable (refer to "Changing Static Initialization" for details on static initialization); the other method uses specifications in your Panther initialization file (PROL5W32.INI or PROL5W64.INI) to initialize database engines at runtime when the Panther program is started.
Add a database-specific section to the file. The syntax is:
[databases]
installed =engineName[engineName]
default =engineName
[dbmsengineName]
case={upper | lower | preserve | default}
driver=driver DLLmodel=model DLL
engineName
engineName specification tells Panther which database engine to use. Most of the examples in this guide use a vendor name as the engineName mnemonic, for example sybase or oracle.
The default engineName specification is optional and lets you name a default database engine. If there is no specification, JDB is the default database engine.
case
SQL SELECT statements. Variables can be widgets on the screen, JPL variables, or LDB variables. Using the case setting lets you can create all your Panther variables in a particular case and Panther converts to that case for you. The case options are described in Table 7-1.
driver DLL
README.vendorCode file in the distributed NOTES directory. (vendorCode is a three-letter abbreviation for the vendor, for example, syb for SYBASE).
model DLL