FLocal/ThirdParty/mysql-connector-net-6.2.3/MySql.Data/Provider/Source/docs/MySqlDataReader.xml

<docs>
  <ClassSummary>
    <summary>
      Provides a means of reading a forward-only stream of rows from a MySQL database. This class cannot be inherited.
    </summary>
    <remarks>
      <para>
        To create a <B>MySQLDataReader</B>, you must call the <see cref="MySqlCommand.ExecuteReader()"/>
        method of the <see cref="MySqlCommand"/> object, rather than directly using a constructor.
      </para>
      <para>
        While the <B>MySqlDataReader</B> is in use, the associated <see cref="MySqlConnection"/>
        is busy serving the <B>MySqlDataReader</B>, and no other operations can be performed
        on the <B>MySqlConnection</B> other than closing it. This is the case until the
        <see cref="MySqlDataReader.Close"/> method of the <B>MySqlDataReader</B> is called.
      </para>
      <para>
        <see cref="MySqlDataReader.IsClosed"/> and <see cref="MySqlDataReader.RecordsAffected"/>
        are the only properties that you can call after the <B>MySqlDataReader</B> is
        closed. Though the <B>RecordsAffected</B> property may be accessed at any time
        while the <B>MySqlDataReader</B> exists, always call <B>Close</B> before returning
        the value of <B>RecordsAffected</B> to ensure an accurate return value.
      </para>
      <para>
        For optimal performance, <B>MySqlDataReader</B> avoids creating
        unnecessary objects or making unnecessary copies of data. As a result, multiple calls
        to methods such as <see cref="MySqlDataReader.GetValue"/> return a reference to the
        same object. Use caution if you are modifying the underlying value of the objects
        returned by methods such as <B>GetValue</B>.
      </para>
    </remarks>

    <example>
      The following example creates a <see cref="MySqlConnection"/>,
      a <see cref="MySqlCommand"/>, and a <B>MySqlDataReader</B>. The example reads through
      the data, writing it out to the console. Finally, the example closes the <B>MySqlDataReader</B>, then the
      <B>MySqlConnection</B>.
      <code lang="vbnet">
        Public Sub ReadMyData(myConnString As String)
        Dim mySelectQuery As String = "SELECT OrderID, CustomerID FROM Orders"
        Dim myConnection As New MySqlConnection(myConnString)
        Dim myCommand As New MySqlCommand(mySelectQuery, myConnection)
        myConnection.Open()
        Dim myReader As MySqlDataReader
        myReader = myCommand.ExecuteReader()
        ' Always call Read before accessing data.
        While myReader.Read()
        Console.WriteLine((myReader.GetInt32(0) &amp; ", " &amp; myReader.GetString(1)))
        End While
        ' always call Close when done reading.
        myReader.Close()
        ' Close the connection when done with it.
        myConnection.Close()
        End Sub 'ReadMyData
      </code>
      <code lang="C#">
        public void ReadMyData(string myConnString) {
        string mySelectQuery = "SELECT OrderID, CustomerID FROM Orders";
        MySqlConnection myConnection = new MySqlConnection(myConnString);
        MySqlCommand myCommand = new MySqlCommand(mySelectQuery,myConnection);
        myConnection.Open();
        MySqlDataReader myReader;
        myReader = myCommand.ExecuteReader();
        // Always call Read before accessing data.
        while (myReader.Read()) {
        Console.WriteLine(myReader.GetInt32(0) + ", " + myReader.GetString(1));
        }
        // always call Close when done reading.
        myReader.Close();
        // Close the connection when done with it.
        myConnection.Close();
        }
      </code>
    </example>
  </ClassSummary>

  <GetBytes>
    <remarks>
      <para>
        <B>GetBytes</B> returns the number of available bytes in the field. In most
        cases this is the exact length of the field. However, the number returned may be
        less than the true length of the field if <B>GetBytes</B> has already been used
        to obtain bytes from the field. This may be the case, for example, if the
        <see cref="MySqlDataReader"/> is reading a large data structure into a buffer.
        For more information, see the <B>SequentialAccess</B> setting for
        <see cref="MySqlCommand.CommandBehavior"/>.
      </para>
      <para>
        If you pass a buffer that is a null reference (<B>Nothing</B> in Visual
        Basic), <B>GetBytes</B> returns the length of the field in bytes.
      </para>
      <para>
        No conversions are performed; therefore the data retrieved must already be a
        byte array.
      </para>
    </remarks>
  </GetBytes>

  <GetTimeSpan>
    <overloads/>
    <summary>
      Gets the value of the specified column as a <see cref="TimeSpan"/> object.
    </summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>Time</b> value.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The zero-based column ordinal or column name.</param>
    <returns>The value of the specified column.</returns>
  </GetTimeSpan>

  <GetDateTime>
    <summary>
      Gets the value of the specified column as a <see cref="DateTime"/> object.
    </summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>DateTime</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
      <note>
        <para>
          MySql allows date columns to contain the value '0000-00-00' and datetime
          columns to contain the value '0000-00-00 00:00:00'.  The DateTime structure cannot contain
          or represent these values.  To read a datetime value from a column that might
          contain zero values, use <see cref="GetMySqlDateTime(int)"/>.
        </para>
        <para>
          The behavior of reading a zero datetime column using this method is defined by the
          <i>ZeroDateTimeBehavior</i> connection string option.  For more information on this option,
          please refer to <see cref="MySqlConnection.ConnectionString"/>.
        </para>
      </note>
    </remarks>
    <param name="i">The zero-based column ordinal.</param>
    <returns>The value of the specified column.</returns>
  </GetDateTime>

  <GetDateTimeS>
    <summary>
      Gets the value of the specified column as a <see cref="DateTime"/> object.
    </summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>DateTime</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
      <note>
        <para>
          MySql allows date columns to contain the value '0000-00-00' and datetime
          columns to contain the value '0000-00-00 00:00:00'.  The DateTime structure cannot contain
          or represent these values.  To read a datetime value from a column that might
          contain zero values, use <see cref="GetMySqlDateTime(int)"/>.
        </para>
        <para>
          The behavior of reading a zero datetime column using this method is defined by the
          <i>ZeroDateTimeBehavior</i> connection string option.  For more information on this option,
          please refer to <see cref="MySqlConnection.ConnectionString"/>.
        </para>
      </note>
    </remarks>
    <param name="column">The column name.</param>
    <returns>The value of the specified column.</returns>
  </GetDateTimeS>

  <GetMySqlDateTime>
    <summary>
      Gets the value of the specified column as a <see cref="MySql.Data.Types.MySqlDateTime"/> object.
    </summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>DateTime</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The zero-based column ordinal or column name.</param>
    <returns>The value of the specified column.</returns>
  </GetMySqlDateTime>

  <GetString>
    <summary>
      Gets the value of the specified column as a <see cref="String"/> object.
    </summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>String</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="i">The zero-based column ordinal.</param>
    <returns>The value of the specified column.</returns>
  </GetString>

  <GetStringS>
    <summary>
      Gets the value of the specified column as a <see cref="String"/> object.
    </summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>String</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The column name.</param>
    <returns>The value of the specified column.</returns>
  </GetStringS>

  <GetDecimal>
    <summary>
      Gets the value of the specified column as a <see cref="Decimal"/> object.
    </summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>Decimal</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="i">The zero-based column ordinal</param>
    <returns>The value of the specified column.</returns>
  </GetDecimal>

  <GetDecimalS>
    <summary>
      Gets the value of the specified column as a <see cref="Decimal"/> object.
    </summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>Decimal</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The column name</param>
    <returns>The value of the specified column.</returns>
  </GetDecimalS>

  <GetDouble>
    <summary>Gets the value of the specified column as a double-precision floating point number.</summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>Double</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="i">The zero-based column ordinal.</param>
    <returns>The value of the specified column.</returns>
  </GetDouble>

  <GetDoubleS>
    <summary>Gets the value of the specified column as a double-precision floating point number.</summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>Double</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The column name</param>
    <returns>The value of the specified column.</returns>
  </GetDoubleS>
  
  <GetFloat>
    <summary>
      Gets the value of the specified column as a single-precision floating point number.
    </summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>Float</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="i">The zero-based column ordinal.</param>
    <returns>The value of the specified column.</returns>
  </GetFloat>

  <GetFloatS>
    <summary>
      Gets the value of the specified column as a single-precision floating point number.
    </summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>Float</b> object.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The column name</param>
    <returns>The value of the specified column.</returns>
  </GetFloatS>

  <GetGiud>
    <summary>Gets the value of the specified column as a globally-unique identifier (GUID).</summary>
    <param name="i">The zero-based column ordinal.</param>
    <returns>The value of the specified column.</returns>
  </GetGiud>

  <GetGiudS>
    <summary>Gets the value of the specified column as a globally-unique identifier (GUID).</summary>
    <param name="column">The column name</param>
    <returns>The value of the specified column.</returns>
  </GetGiudS>

  <GetInt16>
    <summary>Gets the value of the specified column as a 16-bit signed integer.</summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>16 bit integer</b> value.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="i">The zero-based column ordinal.</param>
    <returns>The value of the specified column.</returns>
  </GetInt16>

  <GetInt16S>
    <summary>Gets the value of the specified column as a 16-bit signed integer.</summary>
    <remarks>
      <para>
        No conversions are performed; threfore, the data retrieved must already be a <b>16 bit integer</b> value.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The column name</param>
    <returns>The value of the specified column.</returns>
  </GetInt16S>

  <GetInt32>
    <summary>Gets the value of the specified column as a 32-bit signed integer.</summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>32 bit integer</b> value.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="i">The zero-based column ordinal.</param>
    <returns>The value of the specified column.</returns>
  </GetInt32>

  <GetInt32S>
    <summary>Gets the value of the specified column as a 32-bit signed integer.</summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>32 bit integer</b> value.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The column name.</param>
    <returns>The value of the specified column.</returns>
  </GetInt32S>

  <GetInt64>
    <summary>Gets the value of the specified column as a 64-bit signed integer.</summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>64 bit integer</b> value.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="i">The zero-based column ordinal.</param>
    <returns>The value of the specified column.</returns>
  </GetInt64>

  <GetInt64S>
    <summary>Gets the value of the specified column as a 64-bit signed integer.</summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>64 bit integer</b> value.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The column name.</param>
    <returns>The value of the specified column.</returns>
  </GetInt64S>

  <GetUInt16>
    <summary>Gets the value of the specified column as a 16-bit unsigned integer.</summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>16 bit unsigned integer</b> value.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The zero-based column ordinal or column name.</param>
    <returns>The value of the specified column.</returns>
  </GetUInt16>

  <GetUInt32>
    <summary>Gets the value of the specified column as a 32-bit unsigned integer.</summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>32 bit unsigned integer</b> value.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The zero-based column ordinal or column name.</param>
    <returns>The value of the specified column.</returns>
  </GetUInt32>

  <GetUInt64>
    <summary>Gets the value of the specified column as a 64-bit unsigned integer.</summary>
    <remarks>
      <para>
        No conversions are performed; therefore, the data retrieved must already be a <b>64 bit unsigned integer</b> value.
      </para>
      <para>
        Call IsDBNull to check for null values before calling this method.
      </para>
    </remarks>
    <param name="column">The zero-based column ordinal or column name.</param>
    <returns>The value of the specified column.</returns>
  </GetUInt64>

</docs>