' The MIT License (MIT)
'
' Copyright (C) 2026 Scott Duensing
'
' Permission is hereby granted, free of charge, to any person obtaining a copy
' of this software and associated documentation files (the "Software"), to
' deal in the Software without restriction, including without limitation the
' rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
' sell copies of the Software, and to permit persons to whom the Software is
' furnished to do so, subject to the following conditions:
'
' The above copyright notice and this permission notice shall be included in
' all copies or substantial portions of the Software.
'
' THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
' IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
' FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
' AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
' LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
' FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
' IN THE SOFTWARE.

' sql.bas -- SQL Database Library for DVX BASIC
'
' Provides SQLite database access through DECLARE LIBRARY wrappers.
' Handles and cursors are integers; strings are passed by value.
'
' Usage: Add this file to your project.

DECLARE LIBRARY "basrt"
    ' Open a database file. Returns a handle (>0), or 0 on failure.
    DECLARE FUNCTION SQLOpen(BYVAL path AS STRING) AS INTEGER

    ' Close a database.
    DECLARE SUB SQLClose(BYVAL db AS INTEGER)

    ' Execute a non-query SQL statement. Returns True on success.
    DECLARE FUNCTION SQLExec(BYVAL db AS INTEGER, BYVAL sql AS STRING) AS INTEGER

    ' Return the last error message for a database.
    DECLARE FUNCTION SQLError$(BYVAL db AS INTEGER) AS STRING

    ' Execute a query and return a result set cursor.
    DECLARE FUNCTION SQLQuery(BYVAL db AS INTEGER, BYVAL sql AS STRING) AS INTEGER

    ' Advance the cursor to the next row. Returns True if a row is available.
    DECLARE FUNCTION SQLNext(BYVAL rs AS INTEGER) AS INTEGER

    ' Test whether the cursor is past the last row.
    DECLARE FUNCTION SQLEof(BYVAL rs AS INTEGER) AS INTEGER

    ' Return the number of columns in a result set.
    DECLARE FUNCTION SQLFieldCount(BYVAL rs AS INTEGER) AS INTEGER

    ' Return a column name by index (0-based).
    DECLARE FUNCTION SQLFieldName$(BYVAL rs AS INTEGER, BYVAL col AS INTEGER) AS STRING

    ' Return a column value as text by index (0-based).
    DECLARE FUNCTION SQLFieldText$(BYVAL rs AS INTEGER, BYVAL col AS INTEGER) AS STRING

    ' Return a column value as text by column name.
    DECLARE FUNCTION SQLField$(BYVAL rs AS INTEGER, BYVAL colName AS STRING) AS STRING

    ' Return a column value as an integer by index (0-based).
    DECLARE FUNCTION SQLFieldInt(BYVAL rs AS INTEGER, BYVAL col AS INTEGER) AS INTEGER

    ' Return a column value as a double by index (0-based).
    DECLARE FUNCTION SQLFieldDbl(BYVAL rs AS INTEGER, BYVAL col AS INTEGER) AS DOUBLE

    ' Free a result set cursor.
    DECLARE SUB SQLFreeResult(BYVAL rs AS INTEGER)

    ' Return the number of rows affected by the last INSERT/UPDATE/DELETE.
    DECLARE FUNCTION SQLAffected(BYVAL db AS INTEGER) AS INTEGER
END DECLARE
