docs/en/target/mysql.txt

   1 .. index::
   2         single: MySQL Functions; Introduction
   3
   4 ===============
   5 MySQL Functions
   6 ===============
   7
   8 In this chapter we are going to learn about the MySQL functions provided by the Ring programming language.
   9
  10 * MySQL_Info()
  11 * MySQL_Init()
  12 * MySQL_Error()
  13 * MySQL_Connect()
  14 * MySQL_Close()
  15 * MySQL_Query()
  16 * MySQL_Insert_ID()
  17 * MySQL_Result()
  18 * MySQL_Next_Result()
  19 * MySQL_Columns()
  20 * MySQL_Result2()
  21 * MySQL_Escape_String()
  22 * MySQL_AutoCommit()
  23 * MySQL_Commit()
  24 * MySQL_Rollback()
  25
  26 Before using the next function load the mysqllib.ring library
  27
  28 .. code-block:: ring
  29
  30         load "mysqllib.ring"
  31         # Use MySQL functions
  32
  33 .. index::
  34         pair: MySQL Functions; MySQL_Info()
  35
  36 MySQL_Info() Function
  37 =====================
  38
  39 We can get the MySQL Client version using the MySQL_Info() function.
  40
  41 Syntax:
  42
  43 .. code-block:: ring
  44
  45         MySQL_Info() ---> string contains the MySQL Client version
  46
  47 Example:
  48
  49 .. code-block:: ring
  50
  51         see "MySQL Client Version : " + mysql_info()
  52
  53 Output:
  54
  55 .. code-block:: ring
  56
  57         MySQL Client Version : 6.1.5
  58
  59 .. index::
  60         pair: MySQL Functions; MySQL_Init()
  61
  62 MySQL_Init() Function
  63 =====================
  64
  65 We can start using MySQL Client through the MySQL_Init() function.
  66
  67 Syntax:
  68
  69 .. code-block:: ring
  70
  71         MySQL_Init() ---> MySQL Handle
  72
  73 .. index::
  74         pair: MySQL Functions; MySQL_Error()
  75
  76 MySQL_Error() Function
  77 ======================
  78
  79 We can get the error message from the MySQL Client using the MySQL_Error() function.
  80
  81 Syntax:
  82
  83 .. code-block:: ring
  84
  85         MySQL_Error(MySQL Handle) ---> Error message as string
  86
  87 .. index::
  88         pair: MySQL Functions; MySQL_Connect()
  89
  90 MySQL_Connect() Function
  91 ========================
  92
  93 We can connect to the MySQL database server using the MySQL_Connect() function.
  94
  95 Syntax:
  96
  97 .. code-block:: ring
  98
  99         MySQL_Connect(MySQL Handle, cServer, cUserName, cPassword) ---> lStatus
 100
 101 .. index::
 102         pair: MySQL Functions; MySQL_Close()
 103
 104 MySQL_Close() Function
 105 ======================
 106
 107 We can close the connection to the MySQL database using the MySQL_Close() function
 108
 109 Syntax:
 110
 111 .. code-block:: ring
 112
 113         MySQL_Close(MySQL Handle)
 114
 115 .. index::
 116         pair: MySQL Functions; MySQL_Query()
 117
 118 MySQL_Query() Function
 119 ======================
 120
 121 We can execute SQL queries using the MySQL_Query() function
 122
 123 Syntax:
 124
 125 .. code-block:: ring
 126
 127         MySQL_Query(MySQL Handle, cSQLQuery)
 128
 129 .. index::
 130         pair: MySQL Functions; Create Database
 131
 132 Create Database
 133 ===============
 134
 135 The next example connect to MySQL Server then create new database.
 136
 137 .. code-block:: ring
 138
 139         See "MySQL Test - Create Database" + nl
 140         con = mysql_init()
 141
 142         See "Connect" + nl
 143         if mysql_connect(con,"localhost","root","root") = 0
 144                 see "Can't connect" + nl
 145                 see "Error : " + mysql_error(con) + nl
 146                 mysql_close(con)
 147                 bye
 148         ok
 149
 150         See "Create Database..." + nl
 151         mysql_query(con,"CREATE DATABASE mahdb")
 152
 153         See "Close Connection" + nl
 154         mysql_close(con)
 155
 156 Output:
 157
 158 .. code-block:: ring
 159
 160         MySQL Test - Create Database
 161         Connect
 162         Create Database...
 163         Close Connection
 164
 165 .. index::
 166         pair: MySQL Functions; Create Table and Insert Data
 167
 168 Create Table and Insert Data
 169 ============================
 170
 171 The next example create new table and insert records
 172
 173 .. code-block:: ring
 174
 175         func main
 176                 see "Create Table and Insert Records" + nl
 177                 con = mysql_init()
 178
 179                 see "Connect" + nl
 180                 if mysql_connect(con, "localhost", "root", "root","mahdb") = 0
 181                         system_error(con)
 182                 ok
 183
 184                 see "Drop table" + nl
 185                 if mysql_query(con, "DROP TABLE IF EXISTS Employee")  system_error(con) ok
 186
 187                 see "Create table" + nl
 188                 if mysql_query(con, "CREATE TABLE Employee(Id INT, Name TEXT, Salary INT)")
 189                    system_error(con) ok
 190
 191                 see "Insert data" + nl
 192                 if mysql_query(con, "INSERT INTO Employee VALUES(1,'Mahmoud',15000)")
 193                    system_error(con) ok
 194
 195                 if mysql_query(con, "INSERT INTO Employee VALUES(2,'Samir',16000)")
 196                    system_error(con) ok
 197
 198                 if mysql_query(con, "INSERT INTO Employee VALUES(3,'Fayed',17000)")
 199                    system_error(con) ok
 200
 201                 see "Close connection" + nl
 202                 mysql_close(con)
 203
 204         func system_error con
 205                 see mysql_error(con)  mysql_close(con)  bye
 206
 207
 208 Output:
 209
 210 .. code-block:: ring
 211
 212         Create Table and Insert Records
 213         Connect
 214         Drop table
 215         Create table
 216         Insert data
 217         Close connection
 218
 219 .. index::
 220         pair: MySQL Functions; MySQL_Inser_ID()
 221
 222 MySQL_Insert_ID() Function
 223 ==========================
 224
 225 We can get the inserted row id using the MySQL_Insert_ID() function
 226
 227 Syntax:
 228
 229 .. code-block:: ring
 230
 231         MySQL_Insert_ID() ---> Inserted row id as number
 232
 233 Example:
 234
 235 .. code-block:: ring
 236
 237         con = mysql_init()
 238         see "connect to database" + nl
 239         mysql_connect(con,"localhost","root","root","mahdb")
 240         see "drop table" + nl
 241         mysql_query(con, "DROP TABLE IF EXISTS Customers")
 242         see "create table" + nl
 243         mysql_query(con, "CREATE TABLE Customers(Id INT PRIMARY KEY AUTO_INCREMENT, Name TEXT)")
 244         see "insert record" + nl
 245         mysql_query(con, "INSERT INTO Customers(Name) VALUES('Mahmoud')")
 246         see "insert record" + nl
 247         mysql_query(con, "INSERT INTO Customers(Name) VALUES('Samir')")
 248         see "insert record" + nl
 249         mysql_query(con, "INSERT INTO Customers(Name) VALUES('Fayed')")
 250         see "insert record" + nl
 251         mysql_query(con, "INSERT INTO Customers(Name) VALUES('Test 2015')")
 252
 253         see "inserted row id : " + mysql_insert_id(con) + nl
 254         see "close database" + nl
 255         mysql_close(con)
 256
 257 Output:
 258
 259 .. code-block:: ring
 260
 261         connect to database
 262         drop table
 263         create table
 264         insert record
 265         insert record
 266         insert record
 267         insert record
 268         inserted row id : 4
 269         close database
 270
 271 .. index::
 272         pair: MySQL Functions; MySQL_Result()
 273
 274 MySQL_Result() Function
 275 =======================
 276
 277 We can get the query result (data without column names) using the MySQL_Result() function.
 278
 279 Syntax:
 280
 281 .. code-block:: ring
 282
 283         MySQL_Result(MySQL Handle) ---> List contains the query result
 284
 285 .. index::
 286         pair: MySQL Functions; MySQL_Next_Result()
 287
 288 MySQL_Next_Result() Function
 289 ============================
 290
 291 We can move to the next query result using the MySQL_Next_Result() function.
 292 We use this function when we have multiple SQL statements in the same query.
 293
 294 Syntax:
 295
 296 .. code-block:: ring
 297
 298         MySQL_Next_Result(MySQL Handle)
 299
 300 .. index::
 301         pair: MySQL Functions; Print Query Result
 302
 303 Print Query Result
 304 ==================
 305
 306 The next example execute a query on the database then print the result.
 307
 308 .. code-block:: ring
 309
 310         con = mysql_init()
 311         see "Connect to database" + nl
 312         mysql_connect(con, "localhost", "root", "root","mahdb")
 313         see "Execute Query" + nl
 314         mysql_query(con, "SELECT Name FROM Employee WHERE Id=1;"+
 315                          "SELECT Name FROM Employee WHERE Id=3")
 316         see "Print Result" + nl
 317         see mysql_result(con)
 318         mysql_next_result(con)
 319         see mysql_result(con)
 320         see "close database" + nl
 321         mysql_close(con)
 322
 323 Output:
 324
 325 .. code-block:: ring
 326
 327         Connect to database
 328         Execute Query
 329         Print Result
 330         Mahmoud
 331         Fayed
 332         close database
 333
 334 .. index::
 335         pair: MySQL Functions; MySQL_Columns()
 336
 337 MySQL_Columns() Function
 338 ========================
 339
 340 We can get a list of columns names using the MySQL_Columns() function.
 341
 342 Syntax:
 343
 344 .. code-block:: ring
 345
 346         MySQL_Columns(MySQL Handle) ---> List contains columns information
 347
 348 Example:
 349
 350 .. code-block:: ring
 351
 352         con = mysql_init()
 353         see "Connect to database" + nl
 354         mysql_connect(con, "localhost", "root", "root","mahdb")
 355         see "Execute Query" + nl
 356         mysql_query(con, "SELECT * FROM Employee")
 357         see "Result" + nl
 358         see mysql_columns(con)
 359         see "Close database" + nl
 360         mysql_close(con)
 361
 362 Output:
 363
 364 .. code-block:: ring
 365
 366         Connect to database
 367         Execute Query
 368         Result
 369         Id
 370         11
 371         3
 372         32768
 373         Name
 374         65535
 375         252
 376         16
 377         Salary
 378         11
 379         3
 380         32768
 381         Close database
 382
 383 .. index::
 384         pair: MySQL Functions; MySQL_Result2()
 385
 386 MySQL_Result2() Function
 387 ========================
 388
 389 Instead of using MySQL_Result() to get the result data without columns names, we can use the MySQL_Result2() to get all of the
 390 column names then the query result in one list.
 391
 392 Syntax:
 393
 394 .. code-block:: ring
 395
 396         MySQL_Result2(MySQL Handle) ---> List (query result starts with columns names)
 397
 398 Example:
 399
 400 .. code-block:: ring
 401
 402         con = mysql_init()
 403         see "Connect to database" + nl
 404         mysql_connect(con, "localhost", "root", "root","mahdb")
 405         see "Execute Query" + nl
 406         mysql_query(con, "SELECT * FROM Employee")
 407         see "Print Result" + nl
 408         see mysql_result2(con)
 409         see "Close database" + nl
 410         mysql_close(con)
 411
 412 Output:
 413
 414 .. code-block:: ring
 415
 416         Connect to database
 417         Execute Query
 418         Print Result
 419         Id
 420         Name
 421         Salary
 422         1
 423         Mahmoud
 424         15000
 425         2
 426         Samir
 427         16000
 428         3
 429         Fayed
 430         17000
 431         Close database
 432
 433
 434 .. index::
 435         pair: MySQL Functions; MySQL_Escape_String()
 436
 437 MySQL_Escape_String() Function
 438 ==============================
 439
 440 We can store binary data and special characters in the database after
 441 processing using MySQL_Escape_String() function
 442
 443 Syntax:
 444
 445 .. code-block:: ring
 446
 447         MySQL_Escape_String(MySQL Handle, cString) ---> String after processing
 448
 449 .. index::
 450         pair: MySQL Functions; Save Image Inside the Database
 451
 452 Save Image inside the database
 453 ==============================
 454
 455 Example:
 456
 457 .. code-block:: ring
 458
 459         See "Read file" + nl
 460         cFile = read("tests\mahmoud.jpg")
 461         con = mysql_init()
 462         See "Connect to database..." + nl
 463         mysql_connect(con, "localhost", "root", "root","mahdb")
 464         See "Escape string..." + nl
 465         cFile = mysql_escape_string(con,cFile)
 466         stmt = "INSERT INTO photo(id, data) VALUES(1, '" + cFile + "')"
 467         See "Insert data..." + nl
 468         mysql_query(con,stmt)
 469         See "Close database..." + nl
 470         mysql_close(con)
 471
 472 Output:
 473
 474 .. code-block:: ring
 475
 476         Read file
 477         Connect to database...
 478         Escape string...
 479         Insert data...
 480         Close database...
 481
 482 .. index::
 483         pair: MySQL Functions; Restore Image From The Database
 484
 485 Restore Image From The Database
 486 ===============================
 487
 488 Example:
 489
 490 .. code-block:: ring
 491
 492         con = mysql_init()
 493         See "Connect to database..." + nl
 494         mysql_connect(con, "localhost", "root", "root","mahdb")
 495         See "Read data from database..." + nl
 496         mysql_query(con,"SELECT data FROM photo WHERE id=1")
 497         See "Write new file" + nl
 498         result = mysql_result(con)
 499         write("tests\mahmoud2.jpg",result[1][1])
 500         See "Close database..." + nl
 501         mysql_close(con)
 502
 503 Output:
 504
 505 .. code-block:: ring
 506
 507         Connect to database...
 508         Read data from database...
 509         Write new file
 510         Close database...
 511
 512
 513 .. index::
 514         pair: MySQL Functions; MySQL_AutoCommit()
 515
 516 MySQL_AutoCommit() Function
 517 ===========================
 518
 519 We can enable or disable the auto commit feature using the MySQL_AutoCommit() function.
 520
 521 Syntax:
 522
 523 .. code-block:: ring
 524
 525         MySQL_AutoCommit(MySQL Handle, lStatus)  # lstatus can be True/False
 526
 527 .. index::
 528         pair: MySQL Functions; MySQL_Commit()
 529
 530 MySQL_Commit() Function
 531 =======================
 532
 533 We can commit updates to the database using the MySQL_Commit() function.
 534
 535 Syntax:
 536
 537 .. code-block:: ring
 538
 539         MySQL_Commit(MySQL Handle)
 540
 541 .. index::
 542         pair: MySQL Functions; MySQL_Rollback()
 543
 544 MySQL_Rollback() Function
 545 =========================
 546
 547 We can rollback updates to the database using the MySQL_Rollback() function.
 548
 549 Syntax:
 550
 551 .. code-block:: ring
 552
 553         MySQL_Rollback(MySQL Handle)
 554
 555 .. index::
 556         pair: MySQL Functions; Transaction Example
 557
 558 Transaction Example
 559 ===================
 560
 561 The next example presents the usage of MySQL_Autocommit(), MySQL_Commit()
 562 & MySQL_RollBack() functions.
 563
 564 Example:
 565
 566 .. code-block:: ring
 567
 568         func main
 569
 570                 con = mysql_init()
 571
 572                 see "Connect" + nl
 573                 if mysql_connect(con, "localhost", "root", "root","mahdb") = 0
 574                         system_error(con) ok
 575
 576                 see "Drop table" + nl
 577                 if mysql_query(con, "DROP TABLE IF EXISTS Employee2")
 578                         system_error(con) ok
 579
 580                 see "Create table" + nl
 581                 if mysql_query(con, "CREATE TABLE Employee2(Id INT, Name TEXT, Salary INT)")
 582                         system_error(con) ok
 583
 584                 see "Insert data" + nl
 585                 if mysql_query(con, "INSERT INTO Employee2 VALUES(1,'Mahmoud',15000)")
 586                         system_error(con) ok
 587
 588                 if mysql_query(con, "INSERT INTO Employee2 VALUES(2,'Samir',16000)")
 589                         system_error(con) ok
 590
 591                 if mysql_query(con, "INSERT INTO Employee2 VALUES(3,'Fayed',17000)")
 592                         system_error(con) ok
 593
 594                 mysql_autocommit(con,False)
 595                 mysql_query(con, "INSERT INTO Employee2 VALUES(4,'Ahmed',5000)")
 596                 mysql_query(con, "INSERT INTO Employee2 VALUES(5,'Ibrahim',50000)")
 597                 mysql_query(con, "INSERT INTO Employee2 VALUES(6,'Mohammed',50000)")
 598                 See "Save transaction (y/n) " give nChoice
 599                 if upper(nChoice) = "Y"
 600                         mysql_commit(con)
 601                 else
 602                         mysql_rollback(con)
 603                 ok
 604
 605                 see "Close connection" + nl
 606                 mysql_close(con)
 607
 608         func system_error con
 609
 610                 see mysql_error(con)
 611                 mysql_close(con)
 612                 bye
 613
 614 Output:
 615
 616 .. code-block:: ring
 617
 618         Connect
 619         Drop table
 620         Create table
 621         Insert data
 622         Save transaction (y/n) y
 623         Close connection