Example Explained

CachéAddConnection( cNameSpace ) obtains a connection handle to the namespace supplying ServerIP address, port, user and password information. Connection handle is stored in a persistent object inside the application and becomes the reference point for all subsequent RDD functions. More than one connection can be opened simultaneously for different servers and/or different namespaces on the same server. Tables can be distributed on different servers and/or namespaces as per demand. If connection is established successfully, RDD returns a value greater than 0. A value of 0 represents failure. If establishing a connection fails application should be exited.

The code above is peculiar to CachéRDD only. None of the above functions relates to RDD layer. But for CachéRDD to take charge of subsequent operations this is the starting point.

<aStr> array holds the information about the structure of table which along with table name and schema is passed to CachéRDD. Please refer to "Tables & Schemas" to know how table names and schemas are handled in CachéRDD. CachéRDD parses the supplied parameters to Caché equivalents, creates a new class object with ##class(%ictionary.ClassDefinition).%New(), inserts properties to match <aStr>, defines two CALLBACK methods and two TRIGGERs, saves and compiles the class. Click here to review how the class code looks after DbCreate() finishes.

RDD provides two different modes to open a table, viz., SHARED and EXCLUSIVE. Exclusive mode implies that if one process has opened the table under it, no other process can open the table. In RDBMS there is no concept of, first opening/closing, second SHARED/EXCLUSIVE. So I had to simulate this behavior. I took advantage of Caché's superb locking mechanism. I achieved it for only RDD oriented processes but could not force this mechanism to be recognized by non-RDD processes. The reason is obivous - in RDBMS world every table has a SHARED status by design.

If there are no non-RDD processes active on such tables under use by RDD processes, the behavior is exactly the same what Clipper RDD documents. On the contrary, it is the responsibility of the developer to design non-RDD processes to respect to EXCLUSIVE use.

The code snippet above opens the table in SHARED mode. CachéRDD initializes a few public variables to hold various info about its status, viz., storage globals - data, index and streams, alias, work area, index definitions and so forth. CachéRDD returns the success or failure of such exercise and post it to NetErr() stack short for "NetWork Error" which is later checked by the application. If NetErr() returns TRUE, application need to take corrective measures.

Most demanding aspect of Clipper RDD has been the architecture of index management. Besides column based plain indexes, Clipper RDD features compound indexes, that is, index based on two or more columns, conditional indexes, unique indexes. In all type of indexes columns can be formatted via function calls, both compiler-defined or user-defined. Any number of nested function calls are supported to format a field. This all is not possible in any RDBMS as is, or correct me if something I may be missing. And because rest of the RDD functionality is based heavily on such indexes, it was a MUST to have this in CachéRDD. Single column based plain indexes are the only type similar to what SQL offers. And it took major chunk of development time.

In contrast to SQL which inserts and populate fields in one go, XBASE inserts a blank record before populating the fields. When an insertion is made that record is locked so that no other process could update it. APPEND BLACK requests CachéRDD to insert a blank record, obtain a lock on it, and return its %ID. RDD layer checks for if %ID > 0 and acts accordingly. Once the insertion is successful fields are populated with REPLACE command. After relevant CachéRDD field buffers are filled a request to commit the record is sent with DbCommit() command. Finally DbUnlock() is issued to let the record avaible to other processes to manipulate.

Because a record insert operation is done twice Caché update the data and index globals twice. This is the overhead I could not eliminate, not because Caché doesn't support but because it is RDD's mandatory behavior.

A table can be navigated in natural order or in the order of current index. Clipper RDD provides powerful commands to address those issues. Once an order is set - natural or index, all subsequent navigation commands respect it.

These are the commands to set the controlling index order:

These are the navigation commands in Clipper RDD:

These are the commands to check if above movements succeeded or failed:

These are the commands to search a particular record:

The above sets of commands comprise the backbone of navigation in XBASE dialects. This approach of table navigation is where XBASE dialects differ from SQL dialects.

Retrieval of data as : MyTable->Code, MyTable->Name, MyTable->Salary is a fairly simple process so need not be detailed.

When job is done table is closed via DbCloseArea() method. It frees up the memory occupied by the RDD layer as well as CachéRDD. In CachéRDD context this command kills the node in public variable which was holding information about this table, nay, about this work area. In RDD concept one table can be opened in as many work areas as needed. Once closed the work-area slot on RDD layer is freed and made available to the next table to be opened subsequently.