mcs/class/System.Data/Documentation/en/System.Data/IDbCommand.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <Type Name="IDbCommand" FullName="System.Data.IDbCommand">
   3   <TypeSignature Language="C#" Maintainer="auto" Value="public interface IDbCommand : IDisposable" />
   4   <AssemblyInfo>
   5     <AssemblyName>System.Data</AssemblyName>
   6     <AssemblyPublicKey>[00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00]</AssemblyPublicKey>
   7     <AssemblyVersion>1.0.3300.0</AssemblyVersion>
   8     <AssemblyVersion>1.0.5000.0</AssemblyVersion>
   9     <AssemblyVersion>2.0.0.0</AssemblyVersion>
  10   </AssemblyInfo>
  11   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the &lt;link location="node:gtk-sharp/programming/threads"&gt;Gtk# Thread Programming&lt;/link&gt; for details.</ThreadSafetyStatement>
  12   <Interfaces>
  13     <Interface>
  14       <InterfaceName>System.IDisposable</InterfaceName>
  15     </Interface>
  16   </Interfaces>
  17   <Docs>
  18     <remarks>
  19       <attribution license="cc4" from="Microsoft" modified="false" />
  20       <para>The <see cref="T:System.Data.IDbCommand" /> interface enables an inheriting class to implement a Command class, which represents an SQL statement that is executed at a data source. For more information about Command classes, see <format type="text/html"><a href="40494916-C25A-4CB8-8F7C-FCB8D378464E">[&lt;topic://cpconadonetcommands&gt;]</a></format>. </para>
  21       <para>An application does not create an instance of the <see cref="T:System.Data.IDbCommand" /> interface directly, but creates an instance of a class that inherits <see cref="T:System.Data.IDbCommand" />.</para>
  22       <para>Classes that inherit <see cref="T:System.Data.IDbCommand" /> must implement all inherited members, and typically define additional members to add provider-specific functionality. For example, the <see cref="T:System.Data.IDbCommand" /> interface defines the <see cref="M:System.Data.IDbCommand.ExecuteNonQuery" /> method. In turn, the <see cref="T:System.Data.SqlClient.SqlCommand" /> class inherits this method, and also defines the <see cref="M:System.Data.SqlClient.SqlCommand.ExecuteXmlReader" /> method.</para>
  23     </remarks>
  24     <summary>
  25       <attribution license="cc4" from="Microsoft" modified="false" />
  26       <para>Represents an SQL statement that is executed while connected to a data source, and is implemented by .NET Framework data providers that access relational databases.</para>
  27     </summary>
  28   </Docs>
  29   <Members>
  30     <Member MemberName="Cancel">
  31       <MemberSignature Language="C#" Value="public void Cancel ();" />
  32       <MemberType>Method</MemberType>
  33       <ReturnValue>
  34         <ReturnType>System.Void</ReturnType>
  35       </ReturnValue>
  36       <Parameters />
  37       <Docs>
  38         <remarks>
  39           <attribution license="cc4" from="Microsoft" modified="false" />
  40           <para>If there is nothing to cancel, nothing happens. However, if there is a command in process, and the attempt to cancel fails, no exception is generated.</para>
  41         </remarks>
  42         <summary>
  43           <attribution license="cc4" from="Microsoft" modified="false" />
  44           <para>Attempts to cancels the execution of an <see cref="T:System.Data.IDbCommand" />.</para>
  45         </summary>
  46       </Docs>
  47       <AssemblyInfo>
  48         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
  49         <AssemblyVersion>2.0.0.0</AssemblyVersion>
  50       </AssemblyInfo>
  51     </Member>
  52     <Member MemberName="CommandText">
  53       <MemberSignature Language="C#" Value="public string CommandText { set; get; }" />
  54       <MemberType>Property</MemberType>
  55       <ReturnValue>
  56         <ReturnType>System.String</ReturnType>
  57       </ReturnValue>
  58       <Parameters>
  59       </Parameters>
  60       <Docs>
  61         <value>To be added: an object of type 'string'</value>
  62         <remarks>
  63           <attribution license="cc4" from="Microsoft" modified="false" />
  64           <para>When the <see cref="P:System.Data.IDbCommand.CommandType" /> property is set to StoredProcedure, set the <see cref="P:System.Data.IDbCommand.CommandText" /> property to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command will call this stored procedure when you call one of the Execute methods.</para>
  65         </remarks>
  66         <summary>
  67           <attribution license="cc4" from="Microsoft" modified="false" />
  68           <para>Gets or sets the text command to run against the data source.</para>
  69         </summary>
  70       </Docs>
  71       <AssemblyInfo>
  72         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
  73         <AssemblyVersion>2.0.0.0</AssemblyVersion>
  74       </AssemblyInfo>
  75     </Member>
  76     <Member MemberName="CommandTimeout">
  77       <MemberSignature Language="C#" Value="public int CommandTimeout { set; get; }" />
  78       <MemberType>Property</MemberType>
  79       <ReturnValue>
  80         <ReturnType>System.Int32</ReturnType>
  81       </ReturnValue>
  82       <Parameters>
  83       </Parameters>
  84       <Docs>
  85         <value>To be added: an object of type 'int'</value>
  86         <remarks>To be added</remarks>
  87         <summary>
  88           <attribution license="cc4" from="Microsoft" modified="false" />
  89           <para>Gets or sets the wait time before terminating the attempt to execute a command and generating an error.</para>
  90         </summary>
  91       </Docs>
  92       <AssemblyInfo>
  93         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
  94         <AssemblyVersion>2.0.0.0</AssemblyVersion>
  95       </AssemblyInfo>
  96     </Member>
  97     <Member MemberName="CommandType">
  98       <MemberSignature Language="C#" Value="public System.Data.CommandType CommandType { set; get; }" />
  99       <MemberType>Property</MemberType>
 100       <ReturnValue>
 101         <ReturnType>System.Data.CommandType</ReturnType>
 102       </ReturnValue>
 103       <Parameters>
 104       </Parameters>
 105       <Docs>
 106         <value>To be added: an object of type 'CommandType'</value>
 107         <remarks>
 108           <attribution license="cc4" from="Microsoft" modified="false" />
 109           <para>When you set the <see cref="P:System.Data.IDbCommand.CommandType" /> property to StoredProcedure, you should set the <see cref="P:System.Data.IDbCommand.CommandText" /> property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods.</para>
 110         </remarks>
 111         <summary>
 112           <attribution license="cc4" from="Microsoft" modified="false" />
 113           <para>Indicates or specifies how the <see cref="P:System.Data.IDbCommand.CommandText" /> property is interpreted.</para>
 114         </summary>
 115       </Docs>
 116       <AssemblyInfo>
 117         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 118         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 119       </AssemblyInfo>
 120     </Member>
 121     <Member MemberName="Connection">
 122       <MemberSignature Language="C#" Value="public System.Data.IDbConnection Connection { set; get; }" />
 123       <MemberType>Property</MemberType>
 124       <ReturnValue>
 125         <ReturnType>System.Data.IDbConnection</ReturnType>
 126       </ReturnValue>
 127       <Parameters>
 128       </Parameters>
 129       <Docs>
 130         <value>To be added: an object of type 'IDbConnection'</value>
 131         <remarks>To be added</remarks>
 132         <summary>
 133           <attribution license="cc4" from="Microsoft" modified="false" />
 134           <para>Gets or sets the <see cref="T:System.Data.IDbConnection" /> used by this instance of the <see cref="T:System.Data.IDbCommand" />.</para>
 135         </summary>
 136       </Docs>
 137       <AssemblyInfo>
 138         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 139         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 140       </AssemblyInfo>
 141     </Member>
 142     <Member MemberName="CreateParameter">
 143       <MemberSignature Language="C#" Value="public System.Data.IDbDataParameter CreateParameter ();" />
 144       <MemberType>Method</MemberType>
 145       <ReturnValue>
 146         <ReturnType>System.Data.IDbDataParameter</ReturnType>
 147       </ReturnValue>
 148       <Parameters />
 149       <Docs>
 150         <remarks>
 151           <attribution license="cc4" from="Microsoft" modified="false" />
 152           <para>When inheriting from <see cref="T:System.Data.IDbCommand" />, a .NET Framework data provider implements a strongly-typed version of <see cref="M:System.Data.IDbCommand.CreateParameter" />.</para>
 153         </remarks>
 154         <summary>
 155           <attribution license="cc4" from="Microsoft" modified="false" />
 156           <para>Creates a new instance of an <see cref="T:System.Data.IDbDataParameter" /> object.</para>
 157         </summary>
 158         <returns>
 159           <attribution license="cc4" from="Microsoft" modified="false" />
 160           <para>An IDbDataParameter object.</para>
 161         </returns>
 162       </Docs>
 163       <AssemblyInfo>
 164         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 165         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 166       </AssemblyInfo>
 167     </Member>
 168     <Member MemberName="ExecuteNonQuery">
 169       <MemberSignature Language="C#" Value="public int ExecuteNonQuery ();" />
 170       <MemberType>Method</MemberType>
 171       <ReturnValue>
 172         <ReturnType>System.Int32</ReturnType>
 173       </ReturnValue>
 174       <Parameters />
 175       <Docs>
 176         <remarks>
 177           <attribution license="cc4" from="Microsoft" modified="false" />
 178           <para>You can use the <see cref="M:System.Data.IDbCommand.ExecuteNonQuery" /> to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database without using a <see cref="T:System.Data.DataSet" /> by executing UPDATE, INSERT, or DELETE statements.</para>
 179           <para>Although the <see cref="M:System.Data.IDbCommand.ExecuteNonQuery" /> does not return any rows, any output parameters or return values mapped to parameters are populated with data.</para>
 180           <para>For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1.</para>
 181         </remarks>
 182         <summary>
 183           <attribution license="cc4" from="Microsoft" modified="false" />
 184           <para>Executes an SQL statement against the Connection object of a .NET Framework data provider, and returns the number of rows affected.</para>
 185         </summary>
 186         <returns>
 187           <attribution license="cc4" from="Microsoft" modified="false" />
 188           <para>The number of rows affected.</para>
 189         </returns>
 190       </Docs>
 191       <AssemblyInfo>
 192         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 193         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 194       </AssemblyInfo>
 195     </Member>
 196     <Member MemberName="ExecuteReader">
 197       <MemberSignature Language="C#" Value="public System.Data.IDataReader ExecuteReader ();" />
 198       <MemberType>Method</MemberType>
 199       <ReturnValue>
 200         <ReturnType>System.Data.IDataReader</ReturnType>
 201       </ReturnValue>
 202       <Parameters />
 203       <Docs>
 204         <remarks>To be added</remarks>
 205         <summary>
 206           <attribution license="cc4" from="Microsoft" modified="false" />
 207           <para>Executes the <see cref="P:System.Data.IDbCommand.CommandText" /> against the <see cref="P:System.Data.IDbCommand.Connection" /> and builds an <see cref="T:System.Data.IDataReader" />.</para>
 208         </summary>
 209         <returns>
 210           <attribution license="cc4" from="Microsoft" modified="false" />
 211           <para>An <see cref="T:System.Data.IDataReader" /> object.</para>
 212         </returns>
 213       </Docs>
 214       <AssemblyInfo>
 215         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 216         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 217       </AssemblyInfo>
 218     </Member>
 219     <Member MemberName="ExecuteReader">
 220       <MemberSignature Language="C#" Value="public System.Data.IDataReader ExecuteReader (System.Data.CommandBehavior behavior);" />
 221       <MemberType>Method</MemberType>
 222       <ReturnValue>
 223         <ReturnType>System.Data.IDataReader</ReturnType>
 224       </ReturnValue>
 225       <Parameters>
 226         <Parameter Name="behavior" Type="System.Data.CommandBehavior" />
 227       </Parameters>
 228       <Docs>
 229         <remarks>
 230           <attribution license="cc4" from="Microsoft" modified="false" />
 231           <para>The caller must call the <see cref="M:System.Data.IDbConnection.Open" /> method of the <see cref="P:System.Data.IDbCommand.Connection" /> property.</para>
 232           <para>When the <see cref="P:System.Data.IDbCommand.CommandType" /> property is set to StoredProcedure, the <see cref="P:System.Data.IDbCommand.CommandText" /> property should be set to the name of the stored procedure. The command executes this stored procedure when you call <see cref="M:System.Data.IDbCommand.ExecuteReader" />.</para>
 233           <block subset="none" type="note">
 234             <para>Use <see cref="F:System.Data.CommandBehavior.SequentialAccess" /> to retrieve large values and binary data. Otherwise, an <see cref="T:System.OutOfMemoryException" /> might occur and the connection will be closed.</para>
 235           </block>
 236           <para>While the <see cref="T:System.Data.IDataReader" /> is in use, the associated <see cref="T:System.Data.IDbConnection" /> is busy serving the <see cref="T:System.Data.IDataReader" />. While in this state, no other operations can be performed on the <see cref="T:System.Data.IDbConnection" /> other than closing it. This is the case until the <see cref="M:System.Data.IDataReader.Close" /> method of the DataReader is called. If the DataReader is created with <see cref="T:System.Data.CommandBehavior" /> set to CloseConnection, closing the DataReader closes the connection automatically.</para>
 237         </remarks>
 238         <summary>
 239           <attribution license="cc4" from="Microsoft" modified="false" />
 240           <para>Executes the <see cref="P:System.Data.IDbCommand.CommandText" /> against the <see cref="P:System.Data.IDbCommand.Connection" />, and builds an <see cref="T:System.Data.IDataReader" /> using one of the <see cref="T:System.Data.CommandBehavior" /> values.</para>
 241         </summary>
 242         <returns>
 243           <attribution license="cc4" from="Microsoft" modified="false" />
 244           <para>An <see cref="T:System.Data.IDataReader" /> object.</para>
 245         </returns>
 246         <param name="behavior">
 247           <attribution license="cc4" from="Microsoft" modified="false" />One of the <see cref="T:System.Data.CommandBehavior" /> values. </param>
 248       </Docs>
 249       <AssemblyInfo>
 250         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 251         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 252       </AssemblyInfo>
 253     </Member>
 254     <Member MemberName="ExecuteScalar">
 255       <MemberSignature Language="C#" Value="public object ExecuteScalar ();" />
 256       <MemberType>Method</MemberType>
 257       <ReturnValue>
 258         <ReturnType>System.Object</ReturnType>
 259       </ReturnValue>
 260       <Parameters />
 261       <Docs>
 262         <remarks>
 263           <attribution license="cc4" from="Microsoft" modified="false" />
 264           <para>Use the <see cref="M:System.Data.IDbCommand.ExecuteScalar" /> method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the <see cref="M:System.Data.IDbCommand.ExecuteReader" /> method, and then performing the operations necessary to generate the single value using the data returned by an <see cref="T:System.Data.IDataReader" />.</para>
 265           <para>A typical <see cref="M:System.Data.IDbCommand.ExecuteScalar" /> query can be formatted as in the following C# example: </para>
 266           <code> CommandText = "select count(*) as NumberOfRegions from region";
 267  Int32 count = (int) ExecuteScalar();</code>
 268           <para>If the first column of the first row in the result set is not found, a null reference (Nothing in Visual Basic) is returned. If the value in the database is null, the query returns DBNull.Value.</para>
 269         </remarks>
 270         <summary>
 271           <attribution license="cc4" from="Microsoft" modified="false" />
 272           <para>Executes the query, and returns the first column of the first row in the resultset returned by the query. Extra columns or rows are ignored.</para>
 273         </summary>
 274         <returns>
 275           <attribution license="cc4" from="Microsoft" modified="false" />
 276           <para>The first column of the first row in the resultset.</para>
 277         </returns>
 278       </Docs>
 279       <AssemblyInfo>
 280         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 281         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 282       </AssemblyInfo>
 283     </Member>
 284     <Member MemberName="Parameters">
 285       <MemberSignature Language="C#" Value="public System.Data.IDataParameterCollection Parameters { get; }" />
 286       <MemberType>Property</MemberType>
 287       <ReturnValue>
 288         <ReturnType>System.Data.IDataParameterCollection</ReturnType>
 289       </ReturnValue>
 290       <Docs>
 291         <value>To be added: an object of type 'IDataParameterCollection'</value>
 292         <remarks>To be added</remarks>
 293         <summary>
 294           <attribution license="cc4" from="Microsoft" modified="false" />
 295           <para>Gets the <see cref="T:System.Data.IDataParameterCollection" />.</para>
 296         </summary>
 297       </Docs>
 298       <AssemblyInfo>
 299         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 300         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 301       </AssemblyInfo>
 302     </Member>
 303     <Member MemberName="Prepare">
 304       <MemberSignature Language="C#" Value="public void Prepare ();" />
 305       <MemberType>Method</MemberType>
 306       <ReturnValue>
 307         <ReturnType>System.Void</ReturnType>
 308       </ReturnValue>
 309       <Parameters />
 310       <Docs>
 311         <remarks>
 312           <attribution license="cc4" from="Microsoft" modified="false" />
 313           <para>If the <see cref="P:System.Data.IDbCommand.CommandType" /> property is set to TableDirect, <see cref="M:System.Data.IDbCommand.Prepare" /> does nothing. If <see cref="P:System.Data.IDbCommand.CommandType" /> is set to StoredProcedure, the call to <see cref="M:System.Data.IDbCommand.Prepare" /> should succeed, although it may result in a no-op. The server automatically caches plans for reuse as necessary; therefore, there is no need to call this method directly in your client application.</para>
 314         </remarks>
 315         <summary>
 316           <attribution license="cc4" from="Microsoft" modified="false" />
 317           <para>Creates a prepared (or compiled) version of the command on the data source.</para>
 318         </summary>
 319       </Docs>
 320       <AssemblyInfo>
 321         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 322         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 323       </AssemblyInfo>
 324     </Member>
 325     <Member MemberName="Transaction">
 326       <MemberSignature Language="C#" Value="public System.Data.IDbTransaction Transaction { set; get; }" />
 327       <MemberType>Property</MemberType>
 328       <ReturnValue>
 329         <ReturnType>System.Data.IDbTransaction</ReturnType>
 330       </ReturnValue>
 331       <Parameters>
 332       </Parameters>
 333       <Docs>
 334         <value>To be added: an object of type 'IDbTransaction'</value>
 335         <remarks>To be added</remarks>
 336         <summary>
 337           <attribution license="cc4" from="Microsoft" modified="false" />
 338           <para>Gets or sets the transaction within which the Command object of a .NET Framework data provider executes.</para>
 339         </summary>
 340       </Docs>
 341       <AssemblyInfo>
 342         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 343         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 344       </AssemblyInfo>
 345     </Member>
 346     <Member MemberName="UpdatedRowSource">
 347       <MemberSignature Language="C#" Value="public System.Data.UpdateRowSource UpdatedRowSource { set; get; }" />
 348       <MemberType>Property</MemberType>
 349       <ReturnValue>
 350         <ReturnType>System.Data.UpdateRowSource</ReturnType>
 351       </ReturnValue>
 352       <Parameters>
 353       </Parameters>
 354       <Docs>
 355         <value>To be added: an object of type 'UpdateRowSource'</value>
 356         <remarks>To be added</remarks>
 357         <summary>
 358           <attribution license="cc4" from="Microsoft" modified="false" />
 359           <para>Gets or sets how command results are applied to the <see cref="T:System.Data.DataRow" /> when used by the <see cref="M:System.Data.IDataAdapter.Update(System.Data.DataSet)" /> method of a <see cref="T:System.Data.Common.DbDataAdapter" />.</para>
 360         </summary>
 361       </Docs>
 362       <AssemblyInfo>
 363         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 364         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 365       </AssemblyInfo>
 366     </Member>
 367   </Members>
 368 </Type>