cursor.c

Go to the documentation of this file.

/*!
   \file lib/db/dbmi_base/cursor.c
 
   \brief DBMI Library (base) - cursors management
 
   SPDX-FileCopyrightText: 1999-2009 GRASS Development Team
   SPDX-License-Identifier: GPL-2.0-or-later
 
   \author Joel Jones (CERL/UIUC), Radim Blazek
 */
 
#include <stdlib.h>
#include <grass/dbmi.h>
 
/*!
   \brief Initialize dbCursor
 
   \param cursor pointer to dbCursor to be initialized
 */
void db_init_cursor(dbCursor *cursor)
{
    G_zero(cursor, sizeof(dbCursor));
    cursor->token = -1;
}
 
/*!
   \brief Allocate table for cursor
 
   \param cursor pointer to dbCursor
   \param ncols  number of column in table
 
   \return DB_OK on success
   \return error code on error
 */
int db_alloc_cursor_table(dbCursor *cursor, int ncols)
{
    cursor->table = db_alloc_table(ncols);
    if (cursor->table == NULL)
        return db_get_error_code();
    return DB_OK;
}
 
/*!
   \brief Free allocated dbCursor
 
   \param cursor pointer to dbCursor
 */
void db_free_cursor(dbCursor *cursor)
{
    if (cursor->table)
        db_free_table(cursor->table);
    if (cursor->column_flags)
        db_free_cursor_column_flags(cursor);
    db_init_cursor(cursor);
}
 
/*!
   \brief Get table allocated by cursor
 
   \param cursor pointer to dbCursor
 
   \return pointer to dbTable
 */
dbTable *db_get_cursor_table(dbCursor *cursor)
{
    return cursor->table;
}
 
/*!
   \brief Set table for given cursor
 
   \param cursor pointer to dbCursor
   \param table  pointer to dbTable
 */
void db_set_cursor_table(dbCursor *cursor, dbTable *table)
{
    cursor->table = table;
}
 
/*!
   \brief Get cursor token
 
   \param cursor pointer to dbCursor
 
   \return pointer to dbToken
 */
dbToken db_get_cursor_token(dbCursor *cursor)
{
    return cursor->token;
}
 
/*!
   \brief Set cursor token
 
   \param cursor pointer to dbCursor
   \param token  pointer to dbToken
 */
void db_set_cursor_token(dbCursor *cursor, dbToken token)
{
    cursor->token = token;
}
 
/*!
   \brief Set cursor to be read-only (select)
 
   \param cursor pointer to dbCursor
 */
void db_set_cursor_type_readonly(dbCursor *cursor)
{
    cursor->type = DB_READONLY;
}
 
/*!
   \brief Set cursor to be writable (update)
 
   \param cursor pointer to dbCursor
 */
void db_set_cursor_type_update(dbCursor *cursor)
{
    cursor->type = DB_UPDATE;
}
 
/*!
   \brief Set cursor to be writable (insert)
 
   \param cursor pointer to dbCursor
 */
void db_set_cursor_type_insert(dbCursor *cursor)
{
    cursor->type = DB_INSERT;
}
 
/*!
   \brief Check cursor type
 
   \param cursor pointer to dbCursor
 
   \return 1 for known cursor type
   \return 0 for unknown cursor type
 */
int db_test_cursor_type_fetch(dbCursor *cursor)
{
    return (cursor->type == DB_READONLY || cursor->type == DB_UPDATE ||
            cursor->type == DB_INSERT);
}
 
/*!
   \brief Check if cursor type is 'update'
 
   \param cursor pointer to dbCursor
 
   \return 1 if cursor type is 'update'
   \return 0 otherwise
 */
int db_test_cursor_type_update(dbCursor *cursor)
{
    return (cursor->type == DB_UPDATE);
}
 
/*!
   \brief Check if cursor type is 'insert'
 
   \param cursor pointer to dbCursor
 
   \return 1 if cursor type is 'insert'
   \return 0 otherwise
 */
int db_test_cursor_type_insert(dbCursor *cursor)
{
    return (cursor->type == DB_INSERT);
}
 
/*!
   \brief Set cursor mode
 
   Modes:
   - DB_SCROLL
   - DB_INSENSITIVE
 
   \param cursor pointer to dbCursor
   \param mode cursor mode
 */
void db_set_cursor_mode(dbCursor *cursor, int mode)
{
    cursor->mode = mode;
}
 
/*!
   \brief Set 'scroll' cursor mode
 
   \param cursor pointer to dbCursor
 */
void db_set_cursor_mode_scroll(dbCursor *cursor)
{
    cursor->mode |= DB_SCROLL;
}
 
/*!
   \brief Unset 'scroll' cursor mode
 
   \param cursor pointer to dbCursor
 */
void db_unset_cursor_mode_scroll(dbCursor *cursor)
{
    cursor->mode &= ~DB_SCROLL;
}
 
/*!
   \brief Unset cursor mode
 
   \param cursor pointer to dbCursor
 */
void db_unset_cursor_mode(dbCursor *cursor)
{
    cursor->mode = 0;
}
 
/*!
   \brief Set 'intensive' cursor mode
 
   \param cursor pointer to dbCursor
 */
void db_set_cursor_mode_insensitive(dbCursor *cursor)
{
    cursor->mode |= DB_INSENSITIVE;
}
 
/*!
   \brief Unset 'intensive' cursor mode
 
   \param cursor pointer to dbCursor
 */
void db_unset_cursor_mode_insensitive(dbCursor *cursor)
{
    cursor->mode &= ~DB_INSENSITIVE;
}
 
/*!
   \brief Check if cursor mode is 'scroll'
 
   \param cursor pointer to dbCursor
 
   \return 1 if true
   \return 0 if false
 */
int db_test_cursor_mode_scroll(dbCursor *cursor)
{
    return (cursor->mode & DB_SCROLL);
}
 
/*!
   \brief Check if cursor mode is 'intensive'
 
   \param cursor pointer to dbCursor
 
   \return 1 if true
   \return 0 if false
 */
int db_test_cursor_mode_insensitive(dbCursor *cursor)
{
    return (cursor->mode & DB_INSENSITIVE);
}
 
/*!
   \brief Allocate columns' flags for cursor
 
   \param cursor pointer to dbCursor
 
   \return DB_OK on success
   \return error code on failure
 */
int db_alloc_cursor_column_flags(dbCursor *cursor)
{
    int ncols;
    int col;
 
    ncols = db_get_cursor_number_of_columns(cursor);
    cursor->column_flags = (short *)db_calloc(ncols, sizeof(short));
    if (cursor->column_flags == NULL)
        return db_get_error_code();
    for (col = 0; col < ncols; col++)
        db_unset_cursor_column_flag(cursor, col);
    return DB_OK;
}
 
/*!
   \brief Free columns' flags of cursor
 
   \param cursor pointer to dbCursor
 */
void db_free_cursor_column_flags(dbCursor *cursor)
{
    if (cursor->column_flags)
        db_free(cursor->column_flags);
    cursor->column_flags = NULL;
}
 
/*!
   \brief Set Column flag to 'update'
 
   \param cursor pointer to dbCursor
   \param col    column index (starting with '0')
 */
void db_set_cursor_column_for_update(dbCursor *cursor, int col)
{
    db_set_cursor_column_flag(cursor, col);
}
 
/*!
   \brief Unset 'update' column flag
 
   \param cursor pointer to dbCursor
   \param col    column index (starting with '0')
 */
void db_unset_cursor_column_for_update(dbCursor *cursor, int col)
{
    db_unset_cursor_column_flag(cursor, col);
}
 
/*!
   \brief Check if column flag is 'update'
 
   \param cursor pointer to dbCursor
   \param col    column index (starting with '0')
 
   \return 1 if true
   \return 0 if false
 */
int db_test_cursor_column_for_update(dbCursor *cursor, int col)
{
    return db_test_cursor_column_flag(cursor, col);
}
 
/*!
   \brief Check if columns' flag is 'update'
 
   \param cursor pointer to dbCursor
 
   \return 1 if true
   \return 0 if false
 */
int db_test_cursor_any_column_for_update(dbCursor *cursor)
{
    return db_test_cursor_any_column_flag(cursor);
}
 
/*!
   \brief Set column's flag
 
   \param cursor pointer to dbCursor
   \param col    column index (starting with '0')
 */
void db_set_cursor_column_flag(dbCursor *cursor, int col)
{
    if (cursor->column_flags)
        cursor->column_flags[col] = 1;
}
 
/*!
   \brief Unset column's flag
 
   \param cursor pointer to dbCursor
   \param col    column index (starting with '0')
 */
void db_unset_cursor_column_flag(dbCursor *cursor, int col)
{
    if (cursor->column_flags)
        cursor->column_flags[col] = 0;
}
 
/*!
   \brief Checks column's flag
 
   \param cursor pointer to dbCursor
   \param col    column index (starting with '0')
 
   \return 1 if flag is defined
   \return 0 otherwise
 */
int db_test_cursor_column_flag(dbCursor *cursor, int col)
{
    return cursor->column_flags && cursor->column_flags[col] ? 1 : 0;
}
 
/*!
   \brief Get number of columns
 
   \param cursor pointer to dbCursor
 */
int db_get_cursor_number_of_columns(dbCursor *cursor)
{
    dbTable *table;
 
    table = db_get_cursor_table(cursor);
    if (table)
        return db_get_table_number_of_columns(table);
    return 0;
}
 
/*!
   \brief Checks columns' flag
 
   Is any cursor column flag set?
 
   \param cursor pointer to dbCursor
 
   \return 1 if true
   \return 0 if false
 */
int db_test_cursor_any_column_flag(dbCursor *cursor)
{
    int ncols, col;
 
    ncols = db_get_cursor_number_of_columns(cursor);
    for (col = 0; col < ncols; col++)
        if (db_test_cursor_column_flag(cursor, col))
            return 1;
    return 0;
}