/* KInterbasDB Python Package - Header File for Core ** ** Version 3.1 ** ** The following contributors hold Copyright (C) over their respective ** portions of code (see license.txt for details): ** ** [Original Author (maintained through version 2.0-0.3.1):] ** 1998-2001 [alex] Alexander Kuznetsov ** [Maintainers (after version 2.0-0.3.1):] ** 2001-2002 [maz] Marek Isalski ** 2002-2004 [dsr] David Rushby ** [Contributors:] ** 2001 [eac] Evgeny A. Cherkashin ** 2001-2002 [janez] Janez Jere */ #ifndef _KINTERBASDB_H #define _KINTERBASDB_H #define KIDB_HOME_PAGE "http://sourceforge.net/projects/kinterbasdb" #define KIDB_REPORT " -- please report this to the developers at " /* The standard guide to Embedding and Extending says: "Since Python may ** define some pre-processor definitions which affect the standard headers ** on some systems, you must include Python.h before any standard headers ** are included." */ #include "Python.h" /* 2002.12.31: Switched to memory allocator that redirects to standard in ** <= Py2.2, but is optimized for frequent small-size memory ops in Py2.3 ** (this should be a good fit for kinterbasdb). */ #include "pymemcompat.h" #include #include #include "ibase.h" typedef unsigned char boolean; #define TRUE 1 #define FALSE 0 #ifdef MS_WIN32 #if defined(_MSC_VER) #define COMPILER_IS_MSVC_WIN32 #elif defined(__BORLANDC__) #define COMPILER_IS_BCPP_WIN32 #else #define COMPILER_IS_MINGW_WIN32 #endif #endif #define PYTHON_2_2_OR_LATER (PY_VERSION_HEX >= 0x020200F0) /* 2003.03.31: */ #include "_kimem.h" /* 2003.03.30: Python 2.1/2.2.0 compatibility: */ #ifndef PyBool_Check #define PyBool_FromLong(x) PyInt_FromLong(x) #endif /* Inexplicably, PySequence_Fast_GET_SIZE was left out of Python 2.1. */ #ifndef PySequence_Fast_GET_SIZE #define PySequence_Fast_GET_SIZE(o) \ (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o)) #endif /* PyObject_TypeCheck doesn't exist in Python 2.1, but a replacement is trivial ** because Python 2.1 does not allow type inheritance. */ #ifndef PyObject_TypeCheck #define PyObject_TypeCheck(o, tp) ((o)->ob_type == (tp)) #endif /* Python 2.3b1 no longer defines LONG_LONG. */ #ifndef LONG_LONG #define LONG_LONG PY_LONG_LONG #endif #ifndef LONG_LONG_MIN #ifdef LLONG_MIN #define LONG_LONG_MIN LLONG_MIN #define LONG_LONG_MAX LLONG_MAX #else #ifdef _I64_MIN #define LONG_LONG_MIN _I64_MIN #define LONG_LONG_MAX _I64_MAX #endif #endif #endif /* Python's long type, which has unlimited range, is computationally ** expensive relative to Python's int type, which wraps a native long. So: ** 1. On platforms where C's long is 64 bits or larger, ** PythonIntOrLongFrom64BitValue unconditionally creates a Python int. ** 2. On platforms where C's long is smaller than 64 bits, ** PythonIntOrLongFrom64BitValue tests the value at runtime to see if it's ** within the range of a Python int; if so, it creates a Python int rather ** than a Python long. It is expected that in most contexts, the cost of ** the test will be less than the cost of using a Python long. */ #if defined(_MSC_VER) || defined(__BORLANDC__) /* MSVC 6 and BCPP 5.5 won't accept the LL suffix. */ #define NativeLongIsAtLeast64Bits \ (LONG_MAX >= 9223372036854775807i64 && LONG_MIN <= (-9223372036854775807i64 - 1)) #else #define NativeLongIsAtLeast64Bits \ (LONG_MAX >= 9223372036854775807LL && LONG_MIN <= (-9223372036854775807LL - 1)) #endif #if NativeLongIsAtLeast64Bits #define PythonIntOrLongFrom64BitValue(x) PyInt_FromLong((long) x) #else #define PythonIntOrLongFrom64BitValue(x) \ ( (x < LONG_MIN || x > LONG_MAX) ? PyLong_FromLongLong(x) : PyInt_FromLong((long) x) ) #endif /* 2004.04.21: */ /* FB 1.5 exposes ISC_SHORT in its header file, but FB 1.0 does not. */ #ifndef ISC_SHORT #define ISC_SHORT short #endif /* 2002.02.15: Detect Interbase 6 or later (including Firebird). */ #if (defined(SQL_DIALECT_CURRENT) && defined(SQL_DIALECT_V6)) #define INTERBASE6_OR_LATER #define SQL_DIALECT_DEFAULT SQL_DIALECT_CURRENT #define SQL_DIALECT_OLDEST SQL_DIALECT_V5 #else #define SQL_DIALECT_DEFAULT 1 #define SQL_DIALECT_OLDEST 1 /* IB < 6.0 had less differentiated datetime types; SQL_TIMESTAMP is more ** representative of what columns called SQL_DATE actually contain. */ #define SQL_TIMESTAMP SQL_DATE /* IB 6 API Guide p 301: "The isc_decode_timestamp() is exactly the same as ** the isc_decode_date() function in versions of InterBase prior to 6.0." */ #define isc_decode_timestamp isc_decode_date /* IB 6 API Guide p 346: "This call [isc_encode_timestamp()] is exactly the ** same as the older isc_encode_date(), which is still available for backward ** compatibility. */ #define isc_encode_timestamp isc_encode_date #define ISC_TIMESTAMP ISC_QUAD #define blr_timestamp blr_date /* 2004.07.18: IB < 6.0 doesn't define ISC_ULONG: */ #define ISC_ULONG unsigned long #endif /* Beginning with Firebird 1.5, Firebird defines an integer constant FB_API_VER ** that we can use to determine the version of the client library we're ** compiling against. Unfortunately, Firebird 1.0 defines no such thing, so ** we just test for an ad hoc definition that's defined in Firebird 1.0 but not ** Interbase 6.0. */ #if (defined(dtype_null) || defined(FB_API_VER)) #define FIREBIRD_1_0_OR_LATER #endif #ifdef FB_API_VER #if FB_API_VER >= 15 #define FIREBIRD_1_5_OR_LATER #endif #if FB_API_VER >= 20 #define FIREBIRD_2_0_OR_LATER #endif #endif /* def FB_API_VER? */ /* The field precision determination code uses DB fields not present before IB ** 6.0, so if we're using an earlier version than that, disable the feature ** regardless of the user's setting. */ #ifndef INTERBASE6_OR_LATER #undef DETERMINE_FIELD_PRECISION #endif /******************** COMPILATION OPTIONS:BEGIN ********************/ /* Define KIDB_DEBUGGERING to get lots of debugging output to stderr. ** Note that this facility hasn't really been kept up to date; it's not very ** useful. */ /* #define KIDB_DEBUGGERING */ /* 2002.10.14: */ /* Change this definition to FALSE to turn off explicit GIL release and ** reacquisition. If you plan on using events, turning this off is a very ** bad idea. */ #ifdef WITH_THREAD #define SHOULD_MANAGE_GIL TRUE #else #define SHOULD_MANAGE_GIL FALSE #endif /* WITH_THREAD */ /* 2003.01.20: */ /* For version 3.1, database event support is off by default; uncomment the ** line below to enable it (the prototype is only for Win32). */ #define ENABLE_DB_EVENT_SUPPORT /* INITIAL_SQLVAR_CAPACITY is the number of XSQLVARs that a freshly allocated ** XSQLDA (such as the in_sqlda and out_sqlda of a new cursor) is configured ** to hold. ** If the initial capacity proves insufficient, more space is allocated ** automatically. Therefore, INITIAL_SQLVAR_CAPACITY is an "optimization hint" ** rather than a "hard-coded limit". */ #define INITIAL_SQLVAR_CAPACITY 16 /******************** COMPILATION OPTIONS:END ********************/ /******************** HARD-CODED LIMITS:BEGIN ********************/ /* MAX_BLOB_SEGMENT_SIZE is an IB/Firebird engine constraint, not something ** we could overcome here in kinterbasdb. For that matter, it's not a ** "constraint" in any meaningful sense, since a single blob can have many ** segments, and kinterbasdb manages the segmentation transparently. */ #define MAX_BLOB_SEGMENT_SIZE 65535 /* DSR:2002.02.15: ** I went through and tried to extract all hard-coded buffer size ** specifications to this HARD-CODED LIMITS section. Generally, the respective ** sizes I chose are those used by the Interbase 6 API Guide, though it does ** not officially define the sizes, which leaves the looming specter of buffer ** overflows. ** ** As of 2003.02.13, I've made considerable effort to minimize the likelihood ** of buffer overflows; you can find notes about those measures in the source ** code where these constants are used. */ #define MAX_ISC_ERROR_MESSAGE_BUFFER_SIZE 2048 /* Firebird 1.5 and later publish the size of the status vector as ** ISC_STATUS_LENGTH. */ #ifdef ISC_STATUS_LENGTH #define STATUS_VECTOR_SIZE ISC_STATUS_LENGTH #else #define STATUS_VECTOR_SIZE 20 #endif #define DPB_BUFFER_SIZE 256 #define ISC_INFO_BUFFER_SIZE 20 #define ISC_INFO_RESULT_BUFFER_SIZE 8192 /* 2003.02.19: */ /* These limits are based on the official API examples and observation that ** larger values crash the client library. They are the size limits imposed ** on buffers incoming to pyob_attach_db. */ #define MAX_DPB_SIZE 255 #define MAX_DSN_SIZE 127 /* XSQLDA and XSQLVAR-related limits: */ /* As of 2003.02.13/FB1.0, attempting to prepare and execute a statement with ** an extremely large number of parameters causes the Firebird client library ** to to mishandle memory at risk of segfault. ** I have observed the problem to begin around 3625 parameters. ** kinterbasdb defines MAX_XSQLVARS_IN_SQLDA to prevent Python programmers ** from inadvertently running afoul of the FB client library's irresponsibility. ** If in the future the client library is fixed, there'll be no reason not to ** raise MAX_XSQLVARS_IN_SQLDA (though it goes without saying that anyone who ** actually uses SQL statements with > 2048 parameters routinely should be ** shot). */ /* YYY:2004.04.16: 2048 fields segfaulted on x86_64/1.5.1pre1, so I reduced ** the limit: */ #define MAX_XSQLVARS_IN_SQLDA 1024 /* The database engine does not allow more than 16 database handles to ** participate in a single distributed transaction. */ #define DIST_TRANS_MAX_DATABASES 16 /******************** HARD-CODED LIMITS:END ********************/ /******************** HANDY ABBREVIATIONS:BEGIN ********************/ /* 2002.12.24: Returned to using multi-line macros instead of jamming ** everything onto a single line. People using compilers incapable of dealing ** with multi-line macros will just have to deal with it. */ typedef enum { SIGN_NEGATIVE = -1, SIGN_POSITIVE = 1 } NumberSign; typedef enum { SUBTYPE_NONE = 0, SUBTYPE_NUMERIC = 1, SUBTYPE_DECIMAL = 2 } SQLSubtype; typedef enum { SQLIND_NULL = -1, SQLIND_NOT_NULL = 0 } SQLIndicator_State; /* See IB6 API Guide page 92. */ #define XSQLVAR_IS_ALLOWED_TO_BE_NULL(sqlvar) \ ((sqlvar->sqltype & 1) != 0) #define XSQLVAR_IS_NULL(sqlvar) \ (*(sqlvar->sqlind) == SQLIND_NULL) #define XSQLVAR_SQLTYPE_IGNORING_NULL_FLAG(sqlvar) \ (sqlvar->sqltype & ~1) #define XSQLVAR_SQLTYPE_READ_NULL_FLAG(sqlvar) \ (sqlvar->sqltype & 1) #define XSQLVAR_SET_NULL(sqlvar) \ (*(sqlvar->sqlind) = SQLIND_NULL) #define XSQLVAR_SET_NOT_NULL(sqlvar) \ (*(sqlvar->sqlind) = SQLIND_NOT_NULL) /* Macros for printing debugging information to stderr. */ #ifdef KIDB_DEBUGGERING #define debug_printf( x ) fprintf( stderr, ( x ) ) #define debug_printf1( x, y ) fprintf( stderr, ( x ), ( y ) ) #define debug_printf2( x, y, z ) fprintf( stderr, ( x ), ( y ), ( z ) ) #define debug_dump_status_vector(x) dumpStatusVector(x) #else #define debug_printf( x ) #define debug_printf1( x, y ) #define debug_printf2( x, y, z ) #define debug_dump_status_vector(x) #endif /* KIDB_DEBUGGERING */ /* DB_API_ERROR acts like a boolean function, returning TRUE if ** status_vector indicates an error. */ #define DB_API_ERROR(status_vector) \ ( ((status_vector[0] == 1) && status_vector[1] > 0) ? TRUE : FALSE ) #define MIN( a, b ) ( ( a < b ) ? a : b ) #define MAX( a, b ) ( ( a > b ) ? a : b ) #define RETURN_PY_NONE \ Py_INCREF(Py_None); \ return Py_None; /******************** HANDY ABBREVIATIONS:END ********************/ /******************** MODULE TYPE DEFINITIONS:BEGIN ********************/ /* See Appendix B of Interbase 6 API Guide for explanation of Interbase API ** structures. */ /* 2002.12.15: declared as extern, not staticforward, so that they're visible ** to _kievents. */ extern PyTypeObject ConnectionType; extern PyTypeObject CursorType; /* 2003.04.27: */ extern PyTypeObject TransactionHandleType; /* 2002.06.09: */ /* This structure supports a moderately ugly approach to determining the ** precision of a given field (querying the system tables). */ typedef struct { isc_stmt_handle stmt_handle_table; isc_stmt_handle stmt_handle_stored_procedure; XSQLDA *in_da; XSQLDA *out_da; XSQLVAR *out_var; PyObject *result_cache; } CursorDescriptionCache; typedef enum { CONNECTION_STATE_CLOSED = 0, CONNECTION_STATE_OPEN = 1 } ConnectionState; typedef struct { /* definition of type ConnectionObject */ PyObject_HEAD /* Python API - infrastructural macro. */ unsigned short dialect; isc_db_handle db_handle; isc_tr_handle trans_handle; /* 2003.04.27: */ PyObject *group; /* Buffer used by Interbase API to store error status of calls. */ ISC_STATUS status_vector[ STATUS_VECTOR_SIZE ]; ConnectionState _state; /* Connection state flag. */ #ifdef DETERMINE_FIELD_PRECISION CursorDescriptionCache *desc_cache; #endif /* 2003.03.30: */ PyObject *type_trans_in; PyObject *type_trans_out; /* 2003.10.16: */ PyObject *output_type_trans_return_type_dict; } ConnectionObject; #define CONN_REQUIRE_OPEN(connection) \ if ( _conn_require_open(connection, NULL) != 0 ) \ return NULL; #define CONN_REQUIRE_OPEN2(connection, failure_message) \ if ( _conn_require_open(connection, failure_message) != 0 ) \ return NULL; typedef struct { short sqltype; short sqllen; } OriginalXSQLVARSpecificationCache; typedef enum { CURSOR_STATE_CLOSED = 0, CURSOR_STATE_OPEN = 1 } CursorState; typedef struct { /* definition of type CursorObject */ PyObject_HEAD /* Python API - infrastructural macro. */ /* Connection associated with this cursor. */ ConnectionObject *connection; /* Interbase API - statement handle. */ isc_stmt_handle stmt_handle; /* Interbase API - containers for input and result parameter structures. */ XSQLDA *in_sqlda; XSQLDA *out_sqlda; /* 2002.10.07: */ /* Added to support the use of named cursors with "SELECT ... FOR UPDATE" ** syntax. */ PyObject *name; /* 2002.08.22: */ /* The in_var_orig_spec cache variable allows us to record the original ** values supplied by the database engine for each XSQLVAR's sqltype and ** sqllen fields. These values are reset in cases of implicit parameter ** conversion (or in *any* case with CHAR/VARCHAR fields), but the original ** settings must be remembered (see _prepare_statement_if_necessary in ** _kinterbasdb.c) ** !AND! restored (see PyObject2XSQLDA in _kiconversion.c) before attempting ** to convert each incoming parameter list. ** ** For example, suppose a VARCHAR field is defined to be 20 characters at ** most. Suppose the first row of input parameters to an insert statement ** supplies a string value that is only 15 characters long. In this case, ** the incoming parameter conversion function (PyObject2XSQLVAR) does the ** following: ** 1. sets the XSQLVAR's sqltype flag to SQL_TEXT (was SQL_VARYING) ** 2. sets the XSQLVAR's sqldata pointer to point to the internal buffer ** of the Python string (was NULL) ** 3. sets the XSQLVAR's sqllen field to indicate the length of that ** specific value, which is 15 (was the maximum length of the field, 20). ** ** Suppose that the next row of input parameters includes a 17-character ** string for the same field. Unless the original sqllen flag (20) has been ** restored, the range checking code will conclude that the field has a ** maximum length of 15 characters (which just happened to be the lentgh of ** the last value, now stored in the XSQLVAR's sqllen flag). ** With the XSQLVAR's original sqltype and sqllen flags restored to their ** pre-implicit-conversion values (sqltype SQL_VARYING and sqllen 20, in the ** running example), everything proceeds fine. ** I smell a really ugly hack, don't you? Perhaps I should've rejected ** the implicit parameter conversion feature request, if my implementation ** of can be no cleaner than this. */ OriginalXSQLVARSpecificationCache *in_var_orig_spec; /* Utility buffer where query result values reside before they're converted ** to Python values. */ char *out_buffer; /* Variables to support caching the last SQL string executed (in order to ** detect whether a new statement is identical and thereby avoid having to ** reprepare, etc.). */ PyObject *previous_sql; /* 2003.01.26: */ int statement_type; #define NULL_STATEMENT_TYPE -1 /* 2003.09.06b: */ PyObject *objects_to_release_after_execute; /* 2002.02.21: ** Variable to support caching a single row of results from a stored ** procedure invoked using EXECUTE PROCEDURE syntax. This approach is ** exceptionaly clumsy, but necessary in order to deal with of Interbase ** API quirks and still comply with the Python DB API 2.0. ** (See bug #520793.) ** (See special cases involving isc_info_sql_stmt_exec_procedure in ** functions pyob_execute and pyob_fetch.) */ PyObject *exec_proc_results; /* 2002.04.27: ** last_fetch_status caches the return code of the last isc_dsql_fetch call ** made with this cursor, in order to assist in bridging a gap between the ** IB API and the Python DB API. ** The Python DB API requires that extraneous fetches after a result set ** has been exhausted be tolerated, whereas the IB API raises an error in ** such cases. This flag allows kinterbasdb to detect this situation and ** handle it in the Pythonic way, instead of calling isc_dsql_fetch and ** encountering an error. */ int last_fetch_status; /* Buffer used by Interbase API to store error status of calls. */ ISC_STATUS status_vector[ STATUS_VECTOR_SIZE ]; CursorState _state; /* Cursor state flag. */ /* 2003.03.30: */ PyObject *type_trans_in; PyObject *type_trans_out; /* 2003.10.16: */ PyObject *output_type_trans_return_type_dict; } CursorObject; #define CUR_REQUIRE_OPEN(cursor) \ if ( _cur_require_open(cursor, NULL) != 0 ) \ return NULL; #define CUR_REQUIRE_OPEN2(cursor, failure_message) \ if ( _cur_require_open(cursor, failure_message) != 0 ) \ return NULL; /* 2003.04.27: support for distributed transactions */ /* ISC_TEB: See IB6 API Guide page 71. */ typedef struct teb { long *db_ptr; long tpb_len; char *tpb_ptr; } ISC_TEB; typedef struct { /* definition of type TransactionHandleObject */ PyObject_HEAD /* Python API - infrastructural macro. */ isc_tr_handle native_handle; } TransactionHandleObject; /******************** MODULE TYPE DEFINITIONS:END ********************/ /******************** FUNCTION PROTOTYPES:BEGIN ********************/ void close_cursor(CursorObject *cursor); #ifndef _MSC_VER void init_kinterbasdb( void ); #endif /* _MSC_VER */ #ifdef KIDB_DEBUGGERING void dumpXSQLDA(XSQLDA *sqlda); void dumpXSQLVAR(XSQLVAR *sqlvar); void dumpStatusVector(ISC_STATUS *sv); #endif /* KIDB_DEBUGGERING */ /* Exception functions moved the _kinterbasdb.c on 2003.01.01. */ extern void raise_sql_exception( PyObject *exc, const char *where, ISC_STATUS pvector[] ); extern void raise_exception( PyObject *exc, const char *description ); /******************** FUNCTION PROTOTYPES:END ********************/ /* Allow other source files that are compiled in the kinterbasdb core unit ** to access these MIN/MAX global variables: */ extern PyObject *SHRT_MIN_As_PyObject; extern PyObject *SHRT_MAX_As_PyObject; extern PyObject *INT_MIN_As_PyObject; extern PyObject *INT_MAX_As_PyObject; extern PyObject *LONG_MIN_As_PyObject; extern PyObject *LONG_MAX_As_PyObject; extern PyObject *LONG_LONG_MIN_As_PyObject; extern PyObject *LONG_LONG_MAX_As_PyObject; #endif /* not def _KINTERBASDB_H */