CTDB C tutorial
CTDB quick start tutorial for C programmers
This tutorial helps C programmers use the CTDB API to read, write, update, and delete data on a FairCom server.
Optionally install and start up the FairCom Database Engine as needed
Optionally read an overview of the FairCom record buffer APIs.
When compiling on Windows, first install the Microsoft Windows SDK.
View, edit, and run the source code found in the
<faircom>\drivers\c.nav\tutorialsdirectory that is installed with the product. Go directly to the code and try your hand at it, or proceed with the following instructions.
The source code is located in the<faircom>\drivers\c.nav\tutorials directory.
Select from the following methods to compile this tutorial.
FairCom provides Microsoft Visual Studio solutions for Microsoft Visual Studio 2015, 2017, 2019, and 2022. You can find these solutions under the <faircom>\drivers\c.nav\tutorials\IDEProjects directory inside the named "Microsoft Visual Studio” folders.
This tutorial requires the Microsoft Windows SDK to be installed on your computer.
If the FairCom Database Engine is not already running on your machine, start the server.
How to Use the Visual Studio Environment
Load the
Tutorials.slnfile that corresponds to your version of Visual Studio by double-clicking the.slnfile.To build these samples, use the Build menu of Microsoft Visual Studio and select the Build Solution item:
To run the tutorial, choose Start Debugging in the Debug menu or simply press F5.
To fully observe how this tutorial interacts with the FairCom server, step through the code with the debugger and execute it step-by-step using Step Into from the Debug menu or simply press F11.
By default, the Visual Studio debugger will start the first tutorial project and display text similar to the following.
INIT Logon to server... DEFINE Open table... Add fields... Create table... MANAGE Delete records... Add records... Display records... 1000 Bryan Williams 1001 Michael Jordan 1002 Joshua Brown 1003 Keyon Dooling DONE Close table... Logout... Press <ENTER> key to exit . . .
When you are finished with Tutorial1 you can select a different tutorial using the Solution Explorer. Right-click the desired project and select Set as StartUp Project, then step into the code as described above.
Compile and run the tutorials from the Microsoft Visual Studio Developer Command Prompt window (also called the Native Tools Command Prompt window).
This section is written for a Microsoft Windows command line. The principles are similar for other environments that provide .NET support, such as Linux/Unix.
Prerequisites
Install the 2015, 2017, 2019, or 2022 version of Microsoft Visual Studio.
If the FairCom Database Engine is not already running on your machine, start the server..
Compile the tutorials
Open the appropriate Visual Studio Developer Command Prompt.
There are different developer command prompts for compiling on x86 and x64 platforms. You must run the appropriate one for your platform.
On a 64-bit platform, press the WINDOWS START key.
Start typing x64 native tools command prompt
Press ENTER.
Tip
To open the command prompt, you typically only need to type x64 and press ENTER.
Windows opens the 64-bit Visual Studio command prompt.
Note
if you open the generic Visual Studio Developer Command Prompt, it defaults the compiler to 32-bits, which causes compiles to fail on a 64-bit computer.
You can tell the difference between the generic and x64 versions of the command prompt by looking at the window title. The x64 title is
"x64 Native Tools Command Prompt…". The generic title is"Developer Command Prompt…"
For more information on opening the Visual Studio command prompt see:
In the Developer Command Prompt window, move to the
<faircom>\drivers\c.nav\tutorials\cmdlinedirectory and execute theBuildTutorials.batfile.This batch file identifies your version of the Microsoft C compiler and sets the internal paths accordingly. It then compiles the tutorials included for this driver.
After the tutorials have been built, the batch file runs them one at a time. It prompts you to press <Enter> before running each tutorial.
Each tutorial should run successfully without error. If you see an error, you can look it up in the Error Code Reference. See Troubleshooting for solutions to common problems.
The first tutorial should look similar to the following text when running:
INIT
Logon to server...
DEFINE
Open table...
Add fields...
Create table...
MANAGE
Delete records...
Add records...
Display records...
1000 Bryan Williams
1001 Michael Jordan
1002 Joshua Brown
1003 Keyon Dooling
DONE
Close table...
Logout...
Press <ENTER> key to exit . . .Execute tutorials directly
You can run the tutorials individually by executing each of the newly built executables located in the tutorials\cmdline directory.
Running in Debug Mode
Open the Compile Using Microsoft Visual Studio IDE section to view, run, and debug the code.
FairCom provides a way to compile and run tutorials from a batch file that invokes the Visual Studio IDE to compile them.
The instructions are identical to the section Compile Using Microsoft Visual Studio IDE except the BuildTutorials.bat batch file is located in the <faircom>\drivers\c.nav\tutorials\IDEProjects directory.
Execute tutorials directly
You can run the tutorials individually by running the newly built executable files located in the tutorials\IDEProjects\Microsoft Visual Studio ___\Debug directory that corresponds to the version of Visual Studio you have on your computer.
This section explains the steps to compile and run tutorials from the Linux shell.
Compile
To compile the NAV API tutorials from the Linux command line, follow these steps:
CD into the
<faircom>/drivers/c.nav/tutorials/cmdlinedirectory.Execute make:
>makeIf make works, it prints...
The c.nav tutorials are ready to run.Type 'make run' to run the tutorials.
Note
On systems running a glibc version older than 2.17, the tutorials need to be linked with librt by adding -lrt to the SYSLIBS macro in the makefile. If you are running a system with glbic older than 2.17, edit the makefile and uncomment -lrt.
Run
If the FairCom Database Engine is not already running on your machine, start the server.
To run the c-tree tutorials from the Linux command line, follow these steps from the same folder you compiled from:
Type the following:
>make runThe make file will run the tutorial(s).
A prompt will ask you to press <Enter> after each tutorial is run.
If you see an error, you can look it up in the Error Code Reference.
See Troubleshooting for solutions to common problems.
When running, the first tutorial should look similar to the following text:
INIT
Logon to server...
DEFINE
Open table...
Add fields...
Create table...
MANAGE
Delete records...
Add records...
Display records...
1000 Bryan Williams
1001 Michael Jordan
1002 Joshua Brown
1003 Keyon Dooling
DONE
Close table...
Logout...
Press <ENTER> key to exit . . .The most common cause of run-time error 133 is the FairCom Database Engine is not running on your machine. The most likely cause is that the evaluation license times out after 3 hours and shuts down the server. The solution is to start the server.
ERROR 133 occurs when the FairCom server is not running
This section lists some of the errors that can occur when compiling and running these tutorials:
cl.exe not found! Please set the environment for Visual C/C++ compiler.
The most common cause of this error is running the BuildTutorials.bat file from a DOS shell or normal Windows command shell rather than from the Visual Studio Developer Command Prompt window.
Error MSB8036:
The Windows SDK version 10.0.15063.0 was not found. Install the required version of Windows SDK or change the SDK version in the project property pages or by right-clicking the solution and selecting "Retarget solution".
This build error happens because the Windows SDK version that this solution was built against (10.0.15063.0) does not match the Windows SDK version that is currently installed on your computer.
To fix this, right-click on the solution (not one of the individual projects), select Retarget Solution, and specify a Windows SDK installed on your computer.
The versions of the Windows SDK installed on your computer will be automatically listed. Choose one and click OK to retarget the solution.
FairCom provides four tutorials that show how to create tables and indexes; insert, update, delete, and lock records; query across multiple tables; and process multiple operations as a single atomic transaction.
Note
These tutorials create tables and indexes outside a database as independent data files in the <faircom>\data directory. Thus, they are invisible in SQL, the JSON DB API, and the FairCom Data Explorer application. In addition, these tutorials do not delete these files and records when they finish running. These files include custmast.dat, custmast.idx, custordr.dat, custordr.idx, invent.dat, invent.idx, itemmast.dat, itemmast.idx, ordritem.dat, and ordritem.idx.
This tutorial creates a single customer table and inserts records into it. It then reads, displays, and deletes the records.
It organizes the work into four functions:
Initialize()
Connects to the FairCom Database Engine.
Define()
Creates a customer master table named custmast.
Manage()
Deletes preexisting records.
Adds records.
Reads and displays the records.
Done()
Disconnects from FairCom Database Engine.
This tutorial creates a simple order system with customer, order, order detail, and product tables. It inserts records in the tables and runs a query that lists each customer's name and the total amount of each order.
It organizes the work into four functions:
Initialize()
Connects to the FairCom Database Engine.
Define()
Creates "custmast", "custordr", "ordritem" and the "itemmast" tables with related indexes.
Manage()
Adds records to each of these tables.
Lists each customer's name and the total amount of each order.
Done()
Disconnects from FairCom Database Engine.
This tutorial shows how to lock records so that other concurrent processes cannot interfere with them. It begins by deleting preexisting records in the customer table. It then inserts new records and pauses after it places a lock on a record. You can then run another instance of this tutorial, which will automatically block while waiting for the first instance to release its lock. Press Enterin the first instance to remove the lock and allow the second instance to continue.
It organizes the work into four functions:
Initialize()
Connects to the FairCom Database Engine.
Define()
Creates a custmast table with a primary index.
Manage()
Deletes preexisting records.
Adds records.
Reads and displays the records.
Creates a session-wide write lock that locks all subsequently accessed records to prevent them from being modified.
Finds a record and updates it. It automatically locks the record.
Pauses until the user presses ENTER. When the user has pressed ENTER, it releases the session lock.
Reads and displays the records.
Done()
Disconnects from FairCom Database Engine.
Note
When you run a second instance of this tutorial, it immediately begins deleting all preexisting records. When the delete operation encounters the record locked by the first instance, the delete operation automatically blocks and will not return until the lock is released in the first instance. Once you release the lock in the first instance by pressing ENTER, the second instance deletes the record and continues its process.
This tutorial shows you how to process transactions in a simple order system with customer, order, order detail, and product tables. It shows you how to use transactions in a variety of use cases:
It creates a transaction, deletes existing records, inserts new records in the customer and product tables, and then commits the transaction.
It creates another transaction, deletes existing records in the order and order detail tables, and then commits the transaction.
In a loop that inserts multiple records, it uses transactions and transaction savepoints to commit good records and to roll back bad records that it inserts in the order and order detail tables.
It organizes the work into four functions:
Initialize()
Connects to the FairCom Database Engine.
Define()
Creates "custmast", "custordr", "ordritem" and the "itemmast" tables with related indexes.
Manage()
In a transaction, it deletes existing records and inserts new records in the custmast and itemmast tables.
In a transaction, it deletes existing records in the custordr and ordritem detail tables.
In a loop that inserts multiple records, it uses transactions and transaction savepoints to commit good records and roll back bad records that it inserts in the custordr and ordritem tables. Because of bad data, only 2 of 3 orders and 3 of 6 ordered items are inserted.
Reads and displays the newly inserted records in the custordr table.
Reads and displays the newly inserted records in the ordritem table.
Done()
Disconnects from FairCom Database Engine.
What are transactions and why use them?
A transaction treats multiple operations as if they were a single atomic operation. In an atomic transaction, either all operations succeed or none succeed. You can start a transaction and execute multiple operations. You can then commit the transaction or roll it back.
Use a transaction when running operations across multiple records in multiple tables. If something unexpectedly goes wrong partway through the transaction, you can roll back the transaction to ensure no dangling records are left behind.
You can create transaction savepoints and revert operations back to any savepoint within a transaction. Create savepoints before running a single operation or a group of operations that are likely to fail. You can revert to the savepoint and try again or try something different.
Use a transaction to increase the performance of multiple operations. Transactions cause multiple operations to be performed in memory and committed to the transaction log as a single entry. Because multiple operations are written to the transaction log and flushed to disk as a single write, they increase data processing speed. Be careful not to perform too many operations in a single transaction, or you may run out of memory.