Easy Use of Existing c-tree Plus Data With c-tree Plus for .NET

c-treeDB and c-tree Plus for .NET bring true relational data management to your application without the overhead of a full SQL implementation yet retain the power and performance of c-tree Plus. c-tree Plus for .NET was designed for ease of use. While intended for new developers to quickly get started c-tree Plus for .NET removes the steep learning curve of the many tedious details of traditional c-tree Plus ISAM handling.

To ensure maximum flexibility and compatibility, c-tree Plus for .NET was designed from the ground up to extend this advanced API to existing c-tree Plus data files! With a simple change of session management mode, you can quickly bring your existing data into the .NET world of fast development.

c-treeDB and c-tree Plus for .NET Sessions and Databases

c-treeDB and c-tree Plus for .NET use the relational concepts of sessions and database to bring advanced functionality to your applications.

c-treeDB and c-tree Plus for .NET Session and Database information are stored in dictionaries. These dictionaries are standard c-tree Plus data files with a defined format.

Sessions

Sessions essentially log your client application into the c-treeSQL or c-tree Server and provide a collection of databases. For standalone applications, this is still essential such that proper c-tree data structure initialization and manipulation can be done. For instance, transactions and record locking are session-wide activities.

Once a session object is created, you simply log into the session exactly as you would if using the c-tree Server. c-treeDB and c-tree Plus for .NET sessions also have properties and user profile values with respect to traditional c-tree Plus concepts of defining data file and index buffers, file control blocks, sectors (page sizes) and user profiles.

The session dictionary is by default contained in the following file, typically located in the c-tree Server directory, or your application binary for standalone applications:

ctdbdict.fsd

The session dictionary file layouts are described in the c-tree Plus for .NET Developer’s Guide, Section 3.2.7 “Session Dictionary File Layout”.

Databases

c-treeDB and c-tree Plus for .NET databases are collections of tables and indexes (c-tree data and index files) kept in a relational space.

The database dictionary is the database name followed by the .fdd extension. This is also typically located in the c-tree Server directory, or your application binary directory for standalone applications. c-treeSQL also uses this same c-treeDB database dictionary file for relational management. You will find this file in the SQL_SYS directory of the <database>.dbs directory of the c-treeSQL Server.

myDatabase.fdd

The database dictionary file layouts are described in the c-tree Plus for .NET Developer’s Guide, Section 3.3.6 “Database Dictionary”.

Session Types

c-treeDB and c-tree Plus for .NET offer a choice of session management modes. From a c-tree Plus for .NET application you can specify the exact session type to use while working with that session. The following SESSION_TYPE modes are available:

• CTREE_SESSION - Backward compatibility with existing c-tree data files.
  
  Allocates a new session for logon only. No session or database dictionary files are used. No database functions can be used with this session mode. Table handles are allocated using the session handle.
• CTDB_SESSION - The most flexible option offering all of the advanced core c-tree features with relational c-treeDB management.
  
  Allocates a new session making full usage of c-tree Plus for .NET session and database dictionaries. With this session mode, a Session dictionary file must exist to perform a session logon and you need to connect to a database before attempting to perform operation on tables.
• CTREESQL_SESSION - Full c-treeSQL compatible database handling.
  
  Allocates a new session for c-treeSQL processing. This session type is similar to CTDB_SESSION, however, maintaining full c-treeSQL compatibility.

Should you need to do so, you can even change the SESSION_TYPE after you have created a CTSession object. Simply call CTSession.SetSessionType(SESSION_TYPE type), passing the needed SESSION_TYPE.

Examples

The following example demonstrates how to log into a c-tree Plus for .NET Session for use with legacy c-tree Plus data and index files, without using the session file nor a database file.

.NET Sessionless Example

// Create a session object specifying 
// CTREE_SESSION as the session type

CTSession MySession = new CTSession
                     (SESSION_TYPE.CTREE_SESSION);

// Create a CTTable instance passing in the session handle

CTTable MyTable = new CTTable(MySession);

CTRecord MyRecord = new CTRecord(MyTable);

// logon to session using default

// server name, user name and password.

MySession.Logon("FAIRCOMS", "ADMIN", "ADMIN");

// set table path and open the table

MyTable.SetPath("ctreeSQL.dbs");

MyTable.Open("custmast", OPEN_MODE.NORMAL_OPEN);

// read the first record and display the value of field #4

MyRecord.First();

Console.WriteLine(MyRecord.GetFieldAsString(4));

// close the table and logout

MyTable.Close();

MySession.Logout();

Once a session is established, there is no need to create or manage the session or database dictionary files -- simply go to work with your c-tree Plus data!

If you have a number of tables “organized” in a database and other tables that are not (for example, temporary tables) you can even handle them inside of a single CTSession. Here is an example.

.NET “Mixed” Tables

// Create a session object specifying 
// CTDB_SESSION as the session type

MySession = new CTSession(SESSION_TYPE.CTDB_SESSION);

MyDatabase = new CTDatabase(MySession);

// Create a CTTable instance passing 
// in the database handle

MyTable = new CTTable(MyDatabase);

// Create another CTTable instance passing 
// in the session handle

MyTable2 = new CTTable(MySession);

MyRecord = new CTRecord(MyTable);

MyRecord2 = new CTRecord(MyTable2);

MySession.Logon("FAIRCOMS", "ADMIN", "ADMIN");

MyDatabase.Connect("ctreeSQL");

// open the table using the database,
// you do not need to specify the table path

MyTable.Open("custmast", OPEN_MODE.NORMAL_OPEN);

MyRecord.Last();

Console.WriteLine(MyRecord.GetFieldAsString(4));

// set table path and open the table
// without database support

MyTable2.SetPath("ctreeSQL.dbs");

MyTable2.Open("custordr", OPEN_MODE.NORMAL_OPEN);

MyRecord2.First();

Console.WriteLine(MyRecord2.GetFieldAsString(0));

// close the tables and logout

MyTable.Close();

MyTable2.Close();

MySession.Logout();

Advanced Properties

It is possible to change the session mode once logged in. Simply call one of the following methods or functions from c-treeDB or c-tree Plus for .NET. A parameter of TRUE or FALSE can be passed to indicate if this is a “Logon only” type session (CTREE_SESSION).

• CTSession.SetLogonOnly(bool flag)

Related Items

c-treeDB Transactions are Session Based

c-tree Plus for .NET Developer's Guide