Qore OracleExtensions Module Reference  1.1
OracleExtensions.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // @file OracleExtensions.qm OracleExtensions module definition
3 
4 /* OracleExtensions.qm Copyright (C) 2012 - 2014 Qore Technologies s.r.o.
5 
6 Permission is hereby granted, free of charge, to any person obtaining a
7 copy of this software and associated documentation files (the "Software"),
8 to deal in the Software without restriction, including without limitation
9 the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 and/or sell copies of the Software, and to permit persons to whom the
11 Software is furnished to do so, subject to the following conditions:
12 
13 The above copyright notice and this permission notice shall be included in
14 all copies or substantial portions of the Software.
15 
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 DEALINGS IN THE SOFTWARE.
23 */
24 
25 
26 
27 /* Version History
28  * 2015-03-24 v1.2: Petr Vanek <petr.vanek@qoretechnologies.com>
29  + small refactoring to allow using base classes with Qore::SQL::datasource and Qore::SQL::DatasourcePool
30  + abstract OracleInstrumentationBase::setAppInfoCallback(*string oraclient, *string oramodule, *string oraaction);
31  + abstract bool OracleInstrumentationBase::currentThreadInTransaction();
32  * 2014-01-24 v1.1: Petr Vanek <petr.vanek@qoretechnologies.com>
33  + OracleSQLstatement implemented
34  + documentation fixes
35  * 2012-02-05 v1.0: Petr Vanek <petr.vanek@qoretechnologies.com>
36  + initial implementation
37 */
38 
256 namespace OracleExtensions {
258 
261 {
262  private :
266  *code autoCode;
268  object m_ds;
269 
270 public:
271 
272  constructor(*code userAutoInfo);
273 
274 
275  *code autoCode() { return autoCode; }
276 
278 
289  bool setAutomaticDBInfo(*OracleExtensions::OracleApplicationInfo item, bool checkTransaction=True);
290 
291 
293 
298  abstract setAppInfoCallback(*string oraclient, *string oramodule, *string oraaction);
299 
301  abstract bool currentThreadInTransaction();
302 
304 
308  setAppInfo(*OracleExtensions::OracleApplicationInfo audit, bool fromSystem=True);
309 
310 
312  setAppInfo(*string client, *string module, *string action, bool fromSystem=True);
313 
314 
315 
316 }; // class OracleInstrumentationBase
317 
319 class OracleDatasourceBase : public Qore::SQL::AbstractDatasource,public OracleInstrumentationBase
320 {
322  *string getDBName() { return m_ds.getDBName(); }
324  *string getUserName() { return m_ds.getUserName(); }
326  any getServerVersion() { return m_ds.getServerVersion(); }
328  *string getPassword() { return m_ds.getPassword(); }
330  hash getConfigHash() { return m_ds.getConfigHash(); }
332  *int getPort() { return m_ds.getPort(); }
334  string getConfigString() { return m_ds.getConfigString(); }
336  any getClientVersion() { return m_ds.getClientVersion(); }
338  *string getOSEncoding() { return m_ds.getOSEncoding(); }
340  string getDriverName() { return m_ds.getDriverName(); }
342  string getDBEncoding() { return m_ds.getDBEncoding(); }
344  *string getHostName() { return m_ds.getHostName(); }
346  bool inTransaction() { return m_ds.inTransaction(); }
347 
349  setAppInfoCallback(*string oraclient, *string oramodule, *string oraaction);
350 
351 
354 
355 
357 
367  nothing beginTransaction(*string client, *string module, *string action);
368 
369 
371 
377  nothing beginTransaction(OracleExtensions::OracleApplicationInfo info);
378 
379 
381 
390  any exec(string sql);
391 
392 
394 
402  any execRaw(string sql);
403 
404 
406 
415  any select(string sql);
416 
417 
419 
428  any selectRow(string sql);
429 
430 
432 
441  any selectRows(string sql);
442 
443 
445 
454  any vexec(string sql, softlist vargs);
455 
456 
458 
467  any vselect(string sql, softlist vargs);
468 
469 
471 
480  any vselectRow(string sql, softlist vargs);
481 
482 
484 
493  any vselectRows(string sql, softlist vargs);
494 
495 
497 
507  any exec(OracleExtensions::OracleApplicationInfo info, string sql);
508 
509 
511 
520  any execRaw(OracleExtensions::OracleApplicationInfo info, string sql);
521 
522 
524 
534  any select(OracleExtensions::OracleApplicationInfo info, string sql);
535 
536 
538 
548  any selectRow(OracleExtensions::OracleApplicationInfo info, string sql);
549 
550 
552 
562  any selectRows(OracleExtensions::OracleApplicationInfo info, string sql);
563 
564 
566 
576  any vexec(OracleExtensions::OracleApplicationInfo info, string sql);
577 
578 
580 
590  any vselect(OracleExtensions::OracleApplicationInfo info, string sql);
591 
592 
594 
604  any vselectRow(OracleExtensions::OracleApplicationInfo info, string sql);
605 
606 
608 
618  any vselectRows(OracleExtensions::OracleApplicationInfo info, string sql);
619 
620 
621 };
622 
624 OracleDatasourceBase::constructor(*code userAutoInfo)
625  : OracleInstrumentationBase(userAutoInfo)
626 {
627  userInfo = NOTHING;
628 }
629 
631 nothing OracleDatasourceBase::commit();
632 
633 
635 nothing OracleDatasourceBase::rollback();
636 
637 
639 OracleDatasourceBase::setLongOpsProgress(OracleLongOps lo);
640 
641 
643 OracleDatasourceBase::outputEnable(*int bufferSize);
644 
645 
647 OracleDatasourceBase::outputDisable();
648 
649 
651 OracleDatasourceBase::outputPut(softstring text);
652 
653 
655 OracleDatasourceBase::outputPutLine(softstring text);
656 
657 
659 *string OracleDatasourceBase::outputGet();
660 
661 
663 
669 {
670  public :
672  *string client;
674  *string module;
676  *string action;
677 
678 public:
679 
681 
688  constructor(*string client, *string module, *string action);
689 
690 
692  clear();
693 
694 
696 
699  bool isEmpty();
700 
701 
702 }; // class OracleApplicationInfo
703 
705 
713 {
714  public :
716  string op_name;
718  string target_desc;
720  string units;
722  int op_context = 0;
724  int sofar;
727 
728 public:
729  private :
730  // A token which represents the v$session_longops row to update. Set this to set_session_longops_nohint to start a new row. Use the returned value from the prior call to reuse a row.
731  *int rindex;
732  // Saves information across calls to set_session_longops: It is for internal use and should not be modified by the caller.
733  *int slno;
734  // Specifies the object that is being worked on during the long running operation. For example, it could be a table ID that is being sorted. It appears as the TARGET column of v$session_longops.
735  *int target;
736 
737 public:
738 
740 
748 /*OracleLongOps::*/constructor(string op_name, string target_desc, string units, int totalwork) {
749  if (op_name.strlen() > 64)
750  throw "ORACLE-LONGOPS-ERROR",
751  sprintf("Constructor argument 'op_name' must have length 64 bytes max. Got: %d", op_name.strlen());
752  self.op_name = op_name;
753 
754  if (target_desc.strlen() > 32)
755  throw "ORACLE-LONGOPS-ERROR",
756  sprintf("Constructor argument 'target_desc' must have length 32 bytes max. Got: %d", target_desc.strlen());
757  self.target_desc = target_desc;
758 
759  if (target_desc.strlen() > 32)
760  throw "ORACLE-LONGOPS-ERROR",
761  sprintf("Constructor argument 'units' must have length 32 bytes max. Got: %d", target_desc.strlen());
762  self.units = units;
763 
764  if (totalwork < 1)
765  throw "ORACLE-LONGOPS-ERROR",
766  sprintf("Constructor argument 'totalwork' must have greater than 0. Got: %d", totalwork);
767  self.totalwork = totalwork;
768 
769  sofar = 0;
770 };
771 
773 
776 bool /*OracleLongOps::*/inProgress();
777 
778 
780 
785 *int /*OracleLongOps::*/getTarget();
786 
787 
788 } // class OracleLongOps
789 
791 
797 *int OracleLongOps::getRindex();
798 
800 
806 OracleLongOps::setRindex(int i);
807 
808 
810 
815 *int OracleLongOps::getSlno();
816 
818 
823 OracleLongOps::setSlno(int i);
824 
825 
826 
828 
832 
833 public:
834 
836 
839  constructor(string driver, *string user, *string pass, *string db, *string encoding, *string host, softint min=3, softint max=10, softint port=0, *code userAutoInfo)
840  : OracleExtensions::OracleDatasourceBase(userAutoInfo)
841  {
842  m_ds = new DatasourcePool(driver, user, pass, db, encoding, host, min, max);
843  }
845 
848  constructor(string desc, *code userAutoInfo)
849  : OracleExtensions::OracleDatasourceBase(userAutoInfo)
850  {
851  m_ds = new DatasourcePool(desc);
852  }
854 
857  constructor(hash opts, *code userAutoInfo)
858  : OracleExtensions::OracleDatasourceBase(userAutoInfo)
859  {
860  m_ds = new DatasourcePool(opts);
861  }
863 
867  constructor(DatasourcePool ds, *code userAutoInfo)
868  : OracleExtensions::OracleDatasourceBase(userAutoInfo)
869  {
870  m_ds = ds;
871  }
872 
873  any methodGate(string meth);
874 
875 
876  DatasourcePool getDS() { return m_ds; }
877 
878 }; // class OracleDatasourcePool
879 
880 
882 
886 
887 public:
888 
890 
893  constructor(string driver, *string user, *string pass, *string db, *string encoding, *string host, softint port=0, *code userAutoInfo)
894  : OracleExtensions::OracleDatasourceBase(userAutoInfo)
895  {
896  m_ds = new Datasource(driver, user, pass, db, encoding, host, port);
897  }
899 
902  constructor(string desc, *code userAutoInfo)
903  : OracleExtensions::OracleDatasourceBase(userAutoInfo)
904  {
905  m_ds = new Datasource(desc);
906  }
908 
911  constructor(hash opts, *code userAutoInfo)
912  : OracleExtensions::OracleDatasourceBase(userAutoInfo)
913  {
914  m_ds = new Datasource(opts);
915  }
917 
921  constructor(Datasource ds, *code userAutoInfo)
922  : OracleExtensions::OracleDatasourceBase(userAutoInfo)
923  {
924  m_ds = ds;
925  }
926 
927  nothing setAutoCommit(bool auto);
928 
929 
930  any methodGate(string meth);
931 
932 
933 }; // class OracleDatasource
934 
935 
937 
980 class OracleSQLStatement : public Qore::SQL::SQLStatement,public OracleExtensions::OracleInstrumentationBase {
981 
982 public:
983 
985 
989  constructor(Qore::SQL::Datasource ds, *code userAutoInfo)
990  : Qore::SQL::SQLStatement(ds),
992  {
993  m_ds = ds;
994  }
995 
997 
1001  constructor(Qore::SQL::DatasourcePool ds, *code userAutoInfo)
1002  : Qore::SQL::SQLStatement(ds),
1004  {
1005  m_ds = ds;
1006  }
1007 
1009 
1015  : Qore::SQL::SQLStatement(ds.privateDS()),
1017  {
1018  m_ds = ds.privateDS();
1019  }
1020 
1022 
1028  : Qore::SQL::SQLStatement(ds.privateDS()),
1030  {
1031  m_ds = ds.privateDS();
1032  }
1033 
1035  setAppInfoCallback(*string oraclient, *string oramodule, *string oraaction);
1036 
1037 
1040 
1041 
1043  nothing exec();
1044 
1045 
1047  nothing execArgs(softlist vargs);
1048 
1049 
1051  bool next();
1052 
1053 
1055  nothing commit();
1056 
1057 
1059  nothing rollback();
1060 
1061 
1062 }; // class OracleSQLStatement
1063 
1064 
1065 } // namespace OracleExtensions
1066 
1067 
1068 
1069 
1070 // qore -DOracleExtensionsTest=1 OracleExtensions.qm
1071 extern string connstr = "oracle:pvanek_omq/omq@xbox";
1072 
1073 
1074 any stmtTest(object o);
1075 
1076 
1077 any test(object o, string m);
1078 
1079 
1080 testData(object o1, object o2, string m);
1081 
1082 
1083 
1084 extern bool backRun = True;
1085 backRunLogger();
1086 
1087 
1088 testLongOps(object o);
1089 
1090 
1091 testDBMSOut(object o)
1092 {
1093  printf("testDBMS\n");
1094 
1095  o.outputEnable();
1096  o.outputPutLine('foo');
1097  o.outputPutLine(111);
1098  o.outputPutLine(now());
1099  o.exec("begin dbms_output.put_line(%v); end;", "hey, it's server here");
1100 
1101  *string res = o.outputGet();
1102  printf("DBMS_OUTPUT RESULT:\n%N\n", res);
1103  o.outputDisable();
1104 }
1105 
1106 extern Counter autoCnt();
1108 {
1109 // printf("getAutoInfo: called\n");
1110  autoCnt.inc();
1111  return new OracleExtensions::OracleApplicationInfo("user module",
1112  sprintf("auto info: %d", autoCnt.getCount()),
1113  sprintf("auto info: %n", now())
1114  );
1115 }
1116 
1117 baseTest(object dd);
1118 
1119 
1120 testDataDiffs();
1121 
1122 
1123 testPoolConnectionCount();
1124 
1125 
1126 {
1127  background backRunLogger();
1128  on_exit backRun = False;
1129 
1130  OracleExtensions::OracleDatasource dd(connstr, \getAutoInfo());
1131  dd.setAutoCommit(False);
1132  baseTest(dd);
1133 
1134  OracleExtensions::OracleDatasourcePool dp(connstr, \getAutoInfo());
1135  baseTest(dp);
1136 
1137  testDataDiffs();
1138 
1139  testPoolConnectionCount();
1140 
1141  stmtTest(dd);
1142  stmtTest(dp);
1143 }
1144 
*OracleExtensions::OracleApplicationInfo userInfo
potential user Application Info set by beginTransaction or explicit call of setAppInfo ...
Definition: OracleExtensions.qm.dox.h:264
string op_name
The name of the long running task. It appears as the OPNAME column of v$session_longops.
Definition: OracleExtensions.qm.dox.h:716
constructor(string driver, *string user, *string pass, *string db, *string encoding, *string host, softint port=0, *code userAutoInfo)
Standard Qore::DatasourcePool constructor.
Definition: OracleExtensions.qm.dox.h:893
constructor(OracleExtensions::OracleDatasource ds)
Constructor taking OracleDatasource.
Definition: OracleExtensions.qm.dox.h:1014
*string getHostName()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:344
OracleDatasource class implementation.
Definition: OracleExtensions.qm.dox.h:885
string units
Specifies the units in which sofar and totalwork are being represented. It appears as the UNITS field...
Definition: OracleExtensions.qm.dox.h:720
any getServerVersion()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:326
constructor(OracleExtensions::OracleDatasourcePool ds)
Constructor taking OracleDatasourcePool.
Definition: OracleExtensions.qm.dox.h:1027
public OracleExtensions namespace defines stuff for use
Definition: OracleExtensions.qm.dox.h:257
*string client
Supplies any additional information about the client application. This information is stored in the V...
Definition: OracleExtensions.qm.dox.h:672
bool inTransaction()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:346
constructor(string op_name, string target_desc, string units, int totalwork)
Create an OracleLongOps instance.
Definition: OracleExtensions.qm.dox.h:748
constructor(string desc, *code userAutoInfo)
Standard Qore::DatasourcePool constructor.
Definition: OracleExtensions.qm.dox.h:848
*string getUserName()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:324
*string getOSEncoding()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:338
*string action
Name of current action within the current module. If you do not want to specify an action...
Definition: OracleExtensions.qm.dox.h:676
string getDBEncoding()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:342
*string getPassword()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:328
abstract setAppInfoCallback(*string oraclient, *string oramodule, *string oraaction)
A method automatically called from setAppInfo() to allow custom implementations.
constructor(string driver, *string user, *string pass, *string db, *string encoding, *string host, softint min=3, softint max=10, softint port=0, *code userAutoInfo)
Standard Qore::DatasourcePool constructor.
Definition: OracleExtensions.qm.dox.h:839
constructor(hash opts, *code userAutoInfo)
Standard Qore::DatasourcePool constructor.
Definition: OracleExtensions.qm.dox.h:857
*int getPort()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:332
*string getDBName()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:322
int totalwork
Any number the client wants to store. It appears in the TOTALWORK column of v$session_longops. This is typically an estimate of the total amount of work needed to be done in this long running operation.
Definition: OracleExtensions.qm.dox.h:726
constructor(Qore::SQL::Datasource ds, *code userAutoInfo)
Constructor taking standard Datasource.
Definition: OracleExtensions.qm.dox.h:989
bool setAutomaticDBInfo(*OracleExtensions::OracleApplicationInfo item, bool checkTransaction=True)
Obtain info about transaction capturing and try to get available Application Info.
Qore wrapper/helper for Long Operations.
Definition: OracleExtensions.qm.dox.h:712
OracleExtensions::OracleApplicationInfo holds user info for Application Info.
Definition: OracleExtensions.qm.dox.h:668
*code autoCode
user code used in setAutomaticDBInfo when there is no OracleApplicationInfo value provided ...
Definition: OracleExtensions.qm.dox.h:266
A base class for Automatic Application Info related classes. Not intended to be used directly...
Definition: OracleExtensions.qm.dox.h:260
int sofar
Any number the client wants to store. It appears in the SOFAR column of v$session_longops. This is typically the amount of work which has been done so far.
Definition: OracleExtensions.qm.dox.h:724
abstract bool currentThreadInTransaction()
A backend provided currentThreadInTransaction() for wrappeed or inheritted Datasource/Pool.
*string module
Name of module that is currently running. When the current module terminates, call this procedure wit...
Definition: OracleExtensions.qm.dox.h:674
string target_desc
The description of the object being manipulated in this long operation. This provides a caption for t...
Definition: OracleExtensions.qm.dox.h:718
any getClientVersion()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:336
string getDriverName()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:340
object m_ds
Internally used datasource/pool.
Definition: OracleExtensions.qm.dox.h:268
string getConfigString()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:334
constructor(string desc, *code userAutoInfo)
Standard Qore::DatasourcePool constructor.
Definition: OracleExtensions.qm.dox.h:902
hash getConfigHash()
AbstractDatasource implementation for Datasource and DatasourcePool.
Definition: OracleExtensions.qm.dox.h:330
OracleDatasourcePool class implementation.
Definition: OracleExtensions.qm.dox.h:831
constructor(Qore::SQL::DatasourcePool ds, *code userAutoInfo)
Constructor taking standard DatasourcePool.
Definition: OracleExtensions.qm.dox.h:1001
constructor(Datasource ds, *code userAutoInfo)
New constructor: use already existing Datasource.
Definition: OracleExtensions.qm.dox.h:921
A base class for OracleDatasource and OracleDatasourcePool. Not intended to be used directly...
Definition: OracleExtensions.qm.dox.h:319
Oracle specific SQLStatement variant with Application Info capabilities.
Definition: OracleExtensions.qm.dox.h:980
constructor(hash opts, *code userAutoInfo)
Standard Qore::DatasourcePool constructor.
Definition: OracleExtensions.qm.dox.h:911
setAppInfo(*OracleExtensions::OracleApplicationInfo audit, bool fromSystem=True)
Set the explicit Application Info. The transaction lock is taken.
constructor(DatasourcePool ds, *code userAutoInfo)
New constructor: use already existing DatasourcePool.
Definition: OracleExtensions.qm.dox.h:867