# 3.7 R

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

HDFql can be used in the R programming language through a wrapper named “HDFql.R”, which is stored in the directory “R” found under the directory “wrapper”. The following short script illustrates how HDFql can be used in this language.

```r
# load HDFql R wrapper (make sure it can be found by the R interpreter)
source("HDFql.R")

# display HDFql version in use
print(paste("HDFql version:", HDFQL_VERSION))

# 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_cursor_first() 

# display content of cursor in use
print(paste("Dataset value:", hdfql_cursor_get_int()))
```

Assuming that the script is stored in a file named “example.R”, it can be launched by executing the following command in a terminal:

```sh
R -f example.R
```

In case the script does not launch, it is most likely that either (1) an R interpreter is not installed or (2) the HDFql R wrapper, the HDFql C shared library, and/or the MPI shared library were not found (these are needed to launch the script). To fix the former issue, download and install an R interpreter from the website [https://cloud.r-project.org](https://cloud.r-project.org/). To fix the latter issue:

- On Windows, add the directories where the files “HDFql.R” (i.e. the wrapper) and “HDFql_dll.dll” are located to the environment variable “PATH” by executing the following command in a terminal:

  ```sh
  set PATH=<hdfql_r_wrapper_directory>;<hdfql_lib_directory>;%PATH%
  ```
- On Linux, add the directories where the files “HDFql.R”, “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_r_wrapper_directory>:<hdfql_lib_directory>:$LD_LIBRARY_PATH
    ```
  - With an HDFql MPI-based distribution:

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

  - With an HDFql non MPI-based distribution:

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

    ```sh
    export DYLD_LIBRARY_PATH=<hdfql_r_wrapper_directory>:<hdfql_lib_directory>:<mpi_lib_directory>:$DYLD_LIBRARY_PATH
    ```

Besides these steps, a package named bit64 for R must be installed when working with user-defined variables to store 64 bit integers, as these are not natively supported by R (please refer to the function [hdfql_variable_register](5-2-51-hdfql-variable-register.md) for additional information). This package can be found at <https://cran.r-project.org/web/packages/bit64>, along with instructions on how to install and use it.

[^10]: 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).