5.2.51hdfql_variable_register

#Syntax

#Description

Register a variable named variable for subsequent use. In other words, for HDFql to be able to read/write values from/to a user-defined variable, it must first be registered. If the operation is successful, variable is registered and a number is assigned to it. This number – calculated by HDFql – starts with zero and is incremented by one every time a new variable is registered. If variable is registered more than once, only one number is assigned to it (namely, the number assigned upon the first registration). Of note, currently up to eight variables can be registered at any given time (trying to register more than this number will raise an HDFQL_ERROR_FULL). In C, C++, and Fortran, any variable may be registered as long as HDFql can properly read/write values from/to it by having direct access to the memory associated with it – otherwise, unexpected errors may arise, such as a segmentation fault. The following restrictions apply to other programming languages (supported by HDFql):

• In Java¹, only a variable that is an array of the “byte” (or “Byte”), “short” (or “Short”), “int” (or “Integer”), “long” (or “Long”), “float” (or “Float”), “double” (or “Double”), “String”, “ArrayList”, or “Object” data type, or of a user-defined Java class, may be registered. Any attempt to register a variable that is not an array of one of the previously enumerated data types (or corresponding wrapper classes) or a user-defined Java class will return an error (HDFQL_ERROR_UNEXPECTED_DATA_TYPE).
• In Python, only a variable that is a NumPy array of “int8”, “uint8”, “int16”, “uint16”, “int32”, “uint32”, “int64”, “uint64”, “float32”, “float64”, “Ssize”, “ubyte”, or “void” (i.e. compound/structured) data type, or a Python list, may be registered. Any attempt to register a variable that is not a NumPy array of one of the previously enumerated data types or a Python list will return an error (HDFQL_ERROR_UNEXPECTED_DATA_TYPE). Please refer to https://www.numpy.org for additional information.
• In C#, only a variable that is an array of “SByte” (or “sbyte”), “Byte” (or “byte”), “Int16” (or “short”), “UInt16” (or “ushort”), “Int32” (or “int”), “UInt32” (or “uint”), “Int64” (or “long”), “UInt64” (or “ulong”), “Single” (or “float”), “Double” (or “double”), “String” (or “string”), or “Object” (or “object”) data type, or of a struct, may be registered. Any attempt to register a variable that is not an array of one of the previously enumerated data types (or corresponding aliases) or of a struct will return an error (HDFQL_ERROR_UNEXPECTED_DATA_TYPE).
• In R, only a variable that is a vector, matrix, or array of “integer”, “integer64” (through package bit64), “numeric”, “double”, “character”, or “raw” data type may be registered. Any attempt to register a variable that is not a vector, matrix, or array of one of the previously enumerated data types will return an error (HDFQL_ERROR_UNEXPECTED_DATA_TYPE).
• In MATLAB, only a variable that is a vector, matrix, or array of “int8”, “uint8”, “int16”, “uint16”, “int32”, “uint32”, “int64”, “uint64”, “single”, “double”, or “cell” (i.e. “{}”) data type may be registered. Any attempt to register a variable that is not a vector, matrix, or array of one of the previously enumerated data types will return an error (HDFQL_ERROR_UNEXPECTED_DATA_TYPE).

An important aspect to remember when working with a variable is that its address should not change from the moment it has been registered until it is used in the intended operation (e.g. SELECT) or function (e.g. HDFQL_VARIABLE_GET_NUMBER), as HDFql will not be able to identify the variable. In this case, the operation or function will raise an error (HDFQL_ERROR_NOT_REGISTERED). In case a variable needs to change its address (for whatever reason), first unregister it via the function hdfql_variable_unregister, change its address, and register it again. In general, it is advisable to register a variable just before executing the HDFql operation or function that employs it, and to unregister it as soon as it is no longer used (this is especially relevant in C#, where variables are pinned when registered and thus cannot be moved by the Garbage Collector).

#Parameter(s)

variable – pointer to a variable to register for subsequent use.

#Return

int – depending on the success in registering the variable for subsequent use, it can be equal to or greater than zero (i.e. the number assigned to the variable when successfully registered), HDFQL_ERROR_NO_ADDRESS, HDFQL_ERROR_FULL, or HDFQL_ERROR_UNEXPECTED_DATA_TYPE.

#Example(s)

// declare variables 
char script[1024];
short data[3]; 
int number;

// create an HDF5 dataset named "my_dataset" of data type short of one dimension (size 3) 
hdfql_execute("CREATE DATASET my_dataset AS SMALLINT(3)");

// populate variable "data" with certain values 
data[0] = 21; 
data[1] = 18;
data[2] = 75;

// register variable "data" for subsequent use (by HDFql) 
number = hdfql_variable_register(data);

// prepare script to insert (i.e. write) values from variable "data" into dataset "my_dataset"
sprintf(script, "INSERT INTO my_dataset VALUES FROM MEMORY %d", number);

// execute script 
hdfql_execute(script); 

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

// declare structure 
struct coordinate
{
   double latitude; 
   double longitude; 
};

// declare variables 
char script[1024];
struct coordinate location; 
int number;

// create an HDF5 attribute named "my_attribute" of data type compound composed of two members named "latitude" (of data type double) and "longitude" (of data type double)
hdfql_execute("CREATE ATTRIBUTE my_attribute AS COMPOUND(latitude AS DOUBLE, longitude AS DOUBLE)");

// populate variable "location" with certain values 
location.latitude = 15.9803486587; 
location.longitude = 48.6352028395;

// register variable "location" for subsequent use (by HDFql) 
number = hdfql_variable_register(&location);

// prepare script to insert (i.e. write) values from variable "location" into attribute "my_attribute"
sprintf(script, "INSERT INTO my_attribute VALUES FROM MEMORY %d", number);

// execute script 
hdfql_execute(script); 

// unregister variable "location" as it is no longer used/needed (by HDFql) 
hdfql_variable_unregister(&location);