Project

General

Profile

End-user documentation » doc.txt

iri, 09/27/2011 10:19 PM

 
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)
    (1-1/1)