header file(s): z_dbsubs.h, z_dbconnection.h, z_dbbi.h, z_orthodox.h, z_orthodb_set.h

synopsis.
The SQL group is a large part of the Z Directory. It contains components to access a relational database management system. The Z Directory does not contain a database - that part of computer software has been adequately handled by many others. But the Z Directory needs a database in order to be effective. Although a large part of the Z Directory is independent from databases, without a supporting database, one loses a significant part of the capabilities of the Z Directory system.

Most of the sql group lays the groundwork for more powerful constructs at higher layers that eventually culminate in allowing you to create your own classes that you can readily save to a database:

* dbconnection: the [layer 2] foundation for class for accessing a database. If you are just starting to become familiar wiTH the Z Directory, this class object may be a good place to start, since with it you can do basic database operations, such as create database connections and execute simple SQL statements.

* DBBI (DataBase - dataBag Interface) ("Debbie"): an important [layer 4] class that handles all interaction between your code and a database;

* the orthodox object - the foundation for many higher-level classes that can save themselves to a database. You make a subclass from the orthodox class to be able to use such general-purpose functionality.

classes in this group: dbconnection_o [L02], dbtable_o [L05], dbbi_o [L04], orthodox_o [L06],
                                      orthodb_set_o [L07], simpid_o [L00]

function groups:
                              layer 03 functions group
                              layer 04 functions group
                              layer 05 functions group

description.
As mentioned in the synopsis, the database classes and functions available in the Z Directory require an external database. Access to a database is implemented via ADO (Microsoft platforms only), or ODBC (all supported platforms). On a Microsoft OS, the Active-X Data Object system provides a very seamless, transparent database access. It is particularly well suited to SQL Server databases. For ODBC, you would need to pre-configure an ODBC connection. How to do this is external to the scope of this support section. Once configured, you need just the ODBC connection name, user account and password, passed as parameter-settings to configure objects in the sql group of the Z Directory.

No special libraries are required to the link process when developing your programs when you access an external database via ADO or ODBC. On platforms where either method is available (eg Microsoft), you can dynamically switch between access methods. Generally, a Z Directory sql group object supports only one access method at any given moment.

The database components of the Z Directory form a "stack" model, much like the OSI network stack:

the Orthodox object (orthodox_o) is in layer 6. There is also the relatively minor class related to it: the orthodb_set_o class, in layer 7. The latter is an obscure tool for copying sets of database data from one database to another.

orthodox_o is derived from dbtable_o. It habitats in layer 6, and is a very important member of the Z Directory. From it are derived many "topology" type classes, such as business_o or person_o. Its primary use is to give the ability to store an object, to be later retrieved, when a program is run another time. And since there is no internal, embedded database in the Z Directory, this means that without a database, you lose out on this capability. Although the majority of the Z Directory components don't use a database, that part of the system would be incapacitated. You can still write code as if a database was present - just that executing any operation requiring a database would fail at run time.

orthodox_o is not finicky: many different databases can accomodate it. The virtual access methods ODBC and ADO are available.

The geo database. A set of tables, collectively referred to as the geo database, is employed by several components of the Z Directory and is an integral part of the Z Directory. This "database" need not be literally in a separate database. The tables can be put into any database of your choosing, and is typically done when the Z Directory is installed on a host computer.

When you open a database for the first time in the lifetime of a program, the database becomes the primary, or "master" database. This database will be automatically opened by various Z Directory objects in the sql group, such as the DBBI object (dbbi_o), unless the object is explicitly given a different database to point to. Thus there are 2 databases recognized by the Z Directory: the master, and the geo database. They can be the same database. The geo database will be used (which, again, may be the master database) by components that require "geo" data, such as the proxy object or geographical lookup functions (eg, zgeo_iscountry_valid()). Note that the term "geo" is somewhat of a misnomer, as it includes man- or man-made oriented data, such as person names, proxies, and satellites.

note.
The oid_o class is a subsidiary component that serves the orthodox object. It is a very simple object, maintaining 2 IDs (of 'countable" type, ie count_t). It manages the object's ID. This is complicated by the fact that an object can map onto rows in database tables. The ID values of the object's database image can and usually do differ from the local copy. Thus, this class maintains these 2 IDs, called the internal and external ID. This is more fully discussed in the orthodox class .

examples.
You can find examples how to do simple, low-level SQL statements in the dbconnection object . On the other hand, you can find examples of how to create objects that can store and retrieve themselves into or out of a database via the orthodox object .

For a rich set of objects derived from the orthodox object, visit the "people" group . Classes such as business , worker , and person are all direct subclasses of the orthodox_o class. They provide fully working examples of how the orthodox_o class is used, as well as their own functionality.