Low-level API

Michael Koohafkan

2019-08-05

The hdfqlr package provides a high-level API for reading and writing HDF files. However, the package also provides access to the lower-level API provided by the HDFql R wrapper.

library(hdfqlr)
hql_load('path/to/hdfql-x.x.x')

To access the low-level API, simply attach the hql$wrapper environment to your workspace.

attach(hql$wrapper)

The HDFql wrapper functions can now be accessed directly. The example code from hdfql-2.1.0/example/HDFqlExample.R is included below:

example.h5 = shQuote(tempfile(fileext = ".h5"))
print(paste("HDFql version:", HDFQL_VERSION))

## [1] "HDFql version: 2.1.0"

# create an HDF5 file named "example.h5" and use (i.e. open) it
hdfql_execute(paste("CREATE FILE", example.h5))

## [1] 0

hdfql_execute(paste("USE FILE", example.h5))

## [1] 0

# show (i.e. get) HDF5 file currently in use and populate HDFql default cursor with it
hdfql_execute("SHOW USE FILE")

## [1] 0

# display HDF5 file currently in use
hdfql_cursor_first()

## [1] 0

print(paste("File in use:", hdfql_cursor_get_char()))

## [1] "File in use: C:\\Users\\mkoohafk\\AppData\\Local\\Temp\\RtmpwbdzZ8\\file450858325d1.h5"

# create an attribute named "example_attribute" of data type float with an initial value of 12.4
hdfql_execute("CREATE ATTRIBUTE example_attribute AS FLOAT VALUES(12.4)")

## [1] 0

# select (i.e. read) data from attribute "example_attribute" and populate HDFql default cursor with it
hdfql_execute("SELECT FROM example_attribute")

## [1] 0

# display value of attribute "example_attribute"
hdfql_cursor_first()

## [1] 0

print(paste("Attribute value:", hdfql_cursor_get_float()))

## [1] "Attribute value: 12.3999996185303"

# create a dataset named "example_dataset" of data type int of two dimensions (size 3x2)
hdfql_execute("CREATE DATASET example_dataset AS INT(3, 2)")

## [1] 0

# create variable "values" and populate it with certain values
values <- array(dim = c(3, 2))
for (x in 1:2) {
  for (y in 1:3) {
    values[y, x] <- as.integer(x * 3 + y - 3)
  }
}

# register variable "values" for subsequent use (by HDFql)
hdfql_variable_register(values)

## [1] 0

# insert (i.e. write) values from variable "values" into dataset "example_dataset"
hdfql_execute(paste("INSERT INTO example_dataset VALUES FROM MEMORY", hdfql_variable_get_number(values)))

## [1] 0

# unregister variable "values" as it is no longer used/needed (by HDFql)
hdfql_variable_unregister(values)

## [1] 0

# populate variable "values" with zeros (i.e. reset variable)
for (x in 1:2) {
  for (y in 1:3) {
    values[y, x] <- as.integer(0)
  }
}

# register variable "values" for subsequent use (by HDFql)
hdfql_variable_register(values)

## [1] 0

# select (i.e. read) data from dataset "example_dataset" and populate variable "values" with it
hdfql_execute(paste("SELECT FROM example_dataset INTO MEMORY", hdfql_variable_get_number(values)))

## [1] 0

# unregister variable "values" as it is no longer used/needed (by HDFql)
hdfql_variable_unregister(values)

## [1] 0

# display content of variable "values"
print("Dataset value (through variable):")

## [1] "Dataset value (through variable):"

for (x in 1:2) {
  for (y in 1:3) {
    print(values[y, x])
  }
}

## [1] 1
## [1] 2
## [1] 3
## [1] 4
## [1] 5
## [1] 6

# another way to select (i.e. read) data from dataset "example_dataset" using HDFql default cursor
hdfql_execute("SELECT FROM example_dataset")

## [1] 0

# display content of HDFql default cursor
print("Dataset value (through cursor):")

## [1] "Dataset value (through cursor):"

while (hdfql_cursor_next() == HDFQL_SUCCESS) {
  print(hdfql_cursor_get_int())
}

## [1] 1
## [1] 2
## [1] 3
## [1] 4
## [1] 5
## [1] 6

# create cursor "my_cursor" and use it
my_cursor <- hdfql_cursor()
hdfql_cursor_use(my_cursor)

## [1] 0

# show (i.e. get) size (in bytes) of dataset "example_dataset" and populate cursor "my_cursor" with it
hdfql_execute("SHOW SIZE example_dataset")

## [1] 0

# display content of cursor "my_cursor"
hdfql_cursor_first()

## [1] 0

print(paste("Dataset size (in bytes):", hdfql_cursor_get_bigint()))

## [1] "Dataset size (in bytes): 24"

# close the file
hdfql_execute(paste("CLOSE FILE", example.h5))

## [1] 0