home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 October / Chip_2001-10_cd1.bin / zkuste / delphi / kompon / d45 / ARDOCI.ZIP / dOCI_README.eng < prev    next >
Text File  |  2001-07-13  |  15KB  |  381 lines
  1.  
  2. dOCI 1.10 stable 
  3. =================
  4.  
  5.  
  6.  ========================== IMPORTANT =============================
  7.  Now components have a new author. It is me - Romanchenko Andrey.
  8.  The previous author - Alex Buloichik gave all rights me on dOCI 
  9.  package of components.
  10.  Now I will glad see any questions and suggestions.
  11.  You can send it me on e-mail : lasersquard@yahoo.com, roma@axioma.da.ru
  12.  ===================================================================
  13.  
  14.  ========================== IMPORTANT =============================
  15.  If you are using the old version (0.9) of components you may have
  16.  some troubles while upgrading to newest versions. The versions begin 
  17.  with 1.0 are more compatible with delphi standart components.
  18.  For example early you must add fields using call
  19.  OraSQL.Query.AddField(..) but now you can do it so :
  20.  OraSQL.FieldDefs.Add(..) - as in delphi standart components.
  21.  ===================================================================
  22.  
  23.  
  24. Components are tested and good working with Delphi 4,5. It is quite 
  25. probably that they will work in Delphi 3 without any modifications.
  26. (early they worked on delphi 3 but new modifications are not tested on it)
  27.  
  28. My contact e-mail is lasersquard@yahoo.com, roma@axioma.da.ru
  29.  
  30. ================================================================================
  31.  
  32. ============
  33. FEATURES !!!
  34. ============
  35.  
  36. - Do not requires BDE! Application will not need to install BDE. Thre is no troubles 
  37.   with  different verions of BDE.
  38. - Can work with Oracle 7.* and 8.* using client part from Oracle 8.
  39. - Powerful descendant TDataSet - TOraSQL. Implements all possibilites of TDataSet and
  40.   addes new.
  41. - Full implementation of ORACLE BLOB and CLOB fields.
  42. - Possibility to execute stored procs.
  43. - Posibility to execute parts of PL/SQL code big length without creating stored 
  44.   procedure.
  45. - You can customise number of records which will be fetched from Oracle Database 
  46.   during one access to server (much more increases performance on large tables).
  47. - Quick and powerful tables in memory (TMemoryDataSet, TAMemoryDataSet).
  48. - Many nice components for create and work with dynamic arrays for all types of data.
  49.   (search in this arrays implemented on assembler and very fast!)
  50.  
  51.  
  52.  
  53. CONTENTS
  54. Introduction
  55. License
  56. Common description
  57. How I can deal with it
  58.  Description
  59.  Examples
  60. Productivity tests
  61. ChangeLog
  62.  
  63.  
  64. Introduction
  65. ------------
  66.  
  67.  Components are developed for get access to ORACLE 8 Server from Delphi 4,5.
  68.  They are use standart library OCI (Oracle Call Interface).
  69.  To use components you need installed Oracle Client for Windows 9x/NT/2000 on
  70.  you computer.
  71.  
  72.  The library maintain data types BLOB and CLOB.
  73.  From version 1.0 BLOB and CLOB fields are work good in TOraSQL.
  74.  
  75.  You can get access and to ORACLE 7 Server using clients from ORACLE 8.
  76.  If you want use Delphi 3 you can correct source code and send me changes.
  77.  I say thank you and include your changes in next version.
  78.  
  79.  
  80.  Version 1.0 it is a stable version because now it work in real project in my 
  81.  firm. Since version 0.9 many bugs was corrected and now components work 
  82.  quickly and stable.
  83.  
  84.  I trying to do components much more better and I wait your recomendations and 
  85.  suggestions. If you find bug in components please drop me a letter. I will try 
  86.  to correct and send you a corrected version.
  87.  Now I am about to make web site where you can find new versions and other information 
  88.  about dOCI components and other my programs.
  89.  
  90.  if you want receive the newest version you can write me a letter.
  91.  
  92.  My e-mail - lasersquard@yahoo.com,roma@axioma.da.ru or 2:450/93.30 in FIDO.
  93.  
  94.  
  95.  I didn't implement ßached updates and fields LargeInt.
  96.  If you need send me a letter I will implement it.
  97.  
  98.  
  99. LICENSE
  100. -------
  101.  
  102.  Components are Freeware with source code.
  103.  You can use components in any project (and in commersial too).
  104.  You can do any  changes in source code but you should inform me about this changes.
  105.  
  106.  
  107. COMMON DESCRIPTION
  108. ------------------
  109.  
  110.  Now implemented the next data types:
  111.    String,
  112.    Boolean,
  113.    Float,
  114.    Date,
  115.    Time,
  116.    DateTime,
  117.    Integer,
  118.    SmallInt,
  119.    Word,
  120.    Currency,
  121.    BLOB,
  122.    CLOB;
  123.  This data types implemented in fields and params.
  124.  
  125.   Float ¿ Integer - as is.
  126.   Boolean - as NUMBER(1) - 1 byte. 0 = False, >0 = True.
  127.   String - as array of char in memory with fix length as the length of field. 
  128.   Date - stores as TTimeStamp.Date(integer) - days from 1.01.0001
  129.   Time - stores as TTimeStamp.Time(integer)
  130.   DateTime - stores as TTimeStamp
  131.  
  132.  
  133.    TOraDB -is the connect to ORACLE database and transactions control.
  134.      All components (such as TAOraSQL) use this component to connect with the
  135.      database. All OCI calls are concentrated in this component.
  136.  
  137.    TAOraSQL - immediatly make OCI calls (SQL queries or parts of PL/SQL source 
  138.      code). It is a fullfunctional component and can be used when the compatibility
  139.      with TDataSet is not necessary, for example in case when we want to execute 
  140.      stored procedure or part of PL/SQL source code or SQL query which results
  141.      we don't need to show in TDBGrid.
  142.      This component works much faster than TOraSQL because it doesn't need 
  143.      additional actions as TOraSQL concerning the compatibility with TDataSet. 
  144.      TAOraSQL can get access to data using the record number.
  145.      During one access to database TAOraSQL fetch as many records as is in 
  146.      FetchCount's properties. If you work with big tables you should make 
  147.      FetchCount larger. By default FetchCount=100 what corresponds to the middle
  148.      size of databases. If you call method Open the SQL Query opens but any data 
  149.      won't be fetched. To fetch all data after Open you may use method ReadAll 
  150.      or OpenAll instead of Open and Readall. If you need a part of data you may
  151.      use ReadRecord(RecordNum) method that will fetch FetchCount records for
  152.      one access to database till RecordNum or more records will not be fetched.
  153.  
  154.  
  155.    TOraSQL - is the wrapper around TAOraSQL for compatibility with TDataSet. It 
  156.      is very similar to TQuery and TStoredProc. You can type SQL Query, fields 
  157.      (in runtime and designtime). The work with TOraSQL is similar with Delphi
  158.      standart database access components. By default, TOraSQL reads as much 
  159.      records as is needed for TDBGrid. To read more records call OpenAll, ReadAll
  160.      or VGoto.
  161.  
  162.  
  163.    TAOraUpdateSQL - is a component for linking to TOraSQL. You can type SQL 
  164.      Queries to change data in tables such as INSERT,DELETE,UPDATE. It is similar
  165.      to standart TUpdateSQL in Delphi but it doesn't have SQL query editor as
  166.      in TUpdateSQL. That's why you should type queries manual using DeleteSQL,
  167.      InsertSQL,ModifySQL properties.
  168.  
  169.  
  170.  dOCI Files:
  171.     DynamicArrays.pas - my components to work with dynamic arrays and used by 
  172.                 many other components.
  173.                 You can use this unit separatly from dOCI components because
  174.                 it consists many useful classes for work with arrays.
  175.                          
  176.     VirtualDataSet.pas - descendant TDataSet for convenience.
  177.  
  178.     DataSetQuery.pas - descendant TVirtualDataSet which implements 90% functions
  179.                 of end user components. This class very intersting for developers
  180.                 because by override some methods you can do an good component for
  181.                 access to any data (for example you can do MemoryTable and OraSQL).
  182.  
  183.     OraDB.pas - includes class TOraDB for connect to Oracle Server. The analog
  184.                 of TDatabase in Delphi.
  185.  
  186.     AOraSQL.pas - includes TAOraSQL and TAOraField, TAOraParam used by TAOraSQL.
  187.  
  188.     OraSQL.pas  - includes the main component TOraSQL.
  189.  
  190.     OraDefines.pas - some constants and definitions for OCI calls.
  191.  
  192.     OraError.pas - includes class EOraError descendant Exception.
  193.  
  194.  
  195.  
  196.  
  197. INSTALLATION
  198. ------------
  199.  
  200.  Open package dOCI.dpk (dOCI5.dpk in Delphi 5). Push sequently buttons "Compile" 
  201.  and "Install".
  202.  Thats all.
  203.  You can find components on "Data Access" page of pallete components in Delphi.
  204.  
  205.  
  206.     
  207. How I can deal with it
  208. ----------------------
  209.  Description
  210.  -----------
  211.  
  212.   TOraDB - for connect to Oracle Server (as TDatabase in Delphi)
  213.    Properties :
  214.      Active - ¿ Γᬠ∩ß¡«
  215.      DBLogin, DBPassword - ¿¼∩ ¿ »áα«½∞ ó íáºπ 
  216.      DBServer - ß¿¡«¡¿¼ ßÑαóÑαá ¬ ¬«Γ«α«¼π ¬«¡Ñ¬Γ¿¼ß∩ (ß«ºñáÑΓß∩ ß »«¼«Θ∞ε "Oracle
  217.            Net8 Easy Config" ½¿í« απτ¬á¼¿ »α«»¿ßδóáÑΓß∩ ó Σá⌐½Ñ 
  218.            %oraclehome%/net80/admin/tnsnames.ora) 
  219.      OraSessionIsolationLevel - isolation level for transactions. Applies to all 
  220.            transactions in current session.
  221.      OraTransIsolationLevel - isolation level for each new transaction. 
  222.            if OraTransIsolationLevel=tiDefault the OraSessionIsolationLevel is 
  223.            used.  
  224.    Methods:
  225.     Open,
  226.     Close - ßonnect/disconnect.
  227.     StartTransaction,
  228.     CommitTransaction,
  229.     RollbackTransaction - transaction control
  230.  
  231.   TOraSQL - queries to Oracle Server (descendant TDataSet)
  232.    Properies :
  233.      Database - which database use (TOraDB)
  234.      SQL   - query text (as usual parameters begin from ':')
  235.      Params - list of params. 
  236.      FetchCount - for SELECT - how much records will be fetched to one access to 
  237.             server. Value 1 is the same as BDE. 
  238.      Prepare - prepares query to execute. Usefull if you many times execute one 
  239.             query with different values of params. Not mandatory.
  240.      UnPrepare - unprepares SQL Query. 
  241.      
  242.     I recomend to get access to data using next methods:
  243.      GetFieldValue - get field value. Much faster than FieldByName('').As... but
  244.            but gets wrong value if record being edited.
  245.      GetFieldHArray - get pointer on array of values for specified field.
  246.      GetFieldNullHArray - get pointer on array tags Null or NOT Null
  247.        (for more information see DynamicArrays.pas)
  248.     ReadAll - fetch all records on local machine.
  249.     VGoto - fetch all records till specified on local machine.
  250.  
  251.   TAOraUpdateSQL - queries to change data
  252.     DeleteSQL, 
  253.     InsertSQL,
  254.     ModifySQL - as is.
  255.     You can see examples with TAOraUpdateSQL in OraSQL.pas.
  256.  
  257.  
  258.  
  259.  
  260.  Working with BLOB :
  261.  
  262.   If you work with TOraSQL you can use standart TDataSet methods to get access to 
  263.   BLOB fields.
  264.    
  265.   For write BLOB data into table you must specify "FOR UPDATE" in SQL query.
  266.   See ORACLE documentation for additional information.
  267.   For write BLOB data you must use TAOraSQL because TOraSQL support BLOB fields 
  268.   in readonly mode. I will try to correct this as soon as possible.
  269.  
  270.  
  271.   TAOraSQL has some functions to access to  BLOB fields:
  272.     GetLobLength - get size (in bytes) of BLOB field.
  273.     ReadBlob  - read piece of data from BLOB field to local buffer variable.
  274.     WriteBlob - write data from buffer to BLOB field.
  275.     ReadBlobToStream - read all BLOB field data into stream (TStream)
  276.     WriteBlobFromStream - write data from stream (TStream) to BLOB field.
  277.  
  278. =============== éìêîÇìêà! ==================
  279. For open SELECT-queries you should call
  280.  Open/Close, for other - ExecSQL. 
  281. ============================================
  282.  
  283.  
  284. Examples
  285. --------
  286.  
  287.   1.
  288.    Get cursor from StoredProc:
  289.  
  290.     BEGIN  :Result := GetData(12); END;
  291.    
  292.    Param Result has datatype ftCursor.
  293.  
  294.   2.
  295.    For open SELECT-queries you should call Open/Close, for other - ExecSQL. 
  296.  
  297.    If you wish select some fields from one record of table you can use params:
  298.  
  299.     BEGIN SELECT Name,Index INTO :Name,:Index FROM Table1 WHERE ...... ; END; 
  300.  
  301.    and get result as
  302.  
  303.     OraSQL.ParamByName('Name').AsString;
  304.     OraSQL.ParamByName('Index').AsInteger;
  305.  
  306.    This abit faster than  
  307.  
  308.     SELECT Name,Index FROM Table1 WHERE ...... 
  309.  
  310. Productivity tests
  311. ------------------
  312.  
  313.    results in seconds :
  314.            BDE        OCI(FetchCount=1)   OCI(FetchCount=1000)
  315.  INSERT     24                         19
  316.  SELECT     27                26                  4
  317.  
  318.   The tests are execute on :
  319.           server - oracle 8.0.5(linux) - p-200/64ram
  320.           client - NT4                 - pII-233/64ram
  321.           network - 10mbit
  322.           the table has size 10000 records
  323.  
  324.  
  325.  
  326. CHANGE LOG
  327. ----------
  328. v 1.10 (06.04.2001)
  329.  * Added virtual method CreateAField. Now TADataSet can hold list of fields descendances  
  330.    of TAField.
  331.  * Removed method AddField from TAOraSQL. CreateAField works insted of AddField.
  332.  * Added check on empty query text. Now you will see instead of strange "Zero iteration 
  333.    counter" "SQL statement is empty."
  334. v 1.09 (19.03.2001)
  335.  *  Added method OpenDatabase in AOraSQL.
  336.  *  Added editor for AOraUpdateSQL as standart Delphi Query Editor. Now you don't need 
  337.     to create queries by hands.
  338.  
  339. v 1.08 (27.02.2001)
  340.  *  In error message errorcode appeared twice.
  341.  *  Errors with code 20010-20050 are reserved for user information messages
  342.     EOraError cuts all debug information from this messages.
  343.     For additional information see OraError.pas
  344. v 1.07 (08.01.2001)
  345.  *  Events BeforeInitOCI and AfterInitOCI added. You can change OCI libriary 
  346.     name, disable initialization.
  347.  *  Property OraSessionIsolationLevel ¿ OraTransIsolationLevel added.
  348.     You can customise Isolation level for whole session or for each transaction.
  349.     You can see ORACLE documentation for additional information about isolation
  350.     levels.
  351. v 1.06 (21.12.2000)
  352.  *  CopyStructure(DataSet:TDataSet) and CopyStructure(ADataSet:TAdataSet) added.
  353.     in TADataSet.
  354. v 1.05
  355.  *  in ADataSet.pas some comments translated into English.
  356.  *  Check source code of AOraSQL.pas ADataSet.pas AMemoryDataSet.pas and correct
  357.     error messages and some bugs.
  358.  *  Rename some methods in TADataSet.
  359.  *  Move method AddField from TAMemoryDataSet to TADataSet.
  360.  *  List of params is creates in TADataSet not in your descendants.
  361. v 1.04
  362.  *  GetLobLength added in TAOraSQL.
  363. v 1.03
  364.  *  In TDataSetQuery field Query moves from public to protected. 
  365.     It helps easy find erors if migrate from ver 0.9 to 1.03 and later.
  366. v 1.02
  367.  *  Added events to TOraDB: 
  368.      BeforeLogin (have param Accept), 
  369.      AfterLogin, BeforeCommit, AfterCommit,OnStartTransaction.
  370. v 1.01
  371.  *  Fixed bug with OldValue if no edit present.
  372.  *  Method Refresh reopens query.
  373. v 1.0:
  374.  *  Many fixes. More compability with standart Delphi components.
  375.  *  BLOB support added in TOraSQL (readonly). For write you can use TAOraSQL.
  376.  *  Autocreate list of Params from SQL query.
  377.  
  378.  
  379.  With best regards,
  380.     Andrey Romanchenko. lasersquard@yahoo.com,
  381.