Home

	Expand Search

Chapter 2: The Embedded SQL Interface

Library functions

Connection and server management functions

Connection and server management functions

The following functions provide a means to start and stop the database server or, start or stop a database on an existing database server; and connect to or disconnect from a database.

All of these functions take a NULL-terminated string as the second argument. This string is a list of parameter settings of the form KEYWORD= value , delimited by semicolons. The number sign (#) is an alternative to the equals sign, and should be used when the equals sign is a syntax error, such as in environment variables on some platforms..

For an available list of connection parameters, see Connection parameters .

Each function uses a subset of the available connection parameters, but every function will allow any parameter to be set. A sample connection parameter string is:

"UID=dba;PWD=sql;DBF=c:\asa6\asademo.db"

When included in Embedded SQL, the backslash character (\) must be escaped with a second backslash character in order to work:

"UID=dba;PWD=sql;DBF=c:\\asa6\\asademo.db"

db_string_connect function

Prototype

unsigned db_string_connect( struct sqlca * sqlca, char * parms );

Description

Provides extra functionality beyond the Embedded SQL CONNECT command. This function carries out the following steps:

• Start the database server if there is not one running with the name EngineName (calls db_start_engine ). The AutoStop parameter determines if the server automatically stops when the last used database is shut down.

• If the database named by DatabaseName or DatabaseFile is not currently running, send a request to the server to start a database using the DatabaseFile , DatabaseName , and DatabaseSwitches parameters. The AutoStop parameter determines if the database automatically shuts down when the last connection to the database is disconnected.

• Send a connection request to the database server based on the Userid , Password , and ConnectionName parameters.

The return value is true (non-zero) if a connection was successfully established and false (zero) otherwise. Error information for starting the server, starting the database, or connecting is returned in the SQLCA.

db_string_disconnect function

Prototype

unsigned db_string_disconnect( struct sqlca * sqlca, char * parms );

Description

This function disconnects the connection identified by the ConnectionName parameter. All other parameters are ignored.

If no ConnectionName parameter is specified in the string, the unnamed connection is disconnected. This is equivalent to the Embedded SQL DISCONNECT command. The boolean return value is true if a connection was successfully ended. Error information is returned in the SQLCA.

This function shuts down the database if it was started with the AutoStop = yes parameter and there are no other connections to the database. It also stops the server if it was started with the AutoStop = yes parameter and there are no other databases running.

db_start_engine function

Prototype

unsigned db_start_engine( struct sqlca * sqlca, 

char * parms );

Description

Start the database server if it is not running. The steps carried out by this function are those listed in Starting a personal server .

The return value is true if a database server was either found or successfully started. Error information is returned in the SQLCA.

The following call to db_start_engine starts the database server and names it asademo , but does not load the database, despite the DBF connection parameter:

db_start_engine( &sqlca, "DBF=c:\\asa6\\asademo.db; Start=DBENG6" );

If you wish to start a database as well as the server, include the database file in the START connection parameter:

db_start_engine( &sqlca,"ENG=eng_name;START=DBENG6 c:\\asa6\\asademo.db" );

This call starts the server, names it eng_name , and starts the asademo database on that server.

db_start_database function

Prototype

unsigned db_start_database( struct sqlca * sqlca, char * parms ); 

Description

Start a database on an existing server if the database is not already running. The steps carried out to start a database are described iStarting a personal server

The return value is true if the database was already running or successfully started. Error information is returned in the SQLCA.

If a user ID and password are supplied in the parameters, they are ignored.

The permission required to start and stop a database is set on the database command line. For information, see The database server .

db_stop_database function

Prototype

unsigned int db_stop_database( struct sqlca * sqlca, 

 char * parms ); 

Description

Stop the database identified by DatabaseName on the server identified by EngineName . If EngineName is not specified, the default server is used.

By default, this function does not stop a database that has existing connections. If Unconditional is yes , the database is stopped regardless of existing connections.

A return value of TRUE indicates that there were no errors.

The permission required to start and stop a database is set on the database command line. For information, see The database server .

db_stop_engine function

Prototype

unsigned int db_stop_engine( struct sqlca * sqlca, 

 char * parms ); 

Description

Terminates execution of the database server. The steps carried out by this function are:

• Look for a local database server that has a name that matches the EngineName parameter. If no EngineName is specified, look for the default local database server.

• If no matching server is found, this function fails.

• Send a request to the server to tell it to checkpoint and shut down all databases.

• Unload the database server.

By default, this function will not stop a database server that has existing connections. If Unconditional is yes , the database server is stopped regardless of existing connections.

A C program can use this function instead of spawning DBSTOP. A return value of TRUE indicates that there were no errors.

db_find_engine function

Prototype

unsigned short db_find_engine( struct sqlca *sqlca, char *name ); 

Description

Returns an unsigned short value, which indicates status information about the database server whose name is name . If no server can be found with the specified name, the return value is 0. A non-zero value indicates that the server is currently running.

Each bit in the return value conveys some information. Constants that represent the bits for the various pieces of information are defined in the sqldef.h header file. If a null pointer is specified for name , information is returned about the default database environment.