5.2.6hdfql_cursor_initialize

#Syntax

#Description

Initialize a cursor named cursor for subsequent use. Before a new cursor is used for the first time, it should always be initialized (otherwise, unexpected errors may arise, such as a segmentation fault). The initialization of a cursor sets its data type to undefined (HDFQL_UNDEFINED), changes its current element to NULL, and resets its count, number of dimensions, and position attributes to zero, zero, and minus one, respectively, making it ready for use. Of note, the process of initializing a cursor is only required in C and performed once, while in other programming languages supported by HDFql – namely C++, Java, Python, C#, Fortran, R, and MATLAB – such initialization is redundant (i.e. not required), as it is done automatically (by HDFql) when creating a cursor.

#Parameter(s)

cursor – pointer to a cursor (previously declared) to initialize with default values. If the pointer is NULL (in C), the cursor in use is initialized 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 initialized instead).

#Return

int – depending on the success in initializing cursor, it can either be HDFQL_SUCCESS or HDFQL_ERROR_UNKNOWN.

#Example(s)

// create a cursor named "my_cursor" 
HDFQL_CURSOR my_cursor; 

// initialize cursor "my_cursor" 
hdfql_cursor_initialize(&my_cursor);

// use cursor "my_cursor" 
hdfql_cursor_use(&my_cursor);

// display number of elements in cursor "my_cursor" (should be "Number of elements in cursor is 0")
printf("Number of elements in cursor is %d\n", hdfql_cursor_get_count(NULL));