当前位置:Gxlcms > mysql > CAPI函数描述(O-R)

CAPI函数描述(O-R)

时间:2021-07-01 10:21:17 帮助过:18人阅读

25.2.3.48. mysql_options() int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg) 描述 可用于设置额外的连接选项,并影响连接的行为。可多次调用该函数来设置数个选项。 应在mysql_init()之后、以及mysql_connect()或mysql_real_c

25.2.3.48. mysql_options()

int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)

描述

可用于设置额外的连接选项,并影响连接的行为。可多次调用该函数来设置数个选项。

应在mysql_init()之后、以及mysql_connect()或mysql_real_connect()之前调用mysql_options()。

选项参量指的是你打算设置的选项。Arg参量是选项的值。如果选项是整数,那么arg应指向整数的值。

可能的选项值:

选项

参量类型

功能

MYSQL_INIT_COMMAND

char *

连接到MySQL服务器时将执行的命令。再次连接时将自动地再次执行。

MYSQL_OPT_COMPRESS

未使用

使用压缩客户端/服务器协议

MYSQL_OPT_CONNECT_TIMEOUT

unsigned int *

以秒为单位的连接超时。

MYSQL_OPT_GUESS_CONNECTION

未使用

对于与libmysqld链接的应用程序,允许库“猜测”是否使用嵌入式服务器或远程服务器。“猜测”表示,如果设置了主机名但不是本地主机,将使用远程服务器。该行为是默认行为。 可使用MYSQL_OPT_USE_EMBEDDED_CONNECTION和MYSQL_OPT_USE_REMOTE_CONNECTION覆盖它。对于与libmysqlclient链接的应用程序,该选项将被忽略。

MYSQL_OPT_LOCAL_INFILE

指向单元的可选指针

如果未给定指针,或指针指向“unsigned int != 0”,将允许命令LOAD LOCAL INFILE。

MYSQL_OPT_NAMED_PIPE

未使用

使用命名管道连接到NT平台上的MySQL服务器。

MYSQL_OPT_PROTOCOL

unsigned int *

要使用的协议类型。应是mysql.h中定义的mysql_protocol_type的枚举值之一。

MYSQL_OPT_READ_TIMEOUT

unsigned int *

从服务器读取信息的超时(目前仅在Windows平台的TCP/IP连接上有效)。

MYSQL_OPT_RECONNECT

my_bool *

如果发现连接丢失,启动或禁止与服务器的自动再连接。从MySQL 5.0.3开始,默认情况下禁止再连接,这是5.0.13中的新选项,提供了一种以显式方式设置再连接行为的方法。

MYSQL_OPT_SET_CLIENT_IP

char *

对于与libmysqld链接的应用程序(具备鉴定支持特性的已编译libmysqld),它意味着,出于鉴定目的,用户将被视为从指定的IP地址(指定为字符串)进行连接。对于与libmysqlclient链接的应用程序,,该选项将被忽略。

MYSQL_OPT_USE_EMBEDDED_CONNECTION

未使用

对于与libmysqld链接的应用程序,对于连接来说,它将强制使用嵌入式服务器。对于与libmysqlclient链接的应用程序,,该选项将被忽略。

MYSQL_OPT_USE_REMOTE_CONNECTION

未使用

对于与libmysqld链接的应用程序,对于连接来说,它将强制使用远程服务器。对于与libmysqlclient链接的应用程序,,该选项将被忽略。

MYSQL_OPT_USE_RESULT

未使用

不使用该选项。

MYSQL_OPT_WRITE_TIMEOUT

unsigned int *

写入服务器的超时(目前仅在Windows平台的TCP/IP连接上有效)。

MYSQL_READ_DEFAULT_FILE

char *

从命名选项文件而不是从my.cnf读取选项。

MYSQL_READ_DEFAULT_GROUP

char *

从my.cnf或用MYSQL_READ_DEFAULT_FILE指定的文件中的命名组读取选项。

MYSQL_REPORT_DATA_TRUNCATION

my_bool *

通过MYSQL_BIND.error,对于预处理语句,允许或禁止通报数据截断错误(默认为禁止)。

MYSQL_SECURE_AUTH

my_bool*

是否连接到不支持密码混编功能的服务器,在MySQL 4.1.1和更高版本中,使用了密码混编功能。

MYSQL_SET_CHARSET_DIR

char*

指向包含字符集定义文件的目录的路径名。

MYSQL_SET_CHARSET_NAME

char*

用作默认字符集的字符集的名称。

MYSQL_SHARED_MEMORY_BASE_NAME

char*

命名为与服务器进行通信的共享内存对象。应与你打算连接的mysqld服务器使用的选项“-shared-memory-base-name”相同。

注意,如果使用了MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP,总会读取客户端组。

选项文件中指定的组可能包含下述选项:

选项

描述

connect-timeout

以秒为单位的连接超时。在Linux平台上,该超时也用作等待服务器首次回应的时间。

compress

使用压缩客户端/服务器协议。

database

如果在连接命令中未指定数据库,连接到该数据库。

debug

调试选项。

disable-local-infile

禁止使用LOAD DATA LOCAL。

host

默认主机名。

init-command

连接到MySQL服务器时将执行的命令。再次连接时将自动地再次执行。

interactive-timeout

等同于将CLIENT_INTERACTIVE指定为mysql_real_connect()。请参见25.2.3.51节,“mysql_real_connect()”。

local-infile[=(0|1)]

如果无参量或参量!= 0,那么将允许使用LOAD DATA LOCAL。

max_allowed_packet

客户端能够从服务器读取的最大信息包。

multi-results

允许多语句执行或存储程序的多个结果集。

multi-statements

允许客户端在1个字符串内发送多条语句。(由“;”隔开)。

password

默认密码。

pipe

使用命名管道连接到NT平台上的MySQL服务器。

protocol={TCP | SOCKET | PIPE | MEMORY}

连接到服务器时将使用的协议。

port

默认端口号。

return-found-rows

通知mysql_info()返回发现的行,而不是使用UPDATE时更新的行。

shared-memory-base-name=name

共享内存名称,用于连接到服务器(默认为"MYSQL")。

socket

默认的套接字文件。

user

默认用户。

注意,“timeout”(超时)已被“connect-timeout”(连接超时)取代,但为了保持向后兼容,在MySQL 5.1.2-alpha中仍支持“timeout”(超时)。

关于选项文件的更多信息,请参见4.3.2节,“使用选项文件”。

返回值

成功时返回0。如果使用了未知选项,返回非0值。

示例:

MYSQL mysql;
 
mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}

该代码请求客户端使用压缩客户端/服务器协议,并从my.cnf文件的obdc部分读取额外选项。

25.2.3.49. mysql_ping()

int mysql_ping(MYSQL *mysql)

描述

检查与服务器的连接是否工作。如果连接丢失,将自动尝试再连接。

该函数可被闲置了较长时间的客户端使用,用以检查服务器是否已关闭了连接,并在必要时再次连接。

返回值

如果与服务器的连接有效返回0。如果出现错误,返回非0值。返回的非0值不表示MySQL服务器本身是否已关闭,连接可能因其他原因终端,如网络问题等。

错误

· CR_COMMANDS_OUT_OF_SYNC

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

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.50. mysql_query()

int mysql_query(MYSQL *mysql, const char *query)

描述

执行由“Null终结的字符串”查询指向的SQL查询。正常情况下,字符串必须包含1条SQL语句,而且不应为语句添加终结分号(‘;’)或“\g”。如果允许多语句执行,字符串可包含多条由分号隔开的语句。请参见25.2.9节,“多查询执行的C API处理”。

mysql_query()不能用于包含二进制数据的查询,应使用mysql_real_query()取而代之(二进制数据可能包含字符‘\0’,mysql_query()会将该字符解释为查询字符串结束)。

如果希望了解查询是否应返回结果集,可使用mysql_field_count()进行检查。请参见25.2.3.22节,“mysql_field_count()”。

返回值

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

错误

· CR_COMMANDS_OUT_OF_SYNC

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

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

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

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.51. mysql_real_connect()

MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag)

描述

mysql_real_connect()尝试与运行在主机上的MySQL数据库引擎建立连接。在你能够执行需要有效MySQL连接句柄结构的任何其他API函数之前,mysql_real_connect()必须成功完成。

参数的指定方式如下:

· 第1个参数应是已有MYSQL结构的地址。调用mysql_real_connect()之前,必须调用mysql_init()来初始化MYSQL结构。通过mysql_options()调用,可更改多种连接选项。请参见25.2.3.48节,“mysql_options()”。

· “host”的值必须是主机名或IP地址。如果“host”是NULL或字符串"localhost",连接将被视为与本地主机的连接。如果操作系统支持套接字(Unix)或命名管道(Windows),将使用它们而不是TCP/IP连接到服务器。

· “user”参数包含用户的MySQL登录ID。如果“user”是NULL或空字符串"",用户将被视为当前用户。在UNIX环境下,它是当前的登录名。在Windows ODBC下,必须明确指定当前用户名。请参见26.1.9.2节,“在Windows上配置MyODBC DSN”。

· “passwd”参数包含用户的密码。如果“passwd”是NULL,仅会对该用户的(拥有1个空密码字段的)用户表中的条目进行匹配检查。这样,数据库管理员就能按特定的方式设置MySQL权限系统,根据用户是否拥有指定的密码,用户将获得不同的权限。

注释:调用mysql_real_connect()之前,不要尝试加密密码,密码加密将由客户端API自动处理。

· “db”是数据库名称。如果db为NULL,连接会将默认的数据库设为该值。

· 如果“port”不是0,其值将用作TCP/IP连接的端口号。注意,“host”参数决定了连接的类型。

· 如果unix_socket不是NULL,该字符串描述了应使用的套接字或命名管道。注意,“host”参数决定了连接的类型。

· client_flag的值通常为0,但是,也能将其设置为下述标志的组合,以允许特定功能:

标志名称

标志描述

CLIENT_COMPRESS

使用压缩协议。

CLIENT_FOUND_ROWS

返回发现的行数(匹配的),而不是受影响的行数。

CLIENT_IGNORE_SPACE

允许在函数名后使用空格。使所有的函数名成为保留字。

CLIENT_INTERACTIVE

关闭连接之前,允许interactive_timeout(取代了wait_timeout)秒的不活动时间。客户端的会话wait_timeout变量被设为会话interactive_timeout变量的值。

CLIENT_LOCAL_FILES

允许LOAD DATA LOCAL处理功能。

CLIENT_MULTI_STATEMENTS

通知服务器,客户端可能在单个字符串内发送多条语句(由‘;’隔开)。如果未设置该标志,将禁止多语句执行。

CLIENT_MULTI_RESULTS

通知服务器,客户端能够处理来自多语句执行或存储程序的多个结果集。如果设置了CLIENT_MULTI_STATEMENTS,将自动设置它。

CLIENT_NO_SCHEMA

禁止db_name.tbl_name.col_name语法。它用于ODBC。如果使用了该语法,它会使分析程序生成错误,在捕获某些ODBC程序中的缺陷时,它很有用。

CLIENT_ODBC

客户端是ODBC客户端。它将mysqld变得更为ODBC友好。

CLIENT_SSL

使用SSL(加密协议)。该选项不应由应用程序设置,它是在客户端库内部设置的。

对于某些参数,能够从选项文件获得取值,而不是取得mysql_real_connect()调用中的确切值。为此,在调用mysql_real_connect()之前,应与MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP选项一起调用mysql_options()。随后,在mysql_real_connect()调用中,为准备从选项文件读取值的每个参数指定“无值”值:

· 对于host,指定NULL值或空字符串("")。

· 对于user,指定NULL值或空字符串。

· 对于passwd,指定NULL值。(对于密码,mysql_real_connect()调用中的空字符串的值不能被选项文件中的字符串覆盖,这是因为,空字符串明确指明MySQL账户必须有空密码)。

· 对于db,指定NULL值或空字符串

· 对于port,指定“0”值。

· 对于unix_socket,指定NULL值。

对于某一参数,如果在选项文件中未发现值,将使用它的默认值,如本节前面介绍的那样。

返回值

如果连接成功,返回MYSQL*连接句柄。如果连接失败,返回NULL。对于成功的连接,返回值与第1个参数的值相同。

错误

· CR_CONN_HOST_ERROR

无法连接到MySQL服务器。

· CR_CONNECTION_ERROR

无法连接到本地MySQL服务器。

· CR_IPSOCK_ERROR

无法创建IP套接字。

· CR_OUT_OF_MEMORY

内存溢出。

· CR_SOCKET_CREATE_ERROR

无法创建Unix套接字。

· CR_UNKNOWN_HOST

无法找到主机名的IP地址。

· CR_VERSION_ERROR

协议不匹配,起因于:试图连接到具有特定客户端库(该客户端库使用了不同的协议版本)的服务器。如果使用很早的客户端库来建立与较新的服务器(未使用“--old-protocol”选项开始的)的连接,就会出现该情况。

· CR_NAMEDPIPEOPEN_ERROR

无法在Windows平台下创建命名管道。

· CR_NAMEDPIPEWAIT_ERROR

在Windows平台下等待命名管道失败。

· CR_NAMEDPIPESETSTATE_ERROR

在Windows平台下获取管道处理程序失败。

· CR_SERVER_LOST

如果connect_timeout > 0,而且在连接服务器时所用时间长于connect_timeout秒,或在执行init-command时服务器消失。

示例:

MYSQL mysql;
 
mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}

通过使用mysql_options(),MySQL库将读取my.cnf文件的[client]和[your_prog_name]部分,以确保程序工作,即使某人以某种非标准的方式设置MySQL也同样。

注意,一旦建立了连接,mysql_real_connect()将设置再连接标志(MYSQL结构的组成部份)的值,在低于5.0.3版的API中,将其设为“1”,在较新的版本中,将其设为“0”。对于该标志,值“1”表示,如果因连接丢失而无法执行语句,放弃前,将尝试再次连接到服务器。从MySQL 5.0.13开始,可以对mysql_options()使用MYSQL_OPT_RECONNECT选项,对再连接行为进行控制。

25.2.3.52. mysql_real_escape_string()

unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)

注意,mysql必须是有效的开放式连接。之所以需要它是因为,转义功能取决于服务器使用的字符集。

描述

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

按照连接的当前字符集,将“from”中的字符串编码为转义SQL字符串。将结果置于“to”中,并添加1个终结用NULL字节。编码的字符为NUL (ASCII 0)、‘\n’、‘\r’、‘\’、‘'’、‘"’、以及Control-Z(请参见9.1节,“文字值”)。(严格地讲,MySQL仅需要反斜杠和引号字符,用于引用转义查询中的字符串。该函数能引用其他字符,从而使得它们在日志文件中具有更好的可读性)。

“from”指向的字符串必须是长度字节“long”。必须为“to”缓冲区分配至少length*2+1字节。在最坏的情况下,每个字符或许需要使用2个字节进行编码,而且还需要终结Null字节。当mysql_real_escape_string()返回时,“to”的内容是由Null终结的字符串。返回值是编码字符串的长度,不包括终结用Null字符。

如果需要更改连接的字符集,应使用mysql_set_character_set()函数,而不是执行SET NAMES (或SET CHARACTER SET)语句。mysql_set_character_set()的工作方式类似于SET NAMES,但它还能影响mysql_real_escape_string()所使用的字符集,而SET NAMES则不能。

示例:

char query[1000],*end;
 
end = strmov(query,"INSERT INTO test_table values(");
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"What's this",11);
*end++ = '\'';
*end++ = ',';
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"binary data: \0\r\n",16);
*end++ = '\'';
*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.53. mysql_real_query()

int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length)

描述

执行由“query”指向的SQL查询,它应是字符串长度字节“long”。正常情况下,字符串必须包含1条SQL语句,而且不应为语句添加终结分号(‘;’)或“\g”。如果允许多语句执行,字符串可包含由分号隔开的多条语句。请参见25.2.9节,“多查询执行的C API处理”。

对于包含二进制数据的查询,必须使用mysql_real_query()而不是mysql_query(),这是因为,二进制数据可能会包含‘\0’字符。此外,mysql_real_query()比mysql_query()快,这是因为它不会在查询字符串上调用strlen()。

如果希望知道查询是否应返回结果集,可使用mysql_field_count()进行检查25.2.3.22节,“mysql_field_count()”。

返回值

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

错误

· CR_COMMANDS_OUT_OF_SYNC

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

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

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

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.54. mysql_refresh()

int mysql_refresh(MYSQL *mysql, unsigned int options)

描述

该函数用于刷新表或高速缓冲,或复位复制服务器信息。连接的用户必须具有RELOAD权限。

“options”参量是一种位掩码,由下述值的任意组合构成。能够以“Or”(或)方式将多个值组合在一起,用一次调用执行多项操作。

· REFRESH_GRANT

刷新授权表,与FLUSH PRIVILEGES类似。

· REFRESH_LOG

刷新日志,与FLUSH LOGS类似。

· REFRESH_TABLES

刷新表高速缓冲,与FLUSH TABLES类似。

· REFRESH_HOSTS

刷新主机高速缓冲,与FLUSH HOSTS类似。

· REFRESH_STATUS

复位状态变量,与FLUSH STATUS类似。

· REFRESH_THREADS

刷新线程高速缓冲。

· REFRESH_SLAVE

在从复制服务器上,复位主服务器信息,并重新启动从服务器,与RESET SLAVE类似。

· REFRESH_MASTER

在主复制服务器上,删除二进制日志索引中列出的二进制日志文件,并截短索引文件,与RESET MASTER类似。

返回值

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

错误

· CR_COMMANDS_OUT_OF_SYNC

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

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

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

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.55. mysql_reload()

int mysql_reload(MYSQL *mysql)

描述

请求MySQL服务器重新加载授权表。连接的用户必须具有RELOAD权限。

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

返回值

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

错误

· CR_COMMANDS_OUT_OF_SYNC

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

· CR_SERVER_GONE_ERROR

MySQL服务器不可用。

· CR_SERVER_LOST

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

· CR_UNKNOWN_ERROR

出现未知错误。

25.2.3.56. mysql_rollback()

my_bool mysql_rollback(MYSQL *mysql)

描述

回滚当前事务。

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

返回值

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

错误

无。

25.2.3.57. mysql_row_seek()

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

描述

将行光标置于查询结果集中的任意行。“offset”值是行偏移量,它应是从mysql_row_tell()或mysql_row_seek()返回的值。该值不是行编号,如果你打算按编号查找结果集中的行,请使用mysql_data_seek()。

该函数要求在结果集的结构中包含查询的全部结果,因此,mysql_row_seek()仅应与mysql_store_result()一起使用,而不是与mysql_use_result()。

返回值

行光标的前一个值。该值可传递给对mysql_row_seek()的后续调用。

错误

无。

25.2.3.58. mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

描述

对于上一个mysql_fetch_row(),返回行光标的当前位置。该值可用作mysql_row_seek()的参量。

仅应在mysql_store_result()之后,而不是mysql_use_result()之后使用mysql_row_tell()。

返回值

行光标的当前偏移量。

错误

无。

人气教程排行