A session: the object statements are run through. More...

Data Fields
CMBool(*	BeginTransaction )(CMDBM_Session *session)
	Start a transaction across every datasource this session uses.

void(*	EndTransaction )(CMDBM_Session *session)
	Put the connections of this session back into autocommit.

int(*	Execute )(CMDBM_Session session, const char dbid, const char sqlid, CMUTIL_JsonObject params)
	Run a statement for its effect.

CMUTIL_JsonValue (	GetObject )(CMDBM_Session session, const char dbid, const char sqlid, CMUTIL_JsonObject params)
	Run a select and return one single value.

CMUTIL_JsonObject (	GetRow )(CMDBM_Session session, const char dbid, const char sqlid, CMUTIL_JsonObject params)
	Run a select and return its first row.

CMUTIL_JsonArray (	GetRowSet )(CMDBM_Session session, const char dbid, const char sqlid, CMUTIL_JsonObject params)
	Run a select and return all of its rows.

CMBool(*	ForEachRow )(CMDBM_Session session, const char dbid, const char sqlid, CMUTIL_JsonObject params, void udata, CMBool(rowcb)(CMUTIL_JsonObject row, uint32_t rownum, void udata))
	Run a select and hand its rows to a callback one by one.

CMBool(*	Commit )(CMDBM_Session *session)
	Commit the running transaction on every connection of this session.

void(*	Rollback )(CMDBM_Session *session)
	Roll the running transaction back on every connection of this session.

void(*	Close )(CMDBM_Session *session)
	Return the borrowed connections and destroy the session.

Detailed Description

A session: the object statements are run through.

Field Documentation

◆ BeginTransaction

CMBool(* CMDBM_Session::BeginTransaction) (CMDBM_Session *session)

Start a transaction across every datasource this session uses.

Connections already borrowed leave autocommit at once, and connections borrowed later join the transaction as they are taken - so a transaction can be started before the first statement runs.

Every transaction is ended by Commit or Rollback followed by EndTransaction. A session closed while one is running rolls it back.

Parameters

session The session.

Returns: CMTrue while a transaction is running, including when this call found one already started - which is logged as a warning.

◆ EndTransaction

void(* CMDBM_Session::EndTransaction) (CMDBM_Session *session)

Put the connections of this session back into autocommit.

Neither commits nor rolls back: the work is decided by Commit or Rollback before this call.

Parameters

session The session.

◆ Execute

int(* CMDBM_Session::Execute) (CMDBM_Session *session, const char *dbid, const char *sqlid, CMUTIL_JsonObject *params)

Run a statement for its effect.

The statement is an insert, update, delete or DDL. A selectKey of the statement runs as its order says, and writes the key it read into params.

Parameters

session	The session.
dbid	Id of the datasource to run against.
sqlid	Id of the statement, "namespace.statement".
params	The parameters of the statement, and where a `selectKey` or an OUT parameter writes back.

Returns: The number of rows affected, or -1 when the statement could not be built or failed.

◆ GetObject

CMUTIL_JsonValue *(* CMDBM_Session::GetObject) (CMDBM_Session *session, const char *dbid, const char *sqlid, CMUTIL_JsonObject *params)

Run a select and return one single value.

The first column of the first row - a count, a sum, one column of one row looked up by key.

Parameters

session	The session.
dbid	Id of the datasource to run against.
sqlid	Id of the statement, "namespace.statement".
params	The parameters of the statement.

Returns: The value, owned by the caller, or NULL when the statement failed or matched no row.

◆ GetRow

CMUTIL_JsonObject *(* CMDBM_Session::GetRow) (CMDBM_Session *session, const char *dbid, const char *sqlid, CMUTIL_JsonObject *params)

Run a select and return its first row.

Parameters

session	The session.
dbid	Id of the datasource to run against.
sqlid	Id of the statement, "namespace.statement".
params	The parameters of the statement.

Returns: The row as an object keyed by column name, owned by the caller, or NULL when the statement failed or matched no row.

◆ GetRowSet

CMUTIL_JsonArray *(* CMDBM_Session::GetRowSet) (CMDBM_Session *session, const char *dbid, const char *sqlid, CMUTIL_JsonObject *params)

Run a select and return all of its rows.

The whole result is read into memory before the call returns; ForEachRow is the way to walk a result too large for that.

Parameters

session	The session.
dbid	Id of the datasource to run against.
sqlid	Id of the statement, "namespace.statement".
params	The parameters of the statement.

Returns: An array owned by the caller - of row objects, or of plain values when the statement carries resultType="value" - empty when nothing matched, or NULL when the statement failed.

◆ ForEachRow

CMBool(* CMDBM_Session::ForEachRow) (CMDBM_Session *session, const char *dbid, const char *sqlid, CMUTIL_JsonObject *params, void *udata, CMBool(*rowcb)( CMUTIL_JsonObject *row, uint32_t rownum, void *udata))

Run a select and hand its rows to a callback one by one.

Only one row is in memory at a time, which is what makes a result of any size iterable. A statement which carries fetchSize also keeps the client library from buffering the whole result - unless it has a selectKey to run afterwards, in which case streaming is dropped and a warning is logged, since the cursor would block that statement.

Parameters

session	The session.
dbid	Id of the datasource to run against.
sqlid	Id of the statement, "namespace.statement".
params	The parameters of the statement.
udata	Passed to rowcb untouched.
rowcb	Called for every row, with the row, its zero based number and udata. The row is destroyed by the library as soon as the callback returns, so anything to be kept is to be copied out of it. Returning CMFalse stops the iteration.

Returns: CMTrue when the statement ran, whether or not it matched any row and whether or not the callback stopped early; CMFalse when it could not be built or failed.

◆ Commit

CMBool(* CMDBM_Session::Commit) (CMDBM_Session *session)

Commit the running transaction on every connection of this session.

Parameters

session The session.

Returns: CMFalse when no transaction is running.

◆ Rollback

void(* CMDBM_Session::Rollback) (CMDBM_Session *session)

Roll the running transaction back on every connection of this session.

Parameters

session The session.

◆ Close

void(* CMDBM_Session::Close) (CMDBM_Session *session)

Return the borrowed connections and destroy the session.

A transaction still running is rolled back first, with a warning: a connection must never go back to the pool with uncommitted work on it.

Parameters

session The session.

The documentation for this struct was generated from the following file:

/home/runner/work/libcmdbm/libcmdbm/src/libcmdbm.h

Data Fields

Detailed Description

Field Documentation

◆ BeginTransaction

◆ EndTransaction

◆ Execute

◆ GetObject

◆ GetRow

◆ GetRowSet

◆ ForEachRow

◆ Commit

◆ Rollback

◆ Close