預處理語句使用數種資料結構
若要取得語句處理常式,請將
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 節,日期和時間值的預備陳述式處理。