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 semicolon-delimited list of parameter settings, each of the form KEYWORD=value. For example, 
    "UID=DBA;PWD=sql;DBF=c:\\db\\mydatabase.db"

    For a list of connection parameters, see Connection parameters.

Description

Starts the database server if it is not running.

For a description of the steps carried out by this function, see Locating a database server.

If the database server was already running or was successfully started, the return value is TRUE (non-zero) and SQLCODE is set to 0. Error information is returned in the SQLCA.

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

db_start_engine( &sqlca, 
    "DBF=samples-dir\\demo.db;START=dbeng11" );

If you want to start a database and the server, include the database file in the StartLine (START) connection parameter:

db_start_engine( &sqlca,
   "ENG=eng_name;START=dbeng11 samples-dir\\demo.db" );

This call starts the server, names it eng_name, and starts the SQL Anywhere sample 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 (FORCE) 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 dbeng11 -n server_1 demo.db

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

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

If ForceStart (FORCE) was not used, and without a ServerName (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 StartLine (START) parameter.

Copyright © 2009, iAnywhere Solutions, Inc. - SQL Anywhere 11.0.1