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

CAPI函数描述(G-N)

程序员文章站 2022-06-11 23:34:16
...

25.2.3.26. mysql_get_character_set_info() void mysql_get_character_set_info(MYSQL *mysql, MY_CHARSET_INFO *cs) 描述 该函数提供了关于默认客户端字符集的信息。可以使用mysql_set_character_set()函数更改默认的字符集。 该函数是在MySQL 5.0.10中增

25.2.3.26. mysql_get_character_set_info()

void mysql_get_character_set_info(MYSQL *mysql, MY_CHARSET_INFO *cs)

描述

该函数提供了关于默认客户端字符集的信息。可以使用mysql_set_character_set()函数更改默认的字符集。

该函数是在MySQL 5.0.10中增加的。

示例:

if (!mysql_set_character_set(&mysql, "utf8"))
{
    MY_CHARSET_INFO cs;
    mysql_get_character_set_info(&mysql, &cs);
    printf("character set information:\n");
    printf("character set name: %s\n", cs.name);
    printf("collation name: %s\n", cs.csname);
    printf("comment: %s\n", cs.comment);
    printf("directory: %s\n", cs.dir);
    printf("multi byte character min. length: %d\n", cs.mbminlen);
    printf("multi byte character max. length: %d\n", cs.mbmaxlen);
}

25.2.3.27. mysql_get_client_info()

char *mysql_get_client_info(void)

描述

返回表示客户端库版本的字符串。

返回值

表示MySQL客户端库版本的字符串。

错误

无。

25.2.3.28. mysql_get_client_version()

unsigned long mysql_get_client_version(void)

描述

返回表示客户端库版本的整数。该值的格式是XYYZZ,其中X是主版本号,YY是发布级别,ZZ是发布级别内的版本号。例如,值40102表示客户端库的版本是4.1.2。

返回值

表示MySQL客户端库版本的整数。

错误

无。

25.2.3.29. mysql_get_host_info()

char *mysql_get_host_info(MYSQL *mysql)

描述

返回描述了所使用连接类型的字符串,包括服务器主机名。

返回值

代表服务器主机名和连接类型的字符串。

错误

无。

25.2.3.30. mysql_get_proto_info()

unsigned int mysql_get_proto_info(MYSQL *mysql)

描述

返回当前连接所使用的协议版本。

返回值

代表当前连接所使用协议版本的无符号整数。

错误

无。

25.2.3.31. mysql_get_server_info()

char *mysql_get_server_info(MYSQL *mysql)

描述

返回代表服务器版本号的字符串。

返回值

代表服务器版本号的字符串。

错误

无。

25.2.3.32. mysql_get_server_version()

unsigned long mysql_get_server_version(MYSQL *mysql)

描述

以整数形式返回服务器的版本号。

返回值

表示MySQL服务器版本的数值,格式如下:

major_version*10000 + minor_version *100 + sub_version

例如,对于5.0.12,返回500012。

在客户端程序中,为了快速确定某些与版本相关的服务器功能是否存在,该函数很有用。

错误

无。

25.2.3.33. mysql_hex_string()

unsigned long mysql_hex_string(char *to, const char *from, unsigned long length)

描述

该函数用于创建可用在SQL语句中的合法SQL字符串。请参见9.1.1节,“字符串”。

该字符串从形式上编码为十六进制格式,每个字符编码为2个十六进制数。结果被置入其中,并添加1个终结Null字节。

“from”所指向的字符串必须是长度字节“long”。必须为“to”分配缓冲区,缓冲区至少为length*2+1字节长。当mysql_hex_string()返回时,“to”的内容为由Null终结的字符串。返回值是编码字符串的长度,不包括终结用Null字符。

可采用0xvalue或X'value'格式将返回值置于SQL语句中。但是,返回值不包括0x或X'...'。调用者必须提供所希望的格式是何种。

示例:

char query[1000],*end;
 
end = strmov(query,"INSERT INTO test_table values(");
end = strmov(end,"0x");
end += mysql_hex_string(end,"What's this",11);
end = strmov(end,",0x");
end += mysql_hex_string(end,"binary data: \0\r\n",16);
*end++ = ')';
 
if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&mysql));
}

示例中所使用的strmov()函数包含在mysqlclient库中,它的工作方式类似于strcpy(),但返回指向第1个参数终结Null的指针。

返回值

置于“to”中的值的长度,不包括终结用Null字符。

错误

无。

25.2.3.34. mysql_info()

char *mysql_info(MYSQL *mysql)

描述

检索字符串,该字符串提供了关于最近执行查询的信息,但仅对这里列出的语句有效。对于其他语句,mysql_info()返回NULL。字符串的格式取决于查询的类型,如本节所述。数值仅是说明性的,字符串包含与查询相适应的值。

· INSERT INTO ... SELECT ...

字符串格式:记录,100;副本,0;警告,0

· INSERT INTO ... VALUES (...),(...),(...)...

字符串格式:记录,3;副本,0;警告,0

· LOAD DATA INFILE ...

字符串格式:记录,1;删除,0;跳过,0;警告,0

· ALTER TABLE

字符串格式:记录,3;副本,0;警告,0

· UPDATE

字符串格式:匹配行,40;更改,40;警告,0

注意,mysql_info()为INSERT ... VALUES返回非NULL值,INSERT ... VALUES仅用于多行形式的语句(也就是说,仅当指定了多个值列表时)。

返回值

字符串,它表示最近所执行查询的额外信息。如果该查询无可用信息,返回NULL。

错误

无。

25.2.3.35. mysql_init()

MYSQL *mysql_init(MYSQL *mysql)

描述

分配或初始化与mysql_real_connect()相适应的MYSQL对象。如果mysql是NULL指针,该函数将分配、初始化、并返回新对象。否则,将初始化对象,并返回对象的地址。如果mysql_init()分配了新的对象,当调用mysql_close()来关闭连接时。将释放该对象。

返回值

初始化的MYSQL*句柄。如果无足够内存以分配新的对象,返回NULL。

错误

在内存不足的情况下,返回NULL。

25.2.3.36. mysql_insert_id()

my_ulonglong mysql_insert_id(MYSQL *mysql)

描述

返回由以前的INSERT或UPDATE语句为AUTO_INCREMENT列生成的值。在包含AUTO_INCREMENT字段的表中执行了INSERT语句后,应使用该函数。

更准确地讲,将在下述条件下更新mysql_insert_id():

· 将值保存到AUTO_INCREMENT列中的INSERT语句。无论值是通过在列中存储特殊值NULL或0自动生成的,还是确切的非特殊值,都成立。

· 在有多行INSERT语句的情况下,mysql_insert_id()返回第1个自动生成的AUTO_INCREMENT值,如果未生成这类值,将返回插入在AUTO_INCREMENT列中的最后1个确切值。

· 通过将LAST_INSERT_ID(expr)插入到任意列中以生成AUTO_INCREMENT值的INSERT语句。

· 通过更新任意列至LAST_INSERT_ID(expr)以生成AUTO_INCREMENT值的INSERT语句。

· mysql_insert_id()的值不受诸如SELECT等返回结果集的语句的影响。

· 如果前面的语句返回了错误,mysql_insert_id()的值将是不确定的。

注意,如果前面的语句未使用AUTO_INCREMENT,mysql_insert_id()返回0。如果需要保存值,在生成值的语句后,务必立刻调用mysql_insert_id()。

mysql_insert_id()的值仅受在当前客户端连接内发出的语句的影响。不受由其他客户端发出的语句的影响。

请参见12.9.3节,“信息函数”。

此外还应注意,SQL LAST_INSERT_ID()函数的值总包含最近生成的AUTO_INCREMENT值,而且在语句之间不会被复位,原因在于该函数的值是在服务器中维护的。另一个区别是,如果设置了AUTO_INCREMENT列来指定非特殊值,不会更新LAST_INSERT_ID()。

LAST_INSERT_ID()不同于mysql_insert_id()的原因在于,LAST_INSERT_ID()在脚本中很容易使用,而mysql_insert_id()则试图提供关于在AUTO_INCREMENT列中出现情况的更准确信息。

返回值

在前面的讨论中予以了介绍。

错误

无。

25.2.3.37. mysql_kill()

int mysql_kill(MYSQL *mysql, unsigned long pid)

描述

请求服务器杀死由pid指定的线程。

返回值

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

错误

· CR_COMMANDS_OUT_OF_SYNC

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

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

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

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.38. mysql_library_end()

void mysql_library_end(void)

描述

它是mysql_server_end()函数的同义词。

关于具体的用法,请参见25.2.2节,“C API函数概述”。

25.2.3.39. mysql_library_init()

int mysql_library_init(int argc, char **argv, char **groups)

描述

这是mysql_server_init()函数的同义词。

关于具体的用法,请参见25.2.2节,“C API函数概述”。

25.2.3.40. mysql_list_dbs()

MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)

描述

返回由服务器上的数据库名称组成的结果集,该服务器与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符“%”或“_”,也可以是NULL指针,以便与所有的数据库匹配。调用mysql_list_dbs()的方法类似于执行查询SHOW database [LIKE wild]。

必须用mysql_free_result()释放结果集。

返回值

成功后返回MYSQL_RES结果集。如果出现错误,返回NULL。

错误

· CR_COMMANDS_OUT_OF_SYNC

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

· CR_OUT_OF_MEMORY

内存溢出。

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

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

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.41. mysql_list_fields()

MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)

描述

返回由给定表中的字段名称组成的结果集,给定表与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符“%”或“_”,也可以是NULL指针,以便与所有的字段匹配。调用mysql_list_fields()的方法类似于执行查询SHOW COLUMNS FROM tbl_name [LIKE wild]。

注意,建议使用SHOW COLUMNS FROM tbl_name,而不是mysql_list_fields()。

必须用mysql_free_result()释放结果集。

返回值

如果成功,返回MYSQL_RES结果集。如果出现错误,返回NULL。

错误

· CR_COMMANDS_OUT_OF_SYNC

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

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

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

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.42. mysql_list_processes()

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

描述

返回描述当前服务器线程的结果集。该类信息与mysqladmin processlist或SHOW PROCESSLIST查询给出的信息相同。

必须用mysql_free_result()释放结果集。

返回值

如果成功,返回MYSQL_RES结果集。如果出现错误,返回NULL。

错误

· CR_COMMANDS_OUT_OF_SYNC

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

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

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

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.43. mysql_list_tables()

MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)

描述

返回由当前数据库内的表名组成的结果集,当前数据库与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符“%”或“_”,也可以是NULL指针,以便与所有的表匹配。调用mysql_list_tables()的方法类似于执行查询HOW tables [LIKE wild]。

必须用mysql_free_result()释放结果集。

返回值

如果成功,返回MYSQL_RES结果集。 如果出现错误,返回NULL。

错误

· CR_COMMANDS_OUT_OF_SYNC

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

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

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

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.44. mysql_more_results()

my_bool mysql_more_results(MYSQL *mysql)

描述

如果当前执行的查询存在多个结果,返回“真”,而且应用程序必须调用mysql_next_result()来获取结果。

返回值

如果存在多个结果,返回“真”(1),如果不存在多个结果,返回“假”(0)。

在大多数情况下,可调用mysql_next_result()来测试是否存在多个结果,如果存在多个结果,对检索进行初始化操作。

请参见25.2.9节,“多查询执行的C API处理”。请参见25.2.3.45节,“mysql_next_result()”。

错误

无。

25.2.3.45. mysql_next_result()

int mysql_next_result(MYSQL *mysql)

描述

如果存在多个查询结果,mysql_next_result()将读取下一个查询结果,并将状态返回给应用程序。

如果前面的查询返回了结果集,必须为其调用mysql_free_result()。

调用了mysql_next_result()后,连接状态就像你已为下一查询调用了mysql_real_query()或mysql_query()时的一样。这意味着你能调用mysql_store_result()、mysql_warning_count()、mysql_affected_rows()等等。

如果mysql_next_result()返回错误,将不执行任何其他语句,也不会获取任何更多的结果,

请参见25.2.9节,“多查询执行的C API处理”。

返回值

返回值

描述

0

成功并有多个结果。

-1

成功但没有多个结果。

>0

出错

错误

· CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。例如,没有为前面的结果集调用mysql_use_result()。

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

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

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.46. mysql_num_fields()

unsigned int mysql_num_fields(MYSQL_RES *result)

要想传递MYSQL*参量取而代之,请使用无符号整数mysql_field_count(MYSQL *mysql)。

描述

返回结果集中的行数。

注意,你可以从指向结果集的指针或指向连接句柄的指针获得行数。如果mysql_store_result()或mysql_use_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_errno(&mysql))
        {
           fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
        }
        else if (mysql_field_count(&mysql) == 0)
        {
            // query does not return data
            // (it was not a SELECT)
            num_rows = mysql_affected_rows(&mysql);
        }
    }
}

另一种可选方式是(如果你知道你的查询应返回结果集),使用检查“mysql_field_count(&mysql) is = 0”来替换mysql_errno(&mysql)调用。仅当出错时才应使用它。

25.2.3.47. mysql_num_rows()

my_ulonglong mysql_num_rows(MYSQL_RES *result)

描述

返回结果集中的行数。

mysql_num_rows()的使用取决于是否采用了mysql_store_result()或mysql_use_result()来返回结果集。如果使用了mysql_store_result(),可以立刻调用mysql_num_rows()。如果使用了mysql_use_result(),mysql_num_rows()不返回正确的值,直至检索了结果集中的所有行为止。

返回值

结果集中的行数。

错误

无。