# SQLite GM extension

Version 0.1
Written by Homunculus

# Introduction

> This extension provides functionalities to interface with SQLite databases.
> "SQLite is a software library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine. SQLite is the most widely deployed SQL database engine in the world. The source code for SQLite is in the public domain." ().
> The fact that database files are self-contained and work on a local machine makes this database particulariliy useful in the Game Maker context. Functionalities provided by this extension include some helper funtions reducing the need to know the SQL syntax. Please refer to the website above in order to learn more about the SQL queries syntax.

# Basic functions

Basic functions to handle the database and retrieve data.

> sqlite_open_database(dbname) Opens a database with name dbname. If the database doesn't exist, it is created. Returns the database id > 0. If 0 ise returned, too many connections are open (5 max).

> sqlite_close_database(db)Closes an open database connection. db is the database handle to close. Returns 0 if successfull.
> Returns

> sqlite_error_code(db) Returns the error code produced by the last function call in database db. Don't call this function if there was no error in the last function call.

> sqlite_error_message(db) Returns a string containing the description of the error occurred in the last function call in databae db. Don't call this if there was no error

> sqlite_query(db,query) Generates a query id in a db from a specified sqlite query. This id must be passed to th eother functions neededng a query as argument. Note that this call doesn't executes the query, it just creates it. In order to execute the query sqlite_fetch_row must be called. Returns an id > 0 if query is successfully created, 0 if too many queries are open (max 5), < 0 if an error occured.

> sqlite_fetch_row(query) Executes a given open query, where query is a query id (see sqlite_query function). In multiple rows results, Every call of this function fecthes a new row. Row data can then be accessed using sqlite_get_string or sqlite_get_number. Returns 1 if row data is successfully returned, 0 if there's no more data, < 0 if an error occured.

> sqlite_free_query(query) Queries performed are considered open in order to use functions like sqlite_fetch_row, this means that once finished, they have to be closed with this function. Given a query id, this function returns 0 if the query has been sucessfully closed or freed .

> sqlite_get_number(query,colnum) Given a query id and a column number, this function returns a number value from the secified query at the current row.

> sqlite_get_string(query,colnum) Given a query id and a column number, this function returns a string value from the secified query at the current row.

> sqlite_reset_query(query) Resets a given query, so that calling sqlite_fetch_row starts again formt he first returned row. Returns 0 if successful.

> sqlite_last_id(db) Returns the last sucessfully inserted id in database db.

> sqlite_rows_affected(db) Returns the number of rows affected by the last transaction in db.

# Helper functions

These functions help perofrming actions and queries in the database.

> sqlite_execute_sql(db) Exectues a given sqlite query in database db, like sqlite_query, but this function already executes and closes the query. Useful for queries that don't need to return data.

> sqlite_find_all(db,table,select,conditions,groupby,order,limit,offset) Returns a query id built on the parameters passed, with th scope to fetch rows of data from the database db. Table is the table where the data has to be retrieved, select are the columns to retireve (use "*" for all), conditions are the sql conditions to restrict the results, groupby specifies parameters of the GRUP BY sql parameters, order specifies the orser of the resulting rows based on the specified column name, limit specifies a numeric limit to the rows retireved (-1 for no limit), offset specifies from which row the data should be considered (-1 for default, can not be used without limit). Remember that this query needs to be freed once finished useign the data.

> sqlite_find_first(db,table,select,conditions)Like the function above, but this time a single row is returned containing already the row data, like in sqlite_fetch_row. Query must be freed.

> sqlite_count(db,table,select,conditions) Returns the numbers of rows of a specified table, given some conditions. Parameters are like above, but select this time specifies if NULL data of a specified column is taken into account (use "*" to retireve all rows, even with null values). This query doesn't need to be closed.

> sqlite_insert(db,table,columns,values) Inserts data into a table of database db. Columns specifies where and the order in which values are inserted. If columns is empty (""), values should contain data for every row in the order they appear in the database. This query doesn't need to be closed.

> sqlite_update(db,table,values,conditions) Updates data in a specified table in database db. Values specifies the values to update, in the form: "name = 'Homunculus', age = 23, ...". Conditions are used to specify which record to update. This query doesn't need to be closed.

> sqlite_delete(db,table,conditions) Deletes records from a table in database db. Conditions are used to specify which record(s) to delete. This query doesn't need to be closed.