Scol library SQLITE3 documentation Copyright (c) 2010 Stephane Bisaro, aka Iri 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 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)