CAPI function description (O-R)

25.2.3.48.mysql _ options () intmysql_options (MYSQL * mysql, enummysql_optionoption, constchar * arg) describes how to set additional connection options and affect connection behavior. You can call this function multiple times to set several options. After mysql_init (), and mysql_connect () or mysql_real_c

25.2.3.48. mysql_options () int mysql_options (MYSQL * mysql, enum mysql_option option, const char * arg) description can be used to set additional connection options and affect connection behavior. You can call this function multiple times to set several options. After mysql_init (), and mysql_connect () or mysql_real_c

25.2.3.48. mysql_options ()

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

Description

It can be used to set additional connection options and affect connection behavior. You can call this function multiple times to set several options.

Call mysql_options () after mysql_init () and before mysql_connect () or mysql_real_connect ().

The option parameter refers to the option you want to set. The Arg parameter is the option value. If the option is an integer, arg should point to the integer value.

Possible options:

Option	Parameter type	Function
MYSQL_INIT_COMMAND	Char *	The command that will be executed when you connect to the MySQL server. The connection is automatically re-executed.
MYSQL_OPT_COMPRESS	Unused	Use the compressed Client/Server Protocol
MYSQL_OPT_CONNECT_TIMEOUT	Unsigned int *	Connection timeout in seconds.
MYSQL_OPT_GUESS_CONNECTION	Unused	Applications connected to libmysqld allow the library to "Guess" whether an Embedded Server or remote server is used. "Speculation" indicates that if the host name is set but not the local host, the remote server will be used. This is the default action. You can use MYSQL_OPT_USE_EMBEDDED_CONNECTION and MYSQL_OPT_USE_REMOTE_CONNECTION to overwrite it. This option is ignored for applications connected to libmysqlclient.
MYSQL_OPT_LOCAL_INFILE	An optional pointer to a unit.	If no pointer is given, or the Pointer Points to "unsigned int! = 0 ", the command load local infile is allowed.
MYSQL_OPT_NAMED_PIPE	Unused	Connect to the MySQL server on the NT platform using the named pipe.
MYSQL_OPT_PROTOCOL	Unsigned int *	The protocol type to use. It should be one of the enumerated values of mysql_protocol_type defined in mysql. h.
MYSQL_OPT_READ_TIMEOUT	Unsigned int *	Timeout for reading information from the server (currently only valid for TCP/IP connections on Windows ).
MYSQL_OPT_RECONNECT	My_bool *	If the connection is lost, start or disable automatic connection to the server. Starting from MySQL 5.0.3, reconnect is disabled by default. This is a new option in 5.0.13 and provides an explicit method for setting reconnect behavior.
MYSQL_OPT_SET_CLIENT_IP	Char *	For applications linked to libmysqld (Compiled libmysqld with the authentication support feature), it means that for authentication purposes, the user will be considered from the specified IP address (specified as a string). This option is ignored for applications connected to libmysqlclient.
MYSQL_OPT_USE_EMBEDDED_CONNECTION	Unused	For applications connected to libmysqld, it forces embedded servers to be used for connections. This option is ignored for applications connected to libmysqlclient.
MYSQL_OPT_USE_REMOTE_CONNECTION	Unused	For applications connected to libmysqld, it enforces remote servers for connections. This option is ignored for applications connected to libmysqlclient.
MYSQL_OPT_USE_RESULT	Unused	This option is not used.
MYSQL_OPT_WRITE_TIMEOUT	Unsigned int *	Write server timeout (currently only valid for TCP/IP connections on Windows ).
MYSQL_READ_DEFAULT_FILE	Char *	Read the options from the naming option file instead of from my. cnf.
MYSQL_READ_DEFAULT_GROUP	Char *	Read from the named group in my. cnf or the file specified by MYSQL_READ_DEFAULT_FILE.
MYSQL_REPORT_DATA_TRUNCATION	My_bool *	Through MYSQL_BIND.error, data truncation errors are allowed or prohibited for pre-processing statements (disabled by default ).
MYSQL_SECURE_AUTH	My_bool *	Whether to connect to a server that does not support password mixing. The password mixing function is used in MySQL 4.1.1 and later versions.
MYSQL_SET_CHARSET_DIR	Char *	The path name of the directory that contains the character set definition file.
MYSQL_SET_CHARSET_NAME	Char *	The name of the character set used as the default character set.
MYSQL_SHARED_MEMORY_BASE_NAME	Char *	It is a shared memory object that communicates with the server. The option "-shared-memory-base-name" should be the same as the mysqld server you plan to connect.

NOTE: If MYSQL_READ_DEFAULT_FILE or MYSQL_READ_DEFAULT_GROUP is used, the client group is always read.

The Group specified in the option file may contain the following options:

Option	Description
Connect-timeout	Connection timeout in seconds. On Linux, the timeout is also used to wait for the first response from the server.
Compress	Use the compressed Client/Server protocol.
Database	If no database is specified in the connection command, connect to the database.
Debug	Debugging options.
Disable-local-infile	Do not use load data local.
Host	Default host name.
Init-command	The command that will be executed when you connect to the MySQL server. The connection is automatically re-executed.
Interactive-timeout	It is equivalent to specifying CLIENT_INTERACTIVE as mysql_real_connect (). See section 25.2.3.51, "mysql_real_connect ()".
Local-infile [= (0 | 1)]	If no parameter or parameter exists! = 0, load data local is allowed.
Max_allowed_packet	The maximum information package that the client can read from the server.
Multi-results	Allows multi-statement execution or multiple result sets of the stored program.
Multi-statements	Allow the client to send multiple statements within one string. (Separated ).
Password	Default password.
Pipe	Connect to the MySQL server on the NT platform using the named pipe.
Protocol = {TCP | SOCKET | PIPE | MEMORY}	The protocol used to connect to the server.
Port	Default port number.
Return-found-rows	Notify mysql_info () to return the row found, instead of the row updated during UPDATE.
Shared-memory-base-name =Name	Shared Memory name, used to connect to the server (default: "MYSQL ").
Socket	Default socket file.
User	Default User.

Note that "timeout" has been replaced by "connect-timeout", but to maintain backward compatibility, mySQL 5.1.2-alpha still supports "timeout" (timeout ).

For more information about option files, see section 4.3.2 "Use Option Files ".

Return Value

If the call succeeds, 0 is returned. If the unknown option is used, a non-zero value is returned.

Example:

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));

}

This code requests the client to use the compressed Client/Server protocol and read additional options from the obdc section of the my. cnf file.

25.2.3.49. mysql_ping ()

Int mysql_ping (MYSQL * mysql)

Description

Check whether the connection to the server is working. If the connection is lost, the system will automatically try again.

This function can be used by idle clients for a long time to check whether the server has closed the connection and connect again if necessary.

Return Value

If the connection to the server is valid, 0 is returned. If an error occurs, a non-zero value is returned. The non-0 value returned does not indicate whether the MySQL server is closed or not. The connection may be caused by other reasons, such as network problems.

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order.

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_UNKNOWN_ERROR

An unknown error occurs.

25.2.3.50. mysql_query ()

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

Description

Execute the SQL query pointed to by the "Null-terminated string" query. Under normal circumstances, the string must contain one SQL statement, and the end semicolon (';') or "\ g" should not be added to the statement ". If multiple statements can be executed, a string can contain multiple statements separated by semicolons. See section 25.2.9, "c api processing for multi-query execution ".

Mysql_query () cannot be used to query binary data. Replace mysql_real_query () with mysql_real_query (). binary data may contain the characters '\ 0' and mysql_query () this character is interpreted as the end of the query string ).

If you want to know whether the query should return a result set, you can use mysql_field_count () to check. See section 25.2.3.22, "mysql_field_count ()".

Return Value

If the query is successful, 0 is returned. If an error occurs, a non-zero value is returned.

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order.

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_SERVER_LOST

The connection to the server is lost during the Query Process.

· CR_UNKNOWN_ERROR

An unknown error occurs.

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)

Description

Mysql_real_connect () tries to establish a connection with the MySQL database engine running on the host. Before you can execute any other API functions that require a valid MySQL connection handle structure, mysql_real_connect () must be completed successfully.

The parameter is specified as follows:

· The first parameter should be the address of the existing MYSQL structure. Before calling mysql_real_connect (), you must call mysql_init () to initialize the MYSQL structure. You can use mysql_options () to modify multiple connection options. See section 25.2.3.48, "mysql_options ()".

· The Value of "host" must be the host name or IP address. If "host" is NULL or the string "localhost", the connection is considered as a connection to the local host. If the operating system supports Sockets (Unix) or named pipes (Windows), they are used instead of TCP/IP to connect to the server.

· The "user" parameter contains the user's MySQL Login ID. If "user" is NULL or a NULL String ", the user is treated as the current user. In UNIX, it is the current login name. In Windows ODBC, you must specify the current user name. See section 26.1.9.2, "configure MyODBC DSN on Windows ".

· The passwd parameter contains the user's password. If passwd is NULL, only entries in the User table of this user (with one blank password field) will be checked. In this way, the database administrator can set the MySQL permission system in a specific way. The user will have different permissions based on whether the user has the specified password.

Note:Do not encrypt the password before calling mysql_real_connect (). The client API will automatically process the password encryption.

· "Db" is the database name. If the database is NULL, the connection sets the default database to this value.

· If "port" is not 0, its value will be used as the port number for TCP/IP connection. Note that the "host" parameter determines the connection type.

· If the unix_socket is not NULL, this string describes the socket or named pipe to be used. Note that the "host" parameter determines the connection type.

· The client_flag value is usually 0, but it can also be set as a combination of the following flag to allow specific functions:

Flag name	Flag description
CLIENT_COMPRESS	Use the compression protocol.
CLIENT_FOUND_ROWS	Returns the number of rows (matched), rather than the number of affected rows.
CLIENT_IGNORE_SPACE	Space is allowed after the function name. Make all function names reserved words.
CLIENT_INTERACTIVE	Before closing the connection, interactive_timeout (replacing wait_timeout) seconds are allowed for inactive time. The client's session wait_timeout variable is set to the value of the session interactive_timeout variable.
CLIENT_LOCAL_FILES	Allow the load data local processing function.
CLIENT_MULTI_STATEMENTS	The notification server. The client may send multiple statements (separated by ';') within a single string ). If this flag is not set, multi-statement execution is prohibited.
CLIENT_MULTI_RESULTS	The Notification Server allows the client to process multiple result sets from multi-statement execution or stored programs. If CLIENT_MULTI_STATEMENTS is set, it is set automatically.
CLIENT_NO_SCHEMA	DisableDb_name.tbl_name.col_nameSyntax. It is used for ODBC. If this syntax is used, it will generate errors for the analysis program. It is useful when capturing defects in some ODBC programs.
CLIENT_ODBC	The client is an ODBC client. It setsMysqldBecome More ODBC friendly.
CLIENT_SSL	Use SSL (encryption protocol ). This option should not be set by the application. It is set inside the client library.

For some parameters, values can be obtained from the option file, rather than the exact values in the mysql_real_connect () call. Therefore, before calling mysql_real_connect (), call mysql_options () together with MYSQL_READ_DEFAULT_FILE or MYSQL_READ_DEFAULT_GROUP (). Then, in the mysql_real_connect () call, specify the "NONE" value for each parameter that is preparing to read the value from the option file:

· For the host, specify a NULL value or an empty string ("").

· For user, specify a NULL value or an empty string.

· For passwd, specify the NULL value. (For the password, the Null String Value in the mysql_real_connect () call cannot be overwritten by the string in the option file, because the Null String explicitly specifies that the MySQL account must have a blank password ).

· For db, specify a NULL value or a NULL String

· For port, specify "0.

· For unix_socket, specify the NULL value.

If a parameter is not present in the option file, its default value is used, as described in this section.

Return Value

If the connection is successful, the MYSQL * connection handle is returned. If the connection fails, NULL is returned. For successful connections, the return value is the same as the value of the 1st parameter.

Error

· CR_CONN_HOST_ERROR

Unable to connect to MySQL server.

· CR_CONNECTION_ERROR

Unable to connect to the local MySQL server.

· CR_IPSOCK_ERROR

An IP socket cannot be created.

· CR_OUT_OF_MEMORY

Memory overflow.

· CR_SOCKET_CREATE_ERROR

You cannot create a Unix socket.

· CR_UNKNOWN_HOST

The IP address of the host name cannot be found.

· CR_VERSION_ERROR

Protocol mismatch is caused by an attempt to connect to a server with a specific client library (the client library uses different protocol versions. This happens if you use a very early client library to establish a connection with a newer server (not starting with the "-- old-protocol" option.

· CR_NAMEDPIPEOPEN_ERROR

You cannot create a named pipe on Windows.

· CR_NAMEDPIPEWAIT_ERROR

An error occurred while waiting for the Named Pipe in Windows.

· CR_NAMEDPIPESETSTATE_ERROR

An error occurred while obtaining the MPs queue on Windows.

· CR_SERVER_LOST

If connect_timeout is greater than 0, and the connection time is longer than connect_timeout seconds, or the server disappears when init-command is executed.

Example:

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));

}

By using mysql_options (), the MySQL database reads my. the [client] and [your_prog_name] sections of the cnf file ensure that the program works, even if someone sets MySQL in a non-standard way.

Note: Once a connection is established, mysql_real_connect () sets the value of the reconnect flag (a component of the MYSQL structure). In APIs earlier than 5.0.3, set it to "1". In a newer version, set it to "0 ". For this flag, the value "1" indicates that if the statement cannot be executed due to connection loss, you will try to connect to the server again before giving up. From MySQL 5.0.13, you can use the mysql_options () Option MYSQL_OPT_RECONNECT to control the reconnection behavior.

25.2.3.52. mysql_real_escape_string ()

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

Note that mysql must be a valid open connection. It is needed because the escape function depends on the character set used by the server.

Description

This function is used to create valid SQL strings that can be used in SQL statements. See section 9.1.1, "string ".

Encode the strings in "from" as escape SQL strings Based on the connected current character set. Place the result in "to" and add a NULL byte for termination. The encoded character is NUL (ASCII 0), '\ n',' \ R', '\', ''', '"', and Control-Z (see section 9.1," text value "). (Strictly speaking, MySQL only requires backslashes and quotation marks to reference strings in the escape query. This function can reference other characters to make them more readable in log files ).

The string to which "from" points must be a long byte ". The "to" buffer must be allocated at least 2 + 1 bytes in length. In the worst case, each character may need to be encoded in two bytes, and it also needs to end Null bytes. When mysql_real_escape_string () is returned, the content of "to" is a string terminated by Null. The return value is the length of the encoded string, excluding the Null character used for termination.

To change the character set of the connection, use the mysql_set_character_set () function instead of the set names (or set character set) statement. Mysql_set_character_set () works in a way similar to set names, but it can also affect the character SET used by mysql_real_escape_string (), while set names cannot.

Example:

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));

}

The strmov () function used in this example is included in the mysqlclient library. It works in a similar way as strcpy (), but returns a pointer pointing to the end of 1st parameters with Null.

Return Value

Length of the value placed in "to", excluding the Null character used to terminate.

Error

None.

25.2.3.53. mysql_real_query ()

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

Description

Execute the SQL query directed by "query", which should be a String Length Byte "long ". Under normal circumstances, the string must contain one SQL statement, and the end semicolon (';') or "\ g" should not be added to the statement ". If multiple statements can be executed, a string can contain multiple statements separated by semicolons. See section 25.2.9, "c api processing for multi-query execution ".

For queries that contain binary data, you must use mysql_real_query () instead of mysql_query (). This is because binary data may contain the characters '\ 0. In addition, mysql_real_query () is faster than mysql_query () because it does not call strlen () on the query string ().

If you want to know whether the query should return the result set, you can use mysql_field_count () to check section 25.2.3.22, "mysql_field_count ()".

Return Value

If the query is successful, 0 is returned. If an error occurs, a non-zero value is returned.

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order.

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_SERVER_LOST

The connection to the server is lost during the Query Process.

· CR_UNKNOWN_ERROR

An unknown error occurs.

25.2.3.54. mysql_refresh ()

Int mysql_refresh (MYSQL * mysql, unsigned int options)

Description

This function is used to refresh the table or cache, or reset the replication server information. The connected user must have the RELOAD permission.

The "options" parameter is a bitmask consisting of any combination of the following values. Multiple values can be combined in the "Or" (Or) mode, and multiple operations can be performed with one call.

· REFRESH_GRANT

Refresh the authorization table, similar to flush privileges.

· REFRESH_LOG

Refresh the log, similar to flush logs.

· REFRESH_TABLES

Refresh table cache, similar to flush tables.

· REFRESH_HOSTS

Refresh host high-speed buffer, similar to flush hosts.

· REFRESH_STATUS

Reset STATUS variable, similar to flush status.

· REFRESH_THREADS

Refresh thread high speed buffer.

· REFRESH_SLAVE

On the SLAVE replication server, RESET the master server information and restart the SLAVE server, similar to the reset slave.

· REFRESH_MASTER

On the MASTER replication server, delete the binary log files listed in the binary log index and truncate the index files, similar to the reset master.

Return Value

0 indicates success, and a non-0 value indicates an error.

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order.

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_SERVER_LOST

The connection to the server is lost during the Query Process.

· CR_UNKNOWN_ERROR

An unknown error occurs.

25.2.3.55. mysql_reload ()

Int mysql_reload (MYSQL * mysql)

Description

Request the MySQL server to reload the authorization table. The connected user must have the RELOAD permission.

This function is out of date. It is best to use mysql_query () to issue the sqlflush privileges statement.

Return Value

0 indicates success, and a non-0 value indicates an error.

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order.

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_SERVER_LOST

The connection to the server is lost during the Query Process.

· CR_UNKNOWN_ERROR

An unknown error occurs.

25.2.3.56. mysql_rollback ()

My_bool mysql_rollback (MYSQL * mysql)

Description

Roll back the current transaction.

The action of this function depends on the value of the completion_type system variable. In particular, if the value of completion_type is "2", the server will release the transaction and close the client connection. The client program should call mysql_close () to close the connection from the client side.

Return Value

If successful, 0 is returned. If an error occurs, a non-0 value is returned.

Error

None.

25.2.3.57. mysql_row_seek ()

MYSQL_ROW_OFFSET mysql_row_seek (MYSQL_RES * result, MYSQL_ROW_OFFSET offset)

Description

Place the row cursor on any row in the query result set. The "offset" value is the row offset, which should be the value returned from mysql_row_tell () or mysql_row_seek. This value is not a row number. If you want to query the rows in the result set by number, use mysql_data_seek ().

This function requires that the structure of the result set contain all the results of the query. Therefore, mysql_row_seek () should only be used with mysql_store_result () instead of mysql_use_result ().

Return Value

The first value of the row cursor. This value can be passed to subsequent calls to mysql_row_seek.

Error

None.

25.2.3.58. mysql_row_tell ()

MYSQL_ROW_OFFSET mysql_row_tell (MYSQL_RES * result)

Description

For the previous mysql_fetch_row (), the current position of the row cursor is returned. This value can be used as a parameter of mysql_row_seek.

Use mysql_row_tell () only after mysql_store_result () instead of mysql_use_result ().

Return Value

The current offset of the row cursor.

Error

None.