docs/en/source/odbc.txt

   1 .. index::
   2         single: ODBC Functions; Introduction
   3
   4 ==============
   5 ODBC Functions
   6 ==============
   7
   8 This chapter contains the ODBC functions provided by the Ring programming language.
   9
  10 * odbc_init()
  11 * odbc_drivers()
  12 * odbc_datasources()
  13 * odbc_close()
  14 * odbc_connect()
  15 * odbc_disconnect()
  16 * odbc_execute()
  17 * odbc_colcount()
  18 * odbc_fetch()
  19 * odbc_getdata()
  20 * odbc_tables()
  21 * odbc_columns()
  22 * odbc_autocommit()
  23 * odbc_commit()
  24 * odbc_rollback()
  25
  26 Before using the next function load the odbclib.ring library
  27
  28 .. code-block:: ring
  29
  30         load "odbclib.ring"
  31         # Use ODBC functions
  32
  33 .. index::
  34         pair: ODBC Functions; odbc_init()
  35
  36 odbc_init() Function
  37 ====================
  38
  39 We can create ODBC Handle using the odbc_init() function
  40
  41 Syntax:
  42
  43 .. code-block:: ring
  44
  45         odbc_init() ---> ODBC Handle
  46
  47 .. index::
  48         pair: ODBC Functions; odbc_drivers()
  49
  50 odbc_drivers() Function
  51 =======================
  52
  53 We can get a list of ODBC drivers using the odbc_drivers() function
  54
  55 Syntax:
  56
  57 .. code-block:: ring
  58
  59         odbc_drivers(ODBC Handle) ---> List of Drivers
  60
  61 .. index::
  62         pair: ODBC Functions; odbc_datasources()
  63
  64 odbc_datasources() Function
  65 ===========================
  66
  67 We can get a list of ODBC data sources using the odbc_datasources() function
  68
  69 Syntax:
  70
  71 .. code-block:: ring
  72
  73         odbc_datasources(ODBC Handle) ---> List of Data sources
  74
  75 .. index::
  76         pair: ODBC Functions; odbc_close()
  77
  78 odbc_close() Function
  79 =====================
  80
  81 After the end of using ODBC functions we can free resources using ODBC_Close() function
  82
  83 Syntax:
  84
  85 .. code-block:: ring
  86
  87         odbc_close(ODBC Handle)
  88
  89 .. index::
  90         pair: ODBC Functions; Print List of ODBC Drivers
  91
  92 Print List of ODBC Drivers
  93 ==========================
  94
  95 The next example print a list of ODBC drivers.
  96
  97 .. code-block:: ring
  98
  99         See "ODBC test 1" + nl
 100         oODBC = odbc_init()
 101         See "Drivers " + nl
 102         see odbc_drivers(oODBC)
 103         odbc_close(oODBC)
 104
 105 Output:
 106
 107 .. code-block:: ring
 108
 109         ODBC test 1
 110         Drivers
 111         Microsoft Access-Treiber (*.mdb) - SQLLevel=0
 112         Driver do Microsoft Paradox (*.db ) - SQLLevel=0
 113         Driver do Microsoft Excel(*.xls) - SQLLevel=0
 114         Microsoft Text Driver (*.txt; *.csv) - SQLLevel=0
 115         Driver da Microsoft para arquivos texto (*.txt; *.csv) - SQLLevel=0
 116         Microsoft dBase-Treiber (*.dbf) - SQLLevel=0
 117         SQL Server - CPTimeout=60
 118         Microsoft Excel Driver (*.xls) - SQLLevel=0
 119         Driver do Microsoft dBase (*.dbf) - SQLLevel=0
 120         Microsoft Paradox-Treiber (*.db ) - SQLLevel=0
 121         Microsoft ODBC for Oracle - CPTimeout=120
 122         Microsoft Text-Treiber (*.txt; *.csv) - SQLLevel=0
 123         Microsoft Excel-Treiber (*.xls) - SQLLevel=0
 124         Microsoft Access Driver (*.mdb) - SQLLevel=0
 125         Driver do Microsoft Access (*.mdb) - SQLLevel=0
 126         Microsoft Paradox Driver (*.db ) - SQLLevel=0
 127         Microsoft dBase Driver (*.dbf) - SQLLevel=0
 128         Microsoft Access Driver (*.mdb, *.accdb) - UsageCount=3
 129         Microsoft Excel Driver (*.xls, *.xlsx, *.xlsm, *.xlsb) - UsageCount=3
 130         Microsoft Access Text Driver (*.txt, *.csv) - UsageCount=3
 131         SQL Server Native Client 10.0 - UsageCount=1
 132         SQL Server Native Client 11.0 - UsageCount=1
 133         Microsoft Access dBASE Driver (*.dbf, *.ndx, *.mdx) - UsageCount=3
 134         Microsoft Access Paradox Driver (*.db) - UsageCount=3
 135         MySQL ODBC 5.3 ANSI Driver - UsageCount=1
 136         MySQL ODBC 5.3 Unicode Driver - UsageCount=1
 137         ODBC Driver 11 for SQL Server - UsageCount=1
 138         Lianja ODBC Driver - CPTimeout=60
 139         Microsoft Visual FoxPro Driver - UsageCount=1
 140         Microsoft Visual FoxPro-Treiber - UsageCount=1
 141         Driver para o Microsoft Visual FoxPro - UsageCount=1
 142         Microsoft FoxPro VFP Driver (*.dbf) - UsageCount=1
 143
 144 .. index::
 145         pair: ODBC Functions; Print List of ODBC Data Sources
 146
 147 Print List of ODBC Data Sources
 148 ===============================
 149
 150 The next example print a list of ODBC data sources.
 151
 152 .. code-block:: ring
 153
 154         See "ODBC test 2" + nl
 155         pODBC = odbc_init()
 156         See "Data Sources " + nl
 157         see odbc_datasources(pODBC)
 158         odbc_close(pODBC)
 159
 160 Output:
 161
 162 .. code-block:: ring
 163
 164         ODBC test 2
 165         Data Sources
 166         Excel Files - Microsoft Excel Driver (*.xls, *.xlsx, *.xlsm, *.xlsb)
 167         MS Access Database - Microsoft Access Driver (*.mdb, *.accdb)
 168         Customer - Microsoft Access Driver (*.mdb)
 169         IdCardData - Microsoft Access Driver (*.mdb)
 170         MyProjectData2 - Microsoft Access Driver (*.mdb)
 171         MyData - Microsoft Access Driver (*.mdb)
 172         MonprojetData - Microsoft Access Driver (*.mdb)
 173         dBASE Files - Microsoft Access dBASE Driver (*.dbf, *.ndx, *.mdx)
 174         myvfpdata - Microsoft Visual FoxPro Driver
 175         FACTORYDATA - Microsoft Access Driver (*.mdb)
 176         TRAININGSYSDATA - Microsoft Access Driver (*.mdb)
 177         RVCSYSDATASQLDB - SQL Server Native Client 11.0
 178         PWCTRVCDATA - Microsoft Access Driver (*.mdb)
 179         MyCompany - Microsoft Access Driver (*.mdb)
 180         HCS - Microsoft Access Driver (*.mdb)
 181         HCS2 - Microsoft Access Driver (*.mdb, *.accdb)
 182         MyProjectData - Microsoft Access Driver (*.mdb)
 183         Xtreme Sample Database 2008 - Microsoft Access Driver (*.mdb)
 184         Lianja_Southwind - Lianja ODBC Driver
 185         Visual FoxPro Database - Microsoft Visual FoxPro Driver
 186         Visual FoxPro Tables - Microsoft Visual FoxPro Driver
 187
 188 .. index::
 189         pair: ODBC Functions; odbc_connect()
 190
 191 odbc_connect() Function
 192 =======================
 193
 194 We can connect to the database using the odbc_connect() function.
 195
 196 Syntax:
 197
 198 .. code-block:: ring
 199
 200         odbc_connect(ODBC Handle, cConnectionString)
 201
 202 .. index::
 203         pair: ODBC Functions; odbc_disconnect()
 204
 205 odbc_disconnect() Function
 206 ==========================
 207
 208 We can close the connection to the database using the odbc_disconnect() function.
 209
 210 Syntax:
 211
 212 .. code-block:: ring
 213
 214         odbc_disconnect(ODBC Handle)
 215
 216 .. index::
 217         pair: ODBC Functions; Open and Close Connection
 218
 219 Open and Close Connection
 220 =========================
 221
 222 The next example connect to the database then close the connection
 223
 224 .. code-block:: ring
 225
 226         See "ODBC test 3" + nl
 227         pODBC = odbc_init()
 228         See "Connect to database" + nl
 229         see odbc_connect(pODBC,"DBQ=test.mdb;Driver={Microsoft Access Driver (*.mdb)}") + nl
 230         See "disconnect" + nl
 231         odbc_disconnect(pODBC)
 232         See "Close database..." + nl
 233         odbc_close(pODBC)
 234
 235 Output:
 236
 237 .. code-block:: ring
 238
 239         ODBC test 3
 240         Connect to database
 241         1
 242         disconnect
 243         Close database...
 244
 245 .. index::
 246         pair: ODBC Functions; odbc_execute()
 247
 248 odbc_execute() Function
 249 =======================
 250
 251 We can execute SQL Statements on the database using the odbc_execute() function.
 252
 253 Syntax:
 254
 255 .. code-block:: ring
 256
 257         odbc_execute(ODBC Handle, cSQLStatement)
 258
 259 .. index::
 260         pair: ODBC Functions; odbc_colcount()
 261
 262 odbc_colcount() Function
 263 ========================
 264
 265 We can get columns count in the query result using the odbc_colcount() function.
 266
 267 Syntax:
 268
 269 .. code-block:: ring
 270
 271         odbc_colcount(ODBC Handle) ---> Columns Count as Number
 272
 273 .. index::
 274         pair: ODBC Functions; odbc_fetch()
 275
 276 odbc_fetch() Function
 277 =====================
 278
 279 We can fetch a row from the query result using the odbc_fetch() function.
 280
 281 Syntax:
 282
 283 .. code-block:: ring
 284
 285         odbc_fetch(ODBC Handle)
 286
 287 .. index::
 288         pair: ODBC Functions; odbc_getdata()
 289
 290 odbc_getdata() Function
 291 =======================
 292
 293 We can get column value from the fetched row using the odbc_getdata() function.
 294
 295 Syntax:
 296
 297 .. code-block:: ring
 298
 299         odbc_getdata(ODBC Handle, nColumnNumber) ---> Column Value
 300
 301 .. index::
 302         pair: ODBC Functions; Execute Query and Print Result
 303
 304 Execute Query and Print Result
 305 ==============================
 306
 307 The next example execute query then print the query result.
 308
 309 .. code-block:: ring
 310
 311         See "ODBC test 4" + nl
 312         pODBC = odbc_init()
 313         See "Connect to database" + nl
 314         see odbc_connect(pODBC,"DBQ=test.mdb;Driver={Microsoft Access Driver (*.mdb)}") + nl
 315         See "Select data" + nl
 316         see odbc_execute(pODBC,"select * from person") + nl
 317         nMax = odbc_colcount(pODBC)
 318         See "Columns Count : " + nMax + nl
 319         while odbc_fetch(pODBC)
 320                 See "Row data:" + nl
 321                 for x = 1 to nMax
 322                         see odbc_getdata(pODBC,x) + " - "
 323                 next
 324         end
 325         See "Close database..." + nl
 326         odbc_disconnect(pODBC)
 327         odbc_close(pODBC)
 328
 329 .. index::
 330         pair: ODBC Functions; odbc_tables()
 331
 332 odbc_tables() Function
 333 ======================
 334
 335 We can get a list of tables inside the database using the odbc_tables() function.
 336
 337 We can access the result of this function as we get any query result.
 338
 339 Syntax:
 340
 341 .. code-block:: ring
 342
 343         odbc_tables(ODBC Handle)
 344
 345 Example:
 346
 347 .. code-block:: ring
 348
 349         See "ODBC test - Get Database Tables" + nl
 350         pODBC = odbc_init()
 351         See "Connect to database" + nl
 352         odbc_connect(pODBC,"DBQ=test.mdb;Driver={Microsoft Access Driver (*.mdb)}") + nl
 353         See "Select data" + nl
 354         odbc_tables(pODBC) + nl
 355         nMax = odbc_colcount(pODBC)
 356         See "Columns Count : " + nMax + nl
 357         while odbc_fetch(pODBC)
 358                 for x = 1 to nMax
 359                         see odbc_getdata(pODBC,x)
 360                         if x != nMax see " - " ok
 361                 next
 362                 See nl
 363         end
 364         See "Close database..."
 365         odbc_disconnect(pODBC)
 366         odbc_close(pODBC)
 367
 368 Output:
 369
 370 .. code-block:: ring
 371
 372         ODBC test - Get Database Tables
 373         Connect to database
 374         Select data
 375         Columns Count : 5
 376         .\test - NULL - Customer - TABLE - NULL
 377         .\test - NULL - employee - TABLE - NULL
 378         .\test - NULL - person - TABLE - NULL
 379         .\test - NULL - tel - TABLE - NULL
 380         Close database...
 381
 382 .. index::
 383         pair: ODBC Functions; odbc_columns()
 384
 385 odbc_columns() Function
 386 =======================
 387
 388 We can get a list of columns inside the table using the odbc_columns() function.
 389
 390 Syntax:
 391
 392 .. code-block:: ring
 393
 394         odbc_columns(ODBC Handle, cTableName)
 395
 396 Example:
 397
 398 .. code-block:: ring
 399
 400         See "ODBC test - Get Table Columns" + nl
 401         pODBC = odbc_init()
 402         See "Connect to database" + nl
 403         odbc_connect(pODBC,"DBQ=test.mdb;Driver={Microsoft Access Driver (*.mdb)}") + nl
 404         See "Get Columns inside the Person Table" + nl
 405         odbc_columns(pODBC,"person") + nl
 406         while odbc_fetch(pODBC)
 407                 see odbc_getdata(pODBC,4) + nl
 408         end
 409         See "Close database..." + nl
 410         odbc_disconnect(pODBC)
 411         odbc_close(pODBC)
 412
 413 Output:
 414
 415 .. code-block:: ring
 416
 417         ODBC test - Get Table Columns
 418         Connect to database
 419         Get Columns inside the Person Table
 420         FIRST
 421         LAST
 422         STREET
 423         CITY
 424         STATE
 425         ZIP
 426         HIREDATE
 427         MARRIED
 428         AGE
 429         SALARY
 430         NOTES
 431         Close database...
 432
 433 .. index::
 434         pair: ODBC Functions; odbc_autocommit()
 435
 436 odbc_autocommit() Function
 437 ==========================
 438
 439 We can enable or disable the auto commit feature using the odbc_autocommit() function.
 440
 441 Syntax:
 442
 443 .. code-block:: ring
 444
 445         odbc_autocommit(ODBC Handle, lStatus)   # lStatus can be True or False
 446
 447
 448 .. index::
 449         pair: ODBC Functions; odbc_commit()
 450
 451 odbc_commit() Function
 452 ======================
 453
 454 We can commit updates to the database using the odbc_commit() function.
 455
 456 Syntax:
 457
 458 .. code-block:: ring
 459
 460         odbc_commit(ODBC Handle)
 461
 462 .. index::
 463         pair: ODBC Functions; odbc_rollback()
 464
 465 odbc_rollback() Function
 466 ========================
 467
 468 We can rollback updates to the database using the odbc_rollback() function.
 469
 470 Syntax:
 471
 472 .. code-block:: ring
 473
 474         odbc_rollback(ODBC Handle)
 475
 476 .. index::
 477         pair: ODBC Functions; Transactions and Using Commit and Rollback
 478
 479 Transactions and Using Commit and Rollback
 480 ==========================================
 481
 482 Example:
 483
 484 .. code-block:: ring
 485
 486         See "ODBC Test - Transactions and using Commit and Rollback" + nl
 487         pODBC = odbc_init()
 488         See "Connect to database" + nl
 489         see odbc_connect(pODBC,"DBQ=test.mdb;Driver={Microsoft Access Driver (*.mdb)}") + nl
 490         see "insert data..." + nl
 491         odbc_autocommit(pODBC,0)
 492         for x = 1 to 10000
 493                 odbc_execute(pODBC,"insert into tel values (" + x + ",'mahmoud')")
 494         next
 495         for x = 10001 to 15000
 496                 odbc_execute(pODBC,"insert into tel values (" + x + ",'samir')")
 497         next
 498         odbc_commit(pODBC)
 499
 500         for x = 15001 to 20000
 501                 odbc_execute(pODBC,"insert into tel values (" + x + ",'fayed')")
 502         next
 503
 504         ODBC_ROLLBACK(pODBC)
 505         odbc_execute(pODBC,"insert into tel values (" + x + ",'fayed')")
 506         odbc_commit(pODBC)
 507
 508         See "Close database..." + nl
 509         odbc_disconnect(pODBC)
 510         odbc_close(pODBC)
 511
 512 Output:
 513
 514 .. code-block:: ring
 515
 516         ODBC Test - Transactions and using Commit and Rollback
 517         Connect to database
 518         1
 519         insert data...
 520         Close database...
 521
 522 .. index::
 523         pair: ODBC Functions; Save and Restore Images
 524
 525 Save and Restore images
 526 =======================
 527
 528 The next example save an image inside the database
 529
 530 .. code-block:: ring
 531
 532         See "ODBC test - Save image in the database" + nl
 533         pODBC = odbc_init()
 534         See "Connect to database" + nl
 535         see odbc_connect(pODBC,"DBQ=test.mdb;Driver={Microsoft Access Driver (*.mdb)}") + nl
 536         see "Read Image File..." + nl
 537         cFile = str2hex(read("tests\mahmoud.jpg"))
 538         see "size " + len(CFile)+nl
 539         see "Save image in the database..." + nl
 540         stmt = "insert into tel values (20000,'mahmoud','" + cFile + "');"
 541         odbc_execute(pODBC,stmt)
 542         See "Close database..." + nl
 543         odbc_disconnect(pODBC)
 544         odbc_close(pODBC)
 545
 546 The next example restore the image from the database
 547
 548 .. code-block:: ring
 549
 550         See "ODBC Test - Restore image from the database" + nl
 551         pODBC = odbc_init()
 552         See "Connect to database" + nl
 553         see odbc_connect(pODBC,"DBQ=test.mdb;Driver={Microsoft Access Driver (*.mdb)}") + nl
 554         See "Select data" + nl
 555         see odbc_execute(pODBC,"select * from tel where id = 20000") + nl
 556         nMax = odbc_colcount(pODBC)
 557         See "Columns Count : " + nMax + nl
 558         if odbc_fetch(pODBC)
 559                 See "Write image file" + nl
 560                 write("tests\great.jpg",hex2str( odbc_getdata(pODBC,3) ) )
 561         ok
 562         See "Close database..." + nl
 563         odbc_disconnect(pODBC)
 564         odbc_close(pODBC)