mysql_real_connect()

You can call the mysql_real_connect() function to establish a connection to an OBServer running on a host.

Syntax

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)

Return values

A MYSQL* connection handler is returned if the connection was successful, and NULL is returned if the connection was unsuccessful.

For a successful connection, the return value is the same as the value of the first argument.

Errors

• CR_CONN_HOST_ERROR: Unable to connect to the OBServer.

• CR_CONNECTION_ERROR: Unable to connect to the local OBServer.

• CR_IPSOCK_ERROR: Unable to create an IP socket.

• CR_OUT_OF_MEMORY: The memory is insufficient.

• CR_SOCKET_CREATE_ERROR: Unable to create a Unix socket.

• CR_UNKNOWN_HOST: Unable to find the IP address of the host name.

• CR_VERSION_ERROR: A protocol mismatch is resulted from an attempt to connect to a server with a client library that uses a different protocol version.

• CR_NAMEDPIPEOPEN_ERROR: Unable to create a named pipe on Windows.

• CR_NAMEDPIPEWAIT_ERROR: Failed to wait for a named pipe on Windows.

• CR_NAMEDPIPESETSTATE_ERROR: Unable to obtain a pipe handler on Windows.

• CR_SERVER_LOST: connect_timeout > 0 and the time taken to connect to the server exceeded connect_timeout, or the server was down when executing init-command.

• CR_ALREADY_CONNECTED: The MYSQL connection handler was already connected.

Notes

Arguments

• For the first argument mysql, specify the address of an existing MYSQL structure. Before you call mysql_real_connect(), call mysql_init() to initialize the MYSQL structure.

• The value of host can be a host name or IP address. The client attempts to connect as follows:

  • If the value of host is NULL or the string localhost, assume that the client attempts to connect to the local host:

    • On Windows, if the server enables shared-memory connections, the client connects by using a shared-memory connection.

    • On Unix, the client connects by using a Unix socket file. The unix_socket argument or the MYSQL_UNIX_PORT environment variable can be used to specify the socket name.

  • On Windows, if the value of host is ".", or if TCP/IP is not enabled and unix_socket is not specified or the host parameter is unspecified, the client connects to the server by using a named pipe, provided that the server enables named-pipe connections. If named-pipe connections are not enabled, an error occurs.

  • Otherwise, TCP/IP is used.

• The user argument contains the user's logon ID. If user is NULL or the empty string "", the current user is assumed. In Unix, the current logon name is used. In Windows ODBC, the current username must be explicitly specified.

• The passwd argument contains the password of the user. If passwd is NULL, only entries with a blank (empty) password field in the user table are checked. In this way, the DBA can set up the privilege system so that users obtain different privileges based on whether they have specified a password.

  Note

  Do not attempt to encrypt the password before calling mysql_real_connect(). Password encryption is automatically handled by the client API.

• The user and passwd arguments use the character set configured for the MYSQL object. By default, the character set is latin1, but can be changed by calling mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "charset_name") before connection.

• db is the database name. If db is not NULL, the connection identifies it as the default database.

• If port is not 0, the value is used as the port number for the TCP/IP connection. Note that the host argument determines the type of the connection.

• If unix_socket is not NULL, the string specifies the socket or named pipe to be used. Note that the host argument determines the type of the connection.

• The value of client_flag is usually 0, but can be set to a combination of the following flags to enable certain features:

  • CAN_HANDLE_EXPIRED_PASSWORDS: allows the client to handle expired passwords.

  • CLIENT_COMPRESS: uses compression in the client/server protocol.

  • CLIENT_FOUND_ROWS: returns the number of found (matched) rows, not the number of modified rows.

  • CLIENT_IGNORE_SIGPIPE: prevents the client library from installing a SIGPIPE signal handler. This can avoid conflicts with a handler already installed by the application.

  • CLIENT_IGNORE_SPACE: allows for spaces after function names, and makes all function names reserved words.

  • CLIENT_INTERACTIVE: allows for a period of inactivity of interactive_timeout seconds (rather than wait_timeout seconds) before closing the connection. The session variable wait_timeout of the client is set to the value of the session variable interactive_timeout.

  • CLIENT_LOCAL_FILES: enables LOAD DATA LOCAL.

  • CLIENT_MULTI_RESULTS: notifies the server that the client can handle multiple result sets from multi-statement executions or stored procedures. This flag is automatically enabled if CLIENT_MULTI_STATEMENTS is enabled.

  • CLIENT_MULTI_STATEMENTS: notifies the server that the client can send multiple statements in a single string (separated by ;). If this flag is not set, multi-statement execution is disabled.

  • CLIENT_NO_SCHEMA: prohibits the db_name.tbl_name.col_name syntax. If this syntax is used, the parser generates an error. This is useful for trapping bugs in some ODBC programs.

  • CLIENT_ODBC: not used.

  • CLIENT_SSL: uses SSL (encryption protocol). It is set internally in the client library and cannot be set within applications.

  • CLIENT_REMEMBER_OPTIONS: remembers options specified for mysql_options() calls. Without this option, if mysql_real_connect() fails, you must repeatedly call mysql_options() before trying to reconnect. With this option, you do not need to repeatedly call mysql_options().

If the program uses CALL statements to execute stored procedures, the CLIENT_MULTI_RESULTS flag must be enabled. This is because each CALL statement returns a result to indicate the call status, in addition to the result sets that might be returned by statements executed within the procedure. Because CALL can return multiple results, call mysql_next_result() in a loop manner to determine whether more results exist.

If you CLIENT_MULTI_STATEMENTS or CLIENT_MULTI_RESULTS is enabled, call mysql_next_result() in a loop manner to call the result of mysql_real_query() or mysql_query() to determine whether more results exist.

For some arguments, you can obtain their values from an option file rather than from an explicit value in a call. Therefore, call mysql_options() with the MYSQL_READ_DEFAULT_FILE or MYSQL_READ_DEFAULT_GROUP option before calling mysql_real_connect(). Then, during the mysql_real_connect() call, specify the "no-value" value for each argument to be read from an option file.

• For host, specify NULL or the empty string ("").

• For user, specify NULL or the empty string.

• For passwd, specify NULL.

• For db, specify NULL or the empty string.

• For port, specify 0.

• For unix_socket, specify NULL.

If no value is found in an option file for a argument, the default value is used.