NAME

DBE::Driver - A Guide for creating DBE Drivers

DESCRIPTION

This document is a guide for creating a driver for the DBE module. DBE drivers are mainly written in C. A XS function replaces the important data once. Experience with C, Perl, XS and the ExtUtils::MakeMaker module is a prerequisite for succesfully creating a driver.

Driver Layout

DBE communicates to the driver through a structure drv_def_t. The driver communicates to DBE through a structure dbe_t. Both structures are defined in the header file dbe.h, which is installed with DBE. DBE defines structure types dbe_con_t, dbe_res_t and dbe_stmt_t, that are unknown to the driver. In the opposite side DBE uses prototypes to structures which the driver implements. These structures are drv_con_t, drv_res_t and drv_stmt_t.

The following part shows the design of a driver named Dummy.

Required Files

Makefile.PL
README
MANIFEST
DUMMY.pm
DUMMY.xs
dbe_dummy.h
dbe_dummy.c
t/*.t

[ Makefile.PL ]

  use ExtUtils::MakeMaker;
  # use DBE::Driver to get the include settings
  use DBE::Driver;
  
  WriteMakefile(
      NAME => 'DBE::Driver::DUMMY',
      VERSION_FROM => 'DUMMY.pm',
      # dbe include settings
      INC => $ENV{'DBE_INC'},
      LIB => [],
      OBJECT => '$(O_FILES)',
      XS => {'DUMMY.xs' => 'DUMMY.c'},
      C => ['dummy_dbe.c', 'DUMMY.c'],
      H => ['dummy_dbe.h'],
  );

The Perl Makefile Script for the ExtUtils::MakeMaker Module.

[ README ]

  DBE::Driver::DUMMY
  =====================
  
  Driver description
  
  INSTALLATION
  
  To install this library type the following:
  
     perl Makefile.PL
     make
     make test
     make install
  
  COPYRIGHT AND LICENCE
  
  Copyright (C) [author]
  
  The library is free software. You may redistribute and/or modify under
  the terms of either the GNU General Public License or the Artistic
  License, as specified in the Perl README file.

The README file contains important information, like driver description, installation instruction and copyright.

[ MANIFEST ]

  Makefile.PL
  MANIFEST
  README
  DUMMY.pm
  DUMMY.xs
  dummy_dbe.h
  dummy_dbe.c
  t/...                 test files

The MANIFEST is used to distribute the driver with the command "make dist". It contains the names of the files needed. Each filename must stay on one line. Comments can be added right to the filename separated by whitespace characters.

[ DUMMY.pm ]

  package DBE::Driver::DUMMY;
  
  our $VERSION;
  
  BEGIN {
      $VERSION = '1.0.0';
      require XSLoader;
      XSLoader::load(__PACKAGE__, $VERSION);
  }

DUMMY.pm is the first place of contact with Perl. There will be the version of the driver defined and the Perl XS module loaded.

Note: The name of the module must be written in upper case characters.

[ DUMMY.xs ]

  #include "dummy_dbe.h"
  
  MODULE = DBE::Driver::DUMMY        PACKAGE = DBE::Driver::DUMMY
  
  void
  init(dbe, drv)
      void *dbe;
      void *drv;
  PPCODE:
      /* set the pointer to dbe_t */
      g_dbe = (const dbe_t *) dbe;
      /* return a pointer to the dummy driver structure */
      XSRETURN_IV(PTR2IV(&g_dbe_drv));

The Perl XS module implements a function init. This function will be called once by DBE. The first parameter is a pointer to the structure dbe_t. The second parameter is a pointer to the dbe driver structure dbe_drv_t, which is unknown to the driver and can be mostly ignored. The function must return a pointer to the driver definition structure drv_def_t.

Note: The name of the module must be written in upper case characters.

[ dummy_dbe.h ]

  /* include the dbe header file */
  #include <dbe.h>
  
  /* pointer to the dbe structure, see dbe.h */
  extern const dbe_t *g_dbe;
  
  /* driver definition structure, see dbe.h */
  extern const drv_def_t g_drv_def;

The header file includes dbe.h and prototypes the two global variables dbe_t * and drv_def_t which are used in the init function in the Perl XS module.

[ dummy_dbe.c ]

  #include "dummy_dbe.h"
  
  /* global pointer to dbe_t */
  const dbe_t *g_dbe;
  
  /* implementation of the driver starts here */
  
  drv_con_t *dummy_drv_connect (dbe_con_t *dbe_con, char **args, int argc)
  {
      g_dbe->set_error(dbe_con, -1, "Not yet implemented");
      return NULL;
  }
  
  ...
  
  /* fill drv_def_t with our driver */
  
  const drv_def_t g_drv_def =
  {
      /* dbe version */
      DBE_VERSION,
      /* description */
      "Dummy DBE Driver " XS_VERSION,
      /* functions */
      NULL, /* mem_free */
      NULL, /* drv_free */
      dummy_drv_connect,
      ...
  };

The C file implements the driver functions and fills it into the structure drv_def_t. It also defines a global pointer to structure dbe_t.

[ t/*.t ]

Directory containing test scripts. Please see ExtUtils::MakeMaker for details.

Functions provided by DBE

Functions provided by DBE are defined in dbe_t.

The dbe_t datatype

The dbe_t type defines a structure struct st_dbe. The elements of st_dbe are explained below.

const int st_dbe::version

The installed version of DBE.

void (*st_dbe::dbe_set_error) ( dbe_con_t *dbe_con, int code, const char *msg, ... )

Sets an error code and message to the given connection handle. Additional arguments can be passed to complete msg with vsprintf.

Example

  /* set an error */
  g_dbe->dbe_set_error(
      dbe_con, errno, "Error: table '%s' does not exist", tablename
  );
  
  /* clear the error */
  g_dbe->dbe_set_error(dbe_con, 0, NULL);

void (*st_dbe::trace) ( dbe_con_t *dbe_con, int level, int show_caller, const char *msg, ... )

Trace a message with specified level. Available levels are:

  DBE_TRACE_NONE            do not trace
  DBE_TRACE_SQL             trace sql statements
  DBE_TRACE_SQLFULL         trace sql functions around statements
  DBE_TRACE_ALL             trace all

Example

  /* without caller */
  g_dbe->trace(dbe_con, DBE_TRACE_ALL, FALSE, "Connected to %s", hostname);
  /* output:  Connected to [hostname] */
  
  /* or with caller */
  g_dbe->trace(dbe_con, DBE_TRACE_SQL, TRUE, "sql(%s)", statement);
  /* output:  sql([statement]) at [file] line [line] */

void (*st_dbe::set_base_class) ( dbe_drv_t *dbe_drv, enum dbe_object obj, const char *classname )

Overwrites the default class names of connection, result set or statement objects. Default classes are DBE::CON, DBE::RES and DBE::STMT.

void *(*st_dbe::get_object) ( enum dbe_object obj, SV *this )

Retrieves a pointer to a driver object. Can be used in XS functions within an overloaded class.

Example of a sub classed connection object

[DUMMY.XS]

  MODULE = DBE::Driver::DUMMY        PACKAGE = DBE::Driver::DUMMY
  
  void
  init(dbe, drv)
      void *dbe;
      void *drv;
  PPCODE:
      g_dbe = (const dbe_t *) dbe;
      
      /* set connection class to DBE::CON::DUMMY */
      g_dbe->set_base_class(
          (dbe_drv_t *) drv, DBE_OBJECT_CON, "DBE::CON::DUMMY");
      
      XSRETURN_IV(PTR2IV(&g_dbe_drv));
  
  
  MODULE = DBE::Driver::DUMMY        PACKAGE = DBE::CON::DUMMY
  
  BOOT:
  {
      /* inherit DBE::CON */
      AV *isa = get_av("DBE::CON::DUMMY::ISA", TRUE);
      av_push(isa, newSVpvn("DBE::CON", 8)); 
  }
  
  void
  test(this)
      SV *this;
  PREINIT:
      drv_con_t *con;
  PPCODE:
      con = (drv_con_t *) g_dbe->get_object(DBE_OBJECT_CON, this);
      if (con == NULL)
          XSRETURN_EMPTY;
      /* do something with the connection */
      Perl_warn(aTHX_ "test was succesful");
      XSRETURN_YES;

call the new function

  $con = DBE->connect('driver' => 'dummy');
  $con->test();

void *(*st_dbe::handle_error_xs) ( dbe_con_t *dbe_con, enum dbe_object obj, SV *this, const char *action )

Starts the error handler from you XS function.

Example

  void
  test(this)
      SV *this;
  PREINIT:
      drv_con_t *con;
  PPCODE:
      con = (drv_con_t *) g_dbe->get_object(DBE_OBJECT_CON, this);
      if (con == NULL)
          XSRETURN_EMPTY;
      g_dbe->set_error(con->dbe_con, -1, "test error message");
      g_dbe->handle_error_xs(con->dbe_con, DBE_OBJECT_CON, this, "test");
      // code here would be unreachable

char *(*st_dbe::error_str) ( int errnum, char *buf, size_t buflen )

Fills the error message of a system error into buf. Returns the pointer to buf on success or NULL on error

Driver Result Sets

dbe_res_t *(*st_dbe::alloc_result) ( dbe_con_t *dbe_con, drv_res_t *drv_res, u_long num_fields ): Allocates a dbe result set with a driver result set.
void (*st_dbe::free_result) ( dbe_res_t *dbe_res ): Frees a dbe result set that was allocated by alloc_result()

Virtual Result Sets

dbe_res_t *(*st_dbe::vres_create) ( dbe_con_t *dbe_con )

Creates a virtual result set and returns a pointer to the dbe result set.

void (*st_dbe::vres_free) ( dbe_res_t *dbe_res )

Frees a virtual result set.

int (*st_dbe::vres_add_column) ( dbe_res_t *dbe_res, const char *name, size_t name_length, enum dbe_type type )

Adds a field to a virtual result set. enum dbe_type is defined in dbe.h.

int (*st_dbe::vres_add_row) ( dbe_res_t *dbe_res, dbe_str_t *data )

Adds a row to a virtual result set; the row data must be conform to the column types. NULL pointer in the value part of dbe_str_t define NULL values.

DBE_TYPE_INTEGER points to int
DBE_TYPE_DOUBLE points to double
DBE_TYPE_BIGINT points to xlong
DBE_TYPE_VARCHAR points to char
DBE_TYPE_BINARY points to void

Example of a Virtual Result set

  dbe_res_t *vrt_res;
  dbe_str_t data[2];
  int id;
  
  /* create a virtual result set
     'dbe_con' is given by 'st_drv_def::drv_connect' */
  vrt_res = g_dbe->vres_create(dbe_con);
  
  /* add two columns to the virtual result set */
  g_dbe->vres_add_column(vrt_res, "ID", 2, DBE_TYPE_INTEGER);
  g_dbe->vres_add_column(vrt_res, "NAME", 4, DBE_TYPE_VARCHAR);
  
  /* set the data for the first row */
  /* first field points to int */
  data[0].value = (char *) &id;
  id = 1;
  /* second field points to char */
  data[1].value = "Anderson";
  data[1].length = 8;
  
  /* add the row to the virtual result set */
  g_dbe->vres_add_row(vrt_res, data);

Search Patterns and Regular Expressions

regexp* (*st_dbe::regexp_from_string) ( const char *str, size_t str_len )

Create a Perl regular expression from a string. The expression string must be enclosed by tags and can contain additional options. (i.e. "/^table_*/i")

regexp* (*st_dbe::regexp_from_pattern) ( const char *pattern, size_t pattern_len, int force )

Converts a SQL search pattern to a Perl regular expression (i.e. pattern "%FOO\_BAR_" to regexp /.*?FOO_BAR./).

Returns NULL if pattern contains no search parameters and force was set to FALSE

int (*st_dbe::regexp_match) ( regexp *re, char *str, size_t str_len )

Counts the matches of a regular expression on str and returns the number of hits.

void (*st_dbe::regexp_free) ( regexp *re )

Frees a Perl regexp.

size_t (*st_dbe::unescape_pattern) ( char *str, size_t str_len, const char esc )

Unescapes a search pattern (i.e. table\_name to table_name) within the string an returns the resulting size. Parameter esc defines the escape character.

SV *(*st_dbe::dbe_escape_pattern) ( const char *str, size_t str_len, const char esc )

Escapes a search pattern (i.e table_name to table\_name) and returns the result string as SV. Parameter esc defines the escape character.

Unicode functions

unsigned int (*st_dbe::towupper) ( unsigned int c ): Converts an unicode character (widechar/utf-16be) to upper case.
unsigned int (*st_dbe::towlower) ( unsigned int c ): Converts an unicode character (widechar/utf-16be) to lower case.
int (*st_dbe::utf8_to_unicode) ( const char *src, size_t src_len, char *dst, size_t dst_max ): Converts an utf-8 string in src to unicode and writes it into dst. Returns the number of bytes written, or -1 on invalid utf-8 sequence. It is safe to make dst twice bigger then src.
int (*st_dbe::unicode_to_utf8) ( const char *src, size_t src_len, char *dst, size_t dst_max ): Converts an unicode string in src to utf-8 and writes it into dst. Returns the length of dst without NULL terminating character, or -1 on invalid unicode string. It is safe to make dst twice bigger then src.
int (*st_dbe::utf8_toupper) ( const char *src, size_t src_len, char *dst, size_t dst_max ): Converts an utf-8 string in src to upper case and writes it into dst. Returns the length of dst without \0 terminating character, or -1 on invalid utf-8 sequence. It is safe to make dst twice bigger then src.
int (*st_dbe::utf8_tolower) ( const char *src, size_t src_len, char *dst, size_t dst_max ): Converts an utf-8 string in src to lower case and writes it into dst. Returns the length of dst without \0 terminating character, or -1 on invalid utf-8 sequence. It is safe to make dst twice bigger then src.

DBE LOB functions

SV *(*st_dbe::lob_stream_alloc) ( dbe_con_t *dbe_con, void *context ): Allocates a DBE::LOB class with the drivers lob stream context.
void (*st_dbe::lob_stream_free) ( dbe_con_t *dbe_con, void *context ): Frees a lob stream and destroys the DBE::LOB class.
void *(*st_dbe::lob_stream_get) ( dbe_con_t *dbe_con, SV *sv ): Resturns the context of a lob stream by the given class variable.

Functions provided by the Driver

Functions provided by the driver are defined in drv_def_t.

The dbe_drv_t datatype

The drv_def_t type defines a structure struct st_drv_def. The elements of st_drv_def are explained below. Unused functions can be set to NULL.

Constants

const int st_drv_def::version: The DBE version of the driver. Must be filled with DBE_VERSION.
const char* st_drv_def::description: A description of the driver. For example ("Dummy DBE Driver " XS_VERSION)

Misc Functions

void (*st_drv_def::mem_free) ( void *ptr ): Frees memory allocated by the driver.

Driver Functions

void (*st_drv_def::drv_free) ( drv_def_t *drv_def )

Can be used to cleanup the driver.

drv_con_t* (*st_drv_def::drv_connect) ( dbe_con_t *dbe_con, char **args, int argc )

Makes a connection to the driver.

Parameter dbe_con contains a pointer to the dbe connection object. It should be hold by the driver to communicate to DBE through dbe_t.

Returns a pointer to the driver connection object, or NULL on failure.

Connection Methods

int (*st_drv_def::con_reconnect) ( drv_con_t *drv_con )

Resets the connection an restores previous settings. Returns DBE_OK on success, or DBE_ERROR on failure.

void (*st_drv_def::con_free) ( drv_con_t *drv_con )

Closes the connection frees its resources.

void (*st_drv_def::con_set_trace) ( drv_con_t *drv_con, int level )

Sets the trace level to the connection object. Can be used to check the trace level before sending the message to DBE.

int (*st_drv_def::con_set_charset) ( drv_con_t *drv_con, const char *charset, size_t cs_len )

Sets the client character set. Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_get_charset) ( drv_con_t *drv_con, dbe_str_t *cs )

Gets the character set used by the client. cs->value is allocated with 128 bytes, cs->length must not set. Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_query) ( drv_con_t *drv_con, const char *sql, size_t sql_len, dbe_res_t **dbe_res )

Performs a simple query.

For selectives queries the result set must be created with st_dbe::alloc_result() or st_dbe::vres_create(). (see the dbe_t datatype for details)

For other type of SQL statements, UPDATE, DELETE, DROP, etc, parameters dbe_res must not set.

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

u_xlong (*st_drv_def::con_insert_id) ( drv_con_t *drv_con, const char *catalog, size_t catalog_len, const char *schema, size_t schema_len, const char *table, size_t table_len, const char *field, size_t field_len )

Returns the auto unique value generated by the previous INSERT or UPDATE statement.

u_xlong (*st_drv_def::con_affected_rows) ( drv_con_t *drv_con )

Returns the number of affected rows in a previous SQL operation.

Returns the number of rows changed (for UPDATE), deleted (for DELETE), or inserted (for INSERT).

For SELECT statements, con_affected_rows() works like res_num_rows().

Transaction Methods

int (*st_drv_def::con_auto_commit) ( drv_con_t *drv_con, int mode )

Turns on or off auto-commit mode on queries for the database connection.

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_begin_work) ( drv_con_t *drv_con )

Turns off auto-commit mode for the database connection until transaction is finished.

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_commit) ( drv_con_t *drv_con )

Commits the current transaction for the database connection.

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_rollback) ( drv_con_t *drv_con )

Rollbacks the current transaction for the database.

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

Statement Methods

int (*st_drv_def::con_prepare) ( drv_con_t *drv_con, const char *sql, size_t sql_len, drv_stmt_t **drv_stmt )

Prepares a SQL statement. Parameter 'drv_stmt' must be set to a pointer with the driver statement structure.

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

void (*st_drv_def::stmt_free) ( drv_stmt_t *drv_stmt )

Closes and frees a statement.

int (*st_drv_def::param_count) ( drv_stmt_t *drv_stmt )

Returns the number of parameters in the statement.

int (*st_drv_def::stmt_bind_param) ( drv_stmt_t *drv_stmt, u_long p_num, SV *p_val, char p_type )

Binds a value to a parameter in the statement.

Parameter p_num indicates the number of the parameter starting at 1.

Parameter p_val contains a Perl scalar variable.

Parameter p_type can be one of the following:

  'i'   corresponding value has type integer 
  'd'   corresponding value has type double 
  's'   corresponding value has type string 
  'b'   corresponding value has type binary
  '\0'  autodetect type of the value

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::stmt_param_position) ( drv_stmt_t *drv_stmt, const char *name, size_t name_len, u_long *p_pos )

Gets the position of parameter by given parameter name. First parameter is starting at 1.

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::stmt_execute) ( drv_stmt_t *drv_stmt, dbe_res_t **dbe_res )

Executes a statement.

For selectives queries the result set must be created with st_dbe::alloc_result() or st_dbe::vres_create(). (see the dbe_t datatype for details)

For other type of SQL statements, UPDATE, DELETE, DROP, etc, parameters drv_res must not set.

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

Result Set Methods

void (*st_drv_def::res_free) ( drv_res_t *drv_res )

Closes and frees a result set.

u_xlong (*st_drv_def::res_num_rows) ( drv_res_t *drv_res )

Returns the number of rows in the result set.

int (*st_drv_def::res_fetch_names) ( drv_res_t *drv_res, dbe_str_t *names, int *flags )

Fetches the field names representing in the result set.

The names array is allocated by DBE.

Set flags to DBE_FREE_ITEMS if DBE have to free the value part in the names array.

Returns DBE_OK on success, or DBE_ERROR on failure.

int (*st_drv_def::res_fetch_row) ( drv_res_t *drv_res, SV **row )

Retrieves the next row in the result set.

The row array is allocated by DBE.

The values must set without sv_2mortal(). Undefined values should point to NULL instead of &Pl_sv_undef.

Returns DBE_OK on success, or DBE_NORESULT if no row becomes available anymore.

u_xlong (*st_drv_def::res_row_seek) ( drv_res_t *drv_res, u_xlong offset )

Sets the actual position of the row cursor in the result set (starting at 0). Returns the previous position of the row cursor.

u_xlong (*st_drv_def::res_row_tell) ( drv_res_t *drv_res )

Returns the current position of the row cursor in the result set. First row starts at 0.

int (*st_drv_def::res_fetch_field) ( drv_res_t *drv_res, int offset, SV ***hash, int *flags )

Gets information about a column in the result set. Call this function repeatedly to retrieve information about all columns in the result set.

The hash array must be allocated by the driver and contains an even number of elements in key-value style.

Set flags to DBE_FREE_ARRAY to tell DBE to free the hash array.

The values must set without sv_2mortal. Undefined values must point to NULL instead of &Pl_sv_undef.

Returns the total number of elements, which must be an even number.

int (*st_drv_def::res_field_seek) ( drv_res_t *drv_res, int offset )

Sets the field cursor to the given offset (starting at 0) and returns the previous position of the field cursor.

int (*st_drv_def::res_field_tell) ( drv_res_t *drv_res )

Returns the current position of the field cursors in the result set.

Driver LOB Functions

int (*st_drv_def::con_lob_size) ( drv_con_t *drv_con, void *context )

Returns the size of the lob in bytes or characters, or DBE_NO_DATA when it is unknown, or DBE_ERROR on error.

int (*st_drv_def::con_lob_read) ( drv_con_t *drv_con, void *context, int *offset, char *buffer, int length )

Reads length bytes/characters from the lob starting at *offset. The new offset must be set by the driver.

Returns the number of bytes read, or DBE_NO_DATA on eof, or DBE_ERROR on error.

int (*st_drv_def::con_lob_write) ( drv_con_t *drv_con, void *context, int *offset, char *buffer, int length )

Write length bytes/characters to the lob starting at *offset. The new offset must be set by the driver.

Returns the number of bytes written, or DBE_ERROR on error.

int (*st_drv_def::con_lob_close) ( drv_con_t *drv_con, void *context )

Closes the lob stream.

Returns DBE_OK on success, or DBE_ERROR on failure.

Misc Functions

SV* (*st_drv_def::drv_quote) ( drv_con_t *drv_con, const char *str, size_t str_len )

Quote a value for use as a literal value in an SQL statement, by escaping any special characters (such as quotation marks) contained within the string and adding the required type of outer quotation marks.

Returns a Perl SV without setting sv_2mortal, or NULL on undefined value.

SV* (*st_drv_def::drv_quote_bin) ( drv_con_t *drv_con, const char *bin, size_t bin_len )

Quote a value for use as a binary value in an SQL statement. Skip this function if the driver does not support binary values in SQL statements.

Returns a Perl SV without setting sv_2mortal, or NULL on undefined value.

SV* (*st_drv_def::drv_quote_id) ( drv_con_t *drv_con, const char **args, int argc )

Quote identifiers (table name etc.) for use in an SQL statement, by escaping any special characters it contains and adding the required type of outer quotation marks.

Returns a Perl SV without setting sv_2mortal, or NULL on undefined value.

Information and Catalog Functions

int (*con_getinfo) ( drv_con_t *drv_con, int type, void *val, int cbvalmax, int *pcbval, enum dbe_getinfo_type *rtype )

Get general information about the DBMS that the application is currently connected to.

Parameters

drv_con

Pointer to driver connection structure.

type

Type of information desired. (should be compatible to ODBC 3.0)

val

[output] Pointer to buffer where this function stores the desired information. It has a size of 256 bytes minimum. Depending on the type of information being retrieved, 4 types of information can be returned:

  - DBE_GETINFO_SHORTINT   / 16-bit integer value 
  - DBE_GETINFO_INTEGER    / 32-bit integer value 
  - DBE_GETINFO_32BITMASK  / 32-bit binary value 
  - DBE_GETINFO_STRING     / Null-terminated character string

the returned type must be set to rtype

cbvalmax

Maximum length of the buffer pointed by val pointer.

pcbval

[output] Pointer to location where this function returns the total number of bytes available to return the desired information.

rtype

[output] The return type of information. See also val

Return Codes

DBE_OK
DBE_ERROR
DBE_CONLOST
DBE_GETINFO_ERR_INVALIDARG
DBE_GETINFO_ERR_TRUNCATE

int (*st_drv_def::con_type_info) ( drv_con_t *drv_con, int sql_type, dbe_res_t **dbe_res )

Returns information about the data types that are supported by the DBMS.

Parameters

drv_con

Pointer to driver connection structure.

sql_type

The SQL data type being queried. The supported types are:

SQL_ALL_TYPES
SQL_BIGINT
SQL_BINARY
SQL_VARBINARY
SQL_CHAR
SQL_DATE
SQL_DECIMAL
SQL_DOUBLE
SQL_FLOAT
SQL_INTEGER
SQL_NUMERIC
SQL_REAL
SQL_SMALLINT
SQL_TIME
SQL_TIMESTAMP
SQL_VARCHAR

If SQL_ALL_TYPES is specified, information about all supported data types would be returned in ascending order by TYPE_NAME. All unsupported data types would be absent from the result set.

dbe_res

[output] A pointer to a result set, created with st_dbe::alloc_result or st_dbe::vres_create. See the DBE manpage for a description of the columns.

Return Values

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_data_sources) ( drv_con_t *drv_con, char *wild, size_t wild_len, SV ***names, int *count )

Retrieves a list of data sources (databases) available.

Parameters

drv_con: Pointer to driver connection structure.
wild: wild may contain the wildcard characters "%" or "_", or may be a NULL pointer to match all datasources
wild_len: The length of wild in characters.
names: [output] names contains the list of data sources. The array must be allocated by the driver.
count: [output] Number of datasources in names

Return Values

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_tables) ( drv_con_t *drv_con, char *catalog, size_t catalog_len, char *schema, size_t schema_len, char *table, size_t table_len, char *type, size_t type_len, dbe_res_t **dbe_res )

Gets a result set that can be used to fetch information about tables and views that exist in the database.

Parameters

drv_con

Pointer to driver connection structure.

catalog

Buffer that may contain a pattern-value to qualify the result set. Catalog is the first part of a three-part table name.

catalog_len

Length of catalog.

schema

Buffer that may contain a pattern-value to qualify the result set by schema name.

schema_len

Length of schema.

table

Buffer that may contain a pattern-value to qualify the result set by table name.

table_len

Length of table.

type

Buffer that may contain a value list to qualify the result set by table type.

The value list is a list of values separated by commas for the types of interest. Valid table type identifiers may include: ALL, BASE TABLE, TABLE, VIEW, SYSTEM TABLE. If type argument is a NULL pointer or a zero length string, then this is equivalent to specifying all of the possibilities for the table type identifier.

If SYSTEM TABLE is specified, then both system tables and system views (if there are any) are returned.

type_len

Length of type.

dbe_res

[output] A pointer to a result set, created with st_dbe::alloc_result or st_dbe::vres_create. See the DBE manpage for a description of the columns.

Return Values

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_columns) ( drv_con_t *drv_con, char *catalog, size_t catalog_len, char *schema, size_t schema_len, char *table, size_t table_len, char *column, size_t column_len, dbe_res_t **dbe_res )

Gets a list of columns in the specified tables.

Parameters

drv_con: Pointer to driver connection structure.
catalog: Buffer that may contain a pattern-value to qualify the result set. Catalog is the first part of a three-part table name.
catalog_len: Length of catalog.
schema: Buffer that may contain a pattern-value to qualify the result set by schema name.
schema_len: Length of schema.
table: Buffer that may contain a pattern-value to qualify the result set by table name.
table_len: Length of table.
column: Buffer that may contain a pattern-value to qualify the result set by column name.
column_len: Length of column.
dbe_res: [output] A pointer to a result set, created with st_dbe::alloc_result or st_dbe::vres_create. See the DBE manpage for a description of the columns.

Return Values

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_primary_keys) ( drv_con_t *drv_con, char *catalog, size_t catalog_len, char *schema, size_t schema_len, char *table, size_t table_len, dbe_res_t **dbe_res )

Gets a list of column names that comprise the primary key for a table.

Parameters

drv_con: Pointer to driver connection structure.
catalog: Catalog qualifier of a 3 part table name.
catalog_len: Length of catalog.
schema: Schema qualifier of table name.
schema_len: Length of schema.
table: Table name.
table_len: Length of table.
dbe_res: [output] A pointer to a result set, created with st_dbe::alloc_result or st_dbe::vres_create. See the DBE manpage for a description of the columns.

Return Values

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_foreign_keys) ( drv_con_t *drv_con, char *pk_cat, size_t pk_cat_len, char *pk_schem, size_t pk_schem_len, char *pk_table, size_t pk_table_len, char *fk_cat, size_t fk_cat_len, char *fk_schem, size_t fk_schem_len, char *fk_table, size_t fk_table_len, dbe_res_t **dbe_res )

Gets information about foreign keys for the specified table.

Parameters

drv_con: Pointer to driver connection structure.
pk_cat: Catalog qualifier of the primary key table.
pk_cat_len: Length of pk_cat.
pk_schem: Schema qualifier of the primary key table.
pk_schem_len: Length of pk_schem.
pk_table: Name of the table name containing the primary key.
pk_table_len: Length of pk_table.
fk_cat: Catalog qualifier of the table containing the foreign key.
fk_cat_len: Length of fk_cat.
fk_schem: Schema qualifier of the table containing the foreign key.
fk_schem_len: Length of fk_schem.
fk_table: Name of the table containing the foreign key.
fk_table_len: Length of fk_table.
dbe_res: [output] A pointer to a result set, created with st_dbe::alloc_result or st_dbe::vres_create. See the DBE manpage for a description of the columns.

Usage

If pk_table contains a table name, and fk_table is an empty string, function returns a result set that contains the primary key of the specified table and all of the foreign keys (in other tables) that refer to it.

If fk_table contains a table name, and pk_table is an empty string, function returns a result set that contains all of the foreign keys in the specified table and the primary keys (in other tables) to which they refer.

If both pk_table and fk_table contain table names, function returns the foreign keys in the table specified in FKTableName that refer to the primary key of the table specified in PKTableName. This should be one key at the most.

If the schema qualifier argument that is associated with a table name is not specified, then the schema name defaults to the one currently in effect for the current connection.

Return Values

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_statistics) ( drv_con_t *drv_con, const char *catalog, size_t catalog_len, const char *schema, size_t schema_len, const char *table, size_t table_len, int unique_only, dbe_res_t **dbe_res )

Retrieves a list of statistics about a single table and the indexes associated with the table.

Parameters

drv_con: Pointer to driver connection structure.
catalog: Catalog qualifier of a 3 part table name.
catalog_len: Length of catalog.
schema: Schema qualifier of table name.
schema_len: Length of schema.
table: Table name.
table_len: Length of table.
unique_only: On a TRUE value only unique indexes are returned, else all indexes are returned.
dbe_res: [output] A pointer to a result set, created with st_dbe::alloc_result or st_dbe::vres_create. See the DBE manpage for a description of the columns.

Return Values

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

int (*st_drv_def::con_special_columns) ( drv_con_t *con, int identifier_type, const char *catalog, size_t catalog_len, const char *schema, size_t schema_len, const char *table, size_t table_len, int scope, int nullable, dbe_res_t **dbe_res )

Retrieves the following information about columns within a specified table:

The optimal set of columns that uniquely identifies a row in the table.
Columns that are automatically updated when any value in the row is updated by a transaction.

Parameters

drv_con

Pointer to driver connection structure.

identifier_type

Must be one of the following values:

SQL_BEST_ROWID: Returns the optimal column or set of columns that, by retrieving values from the column or columns, allows any row in the specified table to be uniquely identified. A column can be either a pseudo-column specifically designed for this purpose (as in Oracle ROWID or Ingres TID) or the column or columns of any unique index for the table.

SQL_ROWVER: Returns the column or columns in the specified table, if any, that are automatically updated by the data source when any value in the row is updated by any transaction (as in SQLBase ROWID or Sybase TIMESTAMP).

catalog

Catalog qualifier of a 3 part table name.

catalog_len

Length of catalog.

schema

Schema qualifier of table name.

schema_len

Length of schema.

table

Table name.

table_len

Length of table.

scope

Minimum required scope of the rowid. The returned rowid may be of greater scope. Must be one of the following:

SQL_SCOPE_CURROW: The rowid is guaranteed to be valid only while positioned on that row. A later reselect using rowid may not return a row if the row was updated or deleted by another transaction.

SQL_SCOPE_TRANSACTION: The rowid is guaranteed to be valid for the duration of the current transaction.

SQL_SCOPE_SESSION: The rowid is guaranteed to be valid for the duration of the session (across transaction boundaries).

nullable

Determines whether to return special columns that can have a NULL value. Must be one of the following:

SQL_NO_NULLS: Exclude special columns that can have NULL values. Some drivers cannot support SQL_NO_NULLS, and these drivers will return an empty result set if SQL_NO_NULLS was specified. Applications should be prepared for this case and request SQL_NO_NULLS only if it is absolutely required.

SQL_NULLABLE: Return special columns even if they can have NULL values.

dbe_res

[output] A pointer to a result set, created with st_dbe::alloc_result or st_dbe::vres_create. See the DBE manpage for a description of the columns.

Return Values

Returns DBE_OK on success, or DBE_CONLOST on connection error, or DBE_ERROR on other failure.

AUTHORS

Navalla org., Christian Mueller, http://www.navalla.org/

COPYRIGHT

DBE::Driver is a part of the DBE module and may be used under the same license agreement.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

Driver Layout

[ Makefile.PL ]

[ README ]

[ MANIFEST ]

[ DUMMY.pm ]

[ DUMMY.xs ]

[ dummy_dbe.h ]

[ dummy_dbe.c ]

[ t/*.t ]

Functions provided by DBE

The dbe_t datatype

Driver Result Sets

Virtual Result Sets

Search Patterns and Regular Expressions

Unicode functions

DBE LOB functions

Functions provided by the Driver

The dbe_drv_t datatype

Constants

Misc Functions

Driver Functions

Connection Methods

Transaction Methods

Statement Methods

Result Set Methods

Driver LOB Functions

Misc Functions

Information and Catalog Functions

AUTHORS

COPYRIGHT

SEE ALSO

Module Install Instructions