source: TI12-security/trunk/NDGSecurity/C/pam_oci8/sqlora.h @ 6812

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI12-security/trunk/NDGSecurity/C/pam_oci8/sqlora.h@6812
Revision 6812, 54.0 KB checked in by pjkersha, 10 years ago (diff)
Line 
1#ifndef __SQLORA8_H_LOADED
2#define __SQLORA8_H_LOADED
3/* $Id: sqlora.h,v 1.22 2002/06/12 06:23:53 kpoitschke Exp $ */
4/**
5 * @file sqlora.h
6 * libsqlora8 - Easy C API to Oracle using OCI.
7 *
8 * @version 2.2
9 *
10 * @author Kai Poitschke
11 *
12 * Copyright (c) 1991-2002 Kai Poitschke (kai[_at_]poitschke.de)
13 *   
14 * This file is part of the libsqlora8 package which can be found
15 * at http://www.poitschke.de/libsqlora8/
16 */
17/*
18 *
19 * Permission to use, copy, modify, and distribute this software for
20 * any purpose with or without fee is hereby granted, provided that
21 * the above copyright notice and this permission notice appear in all
22 * copies.
23 *
24 *    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
25 *    WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
26 *    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
27 *    IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
28 *    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
29 *    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
30 *    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
31 *    USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
32 *    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
33 *    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
34 *    OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 *    SUCH DAMAGE.
36 *
37 */
38
39
40/**
41 * @defgroup env Environment Variables
42 * @{
43 * The library evaluates the following enviroment variables during
44 * initialization:
45 * <ul>
46 * <li>SQLORA_PREFETCH_ROWS (1 .. ; initial value 100)
47 * <li>SQLORA_TRACE_LEVEL
48 *   <ul>
49 *   <li>0 : Trace disabled (default)
50 *   <li>1 : Print errors to tracefile
51 *   <li>2 : Print function calls to tracefile
52 *   <li>3 : Print more detailed information to tracefile
53 *   <li>4 : Print also malloc/realloc operations.
54 *   </ul>
55 *
56 * <li>SQLORA_TRACE_FILE (The trace file; default sqlora8.trc)
57 * <li>SQLORA_LONGSIZE   (Max size of a fetched long; default 64K).
58 * </ul>
59 * During login, the library reads ORACLE_SID, if no tnsname was specified in
60 * the connect string.
61 * @}
62 */
63#ifndef DOXYGEN_SHOULD_SKIP_THIS
64#include <stdio.h>
65#include "libsqlora8-config.h"
66#endif /* DOXYGEN_SHOULD_SKIP_THIS */
67
68/*
69 * Definitions that allow this header file to be used either with or
70 * without ANSI C features like function prototypes.
71 */
72
73
74/* @def __BEGIN_DECLS
75 * __BEGIN_DECLS should be used at the beginning of your declarations,
76 *  so that C++ compilers don't mangle their names.  Use @ref__END_DECLS at
77 *  the end of C declarations.
78 */
79
80/* @def __END_DECLS
81 * Opposite of @ref __BEGIN_DECLS
82 */
83#undef __BEGIN_DECLS
84#undef __END_DECLS
85#ifdef __cplusplus
86# define __BEGIN_DECLS extern "C" {
87# define __END_DECLS }
88#else
89# define __BEGIN_DECLS /* empty */
90# define __END_DECLS /* empty */
91#endif
92
93/*
94 * @def __P
95 * __P is a macro used to wrap function prototypes.
96 *
97 * Compilers that don't understand ANSI C prototypes still work, and ANSI C
98 * compilers can issue warnings about type mismatches.
99 * Use autoconf macro AC_C_PROTOTYPES to check for prototypes.
100*/
101#undef __P
102#if (defined(PROTOTYPES) || defined(__STDC_) || defined(__cplusplus) )
103# define __P(protos) protos
104#else
105# define __P(protos) ()
106#endif
107
108/*
109 * @def CONST
110 * Used to define constants.
111 *
112 * For ANSI C compilers this expands to const, for others its an empty definition.
113 * @note AC_C_CONST defines const empty if it is not supported.
114 */
115#undef CONST
116
117#ifndef const
118#  if (defined(__STDC__) || defined(PROTOTYPES) || defined(__cplusplus))
119#    define CONST const
120#  else
121#    define CONST
122#  endif
123#else
124#  define CONST
125#endif
126
127/**
128 * @defgroup constants Constants
129 * @{
130 */
131
132/**
133 * @enum sqlo_status_codes
134 * Constants defining the return codes of the functions.
135 *
136 * These codes map basically to the OCI return codes.
137 */
138enum sqlo_status_codes {
139  SQLO_SUCCESS             = 0,   /**< General success code (maps to OCI_SUCCESS) */
140  SQLO_ERROR               = -1,      /**< General error code (maps to OCI_ERROR) */
141  SQLO_INVALID_HANDLE      = -2,                  /**< Maps to OCI_INVALID_HANDLE */
142  SQLO_STILL_EXECUTING     = -3123,              /**< Maps to OCI_STILL_EXECUTING */
143  SQLO_CONTINUE            = -24200,                    /**< Maps to OCI_CONTINUE */
144  SQLO_SUCCESS_WITH_INFO   = 1,                /**< Maps to OCI_SUCCESS_WITH_INFO */
145  SQLO_NEED_DATA           = 99,                       /**< Maps to OCI_NEED_DATA */
146  SQLO_NO_DATA             = 100                         /**< Maps to OCI_NO_DATA */
147};
148
149/**
150 * @enum sqlo_error_codes
151 * Constants defining error codes returned by the library
152 *
153 * All Error codes are < -30000 to be seperated from the oracle error space.
154 */
155enum sqlo_error_codes {
156  SQLO_ERROR_BASE          = -30000,     /**< All our codes are below this value */
157  SQLO_INVALID_DB_HANDLE   = (SQLO_ERROR_BASE - 1),      /**< Invalid dbh passed */
158  SQLO_ERRMALLOC           = (SQLO_ERROR_BASE - 2),  /**< Cannot allocate memory */
159  SQLO_INVALID_STMT_HANDLE = (SQLO_ERROR_BASE - 3), /**< Invalid statement handle passed*/
160  SQLO_STMT_NOT_OPENED     = (SQLO_ERROR_BASE - 4), /**< Tried to reopen a not opened
161                                                       cursor in @ref sqlo_reopen */
162  SQLO_INVALID_STMT_TYPE   = (SQLO_ERROR_BASE - 5), /**< Tried to parse a PL/SQL block
163                                                       with @ref sqlo_open */
164  SQLO_STMT_NOT_PARSED     = (SQLO_ERROR_BASE - 6), /**< Tried to bind in/out variables
165                                                       for a non-parsed statement */
166  SQLO_INVALID_OCI_HANDLE_TYPE = (SQLO_ERROR_BASE - 7), /**< Passed a wrong handle type
167                                                           to @ref sqlo_get_oci_handle */
168  SQLO_MALFORMED_VERSION_STR = (SQLO_ERROR_BASE - 8), /**< Passed an invalid version
169                                                         string to @ref sqlo_version */
170  SQLO_WRONG_VERSION       = (SQLO_ERROR_BASE - 9), /**< The version of the library does
171                                                      not match your request */
172  SQLO_INVALID_COLPOS      = (SQLO_ERROR_BASE - 10) /**< Column position passed to a function is wrong */
173};
174
175/**
176 * @enum sqlo_constants
177 * Some constants used to pass to the functions.
178 */
179enum sqlo_constants {
180  SQLO_OFF                 =  0, /**< use this to switch something off */
181  SQLO_ON                  =  1, /**< use this to switch someting on */
182  SQLO_NULL_IND            = -1, /**< NULL indicator */
183  SQLO_NOT_NULL_IND        =  0, /**< NOT NULL indicator */
184  SQLO_STH_INIT            = -1, /**< You must init the sth with this before the
185                                    first call of @ref sqlo_open2 */
186
187  /* constants for piece operations (lob writes). */
188  SQLO_ONE_PIECE           = 0, /**< Piecewise operation code in
189                                   @ref sqlo_lob_write_buffer  */
190  SQLO_FIRST_PIECE         = 1, /**< Piecewise operation code in
191                                   @ref sqlo_lob_write_buffer  */
192  SQLO_NEXT_PIECE          = 2, /**< Piecewise operation code in
193                                   @ref sqlo_lob_write_buffer  */
194  SQLO_LAST_PIECE          = 3 /**< Piecewise operation code in
195                                  @ref sqlo_lob_write_buffer  */
196 
197};
198
199/**
200 * @enum sqlo_data_types
201 * The data types for bind variables
202 * The oracle constants are copied from $ORACLE_HOME/rdbms/demo/ocidfn.h
203 * @note Not all datatypes are implemented in this module (especially exotic
204 * ones)
205 * @see sqlo_bind_by_name sqlo_bind_by_pos sqlo_defined_by_pos
206 */
207enum sqlo_data_types {
208  SQLOT_CHR  = 1,                      /**< (ORANET TYPE) character string */
209  SQLOT_NUM  = 2,                        /**< (ORANET TYPE) oracle numeric */
210  SQLOT_INT  = 3,                               /**< (ORANET TYPE) integer */
211  SQLOT_FLT  = 4,                 /**< (ORANET TYPE) Floating point number */
212  SQLOT_STR  = 5,                              /**< zero terminated string */
213  SQLOT_VNU  = 6,                      /**< NUM with preceding length byte */
214  SQLOT_PDN  = 7,                /**< (ORANET TYPE) Packed Decimal Numeric */
215  SQLOT_LNG  = 8,                                                /**< long */
216  SQLOT_VCS  = 9,                           /**< Variable character string */
217  SQLOT_NON  = 10,                    /**< Null/empty PCC Descriptor entry */
218  SQLOT_RID  = 11,                                              /**< rowid */
219  SQLOT_DAT  = 12,                              /**< date in oracle format */
220  SQLOT_VBI  = 15,                               /**< binary in VCS format */
221  SQLOT_BIN  = 23,                                /**< binary data(DTYBIN) */
222  SQLOT_LBI  = 24,                                        /**< long binary */
223  SQLOT_UIN  = 68,                                   /**< unsigned integer */
224  SQLOT_SLS  = 91,                      /**< Display sign leading separate */
225  SQLOT_LVC  = 94,                                /**< Longer longs (char) */
226  SQLOT_LVB  = 95,                                 /**< Longer long binary */ 
227  SQLOT_AFC  = 96,                                    /**< Ansi fixed char */
228  SQLOT_AVC  = 97,                                      /**< Ansi Var char */
229  SQLOT_CUR  = 102,                                      /**< cursor  type */
230  SQLOT_RDD  = 104,                                  /**< rowid descriptor */
231  SQLOT_LAB  = 105,                                        /**< label type */
232  SQLOT_OSL  = 106,                                      /**< oslabel type */
233  SQLOT_NTY  = 108,                                 /**< named object type */
234  SQLOT_REF  = 110,                                          /**< ref type */
235  SQLOT_CLOB = 112,                                     /**< character lob */
236  SQLOT_BLOB = 113,                                        /**< binary lob */
237  SQLOT_BFILEE = 114,                                 /**< binary file lob */
238  SQLOT_CFILEE = 115,                              /**< character file lob */
239  SQLOT_RSET = 116,                                   /**< result set type */
240  SQLOT_NCO  = 122,    /**< named collection type (varray or nested table) */
241  SQLOT_VST  = 155,                                    /**< OCIString type */
242  SQLOT_ODT  = 156,                                      /**< OCIDate type */
243
244/* datetimes and intervals */
245  SQLOT_DATE                   = 184,                      /**< ANSI Date */
246  SQLOT_TIME                   = 185,                           /**< TIME */
247  SQLOT_TIME_TZ                = 186,            /**< TIME WITH TIME ZONE */
248  SQLOT_TIMESTAMP              = 187,                      /**< TIMESTAMP */
249  SQLOT_TIMESTAMP_TZ           = 188,       /**< TIMESTAMP WITH TIME ZONE */
250  SQLOT_INTERVAL_YM            = 189,         /**< INTERVAL YEAR TO MONTH */
251  SQLOT_INTERVAL_DS            = 190,         /**< INTERVAL DAY TO SECOND */
252  SQLOT_TIMESTAMP_LTZ          = 232         /**< TIMESTAMP WITH LOCAL TZ */
253};
254
255/* cxcheng: this has been added for backward compatibility -
256   it needs to be here because ocidfn.h can get included ahead of sqldef.h */
257#define SQLOT_FILE SQLOT_BFILEE                              /* binary file lob */
258#define SQLOT_CFILE SQLOT_CFILEE
259#define SQLOT_BFILE SQLOT_BFILEE
260
261/**
262 * @enum sqlo_statement_states
263 * Possible statement states returned by @ref sqlo_get_stmt_state.
264 */
265enum sqlo_statement_states {
266  SQLO_STMT_STATE_INITIALIZED = 1, /**< Statement initialized */
267  SQLO_STMT_STATE_EXECUTED    = 2, /**< Statement executed */
268  SQLO_STMT_STATE_END_OF_FETCH = 3 /**< Statement end of fetch reached */
269};
270
271/** @} */
272
273/**
274 * @defgroup typedefs Typedefs
275 * @{
276 */
277
278/**
279 * A database handle type.
280 */
281typedef int sqlo_db_handle_t;
282
283/**
284 * A statement handle type.
285 */
286typedef int sqlo_stmt_handle_t;
287
288/**
289 * Oracle OCI Handle types used by @ref sqlo_get_oci_handle
290 */
291typedef enum {
292  SQLO_OCI_HTYPE_ENV     = 1,   /**< Environment handle */
293  SQLO_OCI_HTYPE_ERROR   = 2,   /**< Error handle */
294  SQLO_OCI_HTYPE_SVCCTX  = 3,   /**< Service context handle */
295  SQLO_OCI_HTYPE_SERVER  = 4,   /**< Server handle */
296  SQLO_OCI_HTYPE_SESSION = 5,   /**< Session handle */
297  SQLO_OCI_HTYPE_STMT    = 6    /**< Statement handle  */
298} sqlo_oci_handle_types_e;
299
300
301/**
302 * @typedef (void*) sqlo_lob_desc_t
303 * LOB descriptor type
304 * Hides the Oracle type OCILobLocator*
305 */
306typedef void * sqlo_lob_desc_t;
307
308
309
310/** @} */
311
312/*-------------------------------------------------------------------------
313 * Version Information
314 *-----------------------------------------------------------------------*/
315/**
316 * @defgroup exvars  Exported Variables
317 * @{
318 */
319
320/**
321 * @var sqlo_major_version
322 * The major version of the library
323 */
324extern CONST unsigned sqlo_major_version;
325/**
326 * @var sqlo_minor_version
327 * The minor version of the library
328 */
329extern CONST unsigned sqlo_minor_version;
330/**
331 * @var sqlo_micro_version
332 * The micro version of the library
333 */
334extern CONST unsigned sqlo_micro_version;
335/**
336 * @var sqlo_interface_age
337 * The interface age used by libtool
338 */
339extern CONST unsigned sqlo_interface_age;
340/**
341 * @var sqlo_binary_age
342 * The binary age used by libtool
343 */
344extern CONST unsigned sqlo_binary_age;
345
346/* to keep backward compatibility with <= 2.2, otherwise we break too much */
347extern CONST unsigned sqlora8_major_version;
348extern CONST unsigned sqlora8_minor_version;
349extern CONST unsigned sqlora8_micro_version;
350extern CONST unsigned sqlora8_interface_age;
351extern CONST unsigned sqlora8_binary_age;
352#define SQLORA8_MAJOR_VERSION LIBSQLORA8_MAJOR_VERSION
353#define SQLORA8_MINOR_VERSION LIBSQLORA8_MINOR_VERSION
354#define SQLORA8_MICRO_VERSION LIBSQLORA8_MICRO_VERSION
355
356/* @} */
357
358/**
359 * @def SQLORA8_CHECK_VERSION
360 * A macro used during compile time to check the version
361 * This macro is used during the configure process of your program to check
362 * for the right version. Used in libsqlora8.m4
363 */
364#define SQLORA8_CHECK_VERSION(major,minor,micro)    \
365    (LIBSQLORA8_MAJOR_VERSION > (major) || \
366     (LIBSQLORA8_MAJOR_VERSION == (major) && LIBSQLORA8_MINOR_VERSION > (minor)) || \
367     (LIBSQLORA8_MAJOR_VERSION == (major) && LIBSQLORA8_MINOR_VERSION == (minor) && \
368      LIBSQLORA8_MICRO_VERSION >= (micro)))
369
370
371
372/*-------------------------------------------------------------------------
373 * FUNCTION DECLARATIONS
374 *-----------------------------------------------------------------------*/
375__BEGIN_DECLS
376
377/**
378 * @defgroup init Initialization
379 * @{
380 */
381
382/**
383 * Init the library.
384 *
385 * Reads the environment and sets up the global variables for trace-level/-file,
386 * and arraysize. Initializes the OCI library.
387 * This is the first function you should call, before you use the library. Make
388 * sure you call it only once!
389 *
390 * @param threaded_mode  I - SQLO_ON threading enabled, SQLO_OFF threading disabled.
391 * @param max_db         I - The maximum number of parallel connections
392 * @param max_cursors    I - The maximum number of cursors across all connections
393 *
394 * @return <ul>
395 * <li> SQLO_SUCCESS
396 * <li> < 0 on error
397 * </ul>
398 * @par Example:
399 * @include examples.c
400 */
401int sqlo_init __P((int threaded_mode, unsigned int max_db, unsigned int max_cursors));
402
403/**
404 * Checks if the version is sufficient
405 *
406 * You can use this during runtime, to check if the dynamic linker did
407 * a good job and linked you to the right version.
408 *
409 * @param version_str  I - The minimum version in the format major.minor.micro
410 *
411 * @return <ul>
412 * <li>SQLO_SUCCESS
413 * <li>SQLO_WRONG_VERSION
414 * <li>SQLO_MALFORMED_VERSION_STR
415 * </ul>
416 */
417int sqlo_version __P((CONST char * version_str));
418
419/** @} */
420
421/**
422 * @defgroup error Error handling functions
423 * @{
424 */
425
426/**
427 * Return last error string
428 *
429 * @param dbh I - A database handle
430 *
431 * @return A string containing the last error message for this dbh
432 */
433CONST char * sqlo_geterror __P(( sqlo_db_handle_t dbh ));
434
435/**
436 * Return the last error code
437 *
438 * @param dbh I - A database handle
439 *
440 * @return The last error code for this dbh.
441 */
442int sqlo_geterrcode __P(( sqlo_db_handle_t dbh ));
443
444/** @} */
445
446/**
447 * @defgroup easy The easy interface
448 * Functions in this group use basically bind variables passed as strings in
449 * an argv. The query results are also converted to strings.
450 *
451 * @{ */
452
453/**
454 * Tests if a value exists in a table.
455 *
456 * Tests if a record exists in a table where field = value [AND where].
457 *
458 * @param dbh     I - A database handle
459 * @param table   I - A table name
460 * @param colname I - A column name
461 * @param colval  I - A column value
462 * @param where   I - More conditions (optional)
463 *
464 * @return <ul>
465 * <li>SQLO_SUCCESS
466 * <li>SQLO_NO_DATA
467 * <li> < 0 on error.
468 * </ul>
469 * @par Example:
470 * @include ex1.c
471 */
472int sqlo_exists __P(( sqlo_db_handle_t dbh, 
473                      CONST char * table, 
474                      CONST char * colname,
475                      CONST char * colval, 
476                      CONST char * where ));
477/**
478 * Counts the number of items in the table.
479 *
480 * Counts the number of items where field = value [AND where]
481 *
482 * @param dbh     I - A database handle
483 * @param table   I - A table name
484 * @param colname I - A column name
485 * @param colval  I - A column value
486 * @param where   I - More conditions (optional)
487 *
488 * @return <ul>
489 * <li>SQLO_SUCCESS
490 * <li>SQLO_NO_DATA
491 * <li> < 0 on error
492 * </ul>
493 * @par Example:
494 * @include ex2.c
495 */
496int sqlo_count __P((sqlo_db_handle_t dbh,
497                    CONST char * table,
498                    CONST char * colname,
499                    CONST char * colval,
500                    CONST char * where ));
501
502/**
503 * Run a simple sql statements with parameters
504 *
505 * Like @ref sqlo_exec, but with bind parameters.
506 * This is basically the same as calling @ref sqlo_open followed by @ref sqlo_fetch and
507 * @ref sqlo_close.
508 *
509 * @param dbh   I - A database handle
510 * @param stmt  I - A sql statement (non-query).
511 * @param argc  I - Number of arguments in argv.
512 * @param argv  I - The arguments
513 *
514 * @return <ul>
515 * <li>The number of processed rows.
516 * <li>SQLO_STILL_EXECUTING in non-blocking mode.
517 * <li> < 0 on error.
518 * </ul>
519 * @par Example:
520 * @include ex3.c
521 */
522int sqlo_run __P(( sqlo_db_handle_t dbh, CONST char * stmt, int argc, CONST char ** argv));
523
524
525/**
526 * Open a new cursor
527 *
528 * This function opens a new cursor for a query statement.
529 *
530 * If the stmt is a SELECT statement, the function sets the attribute
531 * OCI_ATTR_PREFETCH rows to the max arraysize parameter of the library.
532 * This is a kind of internal array fetch Oracle provides to speed up the fetching.
533 *
534 * @deprecated  For new developments please use @ref sqlo_open2
535 * @param dbh  I - A database handle
536 * @param stmt I - A sql statement
537 * @param argc I - Number of arguments in argv
538 * @param argv I - Arguments
539 *
540 * @return <ul>
541 * <li>A statement handle
542 * <li> < 0 on error
543 * </ul>
544 * @par Example:
545 * @include ex4.c
546 *
547 * @see sqlo_open2, sqlo_fetch, sqlo_values, sqlo_close
548 */
549sqlo_stmt_handle_t sqlo_open __P((sqlo_db_handle_t dbh, 
550                                  CONST char * stmt, 
551                                  int argc, 
552                                  CONST char ** argv));
553
554/**
555 * Open a new cursor
556 *
557 * This function opens a new cursor for a query statement.
558 * Use this function if your bind variables are all strings.
559 * If you need native datatype support, use @ref sqlo_prepare
560 *
561 * If the stmt is a SELECT statement, the function sets the attribute
562 * OCI_ATTR_PREFETCH rows to the max arraysize parameter of the library.
563 * This is a kind of internal array fetch Oracle provides to speed up the fetching.
564 *
565 * @attention You have to init the passed statement handle with SQLO_STH_INIT.
566 * This is required escpecially in non-blocking mode.
567 *
568 * @param sthp I/O - Returns the new sth in *sthp.
569 * @param dbh  I - A database handle
570 * @param stmt I - A sql statement
571 * @param argc I - Number of arguments in argv
572 * @param argv I - Arguments
573 *
574 * @return <ul>
575 * <li>SQLO_SUCCESS
576 * <li>SQLO_STILL_EXECUTING in non-blocking mode
577 * <li> < 0 on error
578 * </ul>
579 * @par Example:
580 * @include ex5.c
581 *
582 * @see sqlo_fetch, sqlo_values, sqlo_close
583 * @since Version 2.2
584 */
585int sqlo_open2 __P((sqlo_stmt_handle_t * sthp, 
586                    sqlo_db_handle_t dbh, 
587                    CONST char * stmt, 
588                    int argc, 
589                    CONST char ** argv));
590
591/**
592 * Reopens a already used cursor
593 *
594 * This function reopens an already used cursor with new bind variables.
595 * Reopening cursors improve the speed, because no new parse is necessary.
596 *
597 * @param sth  I - The sth you want to rebind.
598 * @param argc I - Number of arguments in argv
599 * @param argv I - Arguments
600 *
601 * @return <ul>
602 * <li>SQLO_SUCCESS
603 * <li>SQLO_STILL_EXECUTING in non-blocking mode
604 * <li> < 0 on error
605 * </ul>
606 *
607 * @par Example:
608 * @anchor ex6
609 * @include ex6.c
610 *
611 * @see sqlo_open2, sqlo_fetch, sqlo_values, sqlo_close
612 */
613int sqlo_reopen __P((sqlo_stmt_handle_t sth, 
614                     int argc, 
615                     CONST char ** argv));
616
617/**
618 * Fetches the data from an open cursor.
619 *
620 * This functions fetches data from an open cursor, if the sql was a query.
621 * For non-queries, the statement is executed. Use @ref sqlo_values to get the
622 * data.
623 * @attention nrows must be 1 for cursors opened with @ref sqlo_open or @sqlo_open2.
624 * For cursors where the output variables were defined manually with @sqlo_define_by_pos,
625 * this can be for example the size of the array in which you are fetching.
626 *
627 * @param sth   I - A statement handle
628 * @param nrows I - The number of rows to fetch.
629 *
630 * @return <ul>
631 * <li>SQLO_SUCCESS
632 * <li>SQLO_NO_DATA
633 * <li>< 0 on error
634 * </ul>
635 *
636 * @par Example:
637 * See @ref ex7 "sqlo_values".
638 *
639 * @see sqlo_open2, sqlo_values, sqlo_close
640 */
641int sqlo_fetch __P((sqlo_stmt_handle_t sth, unsigned int nrows));
642
643/**
644 * Get one dataset
645 *
646 * Returns the data for one set of data fetched via @ref sqlo_fetch.
647 *
648 * @param sth I - A statement handle
649 * @param num O - A destination where the function could write the size of the
650 *                returned array (optional)
651 * @param dostrip I - A flag indicating whether trailing blanks should be stripped
652 *                    off (leading blanks in case of numbers).
653 *
654 * @return A pointer to an array of strings containing the data values
655 *
656 * @par Example:
657 * @anchor ex7
658 * @include ex7.c
659 *
660 * @see sqlo_fetch, sqlo_value_lens, sqlo_open, sqlo_close.
661 */
662CONST char **sqlo_values __P(( sqlo_stmt_handle_t sth, int * num, int dostrip ));
663
664/**
665 * Get the length of the returned values
666 *
667 * Returns the length in number of characters (bytes for non-unicode chars)
668 * for a dataset fetched by sqlo_fetch.
669 *
670 * @param sth I - A statement handle
671 * @param num O - A destination where the function can write the size of the returned
672 * array (optional).
673 *
674 * @return A pointer to an array of unsigned shorts containing the lengths
675 *
676 * @par Example:
677 * See @ref ex7 "sqlo_values".
678 *
679 * @see sqlo_fetch, sqlo_values, sqlo_open2, sqlo_close.
680 */
681CONST unsigned short * sqlo_value_lens __P(( sqlo_stmt_handle_t sth, int * num));
682
683/**
684 * Get the select list columns
685 *
686 * Use this function to get the select list column names.
687 * Most usefull for dynamic sql, where you don't know the sql statement at all.
688 *
689 * @param sth I - A statement handle
690 * @param num O - A destination where the function can write the size of the returned
691 * array (optional).
692 *
693 * @return A pointer to an array of strings containing the column names
694 *
695 * Example:
696 * See @ref ex7 "sqlo_values".
697 *
698 * @see sqlo_fetch, sqlo_values, sqlo_open2, sqlo_close, sqlo_ocol_name_lens.
699 */
700CONST char **sqlo_ocol_names __P(( sqlo_stmt_handle_t sth, int * num));
701
702
703/**
704 * Get the select list columns name lengths
705 *
706 * Use this function to get the length of each select list column.
707 * Call this when you need the length of the column, for formatting purposes etc.
708 *
709 * @param sth I - A statement handle
710 * @param num O - A destination where the function can write the size of the returned
711 * array.
712 *
713 * @return A pointer to an array of integers containing the lengths
714 *
715 * @par Example:
716 * See @ref ex7 "sqlo_values".
717 *
718 * @see sqlo_ocol_names, sqlo_fetch, sqlo_open2, sqlo_close.
719 */
720CONST int *sqlo_ocol_name_lens __P(( sqlo_stmt_handle_t sth, int * num));
721
722/**
723 * Get the number of bind/select-list variables
724 *
725 * @param sth I - A statement handle
726 * @param in  I - 1 returns the number of bind variables, 0 returns the number of
727 *                select list columns.
728 *
729 * @return <ul>
730 * <li>The number of columns
731 * <li>SQLO_INVALID_STMT_HANDLE
732 * </ul>
733 */
734int sqlo_ncols __P((sqlo_stmt_handle_t sth, int in));
735
736/**
737 * Return the sql command
738 *
739 * @return The active sql statement of the sth.
740 *
741 * @param sth I - A statement handle
742 */
743CONST char *sqlo_command __P(( sqlo_stmt_handle_t sth ));
744
745/**
746 * Close the cursor
747 *
748 * Closes the cursor and releases the Oracle statement handle.
749 *
750 * @return <ul>
751 * <li>SQLO_SUCCESS
752 * <li>< 0 on error
753 * </ul>
754 * @par Example:
755 * See @ref ex7 "sqlo_values".
756 *
757 * @see sqlo_open.
758 *
759 */
760int sqlo_close __P(( sqlo_stmt_handle_t sth ));
761
762/**
763 * Execute a simple sql statement
764 *
765 * Use this to execute non-qeuery statements without bind variables.
766 *
767 * @param dbh A database handle
768 * @param stmt A sql statement
769 *
770 * @return The number of processed rows (DML statements), 0 (non DML statements)
771 *         or < 0 on error.
772 *
773 * @par Example:
774 * @include ex8.c
775 *
776 * @see sqlo_run
777 */
778int sqlo_exec __P(( sqlo_db_handle_t dbh, CONST char * stmt ));
779
780
781
782/**
783 * Test if a cursor is open
784 *
785 * @param sth  I - A statement handle.
786 *
787 * @return <ul>
788 * <li>SQLO_SUCCESS  if the cursor is open
789 * <li>1 if not (unused sth)
790 * <li>SQLO_INVALID_STMT_HANDLE.
791 * </ul>
792 * @see sqlo_open2
793 */
794int sqlo_isopen __P((sqlo_stmt_handle_t sth));
795
796/**
797 * Return the number of processed rows by this statement
798 *
799 * @param sth I - A statement handle
800 *
801 * @return <ul>
802 * <li>Number of processed rows
803 * <li> 0 if it is not a dml statement
804 * <li> < 0 on error
805 * </ul>
806 * @par Example:
807 * See @ref ex12 "sqlo_define_by_pos2".
808 *
809 */
810int sqlo_prows __P(( sqlo_stmt_handle_t sth ));
811
812/** @} */
813
814
815/**
816 * @defgroup loginout Functions to do login/logout to/from a database
817 * @{
818 */
819
820/**
821 * Connect to a database
822 *
823 * This is the short form of @ref sqlo_server_attach followed by @ref sqlo_session_begin
824 *
825 * @param dbhp        O - The database handle
826 * @param cstr        I - A Oracle connect string.
827 *
828 * @return <ul>
829 * <li>SQLO_SUCCESS
830 * <li> < 0 on error
831 * </ul>
832 *
833 * @par Example:
834 * @include examples.c
835 * @see sqlo_finish, sqlo_server_attach, sqlo_session_begin
836 */
837int sqlo_connect __P(( sqlo_db_handle_t * dbhp, CONST char * cstr ));
838
839
840/**
841 * Finish the session
842 *
843 * Finish the session with implicit commit.
844 * This is the short form of @ref sqlo_session_end followed by @ref sqlo_server_detach.
845 *
846 * @param dbh I - A database handle
847 *
848 * @return <ul>
849 * <li>SQLO_SUCCESS
850 * <li> < 0 on error
851 * </ul>
852 *
853 * @see sqlo_connect, sqlo_session_end, sqlo_server_detach, sqlo_server_attach
854 */
855int sqlo_finish __P((sqlo_db_handle_t dbh ));
856
857/**
858 * Split an Oracle connect string
859 *
860 * Splits an Oracle connect string of the form uid[[/pwd]@tnsname] into its
861 * components. If no tnsname is found in the cstr, we copy the value of the
862 * env. variable ORACLE_SID into tnsname.
863 *
864 * @param cstr     I - A connect string to split
865 * @param uid      O - The returned uid part.
866 * @param pwd      O - The returned pwd part.
867 * @param tnsname  O - The returned tnsname.
868 * @param bufsize  I - The capacity of the output buffers.
869 *
870 * @return <ul>
871 * <li>SQLO_SUCCESS
872 * <li> SQLO_ERROR (buffer too small)
873 * </ul>
874 * @since Version 2.2
875 */
876int sqlo_split_cstring __P((CONST char * cstr, 
877                            char * uid, 
878                            char * pwd, 
879                            char * tnsname, 
880                            unsigned int bufsize));
881
882/**
883 * Attach to a database server
884 *
885 * Attaches to a database without creating a session.
886 * tnsname can be a database name or a connect string. The function extracts
887 * the database name. If no database name is supplied, the function attaches
888 * to the database given in the env. variable ORACLE_SID.
889 *
890 * @param dbhp    O - The database handle
891 * @param tnsname O - The tnsname or the complete Oracle connect string.
892 *
893 * @return <ul>
894 * <li>SQLO_SUCCESS
895 * <li> < 0 on error
896 * </ul>
897 *
898 * @see sqlo_session_begin, sqlo_server_detach
899 * @since Version 2.2
900 */
901int sqlo_server_attach __P((sqlo_db_handle_t * dbhp, CONST char * tnsname));
902
903/**
904 * Begin a session
905 *
906 * Do the login to an attached server.
907 * You can either pass username and password seperatly, or pass the complete
908 * connect string in username.
909 *
910 * @param dbh      I - A database handle
911 * @param username I - The username for authentication, or a complete Oracle
912 *                     connect string.
913 * @param password I - The password for authentication
914 *
915 * @return <ul>
916 * <li>SQLO_SUCCESS
917 * <li> < 0 on error
918 * </ul>
919 *
920 * @see sqlo_server_attach, sqlo_session_end
921 * @since Version 2.2
922 */
923int sqlo_session_begin __P((sqlo_db_handle_t dbh, CONST char * username, CONST char * password));
924
925/**
926 * Detach from server.
927 *
928 * Closes all open sessions and detaches from the server.
929 *
930 *
931 * @param dbh I - A database handle
932 *
933 * @return <ul>
934 * <li>SQLO_SUCCESS
935 * <li> < 0 on error
936 * </ul>
937 *
938 * @see sqlo_server_attach
939 * @since Version 2.2
940 */
941int sqlo_server_detach __P((sqlo_db_handle_t dbh));
942
943/**
944 * End a session
945 *
946 * Does a logout, but does not detach from the server. It is possible to create a
947 * new session via @ref sqlo_session_begin.
948 *
949 * @attention Closing a session this way, means also to close all the cursors.
950 * Oracle is doing an implicit commit. This is maybe not be what you want.
951 *
952 * @param dbh I - A database handle
953 *
954 * @return <ul>
955 * <li>SQLO_SUCCESS
956 * <li> < 0 on error
957 * </ul>
958 *
959 * @see sqlo_session_begin
960 * @since Version 2.2
961 */
962int sqlo_session_end __P((sqlo_db_handle_t dbh));
963
964
965/**
966 * Returns the tnsname
967 *
968 * Returns the tnsname (or service name) of the given dbh.
969 * @attention The function returns the database name passed to
970 * @ref sqlo_connect or @ref sqlo_server_attach,
971 * not the real SID, which can be different!
972 *
973 * @param dbh I - A database handle
974 *
975 * @return The tnsname or NULL in case of an invalid dbh
976 */
977CONST char * sqlo_getdatabase __P((sqlo_db_handle_t dbh ));
978
979/** @} */
980
981/**
982 * @defgroup transactions Transaction control functions
983 * @{
984 */
985
986/**
987 * Commit
988 *
989 * Execute a commit on this database.
990 *
991 * @param dbh I - A database handle.
992 *
993 * @return <ul>
994 * <li>SQLO_SUCCESS
995 * <li> < 0 on error
996 * </ul>
997 *
998 */
999int sqlo_commit __P((sqlo_db_handle_t dbh));
1000
1001/**
1002 * Rollback
1003 *
1004 * Execute a rollback on this database.
1005 *
1006 * @param dbh I - A database handle.
1007 *
1008 * @return <ul>
1009 * <li>SQLO_SUCCESS
1010 * <li> < 0 on error
1011 * </ul>
1012 *
1013 */
1014int sqlo_rollback __P((sqlo_db_handle_t dbh));
1015/** @} */
1016
1017/**
1018 * @defgroup complex The advanced interface.
1019 *
1020 * This functions offer more flexibility in terms of
1021 * datatypes, but they need (much) more parameters.
1022 * Use these functions if you want to execute PL/SQL or stored procedures.
1023 *
1024 * @{
1025 */
1026
1027/**
1028 * Parse a statement
1029 *
1030 * This functions must be used to parse a statement if you want to bind manually
1031 * the parameters. By doing this you can use native datatypes.
1032 * This is the more complex form of @ref sqlo_open2.
1033 *
1034 * If the stmt is a SELECT statement, the function sets the attribute
1035 * OCI_ATTR_PREFETCH rows to the max arraysize parameter of the library.
1036 * This is a kind of internal array fetch Oracle provides to speed up the fetching.
1037 *
1038 * @param dbh  I - A database handle
1039 * @param stmt I - sql statement.
1040
1041 * @return <ul>
1042 * <li>A new statement handle
1043 * <li> < 0 on error.
1044 * </ul>
1045 * @par Example:
1046 * See @ref ex9 "sqlo_bind_by_name".
1047 *
1048 * @see sqlo_bind_by_name, sqlo_bind_by_pos, sqlo_define_by_pos, sqlo_open2.
1049 */
1050int sqlo_prepare __P((sqlo_db_handle_t dbh, CONST char * stmt));
1051
1052/**
1053 * Bind a variable by name
1054 *
1055 * Use this to bind a variable in a query or a stored procedure call.
1056 *
1057 * If is_array is 1, the parameters param_addr and ind_addr must point to arrays.
1058 * ind_addr is optional and can be passed a NULL.
1059 * The param_size is still the size of one array element, not the whole array size!
1060 *
1061 * @param sth        I - The statement handle.
1062 * @param name       I - The bind parameter name.
1063 * @param param_type I - The datatype of the bind parameter (see @ref sqlo_data_types).
1064 * @param param_addr I - The address of a variable or array.
1065 * @param param_size I - The size of the object at param_addr in bytes.
1066 * @param ind_addr   I - The pointer to the NULL indicator variable (optional).
1067 * @param is_array   I - 1 means param_addr points to an array, 0 means a single variable.
1068 *
1069 * @return <ul>
1070 * <li>SQLO_SUCCESS
1071 * <li> < 0 on error
1072 * </ul>
1073 *
1074 * @par Example:
1075 * @anchor ex9
1076 * @include ex9.c
1077 *
1078 * @see sqlo_prepare, sqlo_bind_by_pos, sqlo_define_by_pos
1079 */
1080int sqlo_bind_by_name __P((sqlo_stmt_handle_t sth, 
1081                           CONST char * name, 
1082                           int param_type, 
1083                           CONST void * param_addr, 
1084                           unsigned int param_size, 
1085                           short * ind_addr, 
1086                           int is_array));
1087
1088/**
1089 * Bind a REF CURSOR
1090 *
1091 * Binds a ref cursor and returns a new sth, which you can use to retrieve
1092 * the data.
1093 * @note You can also use @ref sqlo_bind_by_name and supply as SQLOT_RSET as type
1094 * and the address of the new statement handle as param_addr. All other parameters
1095 * are ignored.
1096 *
1097 * @param sth         I - The statement handle
1098 * @param cursor_name I - The bind name of the cursor
1099 * @param sth2p       O - The new statement handle for the ref cursor.
1100 *
1101 * @par Example:
1102 * Example using sqlo_values to get the result:
1103 * @include ex17.c
1104 * Example using bind variables:
1105 * @include ex18.c
1106 */
1107int sqlo_bind_ref_cursor __P((sqlo_stmt_handle_t sth, CONST char * cursor_name, int * sth2p));
1108
1109/**
1110 * Bind a variable by position
1111 *
1112 * If is_array is 1, the parameters param_addr and ind_addr must point to arrays.
1113 * ind_addr is optional and can be passed a NULL.
1114 * The param_size is still the size of one array element, not the whole array size!
1115 *
1116 * @param sth        I - The statement handle
1117 * @param position   I - The bind parameter position in the string. Starts with
1118 *                       1 for the first.
1119 * @param param_type I - The datatype of the bind parameter (see @ref sqlo_data_types).
1120 * @param param_addr I - The pointer to the parameter data.
1121 * @param param_size I - The size of the object at param_addr in bytes.
1122 * @param ind_addr   I - The pointer to the NULL indicator variable (optional).
1123 * @param is_array   I - 1 means param_addr points to an array, 0 means a single variable.
1124 *
1125 * @return <ul>
1126 * <li>SQLO_SUCCESS
1127 * <li> < 0 on error
1128 * </ul>
1129 *
1130 * @par Example:
1131 * @include ex10.c
1132 * @see sqlo_prepare, sqlo_bind_by_name, sqlo_define_by_pos
1133 */
1134int sqlo_bind_by_pos __P((sqlo_stmt_handle_t sth, 
1135                          int position, 
1136                          int param_type, 
1137                          CONST void * param_addr, 
1138                          unsigned int param_size, 
1139                          short * ind_addr, 
1140                          int is_array));
1141
1142/**
1143 * Bind a variable by position
1144 *
1145 * Bind the input variables. This new version supports arrays of structures. Set
1146 * the skip_size to the size of the structure. rcode and ind must be part of
1147 * the structure.
1148 *
1149 * @param sth        I - The statement handle
1150 * @param position   I - The bind parameter position in the string. Starts with
1151 *                       1 for the first.
1152 * @param param_type I - The datatype of the bind parameter (@ref sqlo_data_types).
1153 * @param param_addr I - The pointer to the parameter data.
1154 * @param param_size I - The size of the object at param_addr in bytes.
1155 * @param ind_addr   I - The pointer to the NULL indicator variable (optional).
1156 * @param rcode_addr I - The pointer to the variable that should return the column level
1157 * @param skip_size  I - In case into an array of structures, set to sizeof(your_struct),
1158 *                       otherwise set it to 0.
1159 *
1160 * @return <ul>
1161 * <li>SQLO_SUCCESS
1162 * <li> < 0 on error
1163 * </ul>
1164 *
1165 * @see sqlo_prepare, sqlo_bind_by_name, sqlo_define_by_pos
1166 * @since Version 2.2
1167 */
1168int sqlo_bind_by_pos2 __P((sqlo_stmt_handle_t sth, 
1169                           int position, 
1170                           int param_type, 
1171                           CONST void * param_addr, 
1172                           unsigned int param_size, 
1173                           short * ind_addr,
1174                           unsigned short * rcode_addr, 
1175                           unsigned int skip_size));
1176
1177
1178/**
1179 * Define a output variable of the select list
1180 *
1181 * Use this to define the output variables.
1182 *
1183 * If is_array is 1, the parameters value_addr, rlen_addr and ind_addr must point to
1184 * arrays.
1185 * ind_addr is optional and can be passed a NULL. Passing NULL is only usefull for
1186 * NOT NULL columns. If you ommit the indicator and a NULL is fetched, @ref sqlo_execute
1187 * will fail with an Oracle error (FETCHED COLUMN VALUE IS NULL).
1188 *
1189 * The value_size is still the size of one array element, not the whole array size!
1190 *
1191 * @param sth         I - The statement handle
1192 * @param value_pos   I - The bind parameter position in the string. Starts with
1193 *                        1 for the first.
1194 * @param value_type  I - The datatype of the bind parameter (@ref sqlo_data_types).
1195 * @param value_addr  I - The pointer to the parameter data.
1196 * @param value_size  I - The size of the object at param_addr in bytes.
1197 * @param ind_addr    I - The pointer to the NULL indicator variable (optional).
1198 * @param rlen_addr   I - The pointer where @ref sqlo_execute writes the actual returned
1199 *                        length.
1200 * @param is_array   I - 1 means param_addr points to an array, 0 means a single variable.
1201 *
1202 * @return <ul>
1203 * <li>SQLO_SUCCESS
1204 * <li> < 0 on error
1205 * </ul>
1206 *
1207 * @par Example:
1208 * @include ex11.c
1209 *
1210 * @see sqlo_prepare, sqlo_bind_by_name, sqlo_define_by_pos
1211 */
1212int sqlo_define_by_pos __P((sqlo_stmt_handle_t sth, 
1213                            int value_pos, 
1214                            int value_type,
1215                            CONST void * value_addr,
1216                            unsigned int value_size,
1217                            short * ind_addr,
1218                            short * rlen_addr,
1219                            int is_array));
1220
1221/**
1222 * Define a output variable of the select list
1223 *
1224 * Use this to define where the result of the query should go.
1225 * This new version supports filling arrays of structures.
1226 * If skip_size is not 0, the parameter value_addr must point to an array of structures.
1227 * If used, the structure must contain variables for ind, rlen and rcode.
1228 *
1229 * The value_size is still the size of one array element, not the whole array size!
1230 *
1231 * @param sth        I - The statement handle
1232 * @param value_pos  I - The bind parameter position in the string.
1233 *                       Starts with 1 for the first.
1234 * @param value_type I - The datatype of the bind parameter (@ref sqlo_data_types).
1235 * @param value_addr I - The pointer to the parameter data.
1236 * @param value_size I - The size of the object at param_addr in bytes.
1237 * @param ind_addr   I - The pointer to the NULL indicator variable (optional).
1238 * @param rlen_addr  I - The pointer where library puts the actual return length.
1239 * @param rcode_addr I - The address where the library puts the return code for the column
1240 * @param skip_size  I - In case into an array of structures, set to sizeof(your_struct),
1241 *                       otherwise set it to 0.
1242 *
1243 * @return <ul>
1244 * <li>SQLO_SUCCESS
1245 * <li> < 0 on error
1246 * </ul>
1247 *
1248 * @par Example:
1249 * @anchor ex12
1250 * This is an example of a fetch into an array of structure.
1251 * @include ex12.c
1252 *
1253 * @see sqlo_prepare, sqlo_bind_by_name, sqlo_define_by_pos, sqlo_execute
1254 * @since Version 2.2
1255 */
1256int sqlo_define_by_pos2 __P((sqlo_stmt_handle_t sth, 
1257                             int value_pos, 
1258                             int value_type,
1259                             CONST void * value_addr,
1260                             unsigned int value_size,
1261                             short * ind_addr,
1262                             unsigned short * rlen_addr,
1263                             unsigned short * rcode_addr,
1264                             unsigned int skip_size));
1265
1266/**
1267 * Define a nested table
1268 * Please visit the example for details.
1269 * @note You can also use @ref sqlo_define_by_pos with type == SQLOT_RSET
1270 * and passing the address of the new sth as value_addr and set all other
1271 * parameters to 0.
1272 *
1273 * @param sth         I - The statement handle
1274 * @param pos         I - The define position of the nested table
1275 * @param sth2p       O - The new statement handle for the nested table.
1276 * @par Examples:
1277 * @include ex19.c
1278 */
1279int sqlo_define_ntable __P((sqlo_stmt_handle_t sth, unsigned int pos, int * sth2p));
1280
1281
1282/**
1283 * Execute a statement
1284 *
1285 * Execute a PL/SQL block or a statement after you prepared it with sqlo_prepare and bound input
1286 * and output variables.
1287 * If you are fetching into arrays, you can set iterations to the actual array
1288 * size. For PL/SQL blocks it must be set to 1.
1289 *
1290 * @param sth        I - A parsed statement handle
1291 * @param iterations I - How many times the statement should be exectuted.
1292 *                       Must be 1 if you execute a PL/SQL block
1293 *
1294 * @return <ul>
1295 * <li>SQLO_SUCCESS
1296 * <li>SQLO_NO_DATA
1297 * <li>SQLO_STILL_EXECUTING (non-blocking)
1298 * <li> < 0 on error
1299 * </ul>
1300 *
1301 * @par Example
1302 * See @ref ex12 "sqlo_define_by_pos2".
1303 *
1304 * @see sqlo_prepare, sqlo_define_by_pos, sqlo_define_by_pos2, sqlo_bind_by_name
1305 */
1306int sqlo_execute __P((sqlo_stmt_handle_t sth, unsigned int iterations));
1307
1308/** @} */
1309
1310/**
1311 * @defgroup lob Functions to insert/select LOBs
1312 *
1313 * @{
1314 */
1315
1316/**
1317 * Allocate a lob descriptor
1318 *
1319 * @param dbh    I - A database handle
1320 * @param loblpp O - The lob locator
1321 *
1322 * @return SQLO_SUCCESS or < 0 on error
1323 * @since Version 2.2
1324 */
1325int sqlo_alloc_lob_desc __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t *loblpp));
1326
1327/**
1328 * Free a lob descriptor
1329 *
1330 * Frees the descriptor and sets *loblp to NULL.
1331 *
1332 * @param dbh    I - A database handle
1333 * @param loblpp I/O - A address where we find the lob locator.
1334 *
1335 * @return <ul>
1336 * <li>SQLO_SUCCESS
1337 * <li> < 0 on error
1338 * </ul>
1339 * @since Version 2.2
1340 */
1341int sqlo_free_lob_desc __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t *loblpp));
1342
1343/**
1344 * Write lob data from buffer into the lob column
1345 *
1346 * @param dbh     I - A database handle.
1347 * @param loblen  I - The length of the lob.
1348 * @param loblp   I - A lob locator.
1349 * @param bufp    I - A buffer of data.
1350 * @param bufl    I - The length of the buffer in terms of bytes.
1351 * @param piece   I - The piece indicator
1352 *                    <ul>
1353 *                    <li>SQLO_ONE_PIECE
1354 *                    <li>SQLO_FIRST_PIECE
1355 *                    <li>SQLO_NEXT_PIECE
1356 *                    <li>SQLO_LAST_PIECE
1357 *                    </ul>
1358 *
1359 * @return <ul>
1360 *         <li>SQLO_SUCCESS
1361 *         <li>SQLO_STILL_EXECUTING
1362 *         <li>SQLO_ERROR
1363 *         </ul>
1364 * @since Version 2.2
1365 * @par Example:
1366 * @include ex13.c
1367 */
1368int sqlo_lob_write_buffer __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, unsigned int loblen, 
1369                               void *bufp, unsigned int bufl, unsigned int piece));
1370/**
1371 * Append lob data from buffer to the lob column
1372 *
1373 * @param dbh     I - A database handle.
1374 * @param loblen  I - The length of the lob.
1375 * @param loblp   I - A lob locator.
1376 * @param bufp    I - A buffer of data.
1377 * @param bufl    I - The length of the buffer in terms of bytes.
1378 * @param piece   I - The piece indicator
1379 *                    <ul>
1380 *                    <li>SQLO_ONE_PIECE
1381 *                    <li>SQLO_FIRST_PIECE
1382 *                    <li>SQLO_NEXT_PIECE
1383 *                    <li>SQLO_LAST_PIECE
1384 *                    </ul>
1385 *
1386 * @return <ul>
1387 *         <li>SQLO_SUCCESS
1388 *         <li>SQLO_STILL_EXECUTING
1389 *         <li>SQLO_ERROR (always when OCILobWriteAppend is not available in your Oracle version)
1390 *         </ul>
1391 * @since Version 2.2 and Oracle version >= 8.1
1392 * @par Example:
1393 * @include ex13.c
1394 */
1395int sqlo_lob_append_buffer __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, 
1396                                unsigned int loblen, 
1397                                void *bufp, unsigned int bufl, 
1398                                unsigned int piece));
1399
1400/**
1401 * Write lob data from a file into the lob column. This function reads the
1402 * data from the stream and writes it into the lob column via
1403 * @ref sqlo_lob_write_buffer.
1404 *
1405 * @attention The function does not close or rewind the fp.
1406 *
1407 * @param dbh     I - A database handle.
1408 * @param loblp   I - A lob locator.
1409 * @param filelen I - The size of the file (total lob length)
1410 * @param fp      I - The filepointer
1411 *
1412 * @return <ul>
1413 * <li>SQLO_SUCCESS
1414 * <li>SQLO_ERROR
1415 * </ul>
1416 * @since Version 2.2
1417 * @par Example:
1418 * @include ex14.c
1419 *
1420 * @see sqlo_lob_write_buffer
1421 */
1422int sqlo_lob_write_stream __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, unsigned int filelen, FILE * fp));
1423
1424
1425/**
1426 * Get the length of a lob
1427 *
1428 * @param dbh      I - Database handle
1429 * @param loblp    I - A lob descriptor
1430 * @param loblenp  O - The length of the lob
1431 *
1432 * @return <ul>
1433 * <li>SQLO_SUCCESS
1434 * <li>SQLO_STILL_EXECUTING
1435 * <li>SQLO_ERROR
1436 * </ul>
1437 */
1438int sqlo_lob_get_length __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, unsigned int * loblenp));
1439
1440/**
1441 * Read lob data from lob column into a buffer
1442 *
1443 * Reads data from the lob and writes it into the supplied buffer.
1444 *
1445 * Use @ref sqlo_lob_get_length to get the loblen you have to use here.
1446 *
1447 * @param dbh     I - A database handle.
1448 * @param loblp   I - A lob locator.
1449 * @param loblen  I - The length of the lob
1450 * @param bufp    O - The output data.
1451 * @param bufl    I - The capacity of the buffer in terms of bytes.
1452 *
1453 * @return <ul>
1454 * <li>SQLO_SUCCESS
1455 * <li>SQLO_NEED_DATA
1456 * <li>SQLO_STILL_EXECUTING
1457 * <li>SQLO_ERROR
1458 * </ul>
1459 *
1460 * @since Version 2.2
1461 * @par Example:
1462 * @include ex15.c
1463 */
1464int sqlo_lob_read_buffer __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, unsigned int loblen, void *bufp, unsigned int bufl));
1465
1466
1467/**
1468 * Read lob data from lob column into a stream
1469 *
1470 * Use @ref sqlo_lob_get_length to get the loblen you have to use here.
1471 *
1472 * @param dbh     I - A database handle.
1473 * @param loblp   I - A lob locator.
1474 * @param loblen  I - The length of the lob
1475 * @param fp      I - A filepointer
1476 *
1477 * @return <ul>
1478 * <li>SQLO_SUCCESS
1479 * <li>SQLO_STILL_EXECUTING
1480 * <li>SQLO_ERROR
1481 * </ul>
1482 * @since Version 2.2
1483 *
1484 * @par Example:
1485 * @include ex16.c
1486 *
1487 * @see sqlo_lob_read_buffer
1488 */
1489int sqlo_lob_read_stream __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, unsigned int loblen, 
1490                              FILE *fp));
1491/** @} */
1492
1493/**
1494 * @defgroup misc Miscellaneous functions
1495 * @{
1496 */
1497/**
1498 * Get the specified OCI handle
1499 *
1500 * You can get the oci handles here, if you want to call other OCI functions.
1501 *
1502 * @param sqloh I - Either a statement or a database handle depending on the handle type
1503 *                  you want to get.
1504 * @param ocihp O - The requested OCI handle.
1505 * @param type  I - The OCI handle type (see @ref sqlo_oci_handle_types_e)
1506 *
1507 * @return <ul>
1508 * <li>SQLO_SUCCESS
1509 * <li> < 0 on error
1510 * </ul>
1511 *
1512 * @see sqlo_oci_handle_types_e
1513 */
1514int sqlo_get_oci_handle __P((int sqloh, void * ocihp, sqlo_oci_handle_types_e type));
1515
1516/**
1517 * Return the database handle of a statement handle.
1518 *
1519 * @param sth  I - A statement handle
1520 * @return <ul>
1521 * <li>The database handle
1522 * <li> < 0 on error
1523 * </ul>
1524 */
1525int sqlo_get_db_handle __P((sqlo_stmt_handle_t sth));
1526
1527
1528/**
1529 * Set OCI blocking mode on/off.
1530 *
1531 * By default a database connection is in blocking mode. This means
1532 * the call does not return until the task is finished. With this
1533 * function you can change to non-blocking mode.
1534 * In this case some functions can return SQLO_STILL_EXECUTING.
1535 *
1536 * The functions are:
1537 * <ul>
1538 * <li>sqlo_open2 (when called for queries)
1539 * <li>sqlo_reopen (when called for queries)
1540 * <li>sqlo_fetch (when called for non-queries)
1541 * <li>sqlo_exec
1542 * <li>sqlo_execute
1543 * </ul>
1544 * @param dbh I - A database handle where the blocking should be changed.
1545 * @param on  I - SQLO_ON switches blocking mode on, SQLO_OFF switches to
1546 *                non-blocking mode
1547 * @return <ul>
1548 * <li>SQLO_SUCCESS
1549 * <li>SQLO_INVALID_DB_HANDLE
1550 * <li> < 0 on error
1551 * </ul>
1552 * @since Version 2.2
1553 */
1554int sqlo_set_blocking __P((sqlo_db_handle_t dbh, unsigned int on));
1555
1556
1557/**
1558 * Get OCI blocking mode
1559 *
1560 * Returns the the blocking mode.
1561 *
1562 * @param dbh      I - A database handle
1563 * @param blocking O - SQL_ON if in blocking mode (database default), or SQLO_OFF if
1564 *                     in non-blocking mode.
1565 * @return SQLO_SUCCESS or OCI status code.
1566 * @since Version 2.2
1567 */
1568int sqlo_get_blocking __P((sqlo_db_handle_t dbh, unsigned int * blocking));
1569
1570
1571/**
1572 * Abort all operations in non-blocking mode
1573 *
1574 * This call performs an immediate (asynchronous) abort of any
1575 * currently executing OCI function that is associated with a connection.
1576 *
1577 * If the connection is in blocking mode, SQLO_SUCCESS is returned without
1578 * doing an abort.
1579 *
1580 * The cursor in "SQLO_STILL_EXECUTING" status is closed.
1581 *
1582 * @param dbh A database handle
1583 *
1584 * @return <ul>
1585 * <li>SQLO_SUCCESS
1586 * <li>SQLO_ERROR
1587 * <li>SQLO_INVALID_DB_HANDLE
1588 * </ul>
1589 * @since Version 2.2
1590 */
1591int sqlo_break __P((sqlo_db_handle_t dbh));
1592
1593
1594/**
1595 * Set the prefetch row attribute for a statement.
1596 * This functions sets the oci attribute OCI_ATTR_PREFETCH_ROWS to the
1597 * given value.
1598 * @note This does not affect the global setting passed by the enviroment
1599 * variable SQLORA_PREFETCH_ROWS.
1600 * @param sth    I - The statement handle
1601 * @param nrows  I - The value of the attribute.
1602 * @return SQLO_SUCCESS or < 0 on error
1603 * @since Version 2.2
1604 */
1605int sqlo_set_prefetch_rows __P((sqlo_stmt_handle_t sth, unsigned int nrows));
1606
1607
1608/**
1609 * Get the server version string.
1610 *
1611 * Returns the server version string which might look like this:
1612 @verbatim
1613   Oracle8i Enterprise Edition Release 8.1.5.0.0 - Production
1614   With the Partitioning and Java options
1615   PL/SQL Release 8.1.5.0.0 - Production.
1616  @endverbatim
1617    The buffer is null terminated.
1618  * @param dbh    I - The database handle
1619  * @param bufp   O - The version string
1620  * @param buflen I - Supply her the capacity of your buffer.
1621 * @return SQLO_SUCCESS or < 0 on error.
1622 * @since Version 2.2
1623 */
1624int sqlo_server_version __P((sqlo_db_handle_t dbh, char *bufp, unsigned int buflen));
1625
1626/**
1627 * Get the state of the statement
1628 * @note Don't use this in Oracle versions < 9.0!
1629 * @param sth I - A statement handle
1630 * @return The state (see @sqlo_statement_states) or < 0 n error.
1631 * @since Version 2.2
1632 */ 
1633int sqlo_get_stmt_state __P((sqlo_stmt_handle_t sth));
1634
1635/**
1636 * Get the datatype of a column in the select list
1637 * @param sth I - The statement handle
1638 * @param pos I - The column position (1 based).
1639 * @return <ul>
1640 * <li>The datatype (see @ref sqlo_data_types)
1641 * <li>SQLO_INVALID_STMT_HANDLE
1642 * <li>SQLO_INVALID_COLPOS
1643 * </ul>
1644 * @since Version 2.2
1645 */
1646int sqlo_get_ocol_dtype __P((sqlo_stmt_handle_t sth, unsigned int pos));
1647
1648
1649/**
1650 * Switches Oracle trace on/off
1651 *
1652 * Use this to switch the Oracle trace facility (tkprof) on or off.
1653 *
1654 * @param dbh I - A database handle
1655 * @param on  I - A flag indicating if we switch tracing on (SQLO_ON) or off (SQLO_OFF)
1656 *
1657 * @return <ul>
1658 * <li> SQLO_SUCCESS
1659 * <li> < 0 on error
1660 * </ul>
1661 */
1662int sqlo_trace __P((sqlo_db_handle_t dbh, int on ));
1663
1664
1665/**
1666 * Print info about the statement to stdout
1667 *
1668 * @deprecated  This function will not be enhanced or maintained. This is a kind
1669 * of debuging code, but better use the builtin trace facility.
1670 *
1671 * @return <ul>
1672 * <li>SQLO_SUCCESS
1673 * <li> < 0 on error
1674 * </ul>
1675 * @param sth A statement handle
1676*/
1677int sqlo_print __P(( sqlo_stmt_handle_t sth ));
1678
1679/**
1680 * }@
1681 */
1682
1683/*-----------------------------------------------------------------------*/
1684/* Functions to keep backward compatibility                              */
1685/* Dont use this for new developments                                    */
1686/*-----------------------------------------------------------------------*/
1687#ifndef DOXYGEN_SHOULD_SKIP_THIS
1688
1689int sql_init __P(( void ));
1690
1691int sql_trace __P(( int on ));
1692
1693CONST char * sql_geterror __P(( void ));
1694
1695int sql_geterrcode __P(( void ));
1696
1697int sql_exists __P((CONST char  * table, CONST char  * field,
1698                    CONST char * value, CONST char * where ));
1699int sql_run __P((CONST char * stmt, int argc, CONST char ** argv));
1700
1701int sql_open __P((CONST char * stmt, int argc, 
1702                                    CONST char ** argv));
1703
1704int sql_reopen __P((int sth, int argc, CONST char ** argv));
1705
1706int sql_fetch __P((int sth ));
1707
1708CONST char **sql_values __P(( int sth, int * num, int dostrip ));
1709
1710CONST char *sql_command __P(( int sth ));
1711
1712int sql_close __P(( int sth ));
1713
1714int sql_print __P(( int sth ));
1715
1716int sql_finish __P((void));
1717
1718CONST char * sql_getdatabase __P(( void ));
1719
1720CONST char ** sql_cnam __P(( int sth, int in, int * num ));
1721
1722CONST char ** sql_sclen __P(( int sth, int in, int * num ));
1723
1724int sql_prows __P(( int sth ));
1725
1726int sql_connect __P(( CONST char  * connect_str ));
1727
1728int sql_commit __P(( void ));
1729
1730int sql_rollback __P(( void ));
1731
1732int sql_count __P((CONST char * table,
1733                   CONST char * field,
1734                   CONST char * value,
1735                   CONST char * where ));
1736
1737int sql_exec __P(( CONST char * stmt ));
1738
1739int sql_setparam __P(( int argc , CONST char ** argv));
1740
1741char CONST ** sql_getparam __P(( int namec, CONST char ** name, int *numvalues ));
1742int sql_isopen __P((int sth));
1743
1744int sql_prepare __P((CONST char * stmt));
1745
1746int sql_bind_by_name __P((int sth, CONST char * name, int param_type, 
1747                          CONST void * param_addr, unsigned int param_size, 
1748                          short * ind_addr, int is_array));
1749
1750int sql_bind_by_pos __P((int sth, int position, int param_type, CONST void * param_addr, unsigned int param_size, short * ind_addr, int is_array));
1751
1752int sql_define_by_pos __P((int sth, int value_pos, int value_type,
1753                           CONST void * value_addr,
1754                           unsigned int value_size,
1755                           short * ind_addr,
1756                           short * rlen_addr,
1757                           int is_array));
1758
1759int sql_execute __P((int sth, int iterations));
1760
1761char CONST **sql_ocol_names __P((int sth, int * num));
1762
1763int CONST *sql_ocol_name_lens __P((int sth, int * num));
1764
1765unsigned short CONST * sql_value_lens __P((int sth, int * num));
1766
1767int sql_ncols __P((int sth, int in));
1768
1769int sql_getdbh __P((void));
1770
1771#define  SQLO_DEFDBH  (sql_getdbh())
1772#endif /* DOXYGEN_SHOULD_SKIP_THIS */
1773
1774__END_DECLS
1775
1776
1777#endif
1778
Note: See TracBrowser for help on using the repository browser.