ORATCL-CAPI

Copyright Tom Poindexter 1995

Oratcl-capi is a C API to Oratcl.  Tcl is not required (nor supported!)
to access Oratcl functionality from C.  Oratcl-capi follows the same
model as Oratcl in that database results are returned as string values.

Oratcl-capi consist of two include files "oratcl-capi.h" ,"tcl.h" and a set of 
support routines "oratcl-capi.c".  These provide oratcl.c enough emulated Tcl 
functionality so that no changes are required in oratcl.c.  


To build the test program, copy ../oratcl.c, review and edit the
Makefile if necessary, then 'make'.

To run the test program: 

	testcapi ora_connect_str 'select * from sometable'

Of course, you should give it your own oracle connect string (id/pass@server) 
and whatever SQL command you would like to execute.

Oratcl-capi was an even quicker hack based on Sybtcl-capi.


THE ORATCL C API

Except as noted, Oratcl-capi routines return TCL_OK (0) on success, or
TCL_ERROR (1) on failure.  A fake Tcl_Interp pointer is required for all
functions, so you should get a new Tcl_Interp first by calling Oratcl_MkInterp.
Then call Oratcl_Init() using your new interp.  

Except for interp, all function agruments should be character strings. 
For function agruments listed as optional, NULL should be coded instead of "".

See the Oratcl man page for definitive information on behavior of each
function.


Tcl_Interp * Oratcl_MkInterp(void);

	Oratcl_MkInterp returns a pointer to a new Tcl_Interp structure.
	Interp structure can be used for more than one connection, or
	you can use a separate interp per connection.


void Oratcl_FreeInterp(Tcl_Interp *interp);

	Oratcl_FreeInterp frees up memory allocated for the interp
	structure.


int Oratcl_Init (Tcl_Interp *interp);

	Oratcl_Init initializes the Oratcl package for the interp.
	Call this before any Oratcl command below.


int Oralogon (Tcl_Interp *interp, char *connect_str);
	
	Oraconnect opens a connection to the server.  The parameter
	connect_str should contain a valid Oracle connection string.  
	The logon connection handle is returned in RESULT(interp).


int Oralogoff (Tcl_Interp *interp, char *lda_handle);

	Oralogoff closes the logon connection specified by lda_handle.
	

int Oraopen (Tcl_Interp *interp, char *lda_handle);

	Oraopen opens a cursor handle based on an login handle.  The
	cursor handle is returned in RESULT(interp).
	

int Oraclose (Tcl_Interp *interp, char *cur_handle);

	Oraclose closes a cursor handle in cur_handle.
	

int Orasql (Tcl_Interp *interp, char *cur_handle, char *sql_str, 
	    char *async_parseonly);

	Orasql sends an SQL statement in sql_str to the server.
	A cursor in cur_handle should have previously been opened.
	Results are in GET_STATUS(interp,Nextrow).


int Orapoll (Tcl_Interp *interp, char *cur_handle, char *all);

	Orapoll polls a cursor that has been submitted in async mode.
	A cursor in cur_handle should have previously been opened.


int Orabreak (Tcl_Interp *interp, char *cur_handle);

	Orabreak interrupts a pending SQL statement that has been submitted
	in async mode.
	A cursor in cur_handle should have previously been opened.
    

int Orabindexec (Tcl_Interp *interp, char *cur_handle, [char * async],
	[char* varname, char* value] ... , char* NULL);

	Orabindexec executes a SQL statement that has previously been
	parsed by Orasql (with "parseonly" option), optionally binding
	varnames to values.  Results are returned in in RESULT(interp).
	Varname/value pairs must terminated by a NULL.


int Orafetch (Tcl_Interp *interp, char *cur_handle);

	Orafetch gets the next row,  NUMCOLS(interp) as the number of
	columns; each column should be accessed as COLUMN(interp,i), where
	i = 0 for column 1, etc. 


int Oracols (Tcl_Interp *interp, char *cur_handle);

	Oracols gets the column names,  NUMCOLS(interp) as the number of
	columns; each column name should be accessed as COLUMN(interp,i), where
	i = 0 for column name 1, etc.  List of column data types are in
	GET_STATUS(interp,Coltypes), list of column lengths in
	GET_STATUS(interp,Collengths), list of column precisions are in
	GET_STATUS(interp,Colprecs), list of column scales are in
	GET_STATUS(interp,Colscales).


int Oracancel (Tcl_Interp *interp, char *cur_handle);

	Oracanel cancels the pending set of results;


int Oraplexec (Tcl_Interp *interp, char *cur_handle, [char* varname, 
	char* value] ... , char* NULL);

	Oraplexec executes a PL/SQL stored procedure, optionally binding
	varnames to values.  Results are returned in in RESULT(interp).
	Varname/value pairs must terminated by a NULL.


int Orawritelong (Tcl_Interp *interp, char *cur_handle, 
		char *rowid, char *table, char *column, char *file);

	Orawritelong writes a file to a LONG or LONG RAW column.
	Rowid is an Oracle row identifier in character format, table name,
	column name, and file name to be written.


int Orareadlong (Tcl_Interp *interp, char *cur_handle, 
		char *rowid, char *table, char *column, char *file);

	Orareadlong reads a LONG or LONG RAW and writes to a file.
	Rowid is an Oracle row identifier in character format, table name,
	column name, and file name containing the column value.


int Oracommit (Tcl_Interp *interp, char *lda_handle);

	Oracommit commits all outstanding transactions for a
	login handle.


int Oraroll (Tcl_Interp *interp, char *lda_handle);

	Oraroll rolls back all outstanding transactions for a
	login handle.


int Oraautocom (Tcl_Interp *interp, char *lda_handle, char *state);

	Oraautocom sets whether transactions should be automatically
	committed.  State should be "yes" or "no".


Macros:

These macros are the safe way to access results, as they ensure a 
valid string is returned.

RESULT(interp)		Gets a single result, interp->column[0]
COLUMN(interp,i)	Gets a column result, interp->colunn[i]
NUMCOLS(interp)		Gets number of result columns, interp->num_columns
GET_STATUS(interp,i)	Gets a status value, interp->status[i]

Defines for status values:

	Handle
	Rc
	Sqlfunc
	Ocifunc
	Errortxt
	Rows
	Collengths
	Coltypes
	Colprecs
	Colscales
	Ociinfo
	Maxlong			can be set by programmer
	Nullvalue		can be set by programmer
	Version

Again, see the oratcl.man page for definitions of each value.

To set a programmer status value (Nullvalue, Maxlong):
Set "value" to something appropriate.

	Tcl_SetVar2(interp, "status", "nullvalue", "value", 0);
	Tcl_SetVar2(interp, "status", "maxlong"  , "value", 0);



