4.2Subcursor

HDFql also provides subcursors – they are meant to complement (i.e. help) cursors in the task of storing data of type HDFQL_CHAR, HDFQL_VARTINYINT, HDFQL_UNSIGNED_VARTINYINT, HDFQL_VARSMALLINT, HDFQL_UNSIGNED_VARSMALLINT, HDFQL_VARINT, HDFQL_UNSIGNED_VARINT, HDFQL_VARBIGINT, HDFQL_UNSIGNED_VARBIGINT, HDFQL_VARFLOAT, HDFQL_VARDOUBLE, and HDFQL_OPAQUE. In practice, when a result set is of one of these data types, only the first element of the result set is stored in the cursor (as expected), while all elements of the result set are stored in the subcursor. In other words, each position of the cursor stores the first element of the result set and also points to a subcursor that, in turn, stores all the elements of the result set. The values stored in a subcursor (which are also known as a result subset) can be accessed with the functions starting with “hdfql_subcursor_get” (enumerated in Table 5.9). Similar to cursors, HDFql subcursors offer several ways or functionalities to traverse result subsets, namely:

• First (moves subcursor to the first position within the result subset – hdfql_subcursor_first)
• Last (moves subcursor to the last position within the result subset – hdfql_subcursor_last)
• Next (moves subcursor to the next position within the result subset – hdfql_subcursor_next)
• Previous (moves subcursor to the previous position within the result subset – hdfql_subcursor_previous)
• Absolute (moves subcursor to an absolute position within the result subset – hdfql_subcursor_absolute)
• Relative (moves subcursor to a relative position within the result subset – hdfql_subcursor_relative)

The following C code snippet illustrates the usage of HDFql subcursors, as well as some typical operations performed on/by these.

// create an HDF5 dataset named "my_dataset" of data type variable-length int of one dimension (size 4)
hdfql_execute("CREATE DATASET my_dataset AS VARINT(4)");

// insert (i.e. write) values into dataset "my_dataset" 
hdfql_execute("INSERT INTO my_dataset VALUES((7, 8), (9), (6, 1, 2), (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 next position within the result set 
while(hdfql_cursor_next(NULL) == HDFQL_SUCCESS) 
{ 
    // display element of the cursor in use 
    printf("Current element of cursor is %d\n", *hdfql_cursor_get_int(NULL)); 

    // move the subcursor in use to the next position within the result subset 
    while(hdfql_subcursor_next(NULL) == HDFQL_SUCCESS) 
    { 
       // display element of the subcursor in use 
       printf("   Current element of subcursor is %d\n", *hdfql_subcursor_get_int(NULL)); 
    } 
}

The output of executing the code snippet would be similar to the following:

Current element of cursor is 7
   Current element of subcursor is 7
   Current element of subcursor is 8
Current element of cursor is 9
   Current element of subcursor is 9
Current element of cursor is 6
   Current element of subcursor is 6
   Current element of subcursor is 1
   Current element of subcursor is 2
Current element of cursor is 4
   Current element of subcursor is 4
   Current element of subcursor is 0