欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  数据库

CAPI函数描述(A-F)

程序员文章站 2023-12-30 22:39:34
...

25.2.3.1. mysql_affected_rows() my_ulonglong mysql_affected_rows(MYSQL *mysql) 描述 返回上次UPDATE更改的行数,上次DELETE删除的行数,或上次INSERT语句插入的行数。对于UPDATE、DELETE或INSERT语句,可在mysql_query()后立刻调用。对于SELECT语句,my

25.2.3.1. mysql_affected_rows()

my_ulonglong mysql_affected_rows(MYSQL *mysql)

描述

返回上次UPDATE更改的行数,上次DELETE删除的行数,或上次INSERT语句插入的行数。对于UPDATE、DELETE或INSERT语句,可在mysql_query()后立刻调用。对于SELECT语句,mysql_affected_rows()的工作方式与mysql_num_rows()类似。

返回值

大于0的整数表明受影响或检索的行数。“0”表示UPDATE语句未更新记录,在查询中没有与WHERE匹配的行,或未执行查询。“-1”表示查询返回错误,或者,对于SELECT查询,在调用mysql_store_result()之前调用了mysql_affected_rows()。由于mysql_affected_rows()返回无符号值,通过比较返回值和“(my_ulonglong)-1”或等效的“(my_ulonglong)~0”,检查是否为“-1”。

错误

无。

示例:

mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10");
printf("%ld products updated",(long) mysql_affected_rows(&mysql));

如果在连接至mysqld时指定了标志CLIENT_FOUND_ROWS,对于UPDATE语句,mysql_affected_rows()将返回WHERE语句匹配的行数。

注意,使用REPLACE命令时,如果新行替代了旧行,mysql_affected_rows()返回2。这是因为,在该情况下,删除了重复行后插入了1行。

如果使用“INSERT ... ON DUPLICATE KEY UPDATE”来插入行,如果行是作为新行插入的,mysql_affected_rows()返回1,如果是更新了已有的行,返回2。

25.2.3.2. mysql_autocommit()

my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)

描述

如果模式为“1”,启用autocommit模式;如果模式为“0”,禁止autocommit模式。

返回值

如果成功,返回0,如果出现错误,返回非0值。

错误

无。

25.2.3.3. mysql_change_user()

my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password, const char *db)

描述

更改用户,并使由db指定的数据库成为由mysql指定的连接上的默认数据库(当前数据库)。在后续查询中,对于不包含显式数据库区分符的表引用,该数据库是默认数据库。

如果不能确定已连接的用户或用户不具有使用数据库的权限,mysql_change_user()将失败。在这种情况下,不会改变用户和数据库。

如果不打算拥有默认数据库,可将db参数设置为NULL。

该命令总是会执行活动事务的ROLLBACK操作,关闭所有的临时表,解锁所有的锁定表,并复位状态,就像进行了新连接那样。即使未更改用户,也会出现该情况。

返回值

0表示成功,非0值表示出现错误。

错误

与从mysql_real_connect()获得的相同。

· CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

在查询过程中丢失了与服务器的连接。

· CR_UNKNOWN_ERROR

出现未知错误。

· ER_UNKNOWN_COM_ERROR

MySQL服务器未实施该命令(或许是较低版本的服务器)。

· ER_ACCESS_DENIED_ERROR

用户或密码错误。

· ER_BAD_DB_ERROR

数据库不存在。

· ER_DBACCESS_DENIED_ERROR

用户没有访问数据库的权限。

· ER_WRONG_DB_NAME

数据库名称过长。

示例:

if (mysql_change_user(&mysql, "user", "password", "new_database"))
{
   fprintf(stderr, "Failed to change user.  Error: %s\n",
           mysql_error(&mysql));
}

25.2.3.4. mysql_character_set_name()

const char *mysql_character_set_name(MYSQL *mysql)

描述

为当前连接返回默认的字符集。

返回值

默认字符集。

错误

无。

25.2.3.5. mysql_close()

void mysql_close(MYSQL *mysql)

描述

关闭前面打开的连接。如果句柄是由mysql_init()或mysql_connect()自动分配的,mysql_close()还将解除分配由mysql指向的连接句柄。

返回值

无。

错误

无。

25.2.3.6. mysql_commit()

my_bool mysql_commit(MYSQL *mysql)

描述

提交当前事务。

该函数的动作受completion_type系统变量的值控制。尤其是,如果completion_type的值为2,终结事务并关闭客户端连接后,服务器将执行释放操作。客户端程序应调用mysql_close(),从客户端一侧关闭连接。

返回值

如果成功,返回0,如果出现错误,返回非0值。

错误

无。

25.2.3.7. mysql_connect()

MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)

描述

该函数已过时。最好使用mysql_real_connect()取而代之。

mysql_connect()试图建立与运行在主机上的MySQL数据库引擎的连接。在能够执行任何其他API函数之前,mysql_connect()必须成功完成,但mysql_get_client_info()例外。

这些参数的意义与mysql_real_connect()的对应参数的意义相同,差别在于连接参数可以为NULL。在这种情况下,C API将自动为连接结构分配内存,并当调用mysql_close()时释放分配的内存。该方法的缺点是,如果连接失败,你无法检索错误消息。要想从mysql_errno()或mysql_error()获得错误消息,必须提供有效的MYSQL指针。

返回值

与mysql_real_connect()的相同。

错误

与mysql_real_connect()的相同。

25.2.3.8. mysql_create_db()

int mysql_create_db(MYSQL *mysql, const char *db)

描述

创建由db参数命名的数据库。

该函数已过时。最好使用mysql_query()来发出SQLCREATE DATABASE语句。

返回值

如果数据库已成功创建,返回0,如果出现错误,返回非0值。

错误

· CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

在查询过程中,与服务器的连接丢失。

· CR_UNKNOWN_ERROR

出现未知错误。

示例:

if(mysql_create_db(&mysql, "my_database"))
{
   fprintf(stderr, "Failed to create new database.  Error: %s\n",
           mysql_error(&mysql));
}

25.2.3.9. mysql_data_seek()

void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)

描述

在查询结果集中寻找任意行。偏移值为行号,范围从0到mysql_num_rows(result)-1。

该函数要求结果集结构包含查询的所有结果,因此,somysql_data_seek()仅应与mysql_store_result()联合使用,而不是与mysql_use_result()。

返回值

无。

错误

无。

25.2.3.10. mysql_debug()

void mysql_debug(const char *debug)

描述

用给定的字符串执行DBUG_PUSH。mysql_debug()采用Fred Fish调试库。要想使用该函数,必须编译客户端库,使之支持调试功能。请参见E.1节,“调试MySQL服务器”。请参见E.2节,“调试MySQL客户端”。

返回值

无。

错误

无。

示例:

这里给出的调用将使客户端库在客户端机器的/tmp/client.trace中生成1个跟踪文件。

mysql_debug("d:t:O,/tmp/client.trace");

25.2.3.11. mysql_drop_db()

int mysql_drop_db(MYSQL *mysql, const char *db)

描述

撤销由db参数命名数据库。

该函数已过时。最好使用mysql_query()来发出SQLDROP DATABASE语句

返回值

如果成功撤销了数据库,返回0。如果出现错误,返回非0值。

错误

· CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

在查询过程中,与服务器的连接丢失。

· CR_UNKNOWN_ERROR

出现未知错误。

示例:

if(mysql_drop_db(&mysql, "my_database"))
  fprintf(stderr, "Failed to drop the database: Error: %s\n",
          mysql_error(&mysql));

25.2.3.12. mysql_dump_debug_info()

int mysql_dump_debug_info(MYSQL *mysql)

描述

指示服务器将一些调试信息写入日志。要想使之工作,已连接的用户必须具有SUPER权限。

返回值

如果命令成功,返回0。如果出现错误,返回非0值。

错误

· CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

在查询过程中,与服务器的连接丢失。

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.13. mysql_eof()

my_bool mysql_eof(MYSQL_RES *result)

描述

该函数已过时。应使用mysql_errno()或mysql_error()取而代之。

mysql_eof()确定是否已读取了结果集的最后1行。

如果通过成功调用mysql_store_result()获得了结果集,客户端将在1次操作中收到整个结果集。在该情况下,从mysql_fetch_row()返回的NULL总表示已到达结果集末尾,而且没必要调用mysql_eof()。与mysql_store_result()一起使用时,mysql_eof()总返回“真”。

另一方面,如果你使用mysql_use_result()来初始化结果集检索,当重复调用mysql_fetch_row()时,将逐个地从服务器获取结果集的行。由于在该过程中,可能出现连接上的错误,从mysql_fetch_row()返回的NULL值不一定表示已正常地抵达结果集末尾。在该情况下,可以使用mysql_eof()来判定出现了什么情况。如果抵达结果集末尾,mysql_eof()返回非0值,如果出现错误,返回0。

从历史的角度上看,mysql_eof()在日期上早于标准的MySQL错误函数mysql_errno()和mysql_error()。由于这类错误函数提供了相同的信息,它们优先于已过时的mysql_eof()。事实上,它们提供了更多信息,这是因为,mysql_eof()仅返回布尔值,错误函数能够在出现错误时指明错误的原因。

返回值

如果未出现错误,返回0。如果抵达结果集的末尾,返回非0值。

错误

无。

示例:

在下面的示例中,介绍了使用mysql_eof()的方法:

mysql_query(&mysql,"SELECT * FROM some_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
    // do something with data
}
if(!mysql_eof(result))  // mysql_fetch_row() failed due to an error
{
    fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}

但是,你也能使用标准的MySQL错误函数实现相同的结果:

mysql_query(&mysql,"SELECT * FROM some_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
    // do something with data
}
if(mysql_errno(&mysql))  // mysql_fetch_row() failed due to an error
{
    fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}

25.2.3.14. mysql_errno()

unsigned int mysql_errno(MYSQL *mysql)

描述

对于由mysql指定的连接,mysql_errno()返回最近调用的API函数的错误代码,该函数调用可能成功也可能失败。“0”返回值表示未出现错误。在MySQLerrmsg.h头文件中,列出了客户端错误消息编号。在附录B:错误代码和消息中,也列出了这些错误。

注意,如果成功,某些函数,如mysql_fetch_row()等,不会设置mysql_errno()。

经验规则是,如果成功,所有向服务器请求信息的函数均会复位mysql_errno()。

返回值

如果失败,返回上次mysql_xxx()调用的错误代码。“0”表示未出现错误。

错误

无。

25.2.3.15. mysql_error()

const char *mysql_error(MYSQL *mysql)

描述

对于由mysql指定的连接,对于失败的最近调用的API函数,mysql_error()返回包含错误消息的、由Null终结的字符串。如果该函数未失败,mysql_error()的返回值可能是以前的错误,或指明无错误的空字符串。

经验规则是,如果成功,所有向服务器请求信息的函数均会复位mysql_error()。

对于复位mysql_errno()的函数,下述两个测试是等效的:

if(mysql_errno(&mysql))
{
    // an error occurred
}
 
if(mysql_error(&mysql)[0] != '\0')
{
    // an error occurred
}

通过重新编译MySQL客户端库,可以更改客户端错误消息的语言。目前,能够选择数种语言显示错误消息,请参见5.10.2节,“设置错误消息语言”。

返回值

返回描述错误的、由Null终结的字符串。如果未出现错误,返回空字符串。

错误

无。

25.2.3.16. mysql_escape_string()

应使用mysql_real_escape_string()取而代之!

该函数与mysql_real_escape_string()等同,但mysql_real_escape_string()会将连接处理程序作为其第1个参量,并按照当前字符集对字符串进行转义处理。mysql_escape_string()不采用连接参量,而且不考虑当前字符集设置。

25.2.3.17. mysql_fetch_field()

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

描述

返回采用MYSQL_FIELD结构的结果集的列。重复调用该函数,以检索关于结果集中所有列的信息。未剩余字段时,mysql_fetch_field()返回NULL。

每次执行新的SELECT查询时,将复位mysql_fetch_field(),以返回关于第1个字段的信息。调用mysql_field_seek()也会影响mysql_fetch_field()返回的字段。

如果调用了mysql_query()以在表上执行SELECT,但未调用mysql_store_result(),如果调用了mysql_fetch_field()以请求BLOB字段的长度,MySQL将返回默认的Blob长度(8KB)。之所以选择8KB是因为MySQL不知道BLOB的最大长度。应在日后使其成为可配置的。一旦检索了结果集,field->max_length将包含特定查询中该列的最大值的长度。

返回值

当前列的MYSQL_FIELD结构。如果未剩余任何列,返回NULL。

错误

无。

示例:

MYSQL_FIELD *field;
 
while((field = mysql_fetch_field(result)))
{
    printf("field name %s\n", field->name);
}

25.2.3.18. mysql_fetch_field_direct()

MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)

描述

给定结果集内某1列的字段编号fieldnr,以MYSQL_FIELD结构形式返回列的字段定义。可以使用该函数检索任意列的定义。Fieldnr的值应在从0到mysql_num_fields(result)-1的范围内。

返回值

对于指定列,返回MYSQL_FIELD结构。

错误

无。

示例:

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *field;
 
num_fields = mysql_num_fields(result);
for(i = 0; i 
{
    field = mysql_fetch_field_direct(result, i);
    printf("Field %u is %s\n", i, field->name);
}

25.2.3.19. mysql_fetch_fields()

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

描述

对于结果集,返回所有MYSQL_FIELD结构的数组。每个结构提供了结果集中1列的字段定义。

返回值

关于结果集所有列的MYSQL_FIELD结构的数组。

错误

无。

示例:

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *fields;
 
num_fields = mysql_num_fields(result);
fields = mysql_fetch_fields(result);
for(i = 0; i 
{
   printf("Field %u is %s\n", i, fields[i].name);
}

25.2.3.20. mysql_fetch_lengths()

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

描述

返回结果集内当前行的列的长度。如果打算复制字段值,该长度信息有助于优化,这是因为,你能避免调用strlen()。此外,如果结果集包含二进制数据,必须使用该函数来确定数据的大小,原因在于,对于包含Null字符的任何字段,strlen()将返回错误的结果。

对于空列以及包含NULL值的列,其长度为0。要想了解区分这两类情况的方法,请参见关于mysql_fetch_row()的介绍。

返回值

无符号长整数的数组表示各列的大小(不包括任何终结NULL字符)。如果出现错误,返回NULL。

错误

mysql_fetch_lengths()仅对结果集的当前行有效。如果在调用mysql_fetch_row()之前或检索了结果集中的所有行后调用了它,将返回NULL。

示例:

MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;
 
row = mysql_fetch_row(result);
if (row)
{
    num_fields = mysql_num_fields(result);
    lengths = mysql_fetch_lengths(result);
    for(i = 0; i 
    {
         printf("Column %u is %lu bytes in length.\n", i, lengths[i]);
    }
}

25.2.3.21. mysql_fetch_row()

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

描述

检索结果集的下一行。在mysql_store_result()之后使用时,如果没有要检索的行,mysql_fetch_row()返回NULL。在mysql_use_result()之后使用时,如果没有要检索的行或出现了错误,mysql_fetch_row()返回NULL。

行内值的数目由mysql_num_fields(result)给出。如果行中保存了调用mysql_fetch_row()返回的值,将按照row[0]到row[mysql_num_fields(result)-1],访问这些值的指针。行中的NULL值由NULL指针指明。

可以通过调用mysql_fetch_lengths()来获得行中字段值的长度。对于空字段以及包含NULL的字段,长度为0。通过检查字段值的指针,能够区分它们。如果指针为NULL,字段为NULL,否则字段为空。

返回值

下一行的MYSQL_ROW结构。如果没有更多要检索的行或出现了错误,返回NULL。

错误

注意,在对mysql_fetch_row()的两次调用之间,不会复位错误。

· CR_SERVER_LOST

在查询过程中,与服务器的连接丢失。

· CR_UNKNOWN_ERROR

出现未知错误。

示例:

MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;
 
num_fields = mysql_num_fields(result);
while ((row = mysql_fetch_row(result)))
{
   unsigned long *lengths;
   lengths = mysql_fetch_lengths(result);
   for(i = 0; i 
   {
       printf("[%.*s] ", (int) lengths[i], row[i] ? row[i] : "NULL");
   }
   printf("\n");
}

25.2.3.22. mysql_field_count()

unsigned int mysql_field_count(MYSQL *mysql)

描述

返回作用在连接上的最近查询的列数。

该函数的正常使用是在mysql_store_result()返回NULL(因而没有结果集指针)时。在这种情况下,可调用mysql_field_count()来判定mysql_store_result()是否应生成非空结果。这样,客户端就能采取恰当的动作,而无需知道查询是否是SELECT(或类似SELECT的)语句。在这里给出的示例中,演示了完成它的方法。

请参见25.2.13.1节,“为什么在mysql_query()返回成功后,mysql_store_result()有时会返回NULL”.

返回值

表示结果集中列数的无符号整数。

错误

无。

示例:

MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;
 
if (mysql_query(&mysql,query_string))
{
    // error
}
else // query succeeded, process any data returned by it
{
    result = mysql_store_result(&mysql);
    if (result)  // there are rows
    {
        num_fields = mysql_num_fields(result);
        // retrieve rows, then call mysql_free_result(result)
    }
    else  // mysql_store_result() returned nothing; should it have?
    {
        if(mysql_field_count(&mysql) == 0)
        {
            // query does not return data
            // (it was not a SELECT)
            num_rows = mysql_affected_rows(&mysql);
        }
        else // mysql_store_result() should have returned data
        {
            fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
        }
    }
}

另一种可选的方法是,用mysql_errno(&mysql)替换mysql_field_count(&mysql)调用。在该情况下,无论语句是否是SELECT,你将直接从mysql_store_result()查找错误,而不是从mysql_field_count()的值进行推断。

25.2.3.23. mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

描述

将字段光标设置到给定的偏移处。对mysql_fetch_field()的下一次调用将检索与该偏移相关的列定义。

要想查找行的开始,请传递值为0的偏移量。

返回值

字段光标的前一个值。

错误

无。

25.2.3.24. mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

描述

返回上一个mysql_fetch_field()所使用的字段光标的定义。该值可用作mysql_field_seek()的参量。

返回值

字段光标的当前偏移量。

错误

无。

25.2.3.25. mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

描述

释放由mysql_store_result()、mysql_use_result()、mysql_list_dbs()等为结果集分配的内存。完成对结果集的操作后,必须调用mysql_free_result()释放结果集使用的内存。

释放完成后,不要尝试访问结果集。

返回值

无。

错误

无。

上一篇:

下一篇: