ISAM C tutorial
ISAM quick start tutorial for C programmers
This tutorial helps C programmers use the FairCom ISAM API for C to interact with FairCom servers.
Note
The <root> directory for this driver is <faircom>\drivers\c.isam\
Install and start up the FairCom server if it is not currently running.
Get started immediately with the source code found in the
<faircom>\drivers\c.isam\tutorialsdirectory, or proceed with the following instructions.
The FairCom Database ISAM API provides an advanced set of NoSQL functions for manipulating data and index files using FairCom ISAM (Indexed Sequential Access Method). Each function performs multiple file and index access operations resulting in improved performance over the FairCom Low-Level API.
FairCom Database ISAM functions assume a hierarchical relationship among the data and index files, in the sense that each data file may have many indexes, while each index relates to only one data file. For example, an accounts payable system may define a vendor data file indexed by vendor name and number and an invoice data file indexed by vendor number and invoice number. In this case, each data file has two indexes. Although each data file is indexed by vendor number, there is a separate vendor number index for each data file.
This API is included for developers with specialized needs and can provide extensive additional control over particular data handling needs such as real-time data capture and processing. If you are just starting with FairCom Database, we recommend the easy-to-use c-treeDB APIs as they reduce the amount of code you need to write and provide the same great performance for which c-tree is famous.
The source code for the tutorials is in the <root>\tutorials directory.
Select from the following methods to compile the tutorial source code.
FairCom provides Microsoft Visual Studio solutions for Microsoft Visual Studio 2015, 2017, 2019, and 2022. You can find these solutions under the <root>\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 a tutorial 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, the compiler defaults 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
<root>\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 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 the newly built executables located in the <root>\tutorials\cmdline directory.
Running in Debug Mode
Open the Microsoft Visual Studio IDE Compile 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 Microsoft Visual Studio IDE Compile except the BuildTutorials.bat batch file is located in the <root>\tutorials\IDEProjects directory.
Execute tutorials directly
You can run the tutorials individually by running the newly built executable files located in the <root>\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
<root>/tutorials/cmdlinedirectory.Execute make:
>makeIf
makeworks, it prints...The <driver> 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 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 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 . . .This tutorial takes you through the basic use of the FairCom Database C ISAM API to add, delete, and get records from a table.
The source code is located in the <faircom>\drivers\c.isam\tutorials\isam_tutorial1.c file.
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.
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.
