ASA Programming Guide
  Embedded SQL Programming
    Library function reference

db_start_engine function

Prototype 

unsigned int db_start_engine( SQLCA * sqlca, char * parms );

Arguments 

sqlca    A pointer to a SQLCA structure. For information, see The SQL Communication Area (SQLCA).

parms    A NULL-terminated string containing a semi-colon-delimited list of parameter settings, each of the form KEYWORD=value. For example,

"UID=DBA;PWD=SQL;DBF=c:\\db\\mydatabase.db"

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

Description 

Starts 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:\\asa9\\asademo.db; Start=dbeng9" );

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=dbeng9 c:\\asa\\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:

1. Start a database server named server_1:

   start dbeng9 -n server_1 asademo.db

2. Force a new server to start and connect to it:

   db_start_engine( &sqlda, 
     "START=dbeng9 -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 option of the START parameter.