ASA Programming Interfaces Guide

Home

ASA Programming Interfaces Guide

Chapter 2: The Embedded SQL Interface

Library 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 _esqlentry_ db_string_connect( struct sqlca * sqlca, char * parms );

Description

Provides extra functionality beyond the Embedded SQL CONNECT command. This function carries out a connection using the algorithm described in Troubleshooting connections .

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 _esqlentry_ 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 _esqlentry_ 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.

The

db_start_engine

function attempts to connect to a server before starting one, to avoid attempting to start a server that is already running.

The FORCESTART connection parameter is used only by the

db_start_engine

function. When set to YES, there is no attempt to connect to a server before trying to start one. This enables the following pair of commands to work as expected:

Start a database server named server_1
```
start dbeng6 -n server_1 asademo.db
```
Force a new server to start and connect to it:

db_start_engine( &sqlda, "START=dbeng6 -n server_2 asademo.db;ForceStart=YES" )

If FORCESTART was not used, and without an ENG parameter, the second command would have attempted to connect to server_1. The

db_start_engine

function does not pick up the server name from the -n switch of the START parameter.

db_start_database function

Prototype

unsigned _esqlentry_ 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 in Starting 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 server command line. For information, see The database server .

db_stop_database function

Prototype

unsigned int _esqlentry_ 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 server command line. For information, see The database server .

db_stop_engine function

Prototype

unsigned int _esqlentry_ 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.

The use of db_stop_ending is subject to the permissions set on the -gk database server command-line option. For more information, see -gk command-line option .

db_find_engine function

Prototype

unsigned short _esqlentry_ 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.


	Expand Search