home *** CD-ROM | disk | FTP | other *** search
/ CD Actual Thematic 7: Programming / CDAT7.iso / Share / Editores / Perl5 / perl / lib / site / auto / DBI / DBIXS.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-10  |  13.2 KB  |  358 lines
  1. /* $Id: DBIXS.h,v 1.42 1997/07/22 23:17:50 timbo Exp $
  2.  *
  3.  * Copyright (c) 1994, 1995 Tim Bunce
  4.  *
  5.  * You may distribute under the terms of either the GNU General Public
  6.  * License or the Artistic License, as specified in the Perl README file.
  7.  */
  8.  
  9. /* DBI Interface Definitions for DBD Modules */
  10.  
  11. /* first pull in the standard Perl header files for extensions */
  12. #include <EXTERN.h>
  13. #include <perl.h>
  14. #include <XSUB.h>
  15.  
  16. #include "dbi_sql.h"
  17.  
  18. /* The DBIXS_VERSION value will be incremented whenever new code is
  19.  * added to the interface (this file) or significant changes are made.
  20.  * It's primary goal is to allow newer drivers to compile against an
  21.  * older installed DBI. This is mainly an issue whilst the API grows
  22.  * and learns from the needs of various drivers.  See also the
  23.  * DBISTATE_VERSION macro below. You can think of DBIXS_VERSION as
  24.  * being a compile time check and DBISTATE_VERSION as a runtime check.
  25.  */
  26. #define DBIXS_VERSION 9
  27.  
  28. #ifdef NEED_DBIXS_VERSION
  29. #if NEED_DBIXS_VERSION > DBIXS_VERSION
  30. error You_need_to_upgrade_your_DBI_module_before_building_this_driver.
  31. #endif
  32. #else
  33. #define NEED_DBIXS_VERSION DBIXS_VERSION
  34. #endif
  35.  
  36.  
  37. /* forward declaration of 'DBI Handle Common Data', see below        */
  38.  
  39. /* implementor needs to define actual struct { dbih_??c_t com; ... }*/
  40. typedef struct imp_drh_st imp_drh_t;    /* driver            */
  41. typedef struct imp_dbh_st imp_dbh_t;    /* database            */
  42. typedef struct imp_sth_st imp_sth_t;    /* statement            */
  43. typedef struct imp_fdh_st imp_fdh_t;    /* field descriptor        */
  44. typedef struct imp_xxh_st imp_xxh_t;    /* any (defined below)        */
  45.  
  46.  
  47.  
  48. /* --- DBI Handle Common Data Structure (all handles have one) ---    */
  49.  
  50. /* Handle types. Code currently assumes child = parent + 1.        */
  51. #define DBIt_DR        1
  52. #define DBIt_DB        2
  53. #define DBIt_ST        3
  54. #define DBIt_FD        4
  55.  
  56. /* component structures */
  57.  
  58. typedef struct dbih_com_std_st {
  59.     U32  flags;        /* XXX will change to U32 at some point        */
  60.     U16  call_depth;    /* used by DBI to track nested calls        */
  61.     U16  type;        /* DBIt_DR, DBIt_DB, DBIt_ST            */
  62.     SV   *my_h;        /* copy of owner inner handle (NO r.c.inc)    */
  63.     SV   *parent_h;    /* parent inner handle (RV(HV)) (r.c.inc)    */
  64.     imp_xxh_t *parent_com;    /* parent com struct shortcut        */
  65.  
  66.     HV   *imp_stash;    /* who is the implementor for this handle    */
  67.     SV   *imp_data;    /* optional implementors data (for perl imp's)    */
  68.  
  69.     I32  kids;        /* count of db's for dr's, st's for db's etc    */
  70.     I32  active_kids;    /* kids which are currently DBIc_ACTIVE        */
  71.     char *last_method;    /* name of last method called, set by dispatch    */
  72. } dbih_com_std_t;
  73.  
  74. typedef struct dbih_com_attr_st {
  75.     /* These are copies of the Hash values (ref.cnt.inc'd)    */
  76.     /* Many of the hash values are themselves references    */
  77.     SV *Debug;
  78.     SV *State;        /* Standard SQLSTATE, 5 char string    */
  79.     SV *Err;        /* Native engine error code        */
  80.     SV *Errstr;        /* Native engine error message        */
  81.     SV *Handlers;
  82.     U32  LongReadLen;    /* auto read length for long/blob types    */
  83. } dbih_com_attr_t;
  84.  
  85.  
  86. struct dbih_com_st {    /* complete core structure (typedef'd above)    */
  87.     dbih_com_std_t    std;
  88.     dbih_com_attr_t    attr;
  89. };
  90.  
  91. /* This 'implementors' type the DBI defines by default as a way to    */
  92. /* refer to the imp_??h data of a handle without considering its type.    */
  93. struct imp_xxh_st { struct dbih_com_st com; };
  94.  
  95. /* Define handle-type specific structures for implementors to include    */
  96. /* at the start of their private structures.                */
  97.  
  98. typedef struct            /* -- DRIVER --                */
  99.     dbih_com_st            /* standard structure only        */
  100. dbih_drc_t;
  101.  
  102. typedef struct {        /* -- DATABASE --            */
  103.     dbih_com_std_t    std;    /* \__ standard structure        */
  104.     dbih_com_attr_t    attr;    /* /   plus... (nothing else right now)    */
  105. } dbih_dbc_t;
  106.  
  107. typedef struct {        /* -- STATEMENT --            */
  108.     dbih_com_std_t    std;    /* \__ standard structure        */
  109.     dbih_com_attr_t    attr;    /* /   plus ...                */
  110.  
  111.     int     num_params;    /* number of placeholders        */
  112.     int     num_fields;    /* NUM_OF_FIELDS, must be set        */
  113.     AV      *fields_svav;    /* special row buffer (inc bind_cols)    */
  114.  
  115.     AV        *fields_fdav;    /* not used yet, may change */
  116.  
  117. } dbih_stc_t;
  118.  
  119. typedef struct {        /* -- FIELD DESCRIPTOR --        */
  120.     dbih_com_std_t    std;    /* standard structure (not fully setup)    */
  121.  
  122.     /* core attributes (from DescribeCol in ODBC)        */
  123.     char *col_name;        /* see dbih_make_fdsv        */
  124.     I16   col_name_len;
  125.     I16   col_sql_type;
  126.     I16   col_precision;
  127.     I16   col_scale;
  128.     I16   col_nullable;
  129.  
  130.     /* additional attributes (from ColAttributes in ODBC)    */
  131.     I32   col_length;
  132.     I32   col_disp_size;
  133.  
  134. } dbih_fdc_t;
  135.  
  136.  
  137. #define _imp2com(p,f)          ((p)->com.f)
  138.  
  139. #define DBIc_FLAGS(imp)        _imp2com(imp, std.flags)
  140. #define DBIc_TYPE(imp)        _imp2com(imp, std.type)
  141. #define DBIc_CALL_DEPTH(imp)    _imp2com(imp, std.call_depth)
  142. #define DBIc_MY_H(imp)      _imp2com(imp, std.my_h)
  143. #define DBIc_PARENT_H(imp)      _imp2com(imp, std.parent_h)
  144. #define DBIc_PARENT_COM(imp)      _imp2com(imp, std.parent_com)
  145. #define DBIc_IMP_STASH(imp)      _imp2com(imp, std.imp_stash)
  146. #define DBIc_IMP_DATA(imp)      _imp2com(imp, std.imp_data)
  147. #define DBIc_KIDS(imp)      _imp2com(imp, std.kids)
  148. #define DBIc_ACTIVE_KIDS(imp)      _imp2com(imp, std.active_kids)
  149. #define DBIc_LAST_METHOD(imp)     _imp2com(imp, std.last_method)
  150.  
  151. #define DBIc_DEBUG(imp)        (_imp2com(imp, attr.Debug))
  152. #define DBIc_DEBUGIV(imp)    SvIV(DBIc_DEBUG(imp))
  153. #define DBIc_STATE(imp)        SvRV(_imp2com(imp, attr.State))
  154. #define DBIc_ERR(imp)        SvRV(_imp2com(imp, attr.Err))
  155. #define DBIc_ERRSTR(imp)    SvRV(_imp2com(imp, attr.Errstr))
  156. #define DBIc_HANDLERS(imp)    SvRV(_imp2com(imp, attr.Handlers))
  157. #define DBIc_LongReadLen(imp)      _imp2com(imp, attr.LongReadLen)
  158. #define DBIc_LongReadLen_init    80
  159.  
  160. /* sub-type specific fields                        */
  161. #define DBIc_NUM_FIELDS(imp)      _imp2com(imp, num_fields)
  162. #define DBIc_NUM_PARAMS(imp)      _imp2com(imp, num_params)
  163. #define DBIc_FIELDS_AV(imp)      _imp2com(imp, fields_svav)
  164. #define DBIc_FDESC_AV(imp)      _imp2com(imp, fields_fdav)
  165. #define DBIc_FDESC(imp, i)      ((imp_fdh_t*)SvPVX(AvARRAY(DBIc_FDESC_AV(imp))[i]))
  166.  
  167. #define DBIcf_COMSET      0x0001    /* needs to be clear'd before free'd    */
  168. #define DBIcf_IMPSET      0x0002    /* has implementor data to be clear'd    */
  169. #define DBIcf_ACTIVE      0x0004    /* needs finish/disconnect before clear    */
  170. #define DBIcf_IADESTROY      0x0008    /* do DBIc_ACTIVE_off before DESTROY    */
  171. #define DBIcf_WARN        0x0010    /* warn about poor practice etc      */
  172. #define DBIcf_COMPAT        0x0020    /* compat/emulation mode (eg oraperl)    */
  173.  
  174. #define DBIcf_ChopBlanks  0x0040    /* rtrim spaces from fetch char columns    */
  175. #define DBIcf_RaiseError  0x0080    /* throw exception (croak) on error    */
  176. #define DBIcf_PrintError  0x0100    /* warn() on error            */
  177. #define DBIcf_AutoCommit  0x0200    /* dbh only. used by drivers        */
  178. #define DBIcf_LongTruncOk 0x0400    /* truncation to LongReadLen is okay    */
  179.  
  180. #define DBIcf_INHERITMASK            /* what NOT to pass on to children */    \
  181.     (U32)( DBIcf_COMSET | DBIcf_IMPSET | DBIcf_ACTIVE | DBIcf_IADESTROY        \
  182.     /* These are for dbh only:                       */    \
  183.     | DBIcf_AutoCommit    )
  184.  
  185. /* general purpose flag setting and testing macros */
  186. #define DBIc_is(imp, flag)    (DBIc_FLAGS(imp) &   (flag))
  187. #define DBIc_has(imp,flag)    DBIc_is(imp, flag) /* alias for _is */
  188. #define DBIc_on(imp, flag)    (DBIc_FLAGS(imp) |=  (flag))
  189. #define DBIc_off(imp,flag)    (DBIc_FLAGS(imp) &= ~(flag))
  190. #define DBIc_set(imp,flag,on)    ((on) ? DBIc_on(imp, flag) : DBIc_off(imp,flag))
  191.  
  192. #define DBIc_COMSET(imp)    DBIc_is(imp, DBIcf_COMSET)
  193. #define DBIc_COMSET_on(imp)    DBIc_on(imp, DBIcf_COMSET)
  194. #define DBIc_COMSET_off(imp)    DBIc_off(imp,DBIcf_COMSET)
  195.  
  196. #define DBIc_IMPSET(imp)    DBIc_is(imp, DBIcf_IMPSET)
  197. #define DBIc_IMPSET_on(imp)    DBIc_on(imp, DBIcf_IMPSET)
  198. #define DBIc_IMPSET_off(imp)    DBIc_off(imp,DBIcf_IMPSET)
  199.  
  200. #define DBIc_ACTIVE(imp)    (DBIc_FLAGS(imp) &   DBIcf_ACTIVE)
  201. #define DBIc_ACTIVE_on(imp)    /* adjust parent's active kid count */    \
  202.     do {                                \
  203.     imp_xxh_t *ph_com = DBIc_PARENT_COM(imp);            \
  204.     if (!DBIc_ACTIVE(imp) && ph_com && !dirty            \
  205.         && ++DBIc_ACTIVE_KIDS(ph_com) > DBIc_KIDS(ph_com))    \
  206.         croak("panic: DBI active kids > kids");            \
  207.     DBIc_FLAGS(imp) |=  DBIcf_ACTIVE;                \
  208.     } while(0)
  209. #define DBIc_ACTIVE_off(imp)    /* adjust parent's active kid count */    \
  210.     do {                                \
  211.     imp_xxh_t *ph_com = DBIc_PARENT_COM(imp);            \
  212.     if (DBIc_ACTIVE(imp) && ph_com && !dirty            \
  213.         && --DBIc_ACTIVE_KIDS(ph_com) > DBIc_KIDS(ph_com))    \
  214.         croak("panic: DBI active kids < 0");            \
  215.     DBIc_FLAGS(imp) &= ~DBIcf_ACTIVE;                \
  216.     } while(0)
  217.  
  218. #define DBIc_IADESTROY(imp)    (DBIc_FLAGS(imp) &   DBIcf_IADESTROY)
  219. #define DBIc_IADESTROY_on(imp)    (DBIc_FLAGS(imp) |=  DBIcf_IADESTROY)
  220. #define DBIc_IADESTROY_off(imp)    (DBIc_FLAGS(imp) &= ~DBIcf_IADESTROY)
  221.  
  222. #define DBIc_WARN(imp)       (DBIc_FLAGS(imp) &   DBIcf_WARN)
  223. #define DBIc_WARN_on(imp)    (DBIc_FLAGS(imp) |=  DBIcf_WARN)
  224. #define DBIc_WARN_off(imp)    (DBIc_FLAGS(imp) &= ~DBIcf_WARN)
  225.  
  226. #define DBIc_COMPAT(imp)       (DBIc_FLAGS(imp) &   DBIcf_COMPAT)
  227. #define DBIc_COMPAT_on(imp)    (DBIc_FLAGS(imp) |=  DBIcf_COMPAT)
  228. #define DBIc_COMPAT_off(imp)    (DBIc_FLAGS(imp) &= ~DBIcf_COMPAT)
  229.  
  230.  
  231. #ifdef IN_DBI_XS        /* get Handle Common Data Structure    */
  232. #define DBIh_COM(h)             (dbih_getcom(h))
  233. #else
  234. #define DBIh_COM(h)             (DBIS->getcom(h))
  235. #define neatsvpv(sv,len)           (DBIS->neat_svpv(sv,len))
  236. #endif
  237.  
  238.  
  239. /* --- Implementors Private Data Support --- */
  240.  
  241. #define D_impdata(name,type,h)    type *name = (type*)(DBIh_COM(h))
  242. #define D_imp_drh(h) D_impdata(imp_drh, imp_drh_t, h)
  243. #define D_imp_dbh(h) D_impdata(imp_dbh, imp_dbh_t, h)
  244. #define D_imp_sth(h) D_impdata(imp_sth, imp_sth_t, h)
  245. #define D_imp_xxh(h) D_impdata(imp_xxh, imp_xxh_t, h)
  246.  
  247. #define D_imp_from_child(name,type,child)    \
  248.                 type *name = (type*)(DBIc_PARENT_COM(child))
  249. #define D_imp_drh_from_dbh D_imp_from_child(imp_drh, imp_drh_t, imp_dbh)
  250. #define D_imp_dbh_from_sth D_imp_from_child(imp_dbh, imp_dbh_t, imp_sth)
  251.  
  252. #define DBI_IMP_SIZE(n,s) sv_setiv(perl_get_sv((n), GV_ADDMULTI), (s)) /* XXX */
  253.  
  254.  
  255. /* --- Implementors Field Descriptor Support --- */
  256.  
  257.  
  258. /* --- Event Support (VERY LIABLE TO CHANGE) --- */
  259.  
  260. #define DBIh_EVENTx(h,t,a1,a2)    (DBIS->event((h), (t), (a1), (a2)))
  261. #define DBIh_EVENT0(h,t)    DBIh_EVENTx((h), (t), &sv_undef, &sv_undef)
  262. #define DBIh_EVENT1(h,t, a1)    DBIh_EVENTx((h), (t), (a1),      &sv_undef)
  263. #define DBIh_EVENT2(h,t, a1,a2)    DBIh_EVENTx((h), (t), (a1),      (a2))
  264.  
  265. #define ERROR_event    "ERROR"
  266. #define WARN_event    "WARN"
  267. #define MSG_event    "MESSAGE"
  268. #define DBEVENT_event    "DBEVENT"
  269. #define UNKNOWN_event    "UNKNOWN"
  270.  
  271. #define DBIh_CLEAR_ERROR(imp_xxh) (void)( \
  272.         (void)SvOK_off(DBIc_ERR(imp_xxh)),        \
  273.         (void)SvOK_off(DBIc_ERRSTR(imp_xxh)),    \
  274.         (SvPOK(DBIc_STATE(imp_xxh)) ? SvCUR(DBIc_STATE(imp_xxh))=0 : 0)    \
  275.     )
  276.  
  277.  
  278. /* --- DBI State Structure --- */
  279.  
  280. typedef struct {
  281.  
  282. #define DBISTATE_VERSION  9    /* Must change whenever dbistate_t does    */
  283.  
  284.     /* this must be the first member in structure            */
  285.     void (*check_version) _((char *name, int dbis_cv, int dbis_cs, int need_dbixs_cv));
  286.  
  287.     /* version and size are used to check for DBI/DBD version mis-match    */
  288.     U16 version;    /* version of this structure            */
  289.     U16 size;
  290.     U16 xs_version;    /* version of the overall DBIXS / DBD interface    */
  291.  
  292.     I32 debug;
  293.     int debugpvlen;    /* only show dbgpvlen chars when debugging pv's    */
  294.     FILE *logfp;
  295.  
  296.     /* pointers to DBI functions which the DBD's will want to use    */
  297.     char      * (*neat_svpv)    _((SV *sv, STRLEN maxlen));
  298.     imp_xxh_t * (*getcom)    _((SV *h));    /* see DBIh_COM macro    */
  299.     void        (*clearcom)    _((imp_xxh_t *imp_xxh));
  300.     SV        * (*event)    _((SV *h, char *name, SV*, SV*));
  301.     int         (*set_attr)    _((SV *h, SV *keysv, SV *valuesv));
  302.     SV        * (*get_attr)    _((SV *h, SV *keysv));
  303.     AV        * (*get_fbav)    _((imp_sth_t *imp_sth));
  304.     SV        * (*make_fdsv)    _((SV *sth, char *imp_class, STRLEN imp_size, char *col_name));
  305.     int         (*bind_as_num)    _((int sql_type, int p, int s));
  306.     U32         (*hash)        _((char *string, long i));
  307.     AV        * (*preparse)    _((SV *sth, char *statement, U32 flags, U32 spare));
  308.  
  309.     void *pad[10];
  310. } dbistate_t;
  311.  
  312. #ifndef DBIS
  313. #define DBIS              dbis /* default name for dbistate_t variable    */
  314. #endif
  315. #define DBISTATE_DECLARE  static dbistate_t *DBIS
  316. #define DBISTATE_PERLNAME "DBI::_dbistate"
  317. #define DBISTATE_ADDRSV   (perl_get_sv(DBISTATE_PERLNAME, 0x05))
  318.  
  319. #define DBISTATE_INIT_DBIS (DBIS = (dbistate_t*)SvIV(DBISTATE_ADDRSV))
  320.  
  321. #define DBISTATE_INIT {        /* typically use in BOOT: of XS file    */    \
  322.     DBISTATE_INIT_DBIS;    \
  323.     if (DBIS == NULL)    \
  324.     croak("Unable to get DBI state. DBI not loaded.");    \
  325.     DBIS->check_version(__FILE__, DBISTATE_VERSION, sizeof(*DBIS), NEED_DBIXS_VERSION); \
  326. }
  327.  
  328. #define DBILOGFP    (DBIS->logfp)
  329.  
  330. /* --- Assorted Utility Macros    --- */
  331.  
  332. #define DBI_INTERNAL_ERROR(msg)    \
  333.     croak("%s: file \"%s\", line %d", msg, __FILE__, __LINE__);
  334.  
  335. #define DBD_ATTRIBS_CHECK(func, h, attribs)    \
  336.     if ((attribs) && SvOK(attribs)) {        \
  337.     if (!SvROK(attribs) || SvTYPE(SvRV(attribs))!=SVt_PVHV)        \
  338.         croak("%s->%s(...): attribute parameter is not a hash ref",    \
  339.             SvPV(h,na), func);        \
  340.     } else (attribs) = Nullsv
  341.  
  342. #define DBD_ATTRIB_GET_SVP(attribs, key, klen)    \
  343.         hv_fetch((HV*)SvRV(attribs), key, klen, 0)
  344.     
  345. #define DBD_ATTRIB_GET_BOOL(attribs, key,klen, svp, var)        \
  346.     if ( (svp=DBD_ATTRIB_GET_SVP(attribs, key,klen)) != NULL)    \
  347.         var = SvTRUE(*svp)
  348.  
  349. #define DBD_ATTRIB_GET_IV(attribs, key,klen, svp, var)            \
  350.     if ( (svp=DBD_ATTRIB_GET_SVP(attribs, key,klen)) != NULL)    \
  351.         var = SvIV(*svp)
  352.  
  353. #ifndef boolSV    /* added in Perl5.004 */
  354. #define boolSV(bool) ((bool) ? &sv_yes : &sv_no) 
  355. #endif
  356.  
  357. /* end of DBIXS.h */
  358.