DSQL C tutorial
Direct SQL quick start tutorial for C programmers
This tutorial helps C programmers use the FairCom DSQL API for C to interact with FairCom servers.
Note
The <root> directory for this driver is <faircom>\drivers\c.sql.direct\
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.sql.direct\tutorialsdirectory, or proceed with the following instructions.
The FairCom DB Direct SQL interface (DSQL) is an inline SQL application programming interface (API) designed for C/C++ developers who wish to embed SQL statements directly into their programs.
The FairCom DB DSQL API is designed as a foundation for building your own SQL APIs. It simplifies your code. Many of the SQL GUI tools authored by FairCom utilize this API.
FairCom DB DSQL gives application developers control and ease of deployment over other embedded APIs, such as ODBC, and DSQL requires no time-consuming pre-processing steps or the presence of an ODBC manager.
Use FairCom DB DSQL for your embedded application solutions.
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 quick start has four programs to demonstrate 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.
Tutorial1 shows basic record management functions of the FairCom DSQL - Direct SQL API.
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.
Tutorial2 establishes some table relationships using the FairCom DB SQL DSQL - Direct SQL API.
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.
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.
Tutorial3 shows how to lock records so that other concurrent processes cannot interfere with them.
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 pre-existing records.
Adds records.
Reads and displays the records.
Updates a record under locking control.
Done()
Releases resources and disconnects from the FairCom Database Engine.
Tutorial4 shows how to process transactions in a simple order system with customer, order, order detail, and product tables. With transaction processing, related updates are either all completed or none of them are completed which ensures data integrity.
Initialize()
Connects to the FairCom Database Engine.
Define()
Creates "custmast", "custordr", "ordritem" and the "itemmast" tables with related indexes.
Manage()
Deletes existing records and inserts new records in the custmast and itemmast tables.
Adds an order and associated items as a transaction if the customer and items are valid.
Reads and displays the newly inserted records from the custordr table.
Reads and displays the newly inserted records from the ordritem table.
Done()
Disconnects from FairCom Database Engine which releases resources.
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.
