<?xml version="1.0" encoding="UTF-8"?>
<refentry version="5.0-subset Scilab" xml:id="mysql_option" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:ns3="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook">
  <refnamediv>
    <refname>mysql_option</refname>

    <refpurpose>Can be used to set extra connect options and affect behavior for a connection.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>

    <synopsis>result = mysql_option(mysql, option, arg)</synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>

    <para>Can be used to set extra connect options and affect 
      behavior for a connection. This function may be called 
      multiple times to set several options.</para>
    <para><literal>mysql_options</literal> should be called after
      <literal>mysql_init</literal> and before 
      <literal>mysql_connect</literal> or 
      <literal>mysql_real_connect</literal>.</para>
    <para>The option argument is the option that you want to set;
      the arg argument is the value for the option. 
      If the option is an integer, arg should point to the value of the integer.</para>
    <para>The following list describes the possible options, 
      their effect, and how arg is used for each option. 
      Several of the options apply only when the application is 
      linked against the libmysqld embedded server library and are 
      unused for applications linked against the libmysql client library. 
      For option descriptions that indicate arg is unused, 
      its value is irrelevant; it is conventional to pass 0.</para>
    <itemizedlist>
      <listitem>
	<para>MYSQL_INIT_COMMAND (argument type: string) SQL statement to execute 
	  when connecting to the MySQL server. 
	  Automatically re-executed if reconnection occurs.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_COMPRESS (argument: not used) Use the compressed client/server protocol.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_CONNECT_TIMEOUT (argument type: int) Connect timeout in seconds.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_GUESS_CONNECTION (argument: not used) For an 
	  application linked against the libmysqld embedded server
	  library, this allows the library to guess whether to use 
	  the embedded server or a remote server. 
	  "Guess" means that if the host name is set and is not localhost, 
	  it uses a remote server. This behavior is the default. 
	  MYSQL_OPT_USE_EMBEDDED_CONNECTION and 
	  MYSQL_OPT_USE_REMOTE_CONNECTION can be used to override it. 
	  This option is ignored for applications linked against
	  the libmysqlclient client library.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_LOCAL_INFILE (argument type: optional pointer to int) If no
	  pointer is given or if pointer points to an unsigned int that has a 
	  nonzero value, the LOAD LOCAL INFILE statement is enabled.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_NAMED_PIPE (argument: not used) Use named pipes 
	  to connect to a MySQL server on Windows, if the server 
	  allows named-pipe connections.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_PROTOCOL (argument type: int) Type of
	  protocol to use. Should be one of the enum values of 
	  mysql_protocol_type defined in mysql.h.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_READ_TIMEOUT (argument type: int) The timeout
	  in seconds for attempts to read from the server. Each attempt
	  uses this timeout value and there are retries if necessary,
	  so the total effective timeout value is three times the 
	  option value. You can set the value so that a lost 
	  connection can be detected earlier than the TCP/IP Close
	  _Wait_Timeout value of 10 minutes. This option works only
	  for TCP/IP connections and, prior to MySQL 5.1.12, only for Windows.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_RECONNECT (argument type: int - boolean) Enable 
	  or disable automatic reconnection to the server if the 
	  connection is found to have been lost. Reconnect is off 
	  by default; this option provides a way to set reconnection 
	  behavior explicitly.</para>
	<para>Note: <literal>mysql_real_connect</literal> incorrectly reset
	  the MYSQL_OPT_RECONNECT option to its default value before MySQL
	  5.1.6. Therefore, prior to that version, if you want reconnect
	  to be enabled for each connection, you must call 
	  <literal>mysql_options</literal> with the MYSQL_OPT_RECONNECT 
	  option after each call to <literal>mysql_real_connect</literal>.</para>
	<para>This is not necessary as of 5.1.6: 
	  Call <literal>mysql_options</literal> only before
	  <literal>mysql_real_connect</literal> as usual.</para>
      </listitem>
      <listitem>
	<para>MYSQL_SET_CLIENT_IP (argument type: string) For an 
	  application linked against the libmysqld embedded server 
	  library (when libmysqld is compiled with authentication 
	  support), this means that the user is considered to have 
	  connected from the specified IP address (specified as a 
	  string) for authentication purposes. This option is ignored
	  for applications linked against the libmysqlclient client library.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_SSL_VERIFY_SERVER_CERT (argument type: int - boolean) Enable
	  or disable verification of the server's Common Name value in its
	  certificate against the host name used when connecting to the 
	  server. The connection is rejected if there is a mismatch. 
	  This feature can be used to prevent man-in-the-middle attacks.
	  Verification is disabled by default. Added in MySQL
	  5.1.11.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_USE_EMBEDDED_CONNECTION (argument: not used) For an
	  application linked against the libmysqld embedded server 
	  library, this forces the use of the embedded server for the 
	  connection. This option is ignored for applications linked 
	  against the libmysqlclient client library.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_USE_REMOTE_CONNECTION (argument: not used) For an 
	  application linked against the libmysqld embedded server 
	  library, this forces the use of a remote server for the 
	  connection. This option is ignored for applications linked 
	  against the libmysqlclient client library.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_USE_RESULT (argument: not used) This option is
	  unused.</para>
      </listitem>
      <listitem>
	<para>MYSQL_OPT_WRITE_TIMEOUT (argument type: int) The 
	  timeout in seconds for attempts to write to the server. 
	  Each attempt uses this timeout value and there are 
	  net_retry_count retries if necessary, so the total 
	  effective timeout value is net_retry_count times the option 
	  value. This option works only for TCP/IP connections and, 
	  prior to MySQL 5.1.12, only for Windows.</para>
      </listitem>
      <listitem>
	<para>MYSQL_READ_DEFAULT_FILE (argument type: string) Read 
	  options from the named option file instead of from
	  my.cnf.</para>
      </listitem>
      <listitem>
	<para>MYSQL_READ_DEFAULT_GROUP (argument type: string) Read
	  options from the named group from my.cnf or the file 
	  specified with MYSQL_READ_DEFAULT_FILE.</para>
      </listitem>
      <listitem>
	<para>MYSQL_REPORT_DATA_TRUNCATION (argument type: int - boolean) Enable 
	  or disable reporting of data truncation errors for prepared 
	  statements via the error member of MYSQL_BIND structures. 
	  (Default: enabled.)</para>
      </listitem>
      <listitem>
	<para>MYSQL_SECURE_AUTH (argument type: int - boolean) Whether to 
	  connect to a server that does not support the password hashing
	  used in MySQL 4.1.1 and later.</para>
      </listitem>
      <listitem>
	<para>MYSQL_SET_CHARSET_DIR (argument type: string) The path name
	  to the directory that contains character set definition files.</para>
      </listitem>
      <listitem>
	<para>MYSQL_SET_CHARSET_NAME (argument type: string) The name 
	  of the character set to use as the default character
	  set.</para>
      </listitem>
      <listitem>
	<para>MYSQL_SHARED_MEMORY_BASE_NAME (argument type: string) The
	  name of the shared-memory object for communication to the 
	  server on Windows, if the server supports shared-memory 
	  connections. Should have the same value as the 
	  --shared-memory-base-name option used for the mysqld 
	  server you want to connect to.</para>
      </listitem>
    </itemizedlist>
    
    <para>The client group is always read if you use MYSQL_READ_DEFAULT_FILE or MYSQL_READ_DEFAULT_GROUP.</para>
    <para>The specified group in the option file may contain the following options.</para>
    
    <itemizedlist>
      <listitem>
	<para><literal>character-sets-dir=path</literal> The directory where character sets are installed.</para>
      </listitem>
      <listitem>
	<para><literal>compress</literal> Use the compressed client/server protocol.</para>
      </listitem>
      <listitem>
	<para><literal>connect-timeout=seconds</literal> Connect timeout in seconds. 
	  On Linux this timeout is also used for waiting for the first 
	  answer from the server.</para>
      </listitem>
      <listitem>
	<para><literal>database=db_name</literal> Connect to this database if
	  no database was specified in the connect command.</para>
      </listitem>
      <listitem>
	<para><literal>debug</literal> Debug options.</para>
      </listitem>
      <listitem>
	<para><literal>default-character-set=charset_name</literal> The default character set to use.</para>
      </listitem>
      <listitem>
	<para><literal>disable-local-infile</literal> Disable use of LOAD DATA LOCAL.</para>
      </listitem>
      <listitem>
	<para><literal>host=host_name</literal> Default host name.</para>
      </listitem>
      <listitem>
	<para><literal>init-command=stmt</literal> Statement to execute when connecting
	  to MySQL server. Automatically re-executed if reconnection occurs.</para>
      </listitem>
      <listitem>
	<para><literal>interactive-timeout=seconds</literal> Same as 
	  specifying CLIENT_INTERACTIVE to <literal>mysql_real_connect</literal>.</para>
      </listitem>
      <listitem>
	<para><literal>local-infile[={0|1}]</literal> If no argument 
	  or nonzero argument, enable use of LOAD DATA LOCAL; otherwise disable.</para>
      </listitem>
      <listitem>
	<para><literal>max_allowed_packet=bytes</literal> Maximum size of packet that client can read from server.</para>
      </listitem>
      <listitem>
	<para><literal>multi-queries, multi-results</literal> Allow
	  multiple result sets from multiple-statement executions or stored procedures.</para>
      </listitem>
      <listitem>
	<para><literal>multi-statements</literal> Allow the client to send 
	  multiple statements in a single string (separated by “;”).</para>
      </listitem>
      <listitem>
	<para><literal>password=password</literal> Default password.</para>
      </listitem>
      <listitem>
	<para><literal>pipe</literal> Use named pipes to connect to a MySQL server on Windows.</para>
      </listitem>
      <listitem>
	<para><literal>port=port_num</literal> Default port number.</para>
      </listitem>
      <listitem>
	<para><literal>protocol={TCP|SOCKET|PIPE|MEMORY}</literal>
	  The protocol to use when connecting to the server.</para>
      </listitem>
      <listitem>
	<para><literal>return-found-rows</literal> Tell <literal>mysql_info</literal>
	  to return found rows instead of updated rows when using UPDATE.</para>
      </listitem>
      <listitem>
	<para><literal>shared-memory-base-name=name</literal> Shared-memory name to use to connect to server.</para>
      </listitem>
      <listitem>
	<para><literal>socket=path</literal> Default socket file.</para>
      </listitem>
      <listitem>
	<para><literal>ssl-ca=file_name</literal> Certificate Authority file.</para>
      </listitem>
      <listitem>
	<para><literal>ssl-capath=path</literal> Certificate Authority directory.</para>
      </listitem>
      <listitem>
	<para><literal>ssl-cert=file_name</literal> Certificate file.</para>
      </listitem>
      <listitem>
	<para><literal>ssl-cipher=cipher_list</literal> Allowable SSL ciphers.</para>
      </listitem>
      <listitem>
	<para><literal>ssl-key=file_name</literal> Key file.</para>
      </listitem>
      <listitem>
	<para><literal>timeout=seconds</literal> Like connect-timeout.</para>
      </listitem>
      <listitem>
	<para><literal>user</literal> Default user.</para>
      </listitem>
    </itemizedlist>
    <para><literal>timeout</literal> has been replaced by 
      <literal>connect-timeout</literal>, but <literal>timeout</literal>
      is still supported in MySQL 5.1 for backward compatibility.</para>
  </refsection>

  <refsection>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>mysql</term>

        <listitem>
          <para>a MySQL pointer</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>option</term>

        <listitem>
          <para>an integer which allows to select the option(YC: put
          the option number list)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>args</term>

        <listitem>
          <para>an optional argument which type depends
	  on the option selected (see above).</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Examples</title>

    <programlisting role="example"><![CDATA[ 
username = 'glpk'; // Put your username
password = 'gnu';  // Put your password
database = 'glpk'; 
port     = 3306;   // use netstat -a | grep mysql to locate the mysql port
                   // or ps -elf | grep mysql and locate --port
myhost   = 'localhost'; // localhost most of the time

sql_ptr = mysql_init();

mysql_options(sql_ptr,MYSQL_OPT_COMPRESS, 0);
mysql_options(sql_ptr,MYSQL_READ_DEFAULT_GROUP,"odbc");
mysql_options(sql_ptr,MYSQL_INIT_COMMAND,"SET autocommit=0");

status  = mysql_real_connect(sql_ptr, myhost, username, password, database, port);

mysql_close(sql_ptr);
 ]]></programlisting>
  </refsection>

  <refsection>
    <title>See Also</title>

    <simplelist type="inline">
      <member><link linkend="mysql_init">mysql_init</link></member>
      <member><link linkend="mysql_real_connect">mysql_real_connect</link></member>
      <member><link linkend="mysql_close">mysql_close</link></member>
    </simplelist>
  </refsection>

  <refsection>
    <title>Authors</title>

    <simplelist type="vert">
      <member>Yann COLLETTE</member>
    </simplelist>
  </refsection>
</refentry>