Scol » Sqlite3

Scol library SQLITE3 documentation

Copyright (c) 2010 Stephane Bisaro, aka Iri <iri@irizone.net>

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.3

or any later version published by the Free Software Foundation;

with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

A copy of the license is included in the section entitled "GNU

Free Documentation License".

[FRENCH]

Usage

Compilation

Installation

API

-> Usage

La librairie libsqlite3 est sous licence Scol et elle est fournie

sans garantie d'efficacité ni de dysfonctionnements.

Voyez le fichier COPYING inclus pour plus amples informations.

Les compilations d'origine ont été faite avec le compilateur GNU GCC

(MingW pour la version MS Windows).

Pour en savoir plus sur le langage Scol, visitez le site :

http://www.scolring.org/

Pour plus d'infos sur SQLite : http://www.sqlite.org/

-> Compilation

Voir le fichier README

-> Installation de la release

Sous GNU/Linux:

1- Quitter Scol s'il était lancé

2- Copiez la bibliothèque "libsqlite3.so" dans le sous-répertoire

"plugins" de SCOL

3- Editez le fichier usm.ini pour y ajouter la ligne suivante :

plugin ./plugins/libsqlite3.so ScolLoadPlugin ScolUnloadPlugin

4- Relancez Scol

Sous MS Windows

1- Quitter Scol s'il était lancé

2- Copiez la bibliothèque "libsqlite3.dll" dans le sous-répertoire

"plugins" de SCOL

3- Editez le fichier usm.ini pour y ajouter la ligne suivante :

plugin plugins/libsqlite3.dll ScolLoadPlugin ScolUnloadPlugin

4- Relancez Scol

-> API fournie

N'hésitez pas à consulter la documentation de SQLite :

http://www.sqlite.org/docs.html

## ObjSqlite :

Type Scol correspondant à un objet connexion Sqlite3

## _sqliteOpenFile

Fonction de connexion à une base de données Sqlite3

La base de données est un fichier physiquement présent dans la partition

Scol active. La base sera en mode sérialisé, cache privé et en lecture

et écriture. Voir _sqliteOpenFileEx ci-dessous.

Typage : fun [Chn P] ObjSqlite

Le second argument demande une référence de fichier en lecture ce qui

implique que le fichier devrait déjà être créé avant. Par exemple, en

utilisant la fonction Scol _createpack (cf doc)

Le premier est le canal dans lequel l'objet sera manipulé. Généralement,

il s'agit du canal courant, correspondant à la fonction Scol _channel

La valeur retournée est l'objet Scol ou nil si une erreur est survenue

(voir les logs le cas échéant)

L'encodage par défaut pour la base de données est l'UTF-8

Note : l'interface entre Sqlite et l'OS sera défini ici par Sqlite

à la valeur par défaut (cf http://www.sqlite.org/c3ref/vfs.html)

Exemple :

typeof mydb = ObjSqlite;;

...

set mydb = _sqliteOpenFile _channel "mybase.db";

## _sqliteOpenFileEx

Comme la fonction précédente, elle permet de se connecter à une base

fichier. Elle permet de configurer plus finement la connexion.

Typage : fun [Chn P I I I] ObjSqlite

Le troisième argument est un drapeau indiquant si la base sera en

lecture seule ou en lecture et écriture (dans ce dernier cas, sous

réserve des restrictions éventuellement imposées : droits d'utilisateur

sur le fichier, droits sur le système de fichiers, etc). Les valeurs

possibles sont : SQLITE_READWRITE (par défaut) ou SQLITE_ONLYREAD

Le quatrième argument est un drapeau indiquant la manière dont est géré le

cache SQLite. Le cache partagé est nouellement supporté, plus d'infos

sur : http://www.sqlite.org/sharedcache.html

Les valeurs possibles sont : SQLITE_OPEN_PRIVATE_CACHE (par défaut) ou

SQLITE_OPEN_SHAREDCACHE.

Pour utiliser le cache partagé, il faut qu'il soit au préalable activé

via _sqliteSharedCacheEnabled (plus bas)

Le cinquième argument est un drapeau indiquant comment est géré le threading.

Si threadsafe est positionné à 1 ou 2, ce drapeau sera pris en compte. Cette

valeur est connue grâce à la fonction _sqliteThreadsafe (voir plus bas).

Les drapeaux possibles sont : SQLITE_OPEN_FULLMUTEX (mode sérialisé, par

défaut) ou SQLITE_OPEN_NOMUTEX (mode multi-thread).

Pour plus de renseignements sur ces modes, voir _sqliteThreadsafe plus bas.

La valeur retournée est l'objet Scol ou nil si une erreur est survenue

(voir les logs le cas échéant)

Exemple :

typeof mydb = ObjSqlite;;

...

set mydb = _sqliteOpenFile _channel "mybase.db" SCOL_SQLITE_ONLYREAD nil nil;

Un ' nil ' est équivalent au drapeau par défaut.

Note : les fonctions de configuration VFS ne sont pas incluses. La configuration

par défaut du système hôte est utilisée.

## _sqliteOpenMemory

Fonction de connexion à une base Sqlite3

La base de données sera créée en mémoire vive et sera effacée lors de l'appel

de la fonction de destruction (_sqliteClose) ou de la vidage de la mémoire par l'OS.

Typage : fun [Chn] ObjSqlite

L'argument est le canal dans lequel l'objet sera manipulé. Généralement,

il s'agit du canal courant, correspondant à la fonction Scol _channel

La valeur retournée est l'objet Scol ou nil si une erreur est survenue

(voir les logs le cas échéant)

Note : cette base de donnée est par nature volatile. Sa destruction

entraîne la destruction irréversible des données qu'elle contient.

La capacité de la base dépend de la mémoire disponible allouée par

le système.

## _sqliteOpenTemp

Fonction de connexion à une base de fichier Sqlite3

La base de données sera créée dans un fichier temporaire et sera effacée

lors de l'appel de la fonction de destruction (_sqliteClose)

Typage : fun [Chn] ObjSqlite

L'argument est le canal dans lequel l'objet sera manipulé. Généralement,

il s'agit du canal courant, correspondant à la fonction Scol _channel

La valeur retournée est l'objet Scol ou nil si une erreur est survenue

(voir les logs le cas échéant).

Note : cette base de données est par nature volatile. Clore la connexion

entraînera la perte des données qu'elle contenait.

## _sqliteClose

Fonction qui ferme et détruit une connexion à une base de données Sqlite3.

Typage : fun [ObjSqlite] I

Le premier argument est l'objet à détruire

La valeur retournée est à 0 si tout est ok, à 1 si la base est occupée

(typiquement, des opérations sont en cours), à nil si l'objet passé en

argument n'est pas valide ou 1 si une erreur est survenue lors de

la destruction de la liaison Sqlite3 (le log donne le numéro de

l'erreur, cf doc http://www.sqlite.org/c3ref/c_abort.html)

## _sqliteCallbackExec

Fonction réflexe appelée à chaque fois qu'une requête effectuée par

_sqliteExec renvoie une valeur (telle qu'un SELECT).

Typage : fun [ObjSqlite fun [ObjSqlite u0 S S] I u0] ObjSqlite

Le typage de la callback est donc : fun [ObjSqlite u0 S S] I

Le premier argument est l'objet connexion à la base de données

Le second est la fonction réflexe

Le troisième est le paramètre utilisateur.

Exemple :

fun mycallback (db, uparam, column, value)=

    _fooS strcat "user parameter : " uparam;

    _fooS strcat "column : " column;

    _fooS strcat "value : " value;

    0;;

...

_sqliteCallbackExec mydb @mycallback "this is my callback";

## _sqliteExec

Exécute une commande SQL compatible dans la base dont la connexion est

passée en premier argument.

Le troisième argument devrait toujours être laissé à NIL.

La fonction retourne un entier qui est le résultat sqlite : 0 si ok ou le

code erreur résultant (cf http://www.sqlite.org/c3ref/c_abort.html).

Le résultat de la requête est envoyé à la callback définie par _sqliteCallbackExec

si et seulement si le code erreur retourné est 0 (succès).

Si plusieurs requêtes sont demandées au sein d'une même commande sql, la callback

sera appelée autant de fois que nécessaire.

Typage : fun [ObjSqlite S I] I

Exemple :

_sqliteExec mydb "CREATE TABLE mytable (nom char(50), prenom char(50));

		INSERT INTO mytable (nom, prenom) VALUES ('Dupond', 'Jean');

		INSERT INTO mytable (nom, prenom) VALUES ('Smith', 'Winston');

		INSERT INTO mytable (nom, prenom) VALUES ('Bartoldi', 'Guiseppe')" nil;

_sqliteExec mydb "SELECT nom FROM mytable" nil;

## _sqliteExecResult (updated 0.2a1 : prototype has changed !)

Exécute une commande SQL compatible dans la base dont la connexion est passée en

premier argument.

Le second argument est la requête.

Le troisième argument devrait être laissé à nil.

La fonction retourne le résultat global de la requête passée en second argument

(et non pas le résultat de l'appel comme c'est le cas avec la fonction '_sqliteExec').

Si la requête est invalide ou les données demandées ne sont pas connues, la fonction

renvoie nil.

Typage : fun [ObjSqlite S I] [[[S S] r1] r1]

Ancien typage obsolète : fun [ObjSqlite S I] [[S S] r1]

Exemple :

typeof db = ObjSqlite;;

fun main ()=

	_showconsole;

	set db = _sqliteOpenFile _channel _checkpack "tests/test.db";

	if db == nil then

		_fooS "ERROR DB"

	else

		nil;

	let "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;" -> sql in

	let _sqliteExecResult db sql nil -> result in

	let _fooS "--> BEGIN" -> _ in

	while result != nil do

		let hd hd result -> [a v] in

		(

		_fooS strcat "A = " a;

		_fooS strcat "V = " v;

		_fooS "";

		set result = tl result;

		);

	_fooS "--> END";

	0;;

## _sqliteVersion

Fonction retournant la version de Sqlite utilisée lors de la compilation

(et par conséquent, celle actuellement utilisée).

Typage : fun [] S

Exemple de valeur retournée : 3.6.23.1

## _sqliteVersionScol

Fonction retournant le numéro de version de la librairie SQLite de Scol.

Typage : fun [] S

Exemple :

_fooS _sqliteVersionScol; // retourne 0.1a1

## _sqliteThreadsafe

Fonction qui retourne l'état du threading. Cette valeur est définie une

fois pour toute lors de la compilation et ne pourra pas être changée

sans recompilation ad hoc.

Si retourne 0, alors le mode est mono-thread

Si retourne 1, alors le mode est sérialisé

Si retourne 2, alors le mode est multi-thread

Devrait retourner 1, mode sérialisé.

Typage : fun [] I

Avec le mode mono-thread (0), SQLite n'est pas sécurié si plus d'un thread

est utilisé en même temps. Si ce mode est actif, il ne peut être changé

même lors de l'ouverture d'une connexion via _sqliteOpenFileEx (dans ce cas,

le drapeau (flag) éventuellement mis sera ignoré).

Avec le mode multi-thread (2), SQlite est ok pour plusieurs threads utilisés

si qu'un seul thread se connecte à une base à la fois. Ce mode peut basculer,

lors de la connexion à une base, via _sqliteOpenFileEx, au mode sérialisé (1).

Avec le mode sérialisé (1), SQLite est ok avec l'utilisation de plusieurs

threads sans aucune restriction. Ce mode peut basculer, lors de la connexion

à une base, via _sqliteOpenFileEx, au mode multi-thread (2).

Toutefois, les developpeurs de SQLite déconseillent les modes (1) et (2).

Ces deux modes sont plus pratiques mais les applications devraient être

codées / conçues de façon à n'utiliser que le mode (0).

http://www.sqlite.org/faq.html (answer 6)

Depuis le code source, la librairie peut être recompilée en modifiant la

valeur définie pour ' SQLITE_THREADSAFE ' dans sqlite3.c. Par défaut elle

est à 1 (mode sérialisé).

## _sqliteSharedCacheEnabled

Active (ou désactive) le cache partagé pour tout le processus (même si

celui-ci contient plusieurs threads).

Typage : fun [I] I

L'argument vaut soit 0 (par défaut, cache non partagé) ou tout autre entier

pour activer cette option.

Retourne 0 si succès ou un code erreur spécifique

(http://www.sqlite.org/c3ref/c_abort.html)

## _sqliteSetSizeLimit

Définit une taille limite maximale pour différents types d'objets SQLite3 pour

une connexion donnée. Cette fonction nécessite une connexion active, un

drapeau indiquant l'objet considéré et la nouvelle taille limite.

Si un objet de taille supérieure se présente, il sera tronqué. Ce peut être une

protection pour certaines attaques malveillantes. Cependant, il reste conseillé

de vérifier le contenu de toute requête avant son exécution.

Plus d'infos : http://www.sqlite.org/limits.html

Typage : fun [ObjSqlite I I] I

Le premier argument est l'objet connexion à la base de données.

Le second argument est un drapeau indiquant l'objet limité. Ce drapeau peut

avoir l'une des valeurs suivantes :

SQLITE_LENGTH_LIMIT : taille max pour chaine, blob ou ligne

SQLITE_SQL_LENGTH_LIMIT : taille max d'une requête (en bytes)

SQLITE_COLUMN_LIMIT : nombre max de colonne d'une table, d'un résultat d'un SELECT,

d'un index oud'une clause GROUP BY ou ORDER BY

SQLITE_EXPR_DEPTH_LIMIT : la profondeur max pour parser l'arbre d'une expression

SQLITE_COMPOUND_SELECT_LIMIT : le nombre max d'une requête SELECT

SQLITE_VDBE_OP_LIMIT : le nombre max d'instructions d'un VM utilisée pour

une requête SQL

SQLITE_FUNCTION_ARG_LIMIT : le nombre max d'arguments d'une fonction

SQLITE_ATTACHED_LIMIT : nombre max de bases attachées à la base courante

SQLITE_LIKE_PATTERN_LENGTH_LIMIT : taille max du motif (pattern) des

opérateurs GLOB ou LIKE

SQLITE_VARIABLE_NUMBER_LIMIT : nombre max de variables contenues dans une requête

SQLITE_TRIGGER_DEPTH_LIMIT : profondeur max des triggers récursifs.

Plus d'infos : http://www.sqlite.org/c3ref/c_limit_attached.html

Le troisième argument est un entier positif donnant la nouvelle valeur.

La fonction retourne cette nouvelle valeur.

Exemple :

typeof mydb = ObjSqlite;;

...

_sqliteSetSizeLimit mydb SCOL_SQLITE_SQL_LENGTH_LIMIT 1024;

Note : les valeurs par défaut conviennent dans les uasages simples et standards.

## _sqliteGetSizeLimit

Retourne la taille limite actuelle d'un objet SQLite pour une connexion

donnée.

Typage : fun [ObjSqlite I] I

Le premier argument est l'objet connexion à la base de données.

Le second argument est un drapeau indiquant l'objet limité. Voir la fonction

_sqliteSetSizeLimit

La fonction retourne la valeur demandée.

## _sqliteCallbackProgress

Définit la callback 'handler_progress'. Elle ne devrait pas être utilisée,

elle est non finalisée et peut provoquer des plantages.

Typage : fun [ObjSqlite fun [ObjSqlite u0] I u0 I] ObjSqlite

Permier argument : objet connexion à la base

Second argument : fonction réflexe

Troisième argument : paramètre utilisateur

Quatrième argument : fréquence d'appel de la callback lors d'une requête. En gros,

tous les X opcodes, elle est appelée.

Retourne l'objet connexion à la base.

[ENGLISH]

Sqlite3 support for Scol language

More infos : visit the Scolring : http://www.scolring.org/

Please, you should remember that this library is still a ALPHA version, provided

"AS IT". Be carefull if you use it to the critical process.

License : Scol (see COPYING file), BSD-like

Author : Stéphane Bisaro, aka iri <iri@irizone.net>

For any suggests and/or comments, go to Scolring forum : http://www.scolring.org/

Thanks.

-==============================================================================-

COMPILATION 

See README file

INSTALLATION

Close Scol, if any.

Copy the library (*.dll under MS Windows, *.so under GNU/Linux) to the subfolder

"plugins" of "scol".

Edit the "usm.ini" file (as the samefolder than "scol.exe" (under Windows) or

"scol" (under GNU/Linux)) and add this line :

- Under windows :

plugin plugins/libsqlite3.dll ScolLoadPlugin ScolUnloadPlugin

- Under GNU/Linux :

plugin ./plugins/libsqlite3.so ScolLoadPlugin ScolUnloadPlugin

Launch Scol.

Note : underGNU/Linux, sqlite3 lib should be present on your system. otherwise,

install all packages needed (as 'libsqlite3-0' under Debian).

More informations : http://www.sqlite.org/

SUPPORT :

Visit or post to the Scolring forum : http://www.scolring.org/

API

You can see the doc file provided by Doxygen

_sqliteOpenFileEx : fun [Chn P I I I] ObjSqlite

Open a new connection to a db file

Chn : a channel

P : a read-reference file

I : flag : SQLITE_READWRITE (default) or SQLITE_ONLYREAD

I : flag : SQLITE_OPEN_PRIVATE_CACHE (default) or SQLITE_OPEN_SHAREDCACHE (see _sqliteSharedCacheEnabled too)

I : flag : SQLITE_OPEN_FULLMUTEX (default) or SQLITE_OPEN_NOMUTEX (multi-thread)

ObjSqlite : a new object or nil if error

_sqliteOpenFile : fun [Chn P] ObjSqlite

Open a new connection (db file). This function is a convenience with the defaults parameters.

Chn : a channel

P : a read reference file

ObjSqlite : a new object or nil if error

_sqliteOpenMemory : fun [Chn] ObjSqlite

Create and connect a database into the memory

Chn : a channel

ObjSqlite : a new object or nil if error

_sqliteOpenTemp : fun [Chn] ObjSqlite

Create and connect a database to the temporarly file

Chn : a channel

ObjSqlite : a new object or nil if error

_sqliteClose : fun [ObjSqlite] I

Close any database connexion

ObjSqlite : a valid object

I : 0 if ok, nil if scol error or an other integer if sqlite error

_sqliteExec : fun [ObjSqlite S I] I

Execute any sql instruction

Return 0 if ok or the sqlite's error code

ObjSqlite : a valid object

S : a valid sqlite request

I : should be nil

I : 0 if success or the error code

_sqliteExecResult : fun [ObjSqlite S I] [[[S S] r1] r1]

Run a sqlite request and return the result without callback

ObjSqlite : a valid object

S : a valid sqlite request

I : should be nil

[[[S S] r1] r1] : the result or nil if error

_sqliteGetSizeLimit : fun [ObjSqlite I] I

Get the maximale size to objects manipulate by SQLite3

more informations : _sqliteSetSizeLimit (below)

ObjSqlite : a valid object

I : flag

I : the value

_sqliteSetSizeLimit : fun [ObjSqlite I I] I

Set the maximale size to objects manipulate by SQLite3

more informations : http://www.sqlite.org/c3ref/c_limit_attached.html

ObjSqlite : a valid object

I : flag : SQLITE_LENGTH_LIMIT, SQLITE_SQL_LENGTH_LIMIT, SQLITE_COLUMN_LIMIT, SQLITE_EXPR_DEPTH_LIMIT, SQLITE_COMPOUND_SELECT_LIMIT, SQLITE_VDBE_OP_LIMIT, SQLITE_FUNCTION_ARG_LIMIT, SQLITE_ATTACHED_LIMIT, SQLITE_LIKE_PATTERN_LENGTH_LIMIT, SQLITE_VARIABLE_NUMBER_LIMIT, SQLITE_TRIGGER_DEPTH_LIMIT

I : the new value

I : this new value

_sqliteThreadsafe : fun [] I

Return 0 if mono-thread, 1 if serialized, 2 if multi-thread (strictly defined at the compile-time)

_sqliteShraedCacheEnabled : fun [I] I

Return 0 if success or a specific error code

_sqliteVersion : fun [] S

Return the SQLITE used version

_sqliteVersionScol : fun [] S

Return this library version (it is defined in main.h)