# 5.2.25 hdfql_subcursor_previous

Part of: [5 Application Programming Interface](5-application-programming-interface.md) › [5.2 Functions](5-2-functions.md)

### Syntax

int hdfql_subcursor_previous(HDFQL_CURSOR \*_cursor_)

### Description

Move the subcursor in use one position backward from its current position. In other words, the subcursor will point to the previous element of the result subset, and its position is decremented by one. If the result subset is empty or the subcursor is in the first position, an error is returned, and its position remains unchanged (i.e. remains minus one) or is set to minus one, respectively.

### Parameter(s)

_cursor_ – pointer to a cursor to move the subcursor in use one position backward from its current position. If the pointer is NULL (in C), the subcursor of the cursor in use is moved one position backward from its current 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 one position backward from its current position instead).

### Return

int – depending on the success in moving the subcursor one position backward from its current position, it can be [HDFQL_SUCCESS](5-1-constants.md#hdfql_success), [HDFQL_ERROR_EMPTY](5-1-constants.md#hdfql_error_empty), [HDFQL_ERROR_BEFORE_FIRST](5-1-constants.md#hdfql_error_before_first), or [HDFQL_ERROR_AFTER_LAST](5-1-constants.md#hdfql_error_after_last).

### Example(s)

```c
// 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 last position within the result subset 
hdfql_subcursor_last(NULL);

// move the subcursor in use to the previous position within the result subset (two times) 
hdfql_subcursor_previous(NULL); 
hdfql_subcursor_previous(NULL);

// display position of the subcursor within the result subset (should be "Position of subcursor is 0")
printf("Position of subcursor is %lld\n", hdfql_subcursor_get_position(NULL));
```