synopsis.
the dbbi_o class is a tool for accessing data in RDBMS tables. It has a long and rich history in the Z Directory. Through the 1990's, it was the de-facto object for accessing data in a database. It was originally built based on informix embedded sql (.ec files). It sits below the orthodox_o and dbtable_o classes, but above the dbconnection_o class. It acts as an insulator from database access implementations such as ADO or ODBC. As other objects evolved in the sql group, the line between dbbi and other components became blurred. Now, you can access data and put them into objects via any of dbconnection_o , dbbi_o , and orthodox_o classes. To sort out which to use when, use these general guidelines:

• When the object is either a standard Z Directory orthodox object such as person, business, postal address, etc., or an orthodox subclass created by an external application, use orthodox_o .
• When the underlying table is a standard Z Directory geo table (such as country, airport, state, or school), use dbbi_o for accessing data in these tables. dbtable_o can be used for creating or loading the tables. There is also the topo_load.exe program to create and load these tables. The program comes with the Z Directory installer.
• When you want or need low-level control over each sql-based action, you can use the dbconnection_o class. This class-object can operate on most any accessible table in a relational database.

description.
the dbbi_o class is an acronym for DataBase - (data) Bag Interface and is pronounced like "Debbie". It is commonly labeled "DBBI".

dbbi_o connection to a database.

DBBI maintains a dbconnection object internally. Many programs use a single database connection. The first one opened becomes the default connection, and each DBBI object makes a copy of the default connection, which is a global object (maintained by dbconnection_o). If a connection has been established by this object to a back-end database, each DBBI object, when created, will attempt to open a connection to the same database. These connections are maintained inside the DBBI object, in the dbconnection object 'dbc'.

member functions (primary)

dbbi_o()
SIGNATURE: dbbi_o ()
SYNOPSIS:
creates a a new DBBI object instance. All parameters are set to their default values. the flags z_Do_Row_Count and z_Trim_Char_Fields are set z_Query_In_Progress and z_Cursor_Allocated are cleared. If a database connection has been established by a dbconnection object, the object will attempt to open a connection to the same database automatically (see the main discussion on this page).
 

destructor
SIGNATURE: ~dbbi_o()
SYNOPSIS:
creates a a new DBBI object instance. All parameters are reset to the default construction state. Any open database connections are closed.
TRAITS: this is a virtual function
 

dbbi_o(<args>)
SIGNATURE: dbbi_o (const dbconnection_o &that_dbc)
SYNOPSIS: Creates a new DBBI object. The connection to a database is based on input parameter 'that_dbc'. The parameter settings
PARAMETERS

that_dbc: a [reference] handle to a database connection object (dbconnection_o). If 'that_dbc' represents a valid, open connection, the current DBBI object will attempt to open a connection to the same database. In either case the settings of 'that_dbc' will be copied to the internal 'dbc' object.

 

main_init()
SIGNATURE: int main_init()
SYNOPSIS:
does global configuration for the dbbi_o class required if using threads. It should be called prior to launching any threads that access this class. For example:

#include "z_thread.h"
main (int argc, char *argv[])
{
    z_start();
    dbbi_o::main_init();  // REQUIRED if using dbbi_o
    // application code..
    thread_o t;
    t.run();              // launch any threads
    t.wait();
    z_finish();
}

This is further documented in the user guide page (the example sliver above is very incomplete..).
TRAITS: this is a static member function
 

reset()
SIGNATURE: int reset ()
SYNOPSIS:
resets the DBBI object to the post-default constructor state. Any open database connection is closed; all subtable names are destroyed; and the 'tbl_desc' internal pointer is deleted.
RETURNS: 0
 

is_connected()
SIGNATURE: boolean is_connected()
SYNOPSIS: tells if the [DBBI] object is currently connected to a database.
RETURNS:
TRUE: the current object has an open database connection.
FALSE: the current object is not currently connected.
 

num_rows()
SIGNATURE: count_t num_rows (int *pi = NULL)
SYNOPSIS: this returns the number of rows from the last query executed. There must be a query currently "open".
PARAMETERS

pi: [output] error indicator variable. values:
0: value successfully retrieved
zErr_Resource_NotOpened: no query currently open

RETURNS:
[n >= 0]: the number of rows from a currently open query
-1: error; no query currently open
 

get()
SIGNATURE: int get (rec_dbag_o &, const string_o &, const string_o &, int * = NULL)
SYNOPSIS: WIP
 

add()
SIGNATURE: int add (const rec_dbag_o &, int * = NULL)
SYNOPSIS: WIP
 

update()
SIGNATURE: int update (const rec_dbag_o &row, const string_o &wc = "", int *pi = NULL)
SYNOPSIS: updates the database record, setting it to the contents found in 'row'
DESCRIPTION:
this function builds a big UPDATE SQL statement for the object. It searches for the database record according to the "where clause", specified in 'wc'. By default, the where clause (usually set up in higher-level objects, notably orthodox_o, or manually by the application) is set to the object's "id" column value.
Only the modified column values (as found in input databag 'row') are included in the update. If there are no modified values, no UPDATE is done and the function returns 1.
RETURNS:
0: successful update
1: nothing changed
-1: error occured (detailed in output variable 'pi')
 

remove()
SIGNATURE: int remove (const string_o & = "", int * = NULL)
SYNOPSIS: WIP
 

open()
SIGNATURE: int open (const string_o &sv, const string_o &db, const string_o &ua, const string_o &pd, int *pi = NULL)
SYNOPSIS: opens a connection to a database based on the given parameters
PARAMETERS

• sv: a string containing the database server name
• db: a string containing the database name
• ua: a string containing the database user account
• pd: a string containing the database account's password

DESCRIPTION:
calling this function allows you to control database parameters dynamically. this function simply maps on to a call to dbconnection_o ::open()
 

close()
SIGNATURE: int close()
SYNOPSIS: closes any open database connection. This first closes any query in progress, if there is one open.
 

close_query()
SIGNATURE: int close_query()
SYNOPSIS: closes any open query in progress.
 

add_subtable()
SIGNATURE: int add_subtable (const string_o &s)
SYNOPSIS: this is currently not implemented.
 

exec_sql()
SIGNATURE: int exec_sql (const string_o &query, int *pi = NULL)
SYNOPSIS: WIP
 

exec_add_sql()
SIGNATURE: int exec_add_sql (const string_o &s)
SYNOPSIS: WIP
TRAITS: as of this writing [2013], this function works only for ADO connections.
 

num_columns_in_table()
SIGNATURE: count_t num_columns_in_table (const string_o &table, int *pi)
SYNOPSIS: returns a count of the number of columns ("fields") in a database table whose name matches 'table'
PARAMETERS

pi: [output] error indicator variable. values:
0: value successfully retrieved
zErr_NoConnection: not connected to a database
zErr_Param_BadVal: invalid table name
zErr_UnsupportedProto: connection method (ODBC) not supported

TRAITS: as of this writing [2013], this function works only for ADO connections.
 

last_insert_id()
SIGNATURE: string_o last_insert_id()
SYNOPSIS: WIP
TRAITS: this is an inline function
 

set_table()
SIGNATURE: int set_table (const string_o &new_tab, const rec_dbag_o * const pbag = NULL)
SYNOPSIS:
this sets the internal recursiave databag pointer 'tbl_desc' to either an explicitly provided databag ('pbag'), or, if the parameter is NULL, a "table descriptor" will be automatically generated and the pointer set from the result.
 

make_dbag()
SIGNATURE: rec_dbag_o make_dbag (const string_o &, int *)
SYNOPSIS: WIP
 

make_table_descriptor()
SIGNATURE: rec_dbag_o make_table_descriptor (const string_o &, int *)
SYNOPSIS: WIP
TRAITS: as of this writing [2013], this function works only for ADO connections.
 

examples.
[this line left intentionally blank]

    [example forthcoming]

limitations.
as of this writing [2013], several operations (member functions) of the dbbi_o class have not been implemented for ODBC. This is a severe handicap that will be hopefully remedied quickly. The list of functions that are ADO-only include:

num_columns_in_table()
exec_add_sql()
make_table_descriptor()
row_count() {this is private, but nevertheless needs a ODBC version}

history.

??? 07/05/1996: [informix version] error checking; releasing cursors
??? 09/06/1996: [informix] added [table].[field] to "select [field].."
??? 11/06/1997: [informix] Y2K: fixed a hardcoded "19"
??? 11/07/1997: [informix] parameterized the ID, descriptor, and cursor
??? 02/04/1998: [informix] adding "varchar" to "dbbi_o::add()"
??? 04/06/1998: [informix] adding "text" [/blob] processing; bug fixes
??? 05/09/1998: [informix] found how to get serial ID value
??? 07/05/1998: [informix] took out using the file object to write blobs
??? 07/12/1998: [informix] changed "get()" for dates, year now YYYY fmt
??? 07/22/1998: [informix] added date-time support ("dbtrfr_dtime")
??? 07/23/1998: [informix] changed format string from external format
Thu 05/09/2002: code clean-up (finally); initialized ADO_dbbi_o::m_spCn
Fri 05/10/2002: dbbi_o::open() fixed, return values are uniform
Tue 05/14/2002: test driver added; dbbi_o::open() -minor fixes [--AG]
Tue 05/21/2002: dbbi_o::is_connected() added [--AG]
Sun 02/06/2011: moving ADO-specific junk out of .h file, into .cpp file
Sun 02/06/2011: created ADO_dbbi_o class
Sun 01/15/2012: corrupt code: got both zdb_Access_ODBC & zdb_Access_ADO
Sat 04/21/2012: "dbbi_o::reset()" called after ptrs deleted.. bug fix
Sun 08/05/2012: bug fixes: matrix_dbag_o::get(row,col) -> (col,row)
Sat 08/11/2012: turned off console error msgs, "table w/out identity"
Sun 08/12/2012: dbbi_o::add() - added int * to "exec_sql(id_ins, &ie)"
Sat 01/19/2013: cleaning up NAME_OPEN, NAME_CLOSE hardcoded junk
Sun 01/20/2013: get_idx (sname, "name") -matrix row-col reversal.
Tue 01/22/2013: update() - NULL string, took out adding single-quotes
Wed 02/06/2013: turned off all "is-modified" flags, dbbi_o::get()
Thu 02/07/2013: "dbbi_o::add()" bug fixes
Tue 02/19/2013: took out "ADO_dbbi_o" class; "dbbi_o::open()" gutted
Wed 02/20/2013: dbbi_o::close() -spun off 'close_query()'
Wed 05/22/2013: overhauling global vars .. STRING_QUOTE, NAME_OPEN, ..
Thu 07/11/2013: dbbi_o::add() - turned off all the "is-modified" flags