Application Development


Chapter 7 . Initializing the Database

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.

Initialization Procedure

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.

Setting the Default Engine

An application with two or more initialized engines sets the default engine with the command:

DBMS ENGINE engineName

or sets the current engine for a statement by including the WITH 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."

Database Interface Initialization Routine

The file dbiinit.c contains:

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
Can contain any character string that is not a keyword; and is case-sensitive. If an application uses two or more database engines, the 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
Is usually in the form dm_vendorCodesup where vendorCode is an abbreviated vendor name. For example:

caseFlag
Determines how Panther uses case when mapping column names to Panther variables for 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.

Table 7-1 caseFlag options

caseFlag Option Description

DM_PRESERVE_CASE

p(reserve)

No conversion is done; uses the case returned by the engine. Column names must match the Panther variable names.

DM_FORCE_TO_LOWER_CASE

l(ower)

Force column names returned by engine to lower case. Use lower case for Panther variable names.

DM_FORCE_TO_UPPER_CASE

u(pper)

Force column names returned by engine to upper case. Use upper case for Panther variable names.

DM_DEFAULT_CASE

d(efault)

Use the default value specified by the Panther support routine. Refer to "Database Drivers" to find the value for a specific engine.

ORACLE, for example, returns column names in upper case.

char
The last argument, (char *)0, is provided for future use.

Changing Static Initialization

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.

How to Create a New Version of dbiinit.c

  1. Delete the current version in your application directory.
  2. Edit the database engine settings in the 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.

  3. Run make (or nmake in Windows).

For details on creating new executables, refer to Chapter 42, "Building Application Executables."

Options and Arguments

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
Use the default case conversion set in the support routine. Refer to "Database Drivers" to find the setting for a particular database engine.

n
Do not install this engine in dbiinit.c.

l
Convert column names to lower case.

u
Convert column names to upper case.

p
Preserve the case of the column names when converting to Panther variable names.

dbs
Three-letter abbreviation that Panther specifies for the database. For example, 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.

How to Identify the Database Engines in the Initialization File

Add a database-specific section to the file. The syntax is:

[databases]
installed = engineName [engineName]
default = engineName
[dbms engineName]
case={upper | lower | preserve | default}
driver=driver DLL
model=model DLL

engineName
(Required) The name assigned to the database engine. It can contain any character string that is not a keyword; it is case-sensitive. If an application uses two or more database engines, the 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
(Optional) Determines how Panther uses case when mapping column names to Panther variables for 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
(Required) The DLL provided by Panther for use with a particular database engine and set by the installation program. For additional information about DLLs for a specific engine, refer to the README.vendorCode file in the distributed NOTES directory. (vendorCode is a three-letter abbreviation for the vendor, for example, syb for SYBASE).

model DLL
The name of the transaction model provided by Panther for use with the transaction manager, and is required if you are using the transaction manager (for example, building screens withe screen wizard) and are not compiling a custom transaction model. For information about the transaction model for a specific engine, refer to the README.vendorCode file in the distributed NOTES directory.