Transact C Client library programmer's guide

Table of content

Debug functions

Overview

The C client library is the prefered way for C applications to communicate with the Transact engine;
Althrough only one kind of the Transact engine is provided with this release of the software ("in process" server in the form of a RISC OS module), future expressions of the client library (for "separate process" servers planned for the v0.2.2 release) will adopt if possible the same API interface (but with different implementations).
Besides providing stubs for calling each of the servicing of the Transact engine, the client library supply one extra facility:

The client library automatically drops every session opened by the client application at its terminaison.

Every client library function returns _kernel_oserror * result; if additional parameters should be returned to the client application, then they are returned by reference, that is a pointer to them is passed by value to the client library function; Eg.
_kernel_oserror *sp_create_session(const ttmode monmode, TYPSID *const pcsid);
The external session ID is returned in *pcsid. In addition to the errors returned by the Transact engine, the client library generates its own error codes which are:

0: Unable to register an atexit function;
1: Memory allocation error;
2: Unknown session (eg a client application tries to initiate an operation in the name of a session it has not created).
3: Uninitialized client library (eg a client application tries to call a function before calling the sp_clinit initialisation function.
4: Client library already initialized (a second call to sp_clinit tries to initialize an already initialized client library).

The client library interface consists of the files below:

mstubs.o	object file to be linked with your client application object files
transact.h	definitions common to ther server and the client sides of the Transact engine
client.h	definitions and prototypes specific to the client side

In every module which calls a client library function call exists, the following lines should be inserted near the head of the file.

#define __CLIENT__
#include "transact.h"

Here are the constants and datatypes defined in the headers which are of some use to the client application:

Name	Type	Comment
TYPSID	t	Session's external ID
TYPCID	t	Cursor's external ID
TYPOID	t	Data object external ID
mfpos_t	t	Offset of a byte from the beginning of a file or difference between two offsets
ttmode	t	Session's transaction mode
DIRTY_READ, READ_COMMITED, REPEATABLE_READ	c	Transaction modes
ALLOW_BACKWARDS	c	Cursor creation option
ERR_BUSY, ERR_UNKNOWN_SESSION, ERR_UNKNOWN_OBJECT, ERR_UNKNOWN_CURSOR, ERR_NOT_ENOUGH_MEMORY, ERR_INVALID_PARMS, ERR_INAPROPRIATE_CURSOR_MODE, ERR_CONFLICT_WITH_ANOTHER, ERR_CURSOR_IN_USE	c	Error reason codes as returned from the Transact engine and returned unmodified by the C client library.
tcompound	t	Type of elementary cell used in the sp_compound call.
CINSERT, CUPDATE, CDELETE	c	Possible values for the creason field in the tcompound structure