描述

 

此函数返回使用作为第一个函数参数传递的数据库连接句柄可访问的特定数据库表的特定列的元数据。

 

C / C ++语法

 

 

PB语法

 

 

参数

 

pDb

 

[in]数据库连接句柄。必须是从sqlite3_open，sqlite3_open16或sqlite3_open_v2获取的sqlite3对象指针。 数据库连接不能关闭。

 

szDbName

 

[in]数据库的名称（即包含指定表或NULL的“main”，“temp”或附加数据库。如果为NULL，则使用与数据库引擎相同的算法来搜索所有附加的数据库以解析不合格的表引用。

 

szTableName

 

[in]所需列的表名称。不能为空。

 

szColumnName

 

[in]所需列的列名称。不能为空。

 

pszDataType

 

[out]指向接收指向声明类型的指针的变量的指针。可以为NULL。

 

pszCollSeq

 

[out]指向接收指向排序规则序列名称的指针的变量的指针。可以为NULL。

 

pNotNull

 

[out]指向一个LONG变量的指针，如果NOT NULL约束存在则接收到TRUE。可以为NULL。

 

pPrimaryKey

 

[out]如果列是主键的一部分，则指向一个LONG变量的指针，该变量接收到TRUE。可以为NULL。

 

pAuntoinc

 

[out]指向一个LONG变量的指针，如果列是自动递增的，则该变量接收到TRUE。可以为NULL。

 

返回值

 

如果成功返回SQLITE_OK，否则返回错误代码。

 

备注

 

通过写入作为此函数的第5个和后续参数传递的存储器位置返回元数据。任何这些参数都可以是NULL，在这种情况下，元数据的相应元素被省略。

 

 

由声明类型和排序规则序列返回的字符指针所指向的内存才有效，直到下一次调用任何SQLite API函数为止。

 

如果指定的表实际上是视图，则返回错误代码。

 

如果指定的列是“rowid”，“oid”或“_rowid_”和INTEGER PRIMARY KEY列已被显式声明，则为显式声明的列设置输出参数。如果没有明确声明的INTEGER PRIMARY KEY列，则输出参数设置如下：

 

数据类型：“INTEGER”

整理顺序：“BINARY”

不为null：0

主键：1

自动增量：0

 

此函数可能会从数据库文件加载一个或多个模式。如果在此过程中发生错误，或者找不到所请求的表或列，则会返回错误代码，并在数据库连接中留下错误消息（使用sqlite3_errmsg检索）。

 

仅当已使用定义的SQLITE_ENABLE_COLUMN_METADATA C预处理器符号编译库时，此API才可用。

 

C ++实现代码

 

/*

** Return meta information about a specific column of a database table.

** See comment in sqlite3.h (sqlite.h.in) for details.

*/

#ifdef SQLITE_ENABLE_COLUMN_METADATA

SQLITE_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 column is auto-increment */

){

int rc;

char *zErrMsg = 0;

Table *pTab = 0;

Column *pCol = 0;

int iCol;

 

char const *zDataType = 0;

char const *zCollSeq = 0;

int notnull = 0;

int primarykey = 0;

int autoinc = 0;

 

/* Ensure the database schema has been loaded */

sqlite3_mutex_enter(db->mutex);

sqlite3BtreeEnterAll(db);

rc = sqlite3Init(db, &zErrMsg);

if( SQLITE_OK!=rc ){

  goto error_out;

}

 

/* Locate the table in question */

pTab = sqlite3FindTable(db, zTableName, zDbName);

if( !pTab || pTab->pSelect ){

  pTab = 0;

  goto error_out;

}

 

/* Find the column for which info is requested */

if( sqlite3IsRowid(zColumnName) ){

  iCol = pTab->iPKey;

  if( iCol>=0 ){

    pCol = &pTab->aCol[iCol];

  }

}else{

  for(iCol=0; iCol<pTab->nCol; iCol++){

    pCol = &pTab->aCol[iCol];

    if( 0==sqlite3StrICmp(pCol->zName, zColumnName) ){

      break;

    }

  }

  if( iCol==pTab->nCol ){

    pTab = 0;

    goto error_out;

  }

}

 

/* The following block stores the meta information that will be returned

** to the caller in local variables zDataType, zCollSeq, notnull, primarykey

** and autoinc. At this point there are two possibilities:

**

**     1. The specified column name was rowid", "oid" or "_rowid_"

**        and there is no explicitly declared IPK column.

**

**     2. The table is not a view and the column name identified an

**        explicitly declared column. Copy meta information from *pCol.

*/

if( pCol ){

  zDataType = pCol->zType;

  zCollSeq = pCol->zColl;

  notnull = pCol->notNull!=0;

  primarykey  = pCol->isPrimKey!=0;

  autoinc = pTab->iPKey==iCol && (pTab->tabFlags & TF_Autoincrement)!=0;

}else{

  zDataType = "INTEGER";

  primarykey = 1;

}

if( !zCollSeq ){

  zCollSeq = "BINARY";

}

 

error_out:

sqlite3BtreeLeaveAll(db);

 

/* Whether the function call succeeded or failed, set the output parameters

** to whatever their local counterparts contain. If an error did occur,

** this has the effect of zeroing all output parameters.

*/

if( pzDataType ) *pzDataType = zDataType;

if( pzCollSeq ) *pzCollSeq = zCollSeq;

if( pNotNull ) *pNotNull = notnull;

if( pPrimaryKey ) *pPrimaryKey = primarykey;

if( pAutoinc ) *pAutoinc = autoinc;

 

if( SQLITE_OK==rc && !pTab ){

  sqlite3DbFree(db, zErrMsg);

  zErrMsg = sqlite3MPrintf(db, "no such table column: %s.%s", zTableName,

      zColumnName);

  rc = SQLITE_ERROR;

}

sqlite3Error(db, rc, (zErrMsg?"%s":0), zErrMsg);

sqlite3DbFree(db, zErrMsg);

rc = sqlite3ApiExit(db, rc);

sqlite3_mutex_leave(db->mutex);

return rc;

}

#endif