預處理語句使用數個資料結構
若要取得語句處理器,請將
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_param()使用MYSQL_BIND結構來定義查詢的屬性。(在以下討論中,將任何提及預處理語句的語句參數都視為也適用於查詢屬性。)對於輸出,請搭配
mysql_stmt_bind_result()使用MYSQL_BIND結構,將緩衝區繫結至結果集資料行,以用於使用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 資料,buffer_length值會在與mysql_stmt_bind_param()或mysql_stmt_bind_named_param()一起使用以指定輸入值時,指定*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 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 節,「預先準備語句的日期和時間值處理」。