sp_compound

Transact C client library

sp_compound

This function is a C front end for the newly designed SWI Transact_Compound which appeared in the v0.2.1 of the engine. Briefly stated, it allows a client application to submit more than a single data manipulation request per SWI call.
The main advantage of dealing with compounded requests is the ability to setup intermediary rollback points (current transaction state before the first request is submitted).

ANSI Prototype

typedef struct
        {
        int creason;
        _kernel_swi_regs r;
        } tcompound;
_kernel_oserror *sp_compound(const TYPSID, tcompound *const);

Possible errors

Any error code that can occur when servicing an INSERT, UPDATE or DELETE request.
Client Library: Unknown session;
Client Library: Uninitialized client library.

Implementation notes

The second parameter that this function accepts is a pointer to an array of tcompound structures (cells);
Each cell descrbes an elementary operation to perform (either INSERT, DELETE or UPDATE);
The creason field in each of the cells takes its value among: CDELETE, CINSERT, CUPDATE and -1; the latter value marks the end of the array list.
The kernel_swi_regs structure is here to hold register values as they should be when submitting individual SWIs.

	INSERT	DELETE	UPDATE
r[0]	session ID	session ID	session ID
r[1]	Pointer to filename	Pointer to filename	Pointer to filename
r[2]	Pointer to internal ref. ID	Pointer to internal ref. ID	Pointer to internal ref. ID
r[3]	Length of data buffer	Offset of first byte to delete	Offset of first byte to update
r[4]	-	-	Offset of byte following the last byte to update
r[5]	New data buffer address	-	New data buffer address

Sample code

{
tcompound tsc[3];
char *pdata[2] = { "cb", "ToBeInserted" };
_kernel_oserror *e;
/* External session ID */
tsc[0].r.r[0]= tsc[1].r.r[0]= tsc[2].r.r[2]= psencours;
tsc[0].r.r[1]= tsc[1].r.r[1]= (TYPREG) "<Obey$Dir>.Datafile";
/* Don't mind getting internal ref ID in return */
tsc[0].r.r[2]= tsc[1].r.r[2]= 0;
tsc[0].creason= CUPDATE; tsc[1].creason= CINSERT; tsc[2].creason= -1;
tsc[0].r.r[4]= (TYPREG) (strlen(pdata[0]) + (tsc[0].r.r[3]= 1)),
tsc[0].r.r[5]= (TYPREG) pdata[0];
tsc[0].r.r[3]= (TYPREG) strlen(pdata[1]),
tsc[1].r.r[5]= (TYPREG) pdata[1];
e= sp_compound(psencours, &tsc);
...
}

The above code submits a compound request made of:

An UPDATE for bytes 1 and 2 of the main data file (new content "cb");
Am INSERT of new bytes "ToBeInserted" at the end of the main data file.