The next generation of the Teknik Services. Written in ASP.NET. https://www.teknik.io/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

MySqlCommand.xml 33KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934
  1. <docs>
  2. <ClassSummary>
  3. <summary>Represents a SQL statement to execute against a MySQL database. This class cannot be inherited.</summary>
  4. <remarks>
  5. <B>MySqlCommand</B> features the following methods for executing commands at a MySQL database:
  6. <list type="table">
  7. <listheader>
  8. <term>Item</term>
  9. <term>Description</term>
  10. </listheader>
  11. <item>
  12. <term>
  13. <a href="MySql.Data.MySqlClient.MySqlCommand.ExecuteReader_overloads.html">ExecuteReader</a>
  14. </term>
  15. <description>Executes commands that return rows.</description>
  16. </item>
  17. <item>
  18. <term>
  19. <a href="MySql.Data.MySqlClient.MySqlCommand.ExecuteNonQuery.html">ExecuteNonQuery</a>
  20. </term>
  21. <description>Executes commands such as SQL INSERT, DELETE, and UPDATE statements.</description>
  22. </item>
  23. <item>
  24. <term>
  25. <a href="MySql.Data.MySqlClient.MySqlCommand.ExecuteScalar.html">ExecuteScalar</a>
  26. </term>
  27. <description>Retrieves a single value (for example, an aggregate value) from a database.</description>
  28. </item>
  29. </list>
  30. You can reset the <B>CommandText</B> property and reuse the <B>MySqlCommand</B>
  31. object. However, you must close the <A
  32. href="MySql.Data.MySqlClient.MySqlDataReader.html">MySqlDataReader</A>
  33. before you can execute a new or previous command.
  34. If a <A href="MySql.Data.MySqlClient.MySqlException.html">MySqlException</A> is
  35. generated by the method executing a <B>MySqlCommand</B>, the <A
  36. href="MySql.Data.MySqlClient.MySqlConnection.html">MySqlConnection</A>
  37. remains open. It is the responsibility of the programmer to close the connection.
  38. <note>
  39. Using the '@' symbol for paramters is now the preferred approach although the old pattern of using
  40. '?' is still supported. Please be aware though that using '@' can cause conflicts when user variables
  41. are also used. To help with this situation please see the documentation on the 'allow user variables'
  42. connection string option. The 'old syntax' connection string option has now been deprecated.
  43. </note>
  44. </remarks>
  45. <example>
  46. The following example creates a <A href="frlrfsystemdatasqlclientsqlcommandclasstopic.htm">MySqlCommand</A> and
  47. a <B>MySqlConnection</B>. The <B>MySqlConnection</B> is opened and set as the <A
  48. href="frlrfsystemdatasqlclientsqlcommandclassconnectiontopic.htm">Connection</A>
  49. for the <B>MySqlCommand</B>. The example then calls <A
  50. href="frlrfsystemdatasqlclientsqlcommandclassexecutenonquerytopic.htm">ExecuteNonQuery</A>,
  51. and closes the connection. To accomplish this, the <B>ExecuteNonQuery</B> is
  52. passed a connection string and a query string that is a SQL INSERT
  53. statement.
  54. <code lang="vbnet">
  55. Public Sub InsertRow(myConnectionString As String)
  56. &quot; If the connection string is null, use a default.
  57. If myConnectionString = "" Then
  58. myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass"
  59. End If
  60. Dim myConnection As New MySqlConnection(myConnectionString)
  61. Dim myInsertQuery As String = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)"
  62. Dim myCommand As New MySqlCommand(myInsertQuery)
  63. myCommand.Connection = myConnection
  64. myConnection.Open()
  65. myCommand.ExecuteNonQuery()
  66. myCommand.Connection.Close()
  67. End Sub
  68. </code>
  69. <code lang="C#">
  70. public void InsertRow(string myConnectionString)
  71. {
  72. // If the connection string is null, use a default.
  73. if(myConnectionString == "")
  74. {
  75. myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass";
  76. }
  77. MySqlConnection myConnection = new MySqlConnection(myConnectionString);
  78. string myInsertQuery = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)";
  79. MySqlCommand myCommand = new MySqlCommand(myInsertQuery);
  80. myCommand.Connection = myConnection;
  81. myConnection.Open();
  82. myCommand.ExecuteNonQuery();
  83. myCommand.Connection.Close();
  84. }
  85. </code>
  86. </example>
  87. </ClassSummary>
  88. <ctor1>
  89. <overloads>
  90. <summary>
  91. Initializes a new instance of the MySqlCommand class.
  92. </summary>
  93. <example>
  94. The following example creates a MySqlCommand and sets some of its properties.
  95. <para></para>
  96. <note>
  97. This example shows how to use one of the overloaded
  98. versions of the MySqlCommand constructor. For other examples that might be available,
  99. see the individual overload topics.
  100. </note>
  101. <code lang="vbnet">
  102. Public Sub CreateMySqlCommand()
  103. Dim myConnection As New MySqlConnection _
  104. ("Persist Security Info=False;database=test;server=myServer")
  105. myConnection.Open()
  106. Dim myTrans As MySqlTransaction = myConnection.BeginTransaction()
  107. Dim mySelectQuery As String = "SELECT * FROM MyTable"
  108. Dim myCommand As New MySqlCommand(mySelectQuery, myConnection, myTrans)
  109. myCommand.CommandTimeout = 20
  110. End Sub
  111. </code>
  112. <code lang="C#">
  113. public void CreateMySqlCommand()
  114. {
  115. MySqlConnection myConnection = new MySqlConnection("Persist Security Info=False;
  116. database=test;server=myServer");
  117. myConnection.Open();
  118. MySqlTransaction myTrans = myConnection.BeginTransaction();
  119. string mySelectQuery = "SELECT * FROM myTable";
  120. MySqlCommand myCommand = new MySqlCommand(mySelectQuery, myConnection,myTrans);
  121. myCommand.CommandTimeout = 20;
  122. }
  123. </code>
  124. <code lang="C++">
  125. public:
  126. void CreateMySqlCommand()
  127. {
  128. MySqlConnection* myConnection = new MySqlConnection(S"Persist Security Info=False;
  129. database=test;server=myServer");
  130. myConnection->Open();
  131. MySqlTransaction* myTrans = myConnection->BeginTransaction();
  132. String* mySelectQuery = S"SELECT * FROM myTable";
  133. MySqlCommand* myCommand = new MySqlCommand(mySelectQuery, myConnection, myTrans);
  134. myCommand->CommandTimeout = 20;
  135. };
  136. </code>
  137. </example>
  138. </overloads>
  139. <summary>
  140. Initializes a new instance of the MySqlCommand class.
  141. </summary>
  142. <remarks>
  143. The base constructor initializes all fields to their default values. The
  144. following table shows initial property values for an instance of <see cref="MySqlCommand"/>.
  145. <list type="table">
  146. <listheader>
  147. <term>Properties</term>
  148. <term>Initial Value</term>
  149. </listheader>
  150. <item>
  151. <term>
  152. <see cref="CommandText"/>
  153. </term>
  154. <term>empty string ("")</term>
  155. </item>
  156. <item>
  157. <term>
  158. <see cref="CommandTimeout"/>
  159. </term>
  160. <term>0</term>
  161. </item>
  162. <item>
  163. <term>
  164. <see cref="CommandType"/>
  165. </term>
  166. <term>CommandType.Text</term>
  167. </item>
  168. <item>
  169. <term>
  170. <see cref="Connection"/>
  171. </term>
  172. <term>Null</term>
  173. </item>
  174. </list>
  175. <para>
  176. You can change the value for any of these properties through a separate call to
  177. the property.
  178. </para>
  179. </remarks>
  180. <example>
  181. The following example creates a <see cref="MySqlCommand"/> and
  182. sets some of its properties.
  183. <code lang="vbnet">
  184. Public Sub CreateMySqlCommand()
  185. Dim myCommand As New MySqlCommand()
  186. myCommand.CommandType = CommandType.Text
  187. End Sub
  188. </code>
  189. <code lang="C#">
  190. public void CreateMySqlCommand()
  191. {
  192. MySqlCommand myCommand = new MySqlCommand();
  193. myCommand.CommandType = CommandType.Text;
  194. }
  195. </code>
  196. </example>
  197. </ctor1>
  198. <ctor2>
  199. <summary>
  200. Initializes a new instance of the <see cref="MySqlCommand"/> class with the text of the query.
  201. </summary>
  202. <param name="cmdText">The text of the query.</param>
  203. <remarks>
  204. When an instance of <see cref="MySqlCommand"/> is created,
  205. the following read/write properties are set to initial values.
  206. <list type="table">
  207. <listheader>
  208. <term>Properties</term>
  209. <term>Initial Value</term>
  210. </listheader>
  211. <item>
  212. <term>
  213. <see cref="CommandText"/>
  214. </term>
  215. <term>
  216. <i>cmdText</i>
  217. </term>
  218. </item>
  219. <item>
  220. <term>
  221. <see cref="CommandTimeout"/>
  222. </term>
  223. <term>0</term>
  224. </item>
  225. <item>
  226. <term>
  227. <see cref="CommandType"/>
  228. </term>
  229. <term>CommandType.Text</term>
  230. </item>
  231. <item>
  232. <term>
  233. <see cref="Connection"/>
  234. </term>
  235. <term>Null</term>
  236. </item>
  237. </list>
  238. <para>
  239. You can change the value for any of these properties through a separate call to
  240. the property.
  241. </para>
  242. </remarks>
  243. <example>
  244. The following example creates a <see cref="MySqlCommand"/> and
  245. sets some of its properties.
  246. <code lang="vbnet">
  247. Public Sub CreateMySqlCommand()
  248. Dim sql as String = "SELECT * FROM mytable"
  249. Dim myCommand As New MySqlCommand(sql)
  250. myCommand.CommandType = CommandType.Text
  251. End Sub
  252. </code>
  253. <code lang="C#">
  254. public void CreateMySqlCommand()
  255. {
  256. string sql = "SELECT * FROM mytable";
  257. MySqlCommand myCommand = new MySqlCommand(sql);
  258. myCommand.CommandType = CommandType.Text;
  259. }
  260. </code>
  261. </example>
  262. </ctor2>
  263. <ctor3>
  264. <summary>
  265. Initializes a new instance of the <see cref="MySqlCommand"/> class
  266. with the text of the query and a <see cref="MySqlConnection"/>.
  267. </summary>
  268. <param name="cmdText">The text of the query.</param>
  269. <param name="connection">
  270. A <see cref="MySqlConnection"/> that represents the
  271. connection to an instance of SQL Server.
  272. </param>
  273. <remarks>
  274. When an instance of <see cref="MySqlCommand"/> is created,
  275. the following read/write properties are set to initial values.
  276. <list type="table">
  277. <listheader>
  278. <term>Properties</term>
  279. <term>Initial Value</term>
  280. </listheader>
  281. <item>
  282. <term>
  283. <see cref="CommandText"/>
  284. </term>
  285. <term>
  286. <i>cmdText</i>
  287. </term>
  288. </item>
  289. <item>
  290. <term>
  291. <see cref="CommandTimeout"/>
  292. </term>
  293. <term>0</term>
  294. </item>
  295. <item>
  296. <term>
  297. <see cref="CommandType"/>
  298. </term>
  299. <term>CommandType.Text</term>
  300. </item>
  301. <item>
  302. <term>
  303. <see cref="Connection"/>
  304. </term>
  305. <term>
  306. <i>connection</i>
  307. </term>
  308. </item>
  309. </list>
  310. <para>
  311. You can change the value for any of these properties through a separate call to
  312. the property.
  313. </para>
  314. </remarks>
  315. <example>
  316. The following example creates a <see cref="MySqlCommand"/> and
  317. sets some of its properties.
  318. <code lang="vbnet">
  319. Public Sub CreateMySqlCommand()
  320. Dim conn as new MySqlConnection("server=myServer")
  321. Dim sql as String = "SELECT * FROM mytable"
  322. Dim myCommand As New MySqlCommand(sql, conn)
  323. myCommand.CommandType = CommandType.Text
  324. End Sub
  325. </code>
  326. <code lang="C#">
  327. public void CreateMySqlCommand()
  328. {
  329. MySqlConnection conn = new MySqlConnection("server=myserver")
  330. string sql = "SELECT * FROM mytable";
  331. MySqlCommand myCommand = new MySqlCommand(sql, conn);
  332. myCommand.CommandType = CommandType.Text;
  333. }
  334. </code>
  335. </example>
  336. </ctor3>
  337. <ctor4>
  338. <summary>
  339. Initializes a new instance of the <see cref="MySqlCommand"/> class
  340. with the text of the query, a <see cref="MySqlConnection"/>, and the
  341. <see cref="MySqlTransaction"/>.
  342. </summary>
  343. <param name="cmdText">The text of the query.</param>
  344. <param name="connection">
  345. A <see cref="MySqlConnection"/> that represents the
  346. connection to an instance of SQL Server.
  347. </param>
  348. <param name="transaction">
  349. The <see cref="MySqlTransaction"/> in which the <see cref="MySqlCommand"/> executes.
  350. </param>
  351. <remarks>
  352. When an instance of <see cref="MySqlCommand"/> is created,
  353. the following read/write properties are set to initial values.
  354. <list type="table">
  355. <listheader>
  356. <term>Properties</term>
  357. <term>Initial Value</term>
  358. </listheader>
  359. <item>
  360. <term>
  361. <see cref="CommandText"/>
  362. </term>
  363. <term>
  364. <i>cmdText</i>
  365. </term>
  366. </item>
  367. <item>
  368. <term>
  369. <see cref="CommandTimeout"/>
  370. </term>
  371. <term>0</term>
  372. </item>
  373. <item>
  374. <term>
  375. <see cref="CommandType"/>
  376. </term>
  377. <term>CommandType.Text</term>
  378. </item>
  379. <item>
  380. <term>
  381. <see cref="Connection"/>
  382. </term>
  383. <term>
  384. <i>connection</i>
  385. </term>
  386. </item>
  387. </list>
  388. <para>
  389. You can change the value for any of these properties through a separate call to
  390. the property.
  391. </para>
  392. </remarks>
  393. <example>
  394. The following example creates a <see cref="MySqlCommand"/> and
  395. sets some of its properties.
  396. <code lang="vbnet">
  397. Public Sub CreateMySqlCommand()
  398. Dim conn as new MySqlConnection("server=myServer")
  399. conn.Open();
  400. Dim txn as MySqlTransaction = conn.BeginTransaction()
  401. Dim sql as String = "SELECT * FROM mytable"
  402. Dim myCommand As New MySqlCommand(sql, conn, txn)
  403. myCommand.CommandType = CommandType.Text
  404. End Sub
  405. </code>
  406. <code lang="C#">
  407. public void CreateMySqlCommand()
  408. {
  409. MySqlConnection conn = new MySqlConnection("server=myserver")
  410. conn.Open();
  411. MySqlTransaction txn = conn.BeginTransaction();
  412. string sql = "SELECT * FROM mytable";
  413. MySqlCommand myCommand = new MySqlCommand(sql, conn, txn);
  414. myCommand.CommandType = CommandType.Text;
  415. }
  416. </code>
  417. </example>
  418. </ctor4>
  419. <ExecuteNonQuery>
  420. <summary>
  421. Executes a SQL statement against the connection and returns the number of rows affected.
  422. </summary>
  423. <returns>Number of rows affected</returns>
  424. <remarks>
  425. You can use ExecuteNonQuery to perform any type of database operation,
  426. however any resultsets returned will not be available. Any output parameters
  427. used in calling a stored procedure will be populated with data and can be
  428. retrieved after execution is complete.
  429. For UPDATE, INSERT, and DELETE statements, the return value is the number
  430. of rows affected by the command. For all other types of statements, the return
  431. value is -1.
  432. </remarks>
  433. <example>
  434. The following example creates a MySqlCommand and then
  435. executes it using ExecuteNonQuery. The example is passed a string that is a
  436. SQL statement (such as UPDATE, INSERT, or DELETE) and a string to use to
  437. connect to the data source.
  438. <code lang="vbnet">
  439. Public Sub CreateMySqlCommand(myExecuteQuery As String, myConnection As MySqlConnection)
  440. Dim myCommand As New MySqlCommand(myExecuteQuery, myConnection)
  441. myCommand.Connection.Open()
  442. myCommand.ExecuteNonQuery()
  443. myConnection.Close()
  444. End Sub
  445. </code>
  446. <code lang="C#">
  447. public void CreateMySqlCommand(string myExecuteQuery, MySqlConnection myConnection)
  448. {
  449. MySqlCommand myCommand = new MySqlCommand(myExecuteQuery, myConnection);
  450. myCommand.Connection.Open();
  451. myCommand.ExecuteNonQuery();
  452. myConnection.Close();
  453. }
  454. </code>
  455. </example>
  456. </ExecuteNonQuery>
  457. <ExecuteReader1>
  458. <summary>
  459. Sends the <see cref="CommandText"/> to the <see cref="MySqlConnection">Connection</see>,
  460. and builds a <see cref="MySqlDataReader"/> using one of the <see cref="CommandBehavior"/> values.
  461. </summary>
  462. <param name="behavior">
  463. One of the <see cref="CommandBehavior"/> values.
  464. </param>
  465. <remarks>
  466. <para>
  467. When the <see cref="CommandType"/> property is set to <B>StoredProcedure</B>,
  468. the <see cref="CommandText"/> property should be set to the name of the stored
  469. procedure. The command executes this stored procedure when you call
  470. <B>ExecuteReader</B>.
  471. </para>
  472. <para>
  473. The <see cref="MySqlDataReader"/> supports a special mode that enables large binary
  474. values to be read efficiently. For more information, see the <B>SequentialAccess</B>
  475. setting for <see cref="CommandBehavior"/>.
  476. </para>
  477. <para>
  478. While the <see cref="MySqlDataReader"/> is in use, the associated
  479. <see cref="MySqlConnection"/> is busy serving the <B>MySqlDataReader</B>.
  480. While in this state, no other operations can be performed on the
  481. <B>MySqlConnection</B> other than closing it. This is the case until the
  482. <see cref="MySqlDataReader.Close"/> method of the <B>MySqlDataReader</B> is called.
  483. If the <B>MySqlDataReader</B> is created with <B>CommandBehavior</B> set to
  484. <B>CloseConnection</B>, closing the <B>MySqlDataReader</B> closes the connection
  485. automatically.
  486. </para>
  487. <note>
  488. When calling ExecuteReader with the SingleRow behavior, you should be aware that using a <i>limit</i>
  489. clause in your SQL will cause all rows (up to the limit given) to be retrieved by the client. The
  490. <see cref="MySqlDataReader.Read"/> method will still return false after the first row but pulling all rows of data
  491. into the client will have a performance impact. If the <i>limit</i> clause is not necessary, it should
  492. be avoided.
  493. </note>
  494. </remarks>
  495. <returns>
  496. A <see cref="MySqlDataReader"/> object.
  497. </returns>
  498. </ExecuteReader1>
  499. <ExecuteReader>
  500. <summary>
  501. Sends the <see cref="CommandText"/> to the <see cref="MySqlConnection">Connection</see>
  502. and builds a <see cref="MySqlDataReader"/>.
  503. </summary>
  504. <returns>
  505. A <see cref="MySqlDataReader"/> object.
  506. </returns>
  507. <remarks>
  508. <para>
  509. When the <see cref="CommandType"/> property is set to <B>StoredProcedure</B>,
  510. the <see cref="CommandText"/> property should be set to the name of the stored
  511. procedure. The command executes this stored procedure when you call
  512. <B>ExecuteReader</B>.
  513. </para>
  514. <para>
  515. While the <see cref="MySqlDataReader"/> is in use, the associated
  516. <see cref="MySqlConnection"/> is busy serving the <B>MySqlDataReader</B>.
  517. While in this state, no other operations can be performed on the
  518. <B>MySqlConnection</B> other than closing it. This is the case until the
  519. <see cref="MySqlDataReader.Close"/> method of the <B>MySqlDataReader</B> is called.
  520. </para>
  521. </remarks>
  522. <example>
  523. The following example creates a <see cref="MySqlCommand"/>, then executes it by
  524. passing a string that is a SQL SELECT statement, and a string to use to connect to the
  525. data source.
  526. <code lang="vbnet">
  527. Public Sub CreateMySqlDataReader(mySelectQuery As String, myConnection As MySqlConnection)
  528. Dim myCommand As New MySqlCommand(mySelectQuery, myConnection)
  529. myConnection.Open()
  530. Dim myReader As MySqlDataReader
  531. myReader = myCommand.ExecuteReader()
  532. Try
  533. While myReader.Read()
  534. Console.WriteLine(myReader.GetString(0))
  535. End While
  536. Finally
  537. myReader.Close
  538. myConnection.Close
  539. End Try
  540. End Sub
  541. </code>
  542. <code lang="C#">
  543. public void CreateMySqlDataReader(string mySelectQuery, MySqlConnection myConnection)
  544. {
  545. MySqlCommand myCommand = new MySqlCommand(mySelectQuery, myConnection);
  546. myConnection.Open();
  547. MMySqlDataReader myReader;
  548. myReader = myCommand.ExecuteReader();
  549. try
  550. {
  551. while(myReader.Read())
  552. {
  553. Console.WriteLine(myReader.GetString(0));
  554. }
  555. }
  556. finally
  557. {
  558. myReader.Close();
  559. myConnection.Close();
  560. }
  561. }
  562. </code>
  563. </example>
  564. </ExecuteReader>
  565. <Prepare>
  566. <summary>
  567. Creates a prepared version of the command on an instance of MySQL Server.
  568. </summary>
  569. <remarks>
  570. <para>
  571. Prepared statements are only supported on MySQL version 4.1 and higher. Calling
  572. prepare while connected to earlier versions of MySQL will succeed but will execute
  573. the statement in the same way as unprepared.
  574. </para>
  575. </remarks>
  576. <example>
  577. The following example demonstrates the use of the <b>Prepare</b> method.
  578. <code lang="VB.NET">
  579. public sub PrepareExample()
  580. Dim cmd as New MySqlCommand("INSERT INTO mytable VALUES (@val)", myConnection)
  581. cmd.Parameters.Add( "@val", 10 )
  582. cmd.Prepare()
  583. cmd.ExecuteNonQuery()
  584. cmd.Parameters(0).Value = 20
  585. cmd.ExecuteNonQuery()
  586. end sub
  587. </code>
  588. <code lang="C#">
  589. private void PrepareExample()
  590. {
  591. MySqlCommand cmd = new MySqlCommand("INSERT INTO mytable VALUES (@val)", myConnection);
  592. cmd.Parameters.Add( "@val", 10 );
  593. cmd.Prepare();
  594. cmd.ExecuteNonQuery();
  595. cmd.Parameters[0].Value = 20;
  596. cmd.ExecuteNonQuery();
  597. }
  598. </code>
  599. </example>
  600. </Prepare>
  601. <ExecuteScalar>
  602. <summary>
  603. Executes the query, and returns the first column of the first row in the
  604. result set returned by the query. Extra columns or rows are ignored.
  605. </summary>
  606. <returns>
  607. The first column of the first row in the result set, or a null reference if the
  608. result set is empty
  609. </returns>
  610. <remarks>
  611. <para>
  612. Use the <B>ExecuteScalar</B> method to retrieve a single value (for example,
  613. an aggregate value) from a database. This requires less code than using the
  614. <see cref="ExecuteReader()"/> method, and then performing the operations necessary
  615. to generate the single value using the data returned by a <see cref="MySqlDataReader"/>
  616. </para>
  617. </remarks>
  618. <example>
  619. The following example creates a <see cref="MySqlCommand"/> and then
  620. executes it using <B>ExecuteScalar</B>. The example is passed a string that is a
  621. SQL statement that returns an aggregate result, and a string to use to
  622. connect to the data source.
  623. <code lang="vbnet">
  624. Public Sub CreateMySqlCommand(myScalarQuery As String, myConnection As MySqlConnection)
  625. Dim myCommand As New MySqlCommand(myScalarQuery, myConnection)
  626. myCommand.Connection.Open()
  627. myCommand.ExecuteScalar()
  628. myConnection.Close()
  629. End Sub
  630. </code>
  631. <code lang="C#">
  632. public void CreateMySqlCommand(string myScalarQuery, MySqlConnection myConnection)
  633. {
  634. MySqlCommand myCommand = new MySqlCommand(myScalarQuery, myConnection);
  635. myCommand.Connection.Open();
  636. myCommand.ExecuteScalar();
  637. myConnection.Close();
  638. }
  639. </code>
  640. <code lang="C++">
  641. public:
  642. void CreateMySqlCommand(String* myScalarQuery, MySqlConnection* myConnection)
  643. {
  644. MySqlCommand* myCommand = new MySqlCommand(myScalarQuery, myConnection);
  645. myCommand-&gt;Connection-&gt;Open();
  646. myCommand-&gt;ExecuteScalar();
  647. myConnection-&gt;Close();
  648. }
  649. </code>
  650. </example>
  651. </ExecuteScalar>
  652. <CommandText>
  653. <summary>
  654. Gets or sets the SQL statement to execute at the data source.
  655. </summary>
  656. <value>
  657. The SQL statement or stored procedure to execute. The default is an empty string.
  658. </value>
  659. <remarks>
  660. <para>
  661. When the <see cref="CommandType"/> property is set to <B>StoredProcedure</B>,
  662. the <B>CommandText</B> property should be set to the name of the stored procedure.
  663. The user may be required to use escape character syntax if the stored procedure name
  664. contains any special characters. The command executes this stored procedure when
  665. you call one of the Execute methods. Starting with Connector/Net 5.0, having both a stored function
  666. and stored procedure with the same name in the same database is not supported. It is
  667. suggested that you provide unqiue names for your stored routines.
  668. </para>
  669. </remarks>
  670. <example>
  671. The following example creates a <see cref="MySqlCommand"/> and sets some of its properties.
  672. <code lang="vbnet">
  673. Public Sub CreateMySqlCommand()
  674. Dim myCommand As New MySqlCommand()
  675. myCommand.CommandText = "SELECT * FROM Mytable ORDER BY id"
  676. myCommand.CommandType = CommandType.Text
  677. End Sub
  678. </code>
  679. <code lang="C#">
  680. public void CreateMySqlCommand()
  681. {
  682. MySqlCommand myCommand = new MySqlCommand();
  683. myCommand.CommandText = "SELECT * FROM mytable ORDER BY id";
  684. myCommand.CommandType = CommandType.Text;
  685. }
  686. </code>
  687. </example>
  688. </CommandText>
  689. <CommandTimeout>
  690. <summary>
  691. Gets or sets the wait time before terminating the attempt to execute a command
  692. and generating an error.
  693. </summary>
  694. <value>
  695. The time (in seconds) to wait for the command to execute. The default is 30
  696. seconds.
  697. </value>
  698. <remarks>
  699. CommandTimeout is dependent on the ability of MySQL to cancel an executing query.
  700. Because of this, CommandTimeout is only supported when connected to MySQL
  701. version 5.0.0 or higher.
  702. </remarks>
  703. </CommandTimeout>
  704. <CommandType>
  705. <summary>
  706. Gets or sets a value indicating how the <see cref="CommandText"/> property is to be interpreted.
  707. </summary>
  708. <value>
  709. One of the <see cref="System.Data.CommandType"/> values. The default is <B>Text</B>.
  710. </value>
  711. <remarks>
  712. <para>
  713. When you set the <B>CommandType</B> property to <B>StoredProcedure</B>, you
  714. should set the <see cref="CommandText"/> property to the name of the stored
  715. procedure. The command executes this stored procedure when you call one of the
  716. Execute methods.
  717. </para>
  718. </remarks>
  719. <example>
  720. The following example creates a <see cref="MySqlCommand"/> and sets some of its properties.
  721. <code lang="vbnet">
  722. Public Sub CreateMySqlCommand()
  723. Dim myCommand As New MySqlCommand()
  724. myCommand.CommandType = CommandType.Text
  725. End Sub
  726. </code>
  727. <code lang="C#">
  728. public void CreateMySqlCommand()
  729. {
  730. MySqlCommand myCommand = new MySqlCommand();
  731. myCommand.CommandType = CommandType.Text;
  732. }
  733. </code>
  734. </example>
  735. </CommandType>
  736. <Connection>
  737. <summary>
  738. Gets or sets the <see cref="MySqlConnection"/> used by this instance of the
  739. <see cref="MySqlCommand"/>.
  740. </summary>
  741. <value>
  742. The connection to a data source. The default value is a null reference
  743. (<B>Nothing</B> in Visual Basic).
  744. </value>
  745. <remarks>
  746. <para>
  747. If you set <B>Connection</B> while a transaction is in progress and the
  748. <see cref="Transaction"/> property is not null, an <see cref="InvalidOperationException"/>
  749. is generated. If the <B>Transaction</B> property is not null and the transaction
  750. has already been committed or rolled back, <B>Transaction</B> is set to
  751. null.
  752. </para>
  753. </remarks>
  754. <example>
  755. The following example creates a <see cref="MySqlCommand"/> and sets some of its properties.
  756. <code lang="vbnet">
  757. Public Sub CreateMySqlCommand()
  758. Dim mySelectQuery As String = "SELECT * FROM mytable ORDER BY id"
  759. Dim myConnectString As String = "Persist Security Info=False;database=test;server=myServer"
  760. Dim myCommand As New MySqlCommand(mySelectQuery)
  761. myCommand.Connection = New MySqlConnection(myConnectString)
  762. myCommand.CommandType = CommandType.Text
  763. End Sub
  764. </code>
  765. <code lang="C#">
  766. public void CreateMySqlCommand()
  767. {
  768. string mySelectQuery = "SELECT * FROM mytable ORDER BY id";
  769. string myConnectString = "Persist Security Info=False;database=test;server=myServer";
  770. MySqlCommand myCommand = new MySqlCommand(mySelectQuery);
  771. myCommand.Connection = new MySqlConnection(myConnectString);
  772. myCommand.CommandType = CommandType.Text;
  773. }
  774. </code>
  775. </example>
  776. </Connection>
  777. <IsPrepared>
  778. </IsPrepared>
  779. <LastInsertedId>
  780. <summary>Provides the id of the last inserted row.</summary>
  781. <value>
  782. Id of the last inserted row. -1 if none exists.
  783. </value>
  784. <remarks>
  785. An important point to remember is that this property can be used
  786. in batch SQL scenarios but it's important to remember that it will
  787. only reflect the insert id from the last insert statement in the batch.
  788. This property can also be used when the batch includes select statements
  789. and ExecuteReader is used. This property can be consulted during result set
  790. processing.
  791. </remarks>
  792. </LastInsertedId>
  793. <Parameters>
  794. <summary>
  795. Get the <see cref="MySqlParameterCollection"/>
  796. </summary>
  797. <value>
  798. The parameters of the SQL statement or stored procedure. The default is
  799. an empty collection.
  800. </value>
  801. <remarks>
  802. Connector/Net does not support unnamed parameters. Every parameter added to the collection must
  803. have an associated name.
  804. </remarks>
  805. <example>
  806. The following example creates a <see cref="MySqlCommand"/> and displays its parameters.
  807. To accomplish this, the method is passed a <see cref="MySqlConnection"/>, a query string
  808. that is a SQL SELECT statement, and an array of <see cref="MySqlParameter"/> objects.
  809. <code lang="vbnet">
  810. Public Sub CreateMySqlCommand(myConnection As MySqlConnection, _
  811. mySelectQuery As String, myParamArray() As MySqlParameter)
  812. Dim myCommand As New MySqlCommand(mySelectQuery, myConnection)
  813. myCommand.CommandText = "SELECT id, name FROM mytable WHERE age=@age"
  814. myCommand.UpdatedRowSource = UpdateRowSource.Both
  815. myCommand.Parameters.Add(myParamArray)
  816. Dim j As Integer
  817. For j = 0 To myCommand.Parameters.Count - 1
  818. myCommand.Parameters.Add(myParamArray(j))
  819. Next j
  820. Dim myMessage As String = ""
  821. Dim i As Integer
  822. For i = 0 To myCommand.Parameters.Count - 1
  823. myMessage += myCommand.Parameters(i).ToString() &amp; ControlChars.Cr
  824. Next i
  825. Console.WriteLine(myMessage)
  826. End Sub
  827. </code>
  828. <code lang="C#">
  829. public void CreateMySqlCommand(MySqlConnection myConnection, string mySelectQuery,
  830. MySqlParameter[] myParamArray)
  831. {
  832. MySqlCommand myCommand = new MySqlCommand(mySelectQuery, myConnection);
  833. myCommand.CommandText = "SELECT id, name FROM mytable WHERE age=@age";
  834. myCommand.Parameters.Add(myParamArray);
  835. for (int j=0; j&lt;myParamArray.Length; j++)
  836. {
  837. myCommand.Parameters.Add(myParamArray[j]) ;
  838. }
  839. string myMessage = "";
  840. for (int i = 0; i &lt; myCommand.Parameters.Count; i++)
  841. {
  842. myMessage += myCommand.Parameters[i].ToString() + "\n";
  843. }
  844. MessageBox.Show(myMessage);
  845. }
  846. </code>
  847. </example>
  848. </Parameters>
  849. <Transaction>
  850. <summary>
  851. Gets or sets the <see cref="MySqlTransaction"/> within which the <see cref="MySqlCommand"/> executes.
  852. </summary>
  853. <value>
  854. The <see cref="MySqlTransaction"/>. The default value is a null reference (<B>Nothing</B> in Visual Basic).
  855. </value>
  856. <remarks>
  857. You cannot set the <B>Transaction</B> property if it is already set to a
  858. specific value, and the command is in the process of executing. If you set the
  859. transaction property to a <see cref="MySqlTransaction"/> object that is not connected
  860. to the same <see cref="MySqlConnection"/> as the <see cref="MySqlCommand"/> object,
  861. an exception will be thrown the next time you attempt to execute a statement.
  862. </remarks>
  863. </Transaction>
  864. <UpdatedRowSource>
  865. <summary>
  866. Gets or sets how command results are applied to the <see cref="DataRow"/>
  867. when used by the <see cref="System.Data.Common.DbDataAdapter.Update"/> method
  868. of the <see cref="System.Data.Common.DbDataAdapter"/>.
  869. </summary>
  870. <value>
  871. One of the <see cref="UpdateRowSource"/> values.
  872. </value>
  873. <remarks>
  874. <para>
  875. The default <see cref="System.Data.UpdateRowSource"/> value is
  876. <B>Both</B> unless the command is automatically generated (as in the case of the
  877. <see cref="MySqlCommandBuilder"/>), in which case the default is <B>None</B>.
  878. </para>
  879. </remarks>
  880. </UpdatedRowSource>
  881. </docs>