/ Check-in [84c2a5c4]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add documentation for new APIs. (CVS 3076)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:84c2a5c4d753d1e39136ac7e80ac816442af0a49
User & Date: danielk1977 2006-02-10 13:14:21
Context
2006-02-10
13:33
Minor test file modifications for builds compiled with OMIT options. (CVS 3077) check-in: c468aa34 user: danielk1977 tags: trunk
13:14
Add documentation for new APIs. (CVS 3076) check-in: 84c2a5c4 user: danielk1977 tags: trunk
13:11
More comments on the unix locking code. Ticket #1672. (CVS 3075) check-in: 4b6f5688 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/capi3ref.tcl.

1
2
3
4
5
6
7
8
...
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
































































































































388
389
390
391
392
393
394
set rcsid {$Id: capi3ref.tcl,v 1.32 2006/02/09 18:35:30 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}
puts {
<h2>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {
................................................................................
api {} {
const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
} {
 The first argument is a prepared SQL statement. If this statement
 is a SELECT statement, the Nth column of the returned result set 
 of the SELECT is a table column then the declared type of the table
 column is returned. If the Nth column of the result set is not at table
 column, then a NULL pointer is returned. The returned string is 
 UTF-8 encoded for sqlite3_column_decltype() and UTF-16 encoded
 for sqlite3_column_decltype16().
 For example, in the database schema:

 <blockquote><pre>
 CREATE TABLE t1(c1 INTEGER);
 </pre></blockquote>

 And the following statement compiled:

 <blockquote><pre>
 SELECT c1 + 1, 0 FROM t1;
 </pre></blockquote>

 Then this routine would return the string "INTEGER" for the second
 result column (i==1), and a NULL pointer for the first result column
 (i==0).
































































































































}

api {} {
const char *sqlite3_column_name(sqlite3_stmt*,int);
const void *sqlite3_column_name16(sqlite3_stmt*,int);
} {
 The first argument is a prepared SQL statement. This function returns
|







 







|


<
|








|





>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







1
2
3
4
5
6
7
8
...
362
363
364
365
366
367
368
369
370
371

372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
set rcsid {$Id: capi3ref.tcl,v 1.33 2006/02/10 13:14:21 danielk1977 Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}
puts {
<h2>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {
................................................................................
api {} {
const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
} {
 The first argument is a prepared SQL statement. If this statement
 is a SELECT statement, the Nth column of the returned result set 
 of the SELECT is a table column then the declared type of the table
 column is returned. If the Nth column of the result set is not a table
 column, then a NULL pointer is returned. The returned string is 
 UTF-8 encoded for sqlite3_column_decltype() and UTF-16 encoded

 for sqlite3_column_decltype16(). For example, in the database schema:

 <blockquote><pre>
 CREATE TABLE t1(c1 INTEGER);
 </pre></blockquote>

 And the following statement compiled:

 <blockquote><pre>
 SELECT c1 + 1, c1 FROM t1;
 </pre></blockquote>

 Then this routine would return the string "INTEGER" for the second
 result column (i==1), and a NULL pointer for the first result column
 (i==0).

 If the following statements were compiled then this routine would
 return "INTEGER" for the first (only) result column.

 <blockquote><pre>
 SELECT (SELECT c1) FROM t1;
 SELECT (SELECT c1 FROM t1);
 SELECT c1 FROM (SELECT c1 FROM t1);
 SELECT * FROM (SELECT c1 FROM t1);
 SELECT * FROM (SELECT * FROM t1);
 </pre></blockquote>
}

api {} {
  int sqlite3_table_column_metadata(
    sqlite3 *db,                /* Connection handle */
    const char *zDbName,        /* Database name or NULL */
    const char *zTableName,     /* Table name */
    const char *zColumnName,    /* Column name */
    char const **pzDataType,    /* OUTPUT: Declared data type */
    char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
    int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
    int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
    int *pAutoinc               /* OUTPUT: True if colums is auto-increment */
  );
} {
 This routine is used to obtain meta information about a specific column of a
 specific database table accessible using the connection handle passed as the
 first function argument.

 The column is identified by the second, third and fourth parameters to 
 this function. The second parameter is either the name of the database
 (i.e. "main", "temp" or an attached database) containing the specified
 table or NULL. If it is NULL, then all attached databases are searched
 for the table using the same algorithm as the database engine uses to 
 resolve unqualified table references.

 The third and fourth parameters to this function are the table and column 
 name of the desired column, respectively. Neither of these parameters 
 may be NULL.

 Meta information is returned by writing to the memory locations passed as
 the 5th and subsequent parameters to this function. Any of these 
 arguments may be NULL, in which case the corresponding element of meta 
 information is ommitted.

<pre>
 Parameter     Output Type      Description
 -----------------------------------
   5th         const char*      Declared data type 
   6th         const char*      Name of the columns default collation sequence 
   7th         int              True if the column has a NOT NULL constraint
   8th         int              True if the column is part of the PRIMARY KEY
   9th         int              True if the column is AUTOINCREMENT
</pre>

 The memory pointed to by the character pointers returned for the 
 declaration type and collation sequence is valid only until the next 
 call to any sqlite API function.

 This function may load one or more schemas from database files. If an
 error occurs during this process, or if the requested table or column
 cannot be found, an SQLITE error code is returned and an error message
 left in the database handle (to be retrieved using sqlite3_errmsg()).
 Specifying an SQL view instead of a table as the third argument is also
 considered an error.

 If the specified column is "rowid", "oid" or "_rowid_" and an 
 INTEGER PRIMARY KEY column has been explicitly declared, then the output 
 parameters are set for the explicitly declared column. If there is no
 explicitly declared IPK column, then the data-type is "INTEGER", the
 collation sequence "BINARY" and the primary-key flag is set. Both
 the not-null and auto-increment flags are clear.

 This API is only available if the library was compiled with the
 SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
}

api {} {
const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N);
const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N);
} {
If the Nth column returned by statement pStmt is a column reference,
these functions may be used to access the name of the database (either 
"main", "temp" or the name of an attached database) that contains
the column. If the Nth column is not a column reference, NULL is
returned.

See the description of function sqlite3_column_decltype() for a
description of exactly which expressions are considered column references.

Function sqlite3_column_database_name() returns a pointer to a UTF-8
encoded string. sqlite3_column_database_name16() returns a pointer
to a UTF-16 encoded string. 
}

api {} {
const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N);
const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N);
} {
If the Nth column returned by statement pStmt is a column reference,
these functions may be used to access the schema name of the referenced 
column in the database schema. If the Nth column is not a column 
reference, NULL is returned.

See the description of function sqlite3_column_decltype() for a
description of exactly which expressions are considered column references.

Function sqlite3_column_origin_name() returns a pointer to a UTF-8
encoded string. sqlite3_column_origin_name16() returns a pointer
to a UTF-16 encoded string. 
}

api {} {
const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N);
const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N);
} {
If the Nth column returned by statement pStmt is a column reference, 
these functions may be used to access the name of the table that 
contains the column.  If the Nth column is not a column reference, 
NULL is returned.

See the description of function sqlite3_column_decltype() for a
description of exactly which expressions are considered column references.

Function sqlite3_column_table_name() returns a pointer to a UTF-8
encoded string. sqlite3_column_table_name16() returns a pointer
to a UTF-16 encoded string. 
}

api {} {
const char *sqlite3_column_name(sqlite3_stmt*,int);
const void *sqlite3_column_name16(sqlite3_stmt*,int);
} {
 The first argument is a prepared SQL statement. This function returns