Project

General

Profile

doc.txt

iri, 09/27/2011 10:19 PM

 
1
Scol library SQLITE3 documentation
2

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

    
5
Permission is granted to copy, distribute and/or modify this document
6
under the terms of the GNU Free Documentation License, Version 1.3
7
or any later version published by the Free Software Foundation;
8
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
9
A copy of the license is included in the section entitled "GNU
10
Free Documentation License".
11

    
12
[FRENCH]
13

    
14
Usage
15
Compilation
16
Installation
17
API
18

    
19

    
20
-> Usage
21

    
22
La librairie libsqlite3 est sous licence Scol et elle est fournie
23
sans garantie d'efficacité ni de dysfonctionnements.
24
Voyez le fichier COPYING inclus pour plus amples informations.
25

    
26
Les compilations d'origine ont été faite avec le compilateur GNU GCC
27
(MingW pour la version MS Windows).
28

    
29
Pour en savoir plus sur le langage Scol, visitez le site :
30
http://www.scolring.org/
31
Pour plus d'infos sur SQLite : http://www.sqlite.org/
32

    
33

    
34
-> Compilation
35

    
36
Voir le fichier README
37

    
38

    
39
-> Installation de la release
40

    
41
Sous GNU/Linux:
42

    
43
1- Quitter Scol s'il était lancé
44

    
45
2- Copiez la bibliothèque "libsqlite3.so" dans le sous-répertoire
46
"plugins" de SCOL
47

    
48
3- Editez le fichier usm.ini pour y ajouter la ligne suivante :
49
plugin ./plugins/libsqlite3.so ScolLoadPlugin ScolUnloadPlugin
50

    
51
4- Relancez Scol
52

    
53
Sous MS Windows
54

    
55
1- Quitter Scol s'il était lancé
56

    
57
2- Copiez la bibliothèque "libsqlite3.dll" dans le sous-répertoire
58
"plugins" de SCOL
59

    
60
3- Editez le fichier usm.ini pour y ajouter la ligne suivante :
61
plugin plugins/libsqlite3.dll ScolLoadPlugin ScolUnloadPlugin
62

    
63
4- Relancez Scol
64

    
65

    
66
-> API fournie
67

    
68
N'hésitez pas à consulter la documentation de SQLite :
69
http://www.sqlite.org/docs.html
70

    
71
## ObjSqlite :
72

    
73
Type Scol correspondant à un objet connexion Sqlite3
74

    
75
## _sqliteOpenFile
76

    
77
Fonction de connexion à une base de données Sqlite3
78
La base de données est un fichier physiquement présent dans la partition
79
Scol active. La base sera en mode sérialisé, cache privé et en lecture
80
et écriture. Voir _sqliteOpenFileEx ci-dessous.
81
Typage : fun [Chn P] ObjSqlite
82

    
83
Le second argument demande une référence de fichier en lecture ce qui
84
implique que le fichier devrait déjà être créé avant. Par exemple, en
85
utilisant la fonction Scol _createpack (cf doc)
86

    
87
Le premier est le canal dans lequel l'objet sera manipulé. Généralement,
88
il s'agit du canal courant, correspondant à la fonction Scol _channel
89

    
90
La valeur retournée est l'objet Scol ou nil si une erreur est survenue
91
(voir les logs le cas échéant)
92

    
93
L'encodage par défaut pour la base de données est l'UTF-8
94
Note : l'interface entre Sqlite et l'OS sera défini ici par Sqlite
95
à la valeur par défaut (cf http://www.sqlite.org/c3ref/vfs.html)
96

    
97
Exemple :
98
typeof mydb = ObjSqlite;;
99
...
100
set mydb = _sqliteOpenFile _channel "mybase.db";
101

    
102

    
103
## _sqliteOpenFileEx
104

    
105
Comme la fonction précédente, elle permet de se connecter à une base
106
fichier. Elle permet de configurer plus finement la connexion.
107
Typage : fun [Chn P I I I] ObjSqlite
108

    
109
Le troisième argument est un drapeau indiquant si la base sera en
110
lecture seule ou en lecture et écriture (dans ce dernier cas, sous
111
réserve des restrictions éventuellement imposées : droits d'utilisateur
112
sur le fichier, droits sur le système de fichiers, etc). Les valeurs
113
possibles sont : SQLITE_READWRITE (par défaut) ou SQLITE_ONLYREAD
114

    
115
Le quatrième argument est un drapeau indiquant la manière dont est géré le
116
cache SQLite. Le cache partagé est nouellement supporté, plus d'infos
117
sur : http://www.sqlite.org/sharedcache.html
118
Les valeurs possibles sont : SQLITE_OPEN_PRIVATE_CACHE (par défaut) ou
119
SQLITE_OPEN_SHAREDCACHE.
120
Pour utiliser le cache partagé, il faut qu'il soit au préalable activé
121
via _sqliteSharedCacheEnabled (plus bas)
122

    
123
Le cinquième argument est un drapeau indiquant comment est géré le threading.
124
Si threadsafe est positionné à 1 ou 2, ce drapeau sera pris en compte. Cette
125
valeur est connue grâce à la fonction _sqliteThreadsafe (voir plus bas).
126
Les drapeaux possibles sont : SQLITE_OPEN_FULLMUTEX (mode sérialisé, par
127
défaut) ou SQLITE_OPEN_NOMUTEX (mode multi-thread).
128
Pour plus de renseignements sur ces modes, voir _sqliteThreadsafe plus bas.
129

    
130
La valeur retournée est l'objet Scol ou nil si une erreur est survenue
131
(voir les logs le cas échéant)
132

    
133
Exemple :
134
typeof mydb = ObjSqlite;;
135
...
136
set mydb = _sqliteOpenFile _channel "mybase.db" SCOL_SQLITE_ONLYREAD nil nil;
137

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

    
140
Note : les fonctions de configuration VFS ne sont pas incluses. La configuration
141
par défaut du système hôte est utilisée.
142

    
143

    
144
## _sqliteOpenMemory
145

    
146
Fonction de connexion à une base Sqlite3
147
La base de données sera créée en mémoire vive et sera effacée lors de l'appel
148
de la fonction de destruction (_sqliteClose) ou de la vidage de la mémoire par l'OS.
149
Typage : fun [Chn] ObjSqlite
150

    
151
L'argument est le canal dans lequel l'objet sera manipulé. Généralement,
152
il s'agit du canal courant, correspondant à la fonction Scol _channel
153

    
154
La valeur retournée est l'objet Scol ou nil si une erreur est survenue
155
(voir les logs le cas échéant)
156

    
157
Note : cette base de donnée est par nature volatile. Sa destruction
158
entraîne la destruction irréversible des données qu'elle contient.
159
La capacité de la base dépend de la mémoire disponible allouée par
160
le système.
161

    
162

    
163
## _sqliteOpenTemp
164

    
165
Fonction de connexion à une base de fichier Sqlite3
166
La base de données sera créée dans un fichier temporaire et sera effacée
167
lors de l'appel de la fonction de destruction (_sqliteClose)
168
Typage : fun [Chn] ObjSqlite
169

    
170
L'argument est le canal dans lequel l'objet sera manipulé. Généralement,
171
il s'agit du canal courant, correspondant à la fonction Scol _channel
172

    
173
La valeur retournée est l'objet Scol ou nil si une erreur est survenue
174
(voir les logs le cas échéant).
175

    
176
Note : cette base de données est par nature volatile. Clore la connexion
177
entraînera la perte des données qu'elle contenait.
178

    
179

    
180
## _sqliteClose
181

    
182
Fonction qui ferme et détruit une connexion à une base de données Sqlite3.
183
Typage : fun [ObjSqlite] I
184

    
185
Le premier argument est l'objet à détruire
186

    
187
La valeur retournée est à 0 si tout est ok, à 1 si la base est occupée
188
(typiquement, des opérations sont en cours), à nil si l'objet passé en
189
argument n'est pas valide ou 1 si une erreur est survenue lors de
190
la destruction de la liaison Sqlite3 (le log donne le numéro de
191
l'erreur, cf doc http://www.sqlite.org/c3ref/c_abort.html)
192

    
193

    
194
## _sqliteCallbackExec
195

    
196
Fonction réflexe appelée à chaque fois qu'une requête effectuée par
197
_sqliteExec renvoie une valeur (telle qu'un SELECT).
198
Typage : fun [ObjSqlite fun [ObjSqlite u0 S S] I u0] ObjSqlite
199

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

    
202
Le premier argument est l'objet connexion à la base de données
203
Le second est la fonction réflexe
204
Le troisième est le paramètre utilisateur.
205

    
206
Exemple :
207
fun mycallback (db, uparam, column, value)=
208
    _fooS strcat "user parameter : " uparam;
209
    _fooS strcat "column : " column;
210
    _fooS strcat "value : " value;
211
    0;;
212

    
213
...
214
_sqliteCallbackExec mydb @mycallback "this is my callback";
215

    
216

    
217
## _sqliteExec
218

    
219
Exécute une commande SQL compatible dans la base dont la connexion est
220
passée en premier argument.
221
Le troisième argument devrait toujours être laissé à NIL.
222
La fonction retourne un entier qui est le résultat sqlite : 0 si ok ou le
223
code erreur résultant (cf http://www.sqlite.org/c3ref/c_abort.html).
224
Le résultat de la requête est envoyé à la callback définie par _sqliteCallbackExec
225
si et seulement si le code erreur retourné est 0 (succès).
226
Si plusieurs requêtes sont demandées au sein d'une même commande sql, la callback
227
sera appelée autant de fois que nécessaire.
228
Typage : fun [ObjSqlite S I] I
229

    
230
Exemple :
231
_sqliteExec mydb "CREATE TABLE mytable (nom char(50), prenom char(50));
232
		INSERT INTO mytable (nom, prenom) VALUES ('Dupond', 'Jean');
233
		INSERT INTO mytable (nom, prenom) VALUES ('Smith', 'Winston');
234
		INSERT INTO mytable (nom, prenom) VALUES ('Bartoldi', 'Guiseppe')" nil;
235
_sqliteExec mydb "SELECT nom FROM mytable" nil;
236

    
237

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

    
240
Exécute une commande SQL compatible dans la base dont la connexion est passée en
241
premier argument.
242
Le second argument est la requête.
243
Le troisième argument devrait être laissé à nil.
244
La fonction retourne le résultat global de la requête passée en second argument
245
(et non pas le résultat de l'appel comme c'est le cas avec la fonction '_sqliteExec').
246
Si la requête est invalide ou les données demandées ne sont pas connues, la fonction
247
renvoie nil.
248
Typage : fun [ObjSqlite S I] [[[S S] r1] r1]
249
Ancien typage obsolète : fun [ObjSqlite S I] [[S S] r1]
250

    
251
Exemple :
252
typeof db = ObjSqlite;;
253

    
254
fun main ()=
255
	_showconsole;
256

    
257
	set db = _sqliteOpenFile _channel _checkpack "tests/test.db";
258
	if db == nil then
259
		_fooS "ERROR DB"
260
	else
261
		nil;
262

    
263
	let "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;" -> sql in
264
	let _sqliteExecResult db sql nil -> result in
265
	let _fooS "--> BEGIN" -> _ in
266
	while result != nil do
267
		let hd hd result -> [a v] in
268
		(
269
		_fooS strcat "A = " a;
270
		_fooS strcat "V = " v;
271
		_fooS "";
272
		set result = tl result;
273
		);
274
	_fooS "--> END";
275
	0;;
276

    
277

    
278
## _sqliteVersion
279

    
280
Fonction retournant la version de Sqlite utilisée lors de la compilation
281
(et par conséquent, celle actuellement utilisée).
282
Typage : fun [] S
283

    
284
Exemple de valeur retournée : 3.6.23.1
285

    
286

    
287
## _sqliteVersionScol
288

    
289
Fonction retournant le numéro de version de la librairie SQLite de Scol.
290
Typage : fun [] S
291

    
292
Exemple :
293
_fooS _sqliteVersionScol; // retourne 0.1a1
294

    
295

    
296
## _sqliteThreadsafe
297

    
298
Fonction qui retourne l'état du threading. Cette valeur est définie une
299
fois pour toute lors de la compilation et ne pourra pas être changée
300
sans recompilation ad hoc.
301
Si retourne 0, alors le mode est mono-thread
302
Si retourne 1, alors le mode est sérialisé
303
Si retourne 2, alors le mode est multi-thread
304
Devrait retourner 1, mode sérialisé.
305
Typage : fun [] I
306

    
307
Avec le mode mono-thread (0), SQLite n'est pas sécurié si plus d'un thread
308
est utilisé en même temps. Si ce mode est actif, il ne peut être changé
309
même lors de l'ouverture d'une connexion via _sqliteOpenFileEx (dans ce cas,
310
le drapeau (flag) éventuellement mis sera ignoré).
311

    
312
Avec le mode multi-thread (2), SQlite est ok pour plusieurs threads utilisés
313
si qu'un seul thread se connecte à une base à la fois. Ce mode peut basculer,
314
lors de la connexion à une base, via _sqliteOpenFileEx, au mode sérialisé (1).
315

    
316
Avec le mode sérialisé (1), SQLite est ok avec l'utilisation de plusieurs
317
threads sans aucune restriction. Ce mode peut basculer, lors de la connexion
318
à une base, via _sqliteOpenFileEx, au mode multi-thread (2).
319

    
320
Toutefois, les developpeurs de SQLite déconseillent les modes (1) et (2).
321
Ces deux modes sont plus pratiques mais les applications devraient être
322
codées / conçues de façon à n'utiliser que le mode (0).
323
http://www.sqlite.org/faq.html (answer 6)
324

    
325
Depuis le code source, la librairie peut être recompilée en modifiant la
326
valeur définie pour ' SQLITE_THREADSAFE ' dans sqlite3.c. Par défaut elle
327
est à 1 (mode sérialisé).
328

    
329

    
330
## _sqliteSharedCacheEnabled
331

    
332
Active (ou désactive) le cache partagé pour tout le processus (même si
333
celui-ci contient plusieurs threads).
334
Typage : fun [I] I
335

    
336
L'argument vaut soit 0 (par défaut, cache non partagé) ou tout autre entier
337
pour activer cette option.
338

    
339
Retourne 0 si succès ou un code erreur spécifique
340
(http://www.sqlite.org/c3ref/c_abort.html)
341

    
342

    
343
## _sqliteSetSizeLimit
344

    
345
Définit une taille limite maximale pour différents types d'objets SQLite3 pour
346
une connexion donnée. Cette fonction nécessite une connexion active, un
347
drapeau indiquant l'objet considéré et la nouvelle taille limite.
348
Si un objet de taille supérieure se présente, il sera tronqué. Ce peut être une
349
protection pour certaines attaques malveillantes. Cependant, il reste conseillé
350
de vérifier le contenu de toute requête avant son exécution.
351
Plus d'infos : http://www.sqlite.org/limits.html
352
Typage : fun [ObjSqlite I I] I
353

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

    
356
Le second argument est un drapeau indiquant l'objet limité. Ce drapeau peut
357
avoir l'une des valeurs suivantes :
358
SQLITE_LENGTH_LIMIT : taille max pour chaine, blob ou ligne
359
SQLITE_SQL_LENGTH_LIMIT : taille max d'une requête (en bytes)
360
SQLITE_COLUMN_LIMIT : nombre max de colonne d'une table, d'un résultat d'un SELECT,
361
d'un index oud'une clause GROUP BY ou ORDER BY
362
SQLITE_EXPR_DEPTH_LIMIT : la profondeur max pour parser l'arbre d'une expression
363
SQLITE_COMPOUND_SELECT_LIMIT : le nombre max d'une requête SELECT
364
SQLITE_VDBE_OP_LIMIT : le nombre max d'instructions d'un VM utilisée pour
365
une requête SQL
366
SQLITE_FUNCTION_ARG_LIMIT : le nombre max d'arguments d'une fonction
367
SQLITE_ATTACHED_LIMIT : nombre max de bases attachées à la base courante
368
SQLITE_LIKE_PATTERN_LENGTH_LIMIT : taille max du motif (pattern) des
369
opérateurs GLOB ou LIKE
370
SQLITE_VARIABLE_NUMBER_LIMIT : nombre max de variables contenues dans une requête
371
SQLITE_TRIGGER_DEPTH_LIMIT : profondeur max des triggers récursifs.
372
Plus d'infos : http://www.sqlite.org/c3ref/c_limit_attached.html
373

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

    
376
La fonction retourne cette nouvelle valeur.
377

    
378
Exemple :
379
typeof mydb = ObjSqlite;;
380
...
381
_sqliteSetSizeLimit mydb SCOL_SQLITE_SQL_LENGTH_LIMIT 1024;
382

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

    
385

    
386
## _sqliteGetSizeLimit
387

    
388
Retourne la taille limite actuelle d'un objet SQLite pour une connexion
389
donnée.
390
Typage : fun [ObjSqlite I] I
391

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

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

    
397
La fonction retourne la valeur demandée.
398

    
399

    
400
## _sqliteCallbackProgress
401

    
402
Définit la callback 'handler_progress'. Elle ne devrait pas être utilisée,
403
elle est non finalisée et peut provoquer des plantages.
404
Typage : fun [ObjSqlite fun [ObjSqlite u0] I u0 I] ObjSqlite
405

    
406
Permier argument : objet connexion à la base
407
Second argument : fonction réflexe
408
Troisième argument : paramètre utilisateur
409
Quatrième argument : fréquence d'appel de la callback lors d'une requête. En gros,
410
tous les X opcodes, elle est appelée.
411

    
412
Retourne l'objet connexion à la base.
413

    
414
[ENGLISH]
415

    
416
Sqlite3 support for Scol language
417

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

    
420
Please, you should remember that this library is still a ALPHA version, provided
421
"AS IT". Be carefull if you use it to the critical process.
422

    
423
License : Scol (see COPYING file), BSD-like
424
Author : Stéphane Bisaro, aka iri <iri@irizone.net>
425

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

    
429
-==============================================================================-
430

    
431
COMPILATION 
432

    
433
See README file
434

    
435

    
436
INSTALLATION
437

    
438
Close Scol, if any.
439
Copy the library (*.dll under MS Windows, *.so under GNU/Linux) to the subfolder
440
"plugins" of "scol".
441
Edit the "usm.ini" file (as the samefolder than "scol.exe" (under Windows) or
442
"scol" (under GNU/Linux)) and add this line :
443

    
444
- Under windows :
445
plugin plugins/libsqlite3.dll ScolLoadPlugin ScolUnloadPlugin
446
- Under GNU/Linux :
447
plugin ./plugins/libsqlite3.so ScolLoadPlugin ScolUnloadPlugin
448

    
449
Launch Scol.
450

    
451
Note : underGNU/Linux, sqlite3 lib should be present on your system. otherwise,
452
install all packages needed (as 'libsqlite3-0' under Debian).
453
More informations : http://www.sqlite.org/
454

    
455
SUPPORT :
456
Visit or post to the Scolring forum : http://www.scolring.org/
457

    
458
API
459

    
460
You can see the doc file provided by Doxygen
461

    
462
_sqliteOpenFileEx : fun [Chn P I I I] ObjSqlite
463

    
464
Open a new connection to a db file
465

    
466
Chn : a channel
467
P : a read-reference file
468
I : flag : SQLITE_READWRITE (default) or SQLITE_ONLYREAD
469
I : flag : SQLITE_OPEN_PRIVATE_CACHE (default) or SQLITE_OPEN_SHAREDCACHE (see _sqliteSharedCacheEnabled too)
470
I : flag : SQLITE_OPEN_FULLMUTEX (default) or SQLITE_OPEN_NOMUTEX (multi-thread)
471

    
472
ObjSqlite : a new object or nil if error
473

    
474

    
475
_sqliteOpenFile : fun [Chn P] ObjSqlite
476

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

    
479
Chn : a channel
480
P : a read reference file
481

    
482
ObjSqlite : a new object or nil if error
483

    
484

    
485
_sqliteOpenMemory : fun [Chn] ObjSqlite
486

    
487
Create and connect a database into the memory
488

    
489
Chn : a channel
490

    
491
ObjSqlite : a new object or nil if error
492

    
493

    
494
_sqliteOpenTemp : fun [Chn] ObjSqlite
495

    
496
Create and connect a database to the temporarly file
497

    
498
Chn : a channel
499

    
500
ObjSqlite : a new object or nil if error
501

    
502

    
503
_sqliteClose : fun [ObjSqlite] I
504

    
505
Close any database connexion
506

    
507
ObjSqlite : a valid object
508

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

    
511

    
512
_sqliteExec : fun [ObjSqlite S I] I
513

    
514
Execute any sql instruction
515
Return 0 if ok or the sqlite's error code
516

    
517
ObjSqlite : a valid object
518
S : a valid sqlite request
519
I : should be nil
520

    
521
I : 0 if success or the error code
522

    
523

    
524
_sqliteExecResult : fun [ObjSqlite S I] [[[S S] r1] r1]
525
Run a sqlite request and return the result without callback
526

    
527
ObjSqlite : a valid object
528
S : a valid sqlite request
529
I : should be nil
530

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

    
533

    
534
_sqliteGetSizeLimit : fun [ObjSqlite I] I
535

    
536
Get the maximale size to objects manipulate by SQLite3
537
more informations : _sqliteSetSizeLimit (below)
538

    
539
ObjSqlite : a valid object
540
I : flag
541

    
542
I : the value
543

    
544

    
545
_sqliteSetSizeLimit : fun [ObjSqlite I I] I
546

    
547
Set the maximale size to objects manipulate by SQLite3
548
more informations : http://www.sqlite.org/c3ref/c_limit_attached.html
549

    
550
ObjSqlite : a valid object
551
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
552
I : the new value
553

    
554
I : this new value
555

    
556

    
557
_sqliteThreadsafe : fun [] I
558

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

    
561

    
562
_sqliteShraedCacheEnabled : fun [I] I
563

    
564
Return 0 if success or a specific error code
565

    
566

    
567
_sqliteVersion : fun [] S
568

    
569
Return the SQLITE used version
570

    
571

    
572
_sqliteVersionScol : fun [] S
573

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