Sqlite3_prepare

這個函數將sql文本轉換成一個準備語句（prepared statement）對象，同時返回這個對象的指針。這個接口須要一個數據庫鏈接指針以及一個要準備的包含SQL語句的文本。它實際上並不執行（evaluate）這個SQL語句，它僅僅爲執行準備這個sql語句

函數定義（僅列出UTF-8的）

int sqlite3_prepare(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v2(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);

 參數：

db：數據指針

zSql：sql語句，使用UTF-8編碼

nByte：若是nByte小於0，則函數取出zSql中從開始到第一個0終止符的內容；若是nByte不是負的，那麼它就是這個函數能從zSql中讀取的字節數的最大值。若是nBytes非負，zSql在第一次碰見’/000/或’u000’的時候終止

pzTail：上面提到zSql在碰見終止符或者是達到設定的nByte以後結束，假如zSql還有剩餘的內容，那麼這些剩餘的內容被存放到pZTail中，不包括終止符

ppStmt：可以使用sqlite3_step()執行的編譯好的準備語句的指針，若是錯誤發生，它被置爲NULL，如假如輸入的文本不包括sql語句。調用過程必須負責在編譯好的sql語句完成使用後使用sqlite3_finalize()刪除它。

 

說明

若是執行成功，則返回SQLITE_OK，不然返回一個錯誤碼。推薦在如今任何的程序中都使用sqlite3_prepare_v2這個函數，sqlite3_prepare只是用於前向兼容

 

備註

<1>準備語句（prepared statement）對象

typedef struct sqlite3_stmt sqlite3_stmt;

        

準備語句（prepared statement）對象一個表明一個簡單SQL語句對象的實例，這個對象一般被稱爲「準備語句」或者「編譯好的SQL語句」或者就直接稱爲「語句」。

    語句對象的生命週期經歷這樣的過程：

l  使用sqlite3_prepare_v2或相關的函數建立這個對象

l  使用sqlite3_bind_*()給宿主參數（host parameters）綁定值

l  經過調用sqlite3_step一次或屢次來執行這個sql

l  使用sqlite3——reset()重置這個語句，而後回到第2步，這個過程作0次或屢次

l  使用sqlite3_finalize()銷燬這個對象

 

在sqlite中並無定義sqlite3_stmt這個結構的具體內容，它只是一個抽象類型，在使用過程當中通常以它的指針進行操做，而sqlite3_stmt類型的指針在其實是一個指向Vdbe的結構體得指針

<2>宿主參數(host parameters)

在傳給sqlite3_prepare_v2()的sql的語句文本或者它的變量中，知足以下模板的文字將被替換成一個參數：

l  ?

l  ?NNN，NNN表明數字

l  :VVV，VVV表明字符

l  @VVV

l  $VVV

在上面這些模板中，NNN表明一個數字，VVV表明一個字母數字標記符（例如:222表示名稱爲222的標記符），sql語句中的參數（變量）經過上面的幾個模板來指定，如

「select ? from ? 「這個語句中指定了兩個參數，sqlite語句中的第一個參數的索引值是1，這就知道這個語句中的兩個參數的索引分別爲1和2，使用」?」的話會被自動給予索引值，而使用」?NNN」則能夠本身指定參數的索引值，它表示這個參數的索引值爲NNN。」:VVV」表示一個名爲」VVV」的參數，它也有一個索引值，被自動指定。

可使用sqlite3_bind_*()來給這些參數綁定值