5.2.26hdfql_cursor_absolute

#Syntax

#Description

Move a cursor named cursor to an absolute position position within the result set. 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 an absolute position within the result set. If the pointer is NULL (in C), the cursor in use is moved to an absolute 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 an absolute position instead).

position – long long that specifies the absolute position to which to move the cursor. If positive, the cursor will position itself with reference to the beginning of the result set. If negative, the cursor will position itself with reference to the end of the result set.

#Return

int – depending on the success in moving the cursor to an absolute position within the result set, 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 absolute position 2 within the result set 
hdfql_cursor_absolute(NULL, 2);

// display current element of the cursor in use 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 absolute position -2 within the result set 
hdfql_cursor_absolute(NULL, -2);

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