# 3.2 C++

Part of: [3 Usage](3-usage.md)

HDFql can be used in the C++ programming language through a shared library, which is stored in the directory “cpp” found under the directory “wrapper”. The following short program illustrates how HDFql can be used in this language.

```cpp
// include HDFql C++ header file (make sure it can be found by the C++ compiler) 
#include <cstdlib> 
#include <cstdio> 
#include <iostream> 
#include "HDFql.hpp" 

int main(int argc, char *argv[])
{
    // display HDFql version in use 
    std::cout << "HDFql version: " << HDFql::Version << std::endl;

    // create an HDF5 file named "my_file.h5" and use (i.e. open) it 
    HDFql::execute("CREATE AND USE FILE my_file.h5");

    // create an HDF5 dataset named "my_dataset" of data type int 
    HDFql::execute("CREATE DATASET my_dataset AS INT VALUES(10)");

    // select (i.e. read) data from dataset "my_dataset" and populate cursor in use with it 
    HDFql::execute("SELECT FROM my_dataset"); 

    // move cursor in use to the first position within the result set 
    HDFql::cursorFirst(); 

    // display content of cursor in use
    std::cout << "Dataset value: " << *HDFql::cursorGetInt() << std::endl;

    return EXIT_SUCCESS;
}
```

Assuming that the program is stored in a file named “example.cpp”, it must first be compiled before it can be launched. To compile the program against the HDFql C++ shared library, execute the following command in a terminal:

- On Windows using Microsoft Visual Studio:

  ```sh
  cl.exe example.cpp /EHsc /I<hdfql_include_directory> <hdfql_cpp_wrapper_directory>\HDFql_dll.lib
  ```
- On Linux and macOS using GCC:

  - With an HDFql non MPI-based distribution:

    ```sh
    g++ example.cpp -I<hdfql_include_directory> -L<hdfql_cpp_wrapper_directory> -lHDFql -ldl
    ```
  - With an HDFql MPI-based distribution:

    ```sh
    g++ example.cpp -I<hdfql_include_directory> -L<hdfql_cpp_wrapper_directory> -L<mpi_lib_directory> -lHDFql -lmpi -ldl
    ```

In case the program does not compile, check whether a C++ compiler is installed. If a C++ compiler is missing, the solution is:

- On Windows, download and install Microsoft Visual Studio from the website <https://visualstudio.microsoft.com/downloads>.
- On Linux, install the GCC C++ compiler by executing the following command in a terminal:

  - On a Red Hat-based distribution:

    ```sh
    sudo dnf install gcc-c++
    ```
  - On a Debian-based distribution:

    ```sh
    sudo apt install g++
    ```
- On macOS, install the GCC C++ compiler by executing the following command in a terminal:

  - With Homebrew:

    ```sh
    brew install gcc
    ```
  - With MacPorts:

    ```sh
    sudo port install gcc
    ```

In case the compiled program does not launch, it is most likely that the HDFql C++ shared library and/or the MPI shared library were not found (these are needed to launch the program). The solution is:

- On Windows, add the directory where the file “HDFql_dll.dll” is located to the environment variable “PATH” by executing the following command in a terminal:

  ```sh
  set PATH=<hdfql_cpp_wrapper_directory>;%PATH%
  ```
- On Linux, add the directories where the files “libHDFql.so” and (optionally) “libmpi.so” are located to the environment variable “LD_LIBRARY_PATH” by executing the following command in a terminal:

  - With an HDFql non MPI-based distribution:

    ```sh
    export LD_LIBRARY_PATH=<hdfql_cpp_wrapper_directory>:$LD_LIBRARY_PATH
    ```
  - With an HDFql MPI-based distribution:

    ```sh
    export LD_LIBRARY_PATH=<hdfql_cpp_wrapper_directory>:<mpi_lib_directory>:$LD_LIBRARY_PATH
    ```
- On macOS, add the directories where the files “libHDFql.dylib” and (optionally) “libmpi.dylib” are located to the environment variable “DYLD_LIBRARY_PATH”[^4] by executing the following command in a terminal:

  - With an HDFql non MPI-based distribution:

    ```sh
    export DYLD_LIBRARY_PATH=<hdfql_cpp_wrapper_directory>:$DYLD_LIBRARY_PATH
    ```
  - With an HDFql MPI-based distribution:

    ```sh
    export DYLD_LIBRARY_PATH=<hdfql_cpp_wrapper_directory>:<mpi_lib_directory>:$DYLD_LIBRARY_PATH
    ```

[^4]: Starting with version 10.11 (i.e. El Capitan), Apple introduced a security feature named System Integrity Protection (SIP) that may prevent setting the environment variable “DYLD_LIBRARY_PATH” and, ultimately, launching the program. To overcome this, SIP should be disabled (please refer to <https://developer.apple.com/library/archive/documentation/Security/Conceptual/System_Integrity_Protection_Guide/ConfiguringSystemIntegrityProtection/ConfiguringSystemIntegrityProtection.html> for additional information).