預處理語句使用數種資料結構
若要取得語句處理常式,請將
MYSQL
連線處理常式傳遞至mysql_stmt_init()
,此函數會傳回指向MYSQL_STMT
資料結構的指標。此結構用於對語句進行後續操作。若要指定要準備的語句,請將MYSQL_STMT
指標和語句字串傳遞至mysql_stmt_prepare()
。-
若要為預處理語句提供輸入參數,請設定
MYSQL_BIND
結構,並將它們傳遞至mysql_stmt_bind_param()
或mysql_stmt_bind_named_param()
。若要接收輸出資料行值,請設定MYSQL_BIND
結構,並將它們傳遞至mysql_stmt_bind_result()
。MYSQL_BIND
結構也與mysql_bind_param()
一起使用,這能夠定義套用至傳送至伺服器的下一個查詢的屬性。 MYSQL_TIME
結構用於在兩個方向上傳輸時間資料。
以下討論詳細說明預處理語句的資料類型。如需顯示如何使用這些資料類型的範例,請參閱 第 6.4.11 節,「mysql_stmt_execute()」和 第 6.4.12 節,「mysql_stmt_fetch()」。
-
此結構是預處理語句的處理常式。處理常式是透過呼叫
mysql_stmt_init()
來建立,此函數會傳回指向MYSQL_STMT
的指標。處理常式用於對語句進行所有後續操作,直到您使用mysql_stmt_close()
關閉它為止,屆時處理常式會失效,且不應再使用。MYSQL_STMT
結構沒有供應用程式使用的成員。應用程式不應嘗試複製MYSQL_STMT
結構。無法保證此類副本將會可用。多個語句處理常式可以與單一連線相關聯。處理常式的數量限制取決於可用的系統資源。
-
此結構用於語句輸入 (傳送至伺服器的資料值) 和輸出 (從伺服器傳回的結果值)。
對於輸入,請將
MYSQL_BIND
結構與mysql_bind_param()
一起使用,以定義查詢的屬性。(在以下討論中,將任何提及預處理語句的語句參數都視為也適用於查詢屬性。)對於輸出,請將
MYSQL_BIND
結構與mysql_stmt_bind_result()
一起使用,將緩衝區繫結至結果集資料行,以用於使用mysql_stmt_fetch()
提取資料列。
若要使用
MYSQL_BIND
結構,請將其內容歸零以初始化它,然後適當設定其成員。例如,若要宣告和初始化三個MYSQL_BIND
結構的陣列,請使用此程式碼MYSQL_BIND bind[3]; memset(bind, 0, sizeof(bind));
MYSQL_BIND
結構包含下列應用程式程式使用的成員。對於數個成員,使用方式取決於該結構是用於輸入還是輸出。-
enum enum_field_types buffer_type
緩衝區的類型。此成員指出繫結至語句參數或結果集資料行的 C 語言變數的資料類型。對於輸入,
buffer_type
指出包含要傳送至伺服器的值的變數類型。對於輸出,它指出應儲存從伺服器接收的值的變數類型。如需允許的buffer_type
值,請參閱 第 6.2.1 節,「C API 預處理語句類型代碼」。 -
void *buffer
指向要用於資料傳輸的緩衝區的指標。這是 C 語言變數的位址。
對於輸入,
buffer
是指向您在其中儲存語句參數資料值的變數的指標。當您呼叫mysql_stmt_execute()
時,MySQL 會使用儲存在變數中的值來取代語句中對應的參數標記 (在語句字串中使用?
指定)。對於輸出,
buffer
是指向要在其中傳回結果集資料行值的變數的指標。當您呼叫mysql_stmt_fetch()
時,MySQL 會將結果集目前資料列的資料行值儲存在此變數中。您可以在呼叫傳回時存取該值。若要盡量減少 MySQL 在用戶端上的 C 語言值和伺服器上的 SQL 值之間執行類型轉換的需求,請使用與對應 SQL 值類型相似的 C 變數。
對於數值資料類型,
buffer
應指向正確的數值 C 類型變數。對於整數變數 (對於單一位元組值可以是char
或對於較大值可以是整數類型),您也應透過設定稍後說明的is_unsigned
成員來指出變數是否具有unsigned
屬性。對於字元 (非二進位) 和二進位字串資料類型,
buffer
應指向字元緩衝區。對於日期和時間資料類型,
buffer
應指向MYSQL_TIME
結構。
如需關於 C 類型與 SQL 類型之間對應的指導方針,以及關於類型轉換的注意事項,請參閱 第 6.2.1 節,「C API 預處理語句類型代碼」和 第 6.2.2 節,「C API 預處理語句類型轉換」。
-
unsigned long buffer_length
*buffer
的實際大小 (以位元組為單位)。這指出可儲存在緩衝區中的最大資料量。對於字元和二進位 C 資料,當與mysql_stmt_bind_param()
或mysql_stmt_bind_named_param()
一起使用以指定輸入值時,buffer_length
值會指定*buffer
的長度,或者當與mysql_stmt_bind_result()
一起使用時,可擷取至緩衝區中的最大輸出資料位元組數。 -
unsigned long *length
指向
unsigned long
變數的指標,該變數指出儲存在*buffer
中的實際資料位元組數。length
用於字元或二進位 C 資料。對於輸入參數資料繫結,請設定
*length
以指出儲存在*buffer
中的參數值的實際長度。這由mysql_stmt_execute()
使用。對於輸出值繫結,當您呼叫
mysql_stmt_fetch()
時,MySQL 會設定*length
。mysql_stmt_fetch()
傳回值決定如何解譯長度如果傳回值為 0,則
*length
指出參數值的實際長度。如果傳回值為
MYSQL_DATA_TRUNCATED
,則*length
指出參數值的未截斷長度。在此情況下,*length
和buffer_length
的最小值指出值的實際長度。
length
會被數值和時間資料類型忽略,因為buffer_type
值決定資料值的長度。如果您必須在擷取傳回值之前判斷其長度,請參閱 第 6.4.12 節,「mysql_stmt_fetch()」,以了解一些策略。
-
bool *is_null
此成員指向
bool
變數,如果值為NULL
,則該變數為 true,如果值不是NULL
,則為 false。對於輸入,請將*is_null
設定為 true,以指出您要傳遞NULL
值作為語句參數。is_null
是布林純量的指標,而不是布林純量,以提供在您指定NULL
值時的彈性。如果您的資料值永遠為
NULL
,當您繫結欄位時,請使用MYSQL_TYPE_NULL
作為buffer_type
的值。其他MYSQL_BIND
成員,包括is_null
,則無關緊要。如果您的資料值永遠為
NOT NULL
,請設定is_null = (bool*) 0
,並為您要繫結的變數適當地設定其他成員。在所有其他情況下,請適當地設定其他成員,並將
is_null
設定為bool
變數的位址。在執行之間,將該變數的值設定為 true 或 false,以分別指示相應的資料值是否為NULL
或NOT NULL
。
對於輸出,當您提取一列時,MySQL 會根據陳述式傳回的結果集欄位值是否為
NULL
,將is_null
所指向的值設定為 true 或 false。 -
bool is_unsigned
此成員適用於具有可為
unsigned
的資料類型(char
、short int
、int
、long long int
)的 C 變數。如果buffer
所指向的變數為unsigned
,則將is_unsigned
設定為 true,否則設定為 false。例如,如果您將signed char
變數繫結到buffer
,請指定MYSQL_TYPE_TINY
的類型代碼,並將is_unsigned
設定為 false。如果您改為繫結unsigned char
,則類型代碼相同,但is_unsigned
應為 true。(對於char
,未定義它是 signed 還是 unsigned,因此最好透過使用signed char
或unsigned char
來明確說明其符號。)is_unsigned
僅適用於用戶端上的 C 語言變數。它不表示伺服器端對應 SQL 值的符號。例如,如果您使用int
變數來為BIGINT UNSIGNED
欄位提供值,則is_unsigned
應為 false,因為int
是帶符號類型。如果您使用unsigned int
變數來為BIGINT
欄位提供值,則is_unsigned
應為 true,因為unsigned int
是不帶符號的類型。MySQL 會在兩個方向執行帶符號和不帶符號值之間的適當轉換,但如果發生截斷,則會出現警告。 -
bool *error
對於輸出,將此成員設定為指向
bool
變數,以便在提取列操作後將參數的截斷資訊儲存在該變數中。當啟用截斷報告時,mysql_stmt_fetch()
會傳回MYSQL_DATA_TRUNCATED
,並且在發生截斷的參數的MYSQL_BIND
結構中,*error
為 true。截斷表示遺失符號或有效數字,或者字串太長而無法放入欄位中。截斷報告預設為啟用,但可以透過使用MYSQL_REPORT_DATA_TRUNCATION
選項呼叫mysql_options()
來控制。
-
此結構用於直接與伺服器來回傳送和接收
DATE
、TIME
、DATETIME
和TIMESTAMP
資料。將buffer
成員設定為指向MYSQL_TIME
結構,並將MYSQL_BIND
結構的buffer_type
成員設定為時間類型之一(MYSQL_TYPE_TIME
、MYSQL_TYPE_DATE
、MYSQL_TYPE_DATETIME
、MYSQL_TYPE_TIMESTAMP
)。MYSQL_TIME
結構包含下表中列出的成員。成員 描述 unsigned int year
年份 unsigned int month
一年中的月份 unsigned int day
一個月中的日期 unsigned int hour
一天中的小時 unsigned int minute
一小時中的分鐘 unsigned int second
一分鐘中的秒數 bool neg
一個布林旗標,指示時間是否為負數 unsigned long second_part
以微秒為單位的秒數的小數部分 僅使用適用於給定時間類型值的
MYSQL_TIME
結構中的那些部分。year
、month
和day
元素用於DATE
、DATETIME
和TIMESTAMP
值。hour
、minute
和second
元素用於TIME
、DATETIME
和TIMESTAMP
值。請參閱 第 3.6.4 節,日期和時間值的預備陳述式處理。