Quick Tour

FairCom provides four quick tutorials showing the major components of our core technology:

• How to init, define, and manage data
• How to handle index files
• How to use locks in a multi-user environment
• How to use transaction processing

To try these tutorials, see the tutorials in these ReadMe files:

• ISAM c-treeDB.NET C#
• FairCom DB API.NET VB
• FairCom ADO.NET Driver

Navigational record-oriented interfaces:

You can find tutorials and information about the entire set of FairCom APIs in the following ReadMe:

• Driver and API ReadMe

The ReadMe files document the very basic tutorials packaged with the product. On the FairCom website you can find highly informative interactive tutorials:

Online Interactive Tutorials

These tutorials cover the major programming languages that FairCom DB API supports and go in depth to illustrate best practices for multi-threaded environments with SQL compatibility.

Run on supported versions of UNIX

The FairCom-provided assemblies can also be used on supported versions of the .NET runtime.

The required FairCom-provided assemblies are part of the FairCom bundles for the platforms where .NET is supported. The main assemblies are located in the <faircom>/drivers/ctree.drivers/lib folder. Look for FairCom.CtreeDb.dll and its variants where provided.

To run tutorials in the FairCom-provided assemblies under UNIX, run the makefile in the desired folder. You must first have .NET installed. See the following websites to know how to install .NET under supported UNIX platforms:

https://learn.microsoft.com/en-us/dotnet/core/install/linux

https://learn.microsoft.com/en-us/dotnet/core/install/macos

NOTE: Each tutorial has its own project file, such as:

<faircom>/drivers/csharp.nav/tutorials/cmdline/Tutorial1/Tutorials1.csproj

The tutorial projects are designed to work with dotnet 6.0 on Linux and MacOS, but will work with dotnet 7.0 and dotnet 8.0. To update to a later version of dotnet, locate the project file and change the following line to match the desired dotnet version:

<TargetFramework>net6.0</TargetFramework>

This applies to all the .csproj and vbproj files contained in the FairCom bundle, and applies to both C# and VB.

See: Target frameworks in SDK-style projects - .NET

Use without a makefile

It is possible to interact directly with the project folder, rather than use a makefile.

Go to the desired folder that contains the projects you want to work with and run the dotnet command.

[cmdline]$ cd <Faircom-folder>/drivers/csharp.nav/tutorials/cmdline
[cmdline]$ dotnet build Tutorial2
[cmdline]$ dotnet run Tutorial2

NOTE: The default tutorials are configured to run in client-server configuration. Make sure the server is started before running the tutorials.

See, https://learn.microsoft.com/it-it/dotnet/core/tools/  

FairCom DB API for C# and VB

FairCom is pleased to present the FairCom DB API API component for the Microsoft® .NET Framework ("FairCom DB API .NET").

Microsoft .NET is software for connecting people, information, systems, and devices. FairCom DB API .NET gives application developers a simple interface into the powerful core of FairCom DB API, yet includes the advanced functionality that distinguishes FairCom DB API from other database solutions. FairCom DB API .NET offers a method of database creation and maintenance that is easier to use than the c-tree ISAM and low-level APIs, which require C programming language and unmanaged code. FairCom DB API .NET utilizes the simplified concepts of sessions, databases, and tables in addition to the standard concepts of records, fields, indexes, and segments. This database API allows for effortless and productive management of database systems.

FairCom DB API .NET is a component that integrates with VB .NET, C#, J#, Delphi .NET and others. This component exposes the methods and properties of the FairCom DB API .NET Class Level API and Function Level API. Please refer to the following chapters for a comprehensive listing of all the methods and properties that encompasses this API.

Background

This section is designed to offer just a taste of the Function Level API. If you have never developed with this API, it will be beneficial to take a moment to learn some of the basics. This will be especially useful when we begin building our first FairCom DB API .NET application.

Below we will list the API function calls necessary to connect to a database, open a table, and add a record. This exercise is meant to expose the more commonly used APIs and follow the sequence of calls to be performed for most database tasks.

The nomenclature for the Function Level API is to prefix "ctdb." to all function names. For example, AllocSession() is ctdbAllocSession() in FairCom DB API and ctdb.AllocSession() in .NET.

In the .NET IDE, once the ‘.’ (period) after "ctdb" is typed, then IntelliSense® will take over and present a drop-down of properties and methods.

Function Level API (FairCom DB API C API)

This section is designed to offer just a taste of the Function Level API. If you have never developed with this API, it will be beneficial to take a moment to learn some of the basics. This will come in handy when we start building our first FairCom DB API .NET application.

Below we will list the API function calls necessary to connect to a database, open a table, and add a record. This exercise is meant to expose the most commonly used parts of the API and goes through the sequence of calls to be performed for most database tasks.

The nomenclature for the Function Level API is to prefix "ctdb." to all function names. For example, AllocSession() is ctdbAllocSession() in FairCom DB API and ctdb.AllocSession() in .NET.

In the .NET IDE, once the "." (period) after "ctdb" is typed, then IntelliSense® will take over and present a drop-down of properties and methods.

Examples:

Connect to a Database

pSession = cdtb.AllocSession(ctdb.SESSION_TYPE.SESSION_CTDB);
ctdb.CreateSession(pSession, uid,upw,svn);
ctdb.Logon(pSession, uid,upw,svn);

pDatabase = ctdb.AllocDatabase(pSession);
ctdb.CreateDatabase(pDatabase, "dbName");
ctdb.Connect(pDatabase, "dbName");

Open a Table

hTable = ctdb.AllocTable(pDatabase);
ctdb.AddField(hTable, ...);
ctdb.AddIndex(hTable, ...);
ctdb.AddSegment(hTable, ...);

ctdb.CreateTable(hTable,"tblName",ctdb.CREATE_MODE.CREATE_NORMAL);
ctdb.OpenTable(hTable, "tblName", ctdb.OPEN_MODE.OPEN_NORMAL);

Add a Record

hRecord = ctdb.AllocRecord(hTable);
ctdb.ClearRecord(hRecord);

ctdb.SetFieldasUnsigned(hRecord,0,1000);
ctdb.SetFieldAsString(hRecord,1,"John Smith");
ctdb.WriteRecord(hRecord); 

Class Level API (FairCom DB API C++ API)

The FairCom DB API C++ API is made up of roughly a dozen classes. A few of the commonly used classes are CTSession, CTDatabase, CTTable, CTRecord, CTIndex and CTSegment. This API is the functional equivalent to its Function Level counterpart. Once a class has been instantiated, typing the name of the instance followed by a ‘.’ (period) will invoke IntelliSense® and a drop-down of all the properties and methods will be presented.

Create Example

pSession = new CTSession(SESSION_TYPE.SESSION_CTDB); pSession.Logon(uid,pwd,svn);
pSession.CreateDatabase("dbName","dbPath");

Open Example

pTable = new CTTable(pDatabase);
pTable.AddField("fldName", ...);
pTable.Create("tblName", CREATE_MODE.CREATE_TRNLOG);
pTable.Open("tblName",OPEN_MODE.OPEN_NORMAL);

Add Example

pRecord = new CTRecord(pTable);
pRecord.Clear();
pRecord.SetFieldValue(0,1000);
pRecord.SetFieldAsString(1,"John Smith");
pRecord.Write();

c-tree and .NET

To be compliant with standard practice for C# programmers, we do not force the assembly to be signed with a FairCom key. This allows developers to sign with their own key, which they can keep secret.

Strong Signing (releases prior to V10.3)

Programming in the .NET environment requires a few steps that should be addressed.

Prior to FairCom DB V10.3, the FairCom.CtreeDb assembly was strong signed, and when one application included a reference to the assembly, it had to be strong signed as well.

To instigate the strong signing process, modify/include the following line in Assemblyinfo.cs (shown in the Solution Explorer) for C# projects:

[assembly: AssemblyKeyFile("c:\\FairCom\\ctreeSDK\\ ctreedotNET\\faircom.snk")]

For Visual Basic projects, modify/include the following line in AssemblyInfo.vb:

<Assembly: AssemblyKeyFileAttribute("c:\\FairCom\\ctreeSDK\\ctreedotNET\\faircom.snk ")>

For Delphi projects, modify/include the following line in AssemblyInfo.pas:

[assembly: AssemblyKeyFile('c:\\FairCom\\ctreesdk\\ctreedotnet\\faircom.snk')]

If your installation directory structure is different from the structure used when this project was created, the file faircom.snk may not be found. In this case, you will receive the following error:

Error creating assembly manifest:
Error reading key file ‘c:\\FairCom\\ctreeSDK\\ctreedotNET\\faircom.snk ’
 - The system cannot find the file specified.

Or :

Cryptographic failure while signing assembly
‘C:\FairCom\ctreeTutorials\ctreedotNET\C#\Tutorial1\obj\Debug\Tutorial1.exe’
-- 'Error reading key file ‘c:\\FairCom\\ctreeSDK\\ctreedotNET\\faircom.snk’
-- The system cannot find the file specified.

If you receive one of these errors, please correct the path to the faircom.snk key file.