FairCom DB API for VB.Net Overview

This book contains Visual Basic developer tutorials for the FairCom DB API API. In four simple steps and about 15 minutes, you’ll be navigating your data:

  1. Install and start up the FairCom Database Engine. See Installing FairCom Products.
  2. Optionally read the overview Introduction to FairCom DB API for Visual Basic.
  3. Compile the tutorials as explained in Compiling Your Projects.
  4. Run the tutorials or read the Tutorials section to see tutorial code with brief explanations.

Tip: To view, edit, and run the source code for the tutorials, you can go directly into the <faircom>\drivers\vb.nav\tutorials folder that is installed with the product. Each tutorial has been thoroughly tested on each operating system, interpreter, and compiler to ensure you have an excellent experience.

Note: This guide focuses on Microsoft Windows, but it works on all platforms where .NET runs.

Resources

c-tree Database API for Other Languages

FairCom allows you to use NAV APIs with the language of your choice:

 

Introduction to FairCom DB API for Visual Basic

The c-tree Database API for Visual Basic is a record-oriented database API for Microsoft .NET. Its short name is FairCom DB API .NET for VB. It is in the "NAV" family of APIs because it makes it easy for application developers to navigate data — no matter how complex.

FairCom DB API for VB is an object-oriented API that provides precise control over every aspect of data processing. It leverages the familiar concepts of databases, tables, records and fields. For example, it can connect to a database, open a table, find a record by key, and walk records in key order.

The FairCom DB API API makes it easy to navigate and process data very quickly across multiple databases no matter where they are located. Its unique ability is to simultaneously open cursors into multiple databases and remote control them. Applications use cursors to control every detail of record lookup and traversal. There are multiple types of cursors: index, table, filtered, range, metadata, batch query, batch insert, batch update, and batch delete. Each is optimized to make different use cases easy and fast. For example, your application can retrieve a record from one database and use its data to quickly position a cursor in another database to batch retrieve additional records.

 

Because the FairCom Database Engine is optimized specifically for cursors, applications can easily do very complex data processing tasks at high speed. Developers are not limited to using built-in SQL or GQL algorithms. A software developer can easily implement algorithms to traverse data as hierarchies, graphs, objects, tables, etc. A data engineer or data scientist can implement unique algorithms for machine learning, graph analytics, knowledge graphs, big data, etc. A back-end programmer can implement optimized algorithms for real-time transaction processing, high-velocity inserts, specialized microservices, etc.

While navigating records, a developer can do anything with the data, such as insert, update, and delete records. FairCom DB API can find, retrieve, and process field values. Field values can be any common data type: JSON, custom binary structures, arrays, strings, numbers of all types, dates, times, monetary values, Boolean, etc. The database can automatically index fields containing these data types.

FairCom DB API works simultaneously with SQL. Applications can use SQL and FairCom DB API at the same time on the same data. SQL tools can simultaneously work with the same data as an application using FairCom DB API.

SQL is ideal for writing queries that join data. FairCom DB API is ideal for navigating complex data, such as walking hierarchies and graphs or implementing custom data processing algorithms. FairCom DB API is easier than SQL because there is very little to learn and it is 100% predictable.

FairCom DB API makes it easy to process complex data because developers can leverage the full power of their development language to break down complexity into manageable code. FairCom DB API extends a developer's favorite development language directly into the database. In other words, a programmer can use their favorite programming language to remote control the database and directly process data. FairCom DB API eliminates the need to learn a proprietary database language; instead, a developer’s favorite language becomes the database language.

FairCom DB API is ideal for achieving extreme, predictable performance because it gives developers complete control over:

  • Navigating records in any order
    • Index- or table-order
    • Forward or backward
    • Filtered
    • Ranged
    • Partial-key
    • Bulk processed
    • Etc.
  • Saving record positions
  • Jumping back to saved positions
  • Controlling if and how each record is locked
  • Managing which records participate in transactions
  • Using custom algorithms to join data across tables
  • etc.

 

Compiling Your Projects

This section explains how to compile the tutorials that guide you through the basic use of the FairCom DB API .NET Visual Basic NAV interface technology.

The source code is located in the drivers\vb.nav\tutorials folder.

Note: The .NET components within FairCom DB reference the .NET Framework v4.x and above. Therefore, if you select Visual Studio 2008, 2005, or prior, you will experience errors with the tutorials due to this Framework incompatibility. Please use VS2010 or later, or contact FairCom if you need support for a prior (v2-v3) .NET framework.

Prerequisite - Configure Microsoft Visual Studio Properly

Be sure Microsoft Visual Studio is configured properly. For Visual Studio 2017 and 2019 to be able to build the tutorials, the .NET desktop development workload needs to be installed as part of Visual Studio. In Visual Studio 2017 and 2019, click Tools > Get Tools and Features, which runs the Visual Studio installer. If the installer requires an update before it will run, allow that update. Find the .NET desktop development workload under the Windows group and make sure it is checked, as shown here:

If it is not already checked, give it a check mark and then click the MODIFY button to install that workload. This ensures that all of the tools needed to build and run these tutorials are installed.

Note that Visual Studio 2015 does not have this prerequisite.

If the FairCom Database Engine is not already running on your machine, start the server as explained in Setting up the FairCom Database Engine.

Compiling and Executing the Tutorials

The sample tutorials can be compiled in Visual Studio:

You can find these solutions in the drivers\vb.nav\tutorials\IDEProjects directory.

 

Compile Using Microsoft Visual Studio IDE

This section explains the steps to compile and run the tutorial from the Microsoft Visual Studio IDE. FairCom provides Microsoft Visual Studio solutions for Microsoft Visual Studio 2015, 2017, and 2019. You can find these solutions in the various “Microsoft Visual Studio” directories in the <faircom>\drivers\vb.nav\tutorials\IDEProjects directory. Please choose the one which corresponds to the version of Visual Studio you have installed.

This tutorial requires the Microsoft Windows SDK to be installed on your computer. See Microsoft Windows SDK.

If the FairCom Database Engine is not already running on your machine, start the server as explained in Starting the FairCom Database Engine.

The source code is located in this directory: <faircom>\drivers\vb.nav\tutorials

How to Use the Visual Studio Environment

  1. Load the Tutorials.sln file that corresponds to your version of Visual Studio by double-clicking the .sln file.
  2. To build these samples, use the Build menu of Microsoft Visual Studio and pick the Build Solution item:
  3. To run the tutorial, choose Start Debugging in the Debug menu or simply press F5.
  4. To fully observe how this tutorial interacts with c-tree, 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.

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 on the desired project and select Set as StartUp Project, then step into the code as described above.

Troubleshooting

This section lists some errors you may encounter when compiling and running the tutorials.

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), and 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.

ERROR: [133] - c-tree logon error

The most common cause of this runtime error is the FairCom Database Engine is not running on your machine. The most likely cause is that the c-tree evaluation license times out after 3 hours and shuts down the server. The solution is to restart the server. See Starting the FairCom Database Engine.

 

Command-Line Compile - Windows

This section explains the steps to compile and run the FairCom DB API .NET VB tutorials from the Microsoft Visual Studio Developer Command Prompt (also called the Native Tools Command Prompt).

This section is oriented toward a command-line running on Microsoft Windows. The principles are similar for other environments that provide .NET support, such as Linux/Unix.

  • The tutorial requires that you have installed the Microsoft Windows SDK, available from Microsoft Windows SDK.
  • FairCom currently supports the 2015, 2017, and 2019 versions of Microsoft Visual Studio.
  • If the FairCom Database Engine is not already running on your machine, start the server. See Starting the FairCom Database Engine.
  • On Windows, be sure the ODBC driver is installed. See Configuring the ODBC Data Source.
  1. Open the Developer Command Prompt window, typically available from the Windows Start menu for your version of Microsoft Visual Studio: Visual Studio 2017 > X64 Native Tools Command prompt for VS 2017
    1. Where 2017 is your version of Visual Studio and X64 is for a 64-bit version of c-tree (note “64” in the name of the default installation directory) or X86 for a 32-bit version of c-tree.
    2. Warning - the Developer Command Prompt Start menu entries which do not specify a bit depth actually open the 32-bit version of the Developer Command Prompt, which is always the wrong one for c-treeEDGE.
    3. For more details, see the Microsoft Developer Command Prompt web page.
  2. In the Developer Command Prompt window, move to the drivers\vb.nav\tutorials\cmdline directory and execute the BuildTutorials.bat file. (If you are using FairCom RTG or FairCom Edge, adjust the path to match your product.
    1. This batch file will determine the version of the Microsoft C compiler you are using and will set the internal paths accordingly. It will then compile the tutorials included for this driver.
    2. After the tutorials have been built, the batch file will run them one-at-a-time. A prompt will ask you to press <Enter> before running each tutorial.
    3. If you see a c-tree error, you can look it up in the Error Code Reference. See the "Troubleshooting" section below for solutions to common problems.

The first tutorial should look similar to the image below 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 . . .

 

Executing the Tutorials by Hand

You can run the tutorials individually using the executables located in \drivers\vb.nav\tutorials\cmdline

tutorial1.exe

tutorial2.exe

tutorial3.exe

tutorial4.exe

 

Running in Debug Mode

To fully observe this API in action, you can single-step through the code with the Visual Studio integrated debugger. You can call this as follows:

devenv tutorial1.exe

devenv tutorial2.exe

devenv tutorial3.exe

devenv tutorial4.exe

Hint: A better way to single-step and debug is to open the Visual Studio solution that we provide. See Compile Using Microsoft Visual Studio IDE.

 

Troubleshooting

This section lists some of the errors that can occur when compiling and running these tutorials:

cl.exe not found! Please set 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: [133] - c-tree logon error.

The most common cause of this error is that the FairCom Database Engine is not running on your machine. Remember that the c-tree evaluation license times out after 3 hours, so the server might have exited and needs to be re-started. See Installing FairCom Products for details.

 

Command-Line IDE Compile - Windows

We also provide a way to compile and run the Low-Level tutorial from a batch file that invokes the Visual Studio IDE to do the compilation.

The instructions are identical to the previous section except the BuildTutorials.bat batch file is located in the drivers\vb.nav\tutorials\IDEProjects directory.

 

 

vb.net faircom

Was this article helpful?

Give feedback about this article

Related Articles