6.2. C language access methods

--- Opening database (creating driver)

esqlDB easysql_open(char const *dbname)

Opens named EasySQL database. You may use easysql_ok(esqlDriver) call to check was it successful or not.

See easysql::easysql(..) C++ method for more complete description.

--- Closing database (destroying driver)

int easysql_close(esqlDB db)

Closes given EasySQL database returning non-zero in case of success.

See easysql::~easysql() method for more complete description.

An example:

#include <easysql/easysql.h>

esqlDriver sql;

int main()
{ sql=easysql_open("mydb");
  if(!easysql_ok(sql))
   { printf("SQL error: %s",easysql_error_text(sql));
     return 1;
   }
  ...
  easysql_close(sql);
}

--- Checking database correctness

int easysql_ok(esqlDB db)

Checks was database opened correctly or not. Returns non-zero in case of `Ok' and zero otherwise.

Corresponding C++ method is easysql::operator bool().

--- Retrieving last error text message

char const *easysql_error_text(esqlDB db)

Returns text of last error happened or NULL in case of no error.

Corresponding C++ method is easysql::error_text().

--- Sending SQL queries

esqlResult easysql_query(esqlDB db, char const *q, ...)

Sends a query generated from format string and a number of arguments to database and returns a reference to results.

Corresponding C++ method is easysql::query(..).

--- Sending SQL queries from `va_list'

esqlResult easysql_query_ap(esqlDB db, char const *q, va_list ap)

Sends a query generated from format string and a `va_list' of arguments to database and returns a reference to results.

Corresponding C++ method is easysql::_query(..).

--- Fetching rows of data

esqlRow easysql_row(esqlDB db, esqlResult r)

Fetches next row in sequence of results. If there is no more results NULL is returned.

Corresponding C++ method is easysql::row(..).

--- Freeing results of queries

int easysql_rfree(esqlDB db, esqlResult r)

Frees results a reference to whose was previously got by query to database. You have to free every result you got when you need it no more.

Corresponding C++ method is easysql::rfree(..).

--- Setting database options by name/value pair

int easysql_set_option(esqlDB db, char const name, char const *value)

Sets a value of option (see discussion of options in `Database configuration' chapter above). Both name and option may be NULL's.

Corresponding C++ method is easysql::option(..).

--- Setting database options by text string

int easysql_put_option(esqlDB db, char const name)

Sets driver's options from given text string of form `name=value name1=value1 ...'. No quoting or escaping is done and so it's impossible to set multiword values by this method.

Corresponding C++ method is easysql::option(..).

--- Resetting all options

void easysql_reset(esqlDB db)

Resets all options to empty values.

Corresponding C++ method is easysql::reset().

--- Checking driver correctness

int easysql_driver_ok(esqlDB db)

Checks for was internal SQL engine driver loaded and initialized successfully or not (returning non-zero in case of success). Usually you need not use this function.

Corresponding C++ method is easysql::driver_ok().

--- Retrieving driver's status information

char const *easysql_driver_status(esqlDB db)

Attempts to retrieve internal SQL driver status. Usually the result is one line of text of about 50..70 characters in length.

Corresponding C++ method is easysql::driver_status().

--- Retrieving driver's version information

char const *easysql_driver_version(esqlDB db)

Attempts to retrieve internal SQL driver version. Format is `driver_name driver_version api_version engine_version', only first field is always present in answer.

Corresponding C++ method is easysql::driver_version().

--- Escaping text string to SQL accepted format

char const *easysql_string(esqlDB db, char const *str, char *buf)

Escapes text string supplied in `str' to help pass it to INSERT/UPDATE/WHERE statements. Usually `buf' is NULL -- see description of appropriate C++ method (easysql::string(..)).

An example:

main()
{ char buf[200];
  ...
  easysql_query(db,"UPDATE logins SET active=1 WHERE user='%s' OR user='%s'",
                   easysql_string(db,user1,NULL),
                   easysql_string(db,user2,buf));
  ...
}

--- Setting retry delay

unsigned easysql_set_retry_delay(esqlDB db, unsigned d)

Sets retry delay.

Corresponding C++ method is easysql::set_retry_delay(..).

--- Forcing connection to engine

int easysql_connect(esqlDB db)

Forces establishment of a connection to SQL engine (usually it's not required). Returns non-zero if successful.

Corresponding C++ method is easysql::connect().

--- Forcing connection closing

int easysql_drop(esqlDB db)

Forces a connection to SQL engine be dropped (usually it's not required). Returns non-zero if successful.

Corresponding C++ method is easysql::drop().

--- Checking connection state

int easysql_connection_ok(esqlDB db)

Checks state of connection to SQL engine. Usually it's not required because if connection is closed it is reopened automatically on nearest query sent to engine.

Returns non-zero if connection is established and zero otherwise.

Corresponding C++ method is easysql::connection_ok().