5.2.28hdfql_cursor_relative

#Syntax

#Description

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

#Parameter(s)

cursor – pointer to a cursor to move to a relative position with respect to its current position. If the pointer is NULL (in C), 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 cursor in use is moved to a relative position instead).

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

#Return

int – depending on the success in moving the cursor 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 five HDF5 groups named "g1", "g2", "g3", "g4", and "g5" 
hdfql_execute("CREATE GROUP g1, g2, g3, g4, g5");

// show (i.e. get) all existing groups and populate cursor in use with these (should return "g1", "g2", "g3", "g4", "g5")
hdfql_execute("SHOW GROUP");

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

// move the cursor in use to relative position 2 within the result set 
hdfql_cursor_relative(NULL, 2);

// display current element of the cursor within the result set (should be "Current element of cursor is g3")
printf("Current element of cursor is %s", hdfql_cursor_get_char(NULL));

// move the cursor in use to relative position -2 within the result set 
hdfql_cursor_relative(NULL, -2); 

// display current element of the cursor within the result set (should be "Current element of cursor is g1")
printf("Current element of cursor is %s", hdfql_cursor_get_char(NULL));