5.2.29hdfql_subcursor_relative

#Syntax

#Description

Move the subcursor in use to a relative position position with respect to its current position. The first element of the result subset is at position zero, while the last element is located at the position returned by hdfql_subcursor_get_count - 1. An attempt to move the subcursor before the first element will return an error and set the position of the subcursor to minus one, while an attempt to move the subcursor after the last element will return an error and set the position of the subcursor to the number of elements in the result set.

#Parameter(s)

cursor – pointer to a cursor to move the subcursor in use to a relative position with respect to its current position. If the pointer is NULL (in C), the subcursor of the cursor in use is moved to a relative position instead. The equivalent of a NULL pointer in C++, Java, Python, C#, Fortran, R, and MATLAB HDFql wrappers is NULL, null, None, null, NULL(), NULL, and NaN, respectively. While in C cursor is mandatory, in C++, Java, Python, C#, Fortran, R, and MATLAB it is optional (when not specified, the subcursor of the cursor in use is moved to a relative position instead).

position – long long that specifies the relative position to which to move the subcursor. If positive, the subcursor will move forward in the result set relative to its current position. If negative, the subcursor will move backward in the result set relative to its current position.

#Return

int – depending on the success in moving the subcursor to a relative position with respect to its current position, it can be HDFQL_SUCCESS, HDFQL_ERROR_EMPTY, HDFQL_ERROR_BEFORE_FIRST, or HDFQL_ERROR_AFTER_LAST.

#Example(s)

// create an HDF5 dataset named "my_dataset" of data type variable-length int of two dimensions (size 2x2)
hdfql_execute("CREATE DATASET my_dataset AS VARINT(2, 2)");

// insert (i.e. write) values into dataset "my_dataset" 
hdfql_execute("INSERT INTO my_dataset VALUES(((7, 8, 5), (9)), ((6, 1, 2, 3), (4, 0)))"); 

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

// move the cursor in use to the first position within the result set 
hdfql_cursor_first(NULL); 

// move the subcursor in use to the first position within the result subset 
hdfql_subcursor_first(NULL);

// move the subcursor in use to relative position 2 within the result subset 
hdfql_subcursor_relative(NULL, 2);

// display current element of the subcursor in use within the result subset (should be "Current element of subcursor is 5")
printf("Current element of subcursor is %d", hdfql_subcursor_get_int(NULL));

// move the subcursor in use to relative position -1 within the result subset 
hdfql_subcursor_relative(NULL, -1); 

// display current element of the subcursor in use within the result subset (should be "Current element of subcursor is 8")
printf("Current element of subcursor is %d", hdfql_subcursor_get_int(NULL));