home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1997 May / Pcwk0597.iso / sybase / starbuck / hpp.z / WQUERY.HPP < prev    next >
C/C++ Source or Header  |  1996-12-04  |  31KB  |  926 lines
  1.  
  2. #ifndef _WQUERY_HPP_INCLUDED
  3. #define _WQUERY_HPP_INCLUDED
  4.  
  5. //-----------------------------------------------------------------------
  6. //
  7. // SQL Query object.
  8. //
  9. // The query object is patterned on the ODBC model.  The simplest way
  10. // to use it is as follows:
  11. //
  12. //     WQuery query;
  13. //
  14. //     query.Create( &transObject );
  15. //     query.SetSQLStatement( "select * from table" );
  16. //
  17. //     if( query.Open() ){
  18. //         query.Close();
  19. //     }
  20. //
  21. // The query object will only work when attached to a transaction object.
  22. // The transaction object must be connected to a database for most of
  23. // the methods to work.
  24. //
  25. //-----------------------------------------------------------------------
  26.  
  27. /*************************************************************************
  28.  *
  29.  *   Events:
  30.  *
  31.  *       AdjustCursor --
  32.  *
  33.  *       BeginFetchData --
  34.  *
  35.  *       BeginMoveCursor --
  36.  *
  37.  *       DatabaseError --
  38.  *
  39.  *       FetchData --
  40.  *
  41.  *       MoveCursor --
  42.  *
  43.  *       QueryBusy --
  44.  *
  45.  *       QueryClose --
  46.  *
  47.  *       QueryOpen --
  48.  *
  49.  *       QueryPrepare --
  50.  *
  51.  *       ValidateData --
  52.  *
  53.  ************************************************************************/
  54.  
  55. #ifndef _WDATASRC_HPP_INCLUDED
  56. #include "wdatasrc.hpp"
  57. #endif
  58. #ifndef _WDATAERR_HPP_INCLUDED
  59. #include "wdataerr.hpp"
  60. #endif
  61.  
  62. class WTransaction;
  63. class WQuery;
  64.  
  65. //
  66. // BindPolicy
  67. //
  68. //    Determines the policy the query object uses to bind the various
  69. //    columns.  The policy applies to columns that are not explicitly
  70. //    bound by the user or by any bound controls:
  71. //
  72. //      All     -- Bind all columns below a size threshhold
  73. //      Minimal -- If column "n" is bound, make sure columns 1 to n-1 are
  74. //                 bound.
  75. //      None    -- Do not do any default binding.
  76.  
  77. enum WQueryBindPolicy {
  78.     WQBPAll,    
  79.     WQBPMinimal,
  80.     WQBPNone
  81. };
  82.  
  83. //
  84. // UpdatePolicy
  85. //
  86. //    This policy determines the type of action to perform an update.
  87. //
  88. //    Auto       -- The query object determines which type to use.
  89. //    Direct     -- Directly updates the current row by using driver specific
  90. //                  functions if it's supported. i.e. in ODBC, SQLSetPos()
  91. //    Cursor     -- Open another query to execute a statement of type
  92. //                  UPDATE .... SET .... WHERE CURRENT OF <cursorname>
  93. //                  if it's supported.
  94. //    UserDefine -- The user defines an event handler for the ValidateData
  95. //                  event and writes their own code to perform the update.
  96. //
  97.  
  98. enum WQueryUpdatePolicy {
  99.     WQUPAuto,
  100.     WQUPDirect,
  101.     WQUPCursor,
  102.     WQUPUserDefine
  103. };
  104.  
  105. enum WQueryCursorType {
  106.     WQCTForwardOnly = SQL_CURSOR_FORWARD_ONLY,
  107.     WQCTKeysetDriven = SQL_CURSOR_KEYSET_DRIVEN,
  108.     WQCTDynamic = SQL_CURSOR_DYNAMIC,
  109.     WQCTStatic = SQL_CURSOR_STATIC
  110. };
  111.  
  112. enum WQueryConcurrencyLevel {
  113.     WQCLReadOnly = SQL_CONCUR_READ_ONLY,
  114.     WQCLLock = SQL_CONCUR_LOCK,
  115.     WQCLOptimisticByRowVer = SQL_CONCUR_ROWVER,
  116.     WQCLOptimisticByValues = SQL_CONCUR_VALUES
  117. };
  118.  
  119. enum WQueryParameterType {
  120.     WQPTInput = SQL_PARAM_INPUT,
  121.     WQPTInputOutput = SQL_PARAM_INPUT_OUTPUT,
  122.     WQPTOutput = SQL_PARAM_OUTPUT
  123. };
  124.  
  125. enum WQOption {
  126.  
  127.     // These are defined by ODBC
  128.  
  129.     WQOCursorType = SQL_CURSOR_TYPE,
  130.     WQORowsetSize = SQL_ROWSET_SIZE,
  131.     WQOMaxLength  = SQL_MAX_LENGTH,
  132.     WQOConcurrency = SQL_CONCURRENCY,
  133.     WQORetrieveData = SQL_RETRIEVE_DATA,
  134.     WQOUseBookmarks = SQL_USE_BOOKMARKS,
  135.     WQOKeysetSize = SQL_KEYSET_SIZE,
  136.     WQOMaxRows = SQL_MAX_ROWS,
  137.     WQOQueryTimeout = SQL_QUERY_TIMEOUT,
  138.  
  139.     // These are our own...
  140.  
  141.     WQOFirstNonODBC = 65536,
  142.  
  143.     WQOAutoPrepare,
  144.     WQOBindPolicy,
  145.     WQOBindLimit,
  146.     WQOAlwaysFetchOptions,
  147.     WQOAlwaysFetchRowPosition,
  148.     WQOAlwaysMoveCursor,
  149. };
  150.  
  151. enum WStmtCompare {
  152.     WSMLike = 0,
  153.     WSMNotLike,
  154.     WSMEqual,
  155.     WSMNotEqual,
  156.     WSMLessThan,
  157.     WSMGreaterThan,
  158.     WSMLessThanEqual,
  159.     WSMGreaterThanEqual,
  160. };
  161.  
  162. enum WStmtCondition {
  163.     WSNAnd = 0,
  164.     WSNOr,
  165. };
  166.  
  167. //
  168. // State information
  169. //
  170.  
  171. #define WQDRSTATE_OPENED       0x01
  172. #define WQDRSTATE_PREPARED     0x02
  173. #define WQDRSTATE_NOTFETCHED   0x04
  174. #define WQDRSTATE_NOTBOUND     0x08
  175. #define WQDRSTATE_NOTALLOCATED 0x10
  176. #define WQDRSTATE_NOTDATAOPEN  0x20
  177.  
  178. enum WODBCStmtHandle { NULLHSTMT = 0, LASTHSTMT = LAST_32BIT };
  179.  
  180. //
  181. // WICursorProxy
  182. //
  183.  
  184. class WQueryICursor;
  185.  
  186. class WCMCLASS WICursorProxyBase : public WReferenceObject {
  187.  
  188.     WDeclareSubclass( WICursorProxyBase, WReferenceObject );
  189.  
  190.     protected:
  191.         WICursorProxyBase( const WICursorProxyBase & ref );
  192.         WICursorProxyBase& operator=( const WICursorProxyBase & ref );
  193.  
  194.     protected:
  195.         WICursorProxyBase();
  196.  
  197.     public:
  198.         virtual ~WICursorProxyBase();
  199.  
  200.         virtual WBool DetachQuery( WQuery * ) = 0;
  201. };
  202.  
  203. //
  204. // WQuery -- Represents the results of a SQL statement.
  205. //
  206.  
  207. class WCMCLASS WQuery : public WDataSource {
  208.  
  209.     WDeclareSubclass( WQuery, WDataSource );
  210.  
  211.     public:
  212.  
  213.         WQuery();
  214.  
  215.         virtual ~WQuery();
  216.  
  217.  
  218.  
  219.         /***************************************************************
  220.          * Properties
  221.          ***************************************************************/
  222.  
  223.         // AlwaysFetchOptions
  224.         //
  225.         //    If TRUE, the query object always asks the database for
  226.         //    the state of a particular option.  If FALSE it uses the
  227.         //    value from its own cache.  If options are being set directly
  228.         //    by bypassing the query object you should set this to TRUE.
  229.         //    FALSE by default.
  230.  
  231.         virtual WBool GetAlwaysFetchOptions() const;
  232.         virtual WBool SetAlwaysFetchOptions( WBool always );
  233.  
  234.         // AlwaysFetchRowPosition
  235.         //
  236.         //    If TRUE, the query object always asks the database for
  237.         //    the current row position after each fetch.  Otherwise
  238.         //    the query object maintains its own count, which may not
  239.         //    be accurate if bookmarks are being used.  Because this
  240.         //    adds overhead, it is FALSE by default.  Also, not all
  241.         //    database drivers support this capability.
  242.  
  243.         virtual WBool GetAlwaysFetchRowPosition() const;
  244.         virtual WBool SetAlwaysFetchRowPosition( WBool always );
  245.  
  246.         // AlwaysMoveCursor
  247.         //
  248.         //    If TRUE, the query object always notifies the database
  249.         //    whenever the cursor is moved within the current rowset.
  250.         //    If FALSE, the database is only notified when necessary
  251.         //    (to get BLOB data, for example).  Default is FALSE.
  252.  
  253.         virtual WBool GetAlwaysMoveCursor() const;
  254.         virtual WBool SetAlwaysMoveCursor( WBool always );
  255.  
  256.         // AutoPrepare
  257.         //
  258.         //    If TRUE, the Prepare method will be called automatically
  259.         //    the first time a SQL statement is opened.
  260.  
  261.         virtual WBool GetAutoPrepare() const;
  262.         virtual WBool SetAutoPrepare( WBool on );
  263.  
  264.         // BindPolicy
  265.         //
  266.         //    The bind policy for default column binding.
  267.  
  268.         virtual WQueryBindPolicy GetBindPolicy() const;
  269.         virtual WBool            SetBindPolicy( WQueryBindPolicy policy );
  270.  
  271.         // BindLimit
  272.         //
  273.         //    The maximum size which a character or binary column can be
  274.         //    to be bindable.  A value of 0 means no limits.
  275.  
  276.         virtual WULong GetBindLimit() const;
  277.         virtual WBool  SetBindLimit( WULong limit );
  278.  
  279.         // ConcurrencyLevel
  280.         //
  281.         //    The concurrency level for the query. Can only be set
  282.         //    if the query is not open.  The default is read-only.
  283.  
  284.         virtual WQueryConcurrencyLevel GetConcurrencyLevel() const;
  285.         virtual WBool                  SetConcurrencyLevel( WQueryConcurrencyLevel l );
  286.  
  287.         // CurrentOffset
  288.         //
  289.         //    Returns the offset of the current row within the rowset
  290.         //    buffer, a value from 0 to RowsetSize-1.
  291.  
  292.         virtual WLong GetCurrentOffset() const;
  293.  
  294.         // CursorName
  295.         //
  296.         //    The name of the cursor.  If none is specified,
  297.         //    it is generated automatically.
  298.  
  299.         virtual WString GetCursorName() const;
  300.         virtual WBool   SetCursorName( const WString & str );
  301.  
  302.         // CursorType
  303.         //
  304.         //    Return the cursor type.
  305.  
  306.         virtual WQueryCursorType GetCursorType() const;
  307.         virtual WBool            SetCursorType( WQueryCursorType type );
  308.  
  309.         // DisplayErrorDialog
  310.         //
  311.         //    When an error occurs, display a dialog describing the
  312.         //    error.  TRUE by default.
  313.  
  314.         virtual WBool GetDisplayErrorDialog() const;
  315.         virtual WBool SetDisplayErrorDialog( WBool display );
  316.  
  317.         // DisplayWarningDialog
  318.         //
  319.         //    When a warning occurs, display a dialog describing the
  320.         //    warning.  FALSE by default.
  321.  
  322.         virtual WBool GetDisplayWarningDialog() const;
  323.         virtual WBool SetDisplayWarningDialog( WBool display );
  324.  
  325.         // DriverPacksRows
  326.         //
  327.         //    Set to true if the underlying query driver packs inserted and
  328.         //    deleted rows.
  329.  
  330.         virtual WBool GetDriverPacksRows() const;
  331.         virtual WBool SetDriverPacksRows( WBool packsRows );
  332.  
  333.         // ErrorList
  334.         //
  335.         //    Returns the list of errors from the last operation.
  336.  
  337.         virtual WDataErrorArray GetErrorList() const;
  338.  
  339.         // FetchedRows
  340.         //
  341.         //    Returns the number of rows that were actually fetched.
  342.         //    Can be 0 (none) up to RowsetSize.
  343.  
  344.         virtual WLong GetFetchedRows() const;
  345.  
  346.         // Handle
  347.         //
  348.         //    Returns a handle, which is driver-specific.  After a
  349.         //    valid Create, should be non-zero.  After a Destroy,
  350.         //    should be zero.
  351.  
  352.         virtual WDWord GetHandle() const;
  353.  
  354.         // KeysetSize
  355.         //
  356.         //    Determines the keyset size for keyset-driven cursors.
  357.         //    The default is 0, which means a fully keyset-driven
  358.         //    cursor, otherwise the cursor is mixed.  The keyset
  359.         //    size must be greater than the rowset size.
  360.  
  361.         virtual WLong GetKeysetSize() const;
  362.         virtual WBool SetKeysetSize( WLong size );
  363.  
  364.         // LongColumnBindSize
  365.         //
  366.         //    Sets the amount of memory to allocate for LONGVARCHAR
  367.         //    and LONGVARBINARY columns if a buffer size of 0 is
  368.         //    passed to BindColumn.  The default is 0, which means
  369.         //    that long columns are never bound.  Any other value is
  370.         //    the maximum amount of data that can be set or gotten
  371.         //    from the column, up to the BindLimit property.
  372.  
  373.         virtual WULong GetLongColumnBindSize() const;
  374.         virtual WBool  SetLongColumnBindSize( WULong size );
  375.  
  376.         // MaxLength
  377.         //
  378.         //    The maximum of binary or character data that can be
  379.         //    fetched in a single call.  The default value is 0,
  380.         //    which means return as much as possible.  The maximum
  381.         //    value for this property is 64K (=65536 bytes).  Note
  382.         //    that the MaxLength property affects the amount of
  383.         //    data returned by GetRawData.
  384.  
  385.         virtual WULong GetMaxLength() const;
  386.         virtual WBool  SetMaxLength( WULong maxLength );
  387.  
  388.         // MaxRows
  389.         //
  390.         //    The maximum number of rows to return in a result set.
  391.         //    If 0, all rows are returned.
  392.  
  393.         virtual WULong GetMaxRows() const;
  394.         virtual WBool  SetMaxRows( WULong maxRows );
  395.  
  396.         // Parameter
  397.         //
  398.         //    Defines a parameter value for use in parameterized
  399.         //    queries.  Setting a parameter will implicitly cause
  400.         //    the BindParameter method to be called.  Parameters
  401.         //    are numbered starting at 1.  Can optionally declare
  402.         //    whether the parameter should be input, input/output
  403.         //    or output only.  
  404.  
  405.         virtual WDataValue GetParameter( WShort paramNo ) const;
  406.         virtual WBool      SetParameter( WShort paramNo,
  407.                                          const WDataValue & val,
  408.                                          WColumnDataType sqlType=SQL_TYPE_NULL,
  409.                                          WQueryParameterType type=WQPTInput,
  410.                                          SDWORD maxSize=0 );
  411.  
  412.         // Prepared
  413.         //
  414.         //    Returns TRUE if the statement has been prepared for execution.
  415.  
  416.         virtual WBool GetPrepared() const;
  417.  
  418.         // QueryTimeout
  419.         //
  420.         //    Defines the time in seconds to wait for a statement
  421.         //    to execute.  The default is 0, which means wait
  422.         //    indefinitely.
  423.  
  424.         virtual WULong GetQueryTimeout() const;
  425.         virtual WBool  SetQueryTimeout( WULong seconds );
  426.  
  427.         // RetrieveData
  428.         //
  429.         //    If FALSE, no data is actually retrieved when a fetch
  430.         //    is done.  Use this to move around through the data
  431.         //    to get bookmarks, etc.  Default is TRUE.  Can only be
  432.         //    set at run time.
  433.  
  434.         virtual WBool GetRetrieveData() const;
  435.         virtual WBool SetRetrieveData( WBool ret );
  436.  
  437.         // RowsetSize
  438.         //
  439.         //    The maximum number of rows that are buffered locally by the
  440.         //    query object.  Setting the rowset size automatically
  441.         //    unbinds any bound columns.
  442.  
  443.         virtual WLong  GetRowsetSize() const;
  444.         virtual WBool  SetRowsetSize( WLong size );
  445.  
  446.         // RowsetStatus
  447.         //
  448.         //    Returns the status of a row in the current rowset.  Rows
  449.         //    are numbered from 1 to n (where n = GetRowsetSize() ).
  450.  
  451.         virtual UWORD GetRowsetStatus( WLong row=1 ) const;
  452.  
  453.         // SQL
  454.         //
  455.         //    Stores the SQL statement to be executed.  Setting a new
  456.         //    statement closes the current query (if open).
  457.  
  458.         virtual WString GetSQL() const;
  459.         virtual WBool   SetSQL( const WString & str );
  460.  
  461.         // State
  462.         //
  463.         //    Return the current state of the query.
  464.  
  465.         virtual WDWord GetState() const;
  466.  
  467.         // TraceToLog
  468.         //
  469.         //    In debug mode, if TRUE traces important actions
  470.         //    to the debug log.  Has no effect for release mode
  471.         //    applications.  (This is not the same as the ODBC
  472.         //    trace log.)
  473.  
  474.         virtual WBool GetTraceToLog() const;
  475.         virtual WBool SetTraceToLog( WBool on );
  476.  
  477.         // TransactionObject
  478.         //
  479.         //    The transaction object to use.
  480.  
  481.         virtual WTransaction *GetTransactionObject() const;
  482.         virtual WBool         SetTransactionObject( WTransaction *obj );
  483.  
  484.         // UpdatePolicy
  485.         //
  486.         //    The update policy for the type of action to take when
  487.         //    updating.
  488.  
  489.         virtual WQueryUpdatePolicy GetUpdatePolicy() const;
  490.         virtual WBool              SetUpdatePolicy( WQueryUpdatePolicy policy );
  491.  
  492.         // UseBookmarks
  493.         //
  494.         //    If TRUE, bookmarks can be used.  Must be set before
  495.         //    the cursor is opened.  Default is FALSE.
  496.  
  497.         virtual WBool GetUseBookmarks() const;
  498.         virtual WBool SetUseBookmarks( WBool use );
  499.  
  500.         // UseDefaultBindTypes
  501.         //
  502.         //    If TRUE, BindColumn is called with SQL_C_DEFAULT when
  503.         //    a column is bound by a data target.  If FALSE, the
  504.         //    type suggested by the data target is used instead.  This
  505.         //    controls who does the conversion between data types: the
  506.         //    database driver or the WDataValue class.  Calls to
  507.         //    BindColumn by the user are not affected.
  508.  
  509.         virtual WBool GetUseDefaultBindTypes() const;
  510.         virtual WBool SetUseDefaultBindTypes( WBool use );
  511.  
  512.  
  513.         /***************************************************************
  514.          * Search Methods
  515.          ***************************************************************/
  516.  
  517.         virtual WBool ResetSearch();
  518.         virtual WBool AddSearchParameter( WString columnName, WDataValue value,
  519.                       WStmtCondition=WSNAnd,WStmtCompare compare=WSMLike);
  520.         virtual WBool AddSearchParameter( WShort columnIndex, WDataValue value,
  521.                       WStmtCondition=WSNAnd,WStmtCompare compare=WSMLike);
  522.         virtual WBool DeleteSearchParameters();
  523.         virtual WBool Search();
  524.         virtual WBool Search( WShort columnIndex, WDataValue value,
  525.                       WStmtCondition=WSNAnd,WStmtCompare compare=WSMLike);
  526.         virtual WBool Search( WString columnName, WDataValue value,
  527.                       WStmtCondition=WSNAnd,WStmtCompare compare=WSMLike);
  528.         virtual WBool BoundControlSearch( WStmtCondition condition=WSNAnd,
  529.                                  WStmtCompare compare=WSMLike);
  530.         /***************************************************************
  531.          * Methods
  532.          ***************************************************************/
  533.  
  534.         // BindColumn
  535.         //
  536.         //    Bind a column in the current query, which must be open.
  537.         //    By default it will allocate internal storage for the binding
  538.         //    based on the type of the column and the rowset size as
  539.         //    well as an array for storing the actual length of retrieved
  540.         //    data.  The user can provide alternates for any of these.
  541.  
  542.         virtual WBool BindColumn( WShort column, WNativeDataType type=SQL_C_DEFAULT,
  543.                                   void *arrayStart=NULL, SDWORD elementSize=0,
  544.                                   SDWORD *lengthArray=NULL );
  545.  
  546.         // BindParameter
  547.         //
  548.         //    Bind a parameter for execution with the next query.
  549.         //    In most cases you call SetParameter instead of this method,
  550.         //    and the binding will be done automatically for you.
  551.         //    This method provides low-level access to the binding
  552.         //    process.  Parameters start at 1.
  553.  
  554.         virtual WBool BindParameter( WShort paramNo, WQueryParameterType type,
  555.                                      WNativeDataType cType,
  556.                                      WColumnDataType sqlType,
  557.                                      UDWORD precision, SWORD scale,
  558.                                      void *dataBuffer, SDWORD maxSize,
  559.                                      SDWORD *actualLength );
  560.  
  561.         // Clone
  562.         //
  563.         //    Allocates and returns a "clone" of the query object.
  564.         //    The clone is a semi-independent query object needed
  565.         //    for use with complex OCX data binding.
  566.  
  567.         virtual WQuery *Clone();
  568.  
  569.         // Close
  570.         //
  571.         //    Close the current query, if any.
  572.  
  573.         virtual WBool Close( WBool discardResults=TRUE,
  574.                              WBool isRequery=FALSE );
  575.  
  576.         // Create
  577.         //
  578.         //    Calls SetTransactionObject and then checks to see if
  579.         //    the transaction object is ready for use.
  580.  
  581.         virtual WBool Create( WTransaction *trans );
  582.  
  583.         // Destroy
  584.  
  585.         virtual WBool Destroy();
  586.  
  587.         // Execute
  588.         //
  589.         //    Execute a non-select SQL statement.  Closes the current
  590.         //    query, if any.  If an empty or null string is passed in, simply
  591.         //    executes the string in the SQL property.
  592.  
  593.         virtual WBool Execute( const WString & stmt=WString::GetNullString() );
  594.  
  595.         // Fetch
  596.         //
  597.         //    Fetch a rowset of data from the database.
  598.  
  599.         virtual WBool Fetch( WLong row, WBool notifyTargets=TRUE,
  600.                              WDSMoveType type=WDSMoveAbsolute,
  601.                              WBool triggerEvents=TRUE );
  602.  
  603.         // FetchBookmark
  604.         //
  605.         //    Fetch to a bookmark.
  606.  
  607.         WBool FetchBookmark( WDWord bookmark, WBool notify=TRUE,
  608.                              WBool triggerEvents=TRUE );
  609.  
  610.         // FetchErrors
  611.         //
  612.         //    Clear the current error list and fetch errors from the
  613.         //    driver for later retrieval with
  614.         //    GetErrorList.  Note that this function is called automatically
  615.         //    by most of the other methods, so you should only call it
  616.         //    after directly invoking an operation on the driver.
  617.         //    You pass in the return code and function code of the
  618.         //    last operation.  Returns TRUE if messages were fetched
  619.         //    from the driver.
  620.  
  621.         virtual WBool FetchErrors( WLong errorCode, WLong funcCode );
  622.  
  623.         // FetchFirst
  624.         //
  625.         //    Fetch to the first row.
  626.  
  627.         WBool FetchFirst( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  628.  
  629.         // FetchLast
  630.         //
  631.         //    Fetch to the last row.
  632.  
  633.         WBool FetchLast( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  634.  
  635.         // FetchNext
  636.         //
  637.         //    Fetch to the next row.
  638.  
  639.         WBool FetchNext( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  640.  
  641.         // FetchPrevious
  642.         //
  643.         //    Fetch to the previous row.
  644.  
  645.         WBool FetchPrevious( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  646.  
  647.         // FetchRelative
  648.         //
  649.         //    Fetch to a relative row.
  650.  
  651.         WBool FetchRelative( WLong offset, WBool notifyTargets=TRUE,
  652.                              WBool triggerEvents=TRUE );
  653.  
  654.         // FlushUnboundValues
  655.         //
  656.         //    Flushes the unbound value cache.  When data is fetched from
  657.         //    an unbound column, a copy is kept in memory.  This method
  658.         //    frees any copies currently in memory.  It is called implicitly
  659.         //    whenever a move occurs.
  660.  
  661.         virtual WBool FlushUnboundValues();
  662.  
  663.         // MarkColumnForUpdate
  664.         //
  665.         //    After entering add/edit mode, call this method before
  666.         //    calling Update if you wish to manually set the length
  667.         //    field of a bound column so that it will be updated.
  668.         //    Otherwise the length field is set to SQL_IGNORE unless
  669.         //    you call SetValue for that column.  Returns success.
  670.  
  671.         virtual WBool MarkColumnForUpdate( WShort column, WBool mark );
  672.  
  673.         // Open
  674.         //
  675.         //    Execute the SQL statement and open the result set for
  676.         //    processing.
  677.  
  678.         virtual WBool Open( WBool executeStatement=TRUE,
  679.                             WBool isRequery=FALSE );
  680.  
  681.         // Prepare
  682.         //
  683.         //    Prepare the SQL statement for execution.  Call this
  684.         //    if you intend to execute the same SQL statement multiple
  685.         //    times.  Closes any open query.
  686.  
  687.         virtual WBool Prepare();
  688.  
  689.         // QueryColumnBinding
  690.         //
  691.         //    Return information on how a column is bound.  Returns TRUE
  692.         //    if the column is bound, FALSE otherwise. Can optionally
  693.         //    get pointer to data area, element size, etc.
  694.  
  695.         virtual WBool QueryColumnBinding( WShort column,
  696.                                           WNativeDataType *boundAs=NULL,
  697.                                           void **arrayStart=NULL,
  698.                                           SDWORD *elementSize=NULL,
  699.                                           SDWORD **lengthArray=NULL );
  700.  
  701.         // Reference
  702.         //
  703.         //    Bump up the reference count.  Only useful for clones.
  704.         //    Returns the new reference count.
  705.  
  706.         virtual WLong Reference();
  707.  
  708.         // Resubmit
  709.         //
  710.         //    Re-executes the SQL statement that was last set using
  711.         //    the SQL property.  This is equivalent to calling Close
  712.         //    and then Open, but is a bit more efficient.
  713.  
  714.         virtual WBool Resubmit( WBool executeStatement=TRUE,
  715.                                 WBool closeCursor=TRUE );
  716.  
  717.         // UnbindColumn
  718.         //
  719.         //    Undo the binding of a column.  Pass a negative value
  720.         //    to unbind all bound columns.
  721.  
  722.         virtual WBool UnbindColumn( WShort column );
  723.  
  724.         // UnbindParameter
  725.         //
  726.         //    Undo the binding of a parameter.  Pass a negative value
  727.         //    to unbind all parameters.
  728.  
  729.         virtual WBool UnbindParameter( WShort paramNo );
  730.  
  731.         // Unreference
  732.         //
  733.         //    Decrements the reference count.  Only useful for clones.
  734.         //    Returns the new reference count.
  735.  
  736.         virtual WLong Unreference();
  737.  
  738.         /***************************************************************
  739.          * Item Properties
  740.          ***************************************************************/
  741.  
  742.         // NumericOption
  743.         //
  744.         //    Set/get a query option.
  745.  
  746.         virtual WLong GetNumericOption( WULong id, WBool *ok=NULL ) const;
  747.         virtual WBool SetNumericOption( WULong id, WLong value );
  748.  
  749.         // OptionID
  750.         //
  751.         //    Return the ID associated with an option string.  Can also
  752.         //    return whether the option is numeric or string.  A value of
  753.         //    zero means an invalid option.
  754.  
  755.         virtual WULong GetOptionID( const WString & str,
  756.                                     WBool *isString=NULL ) const;
  757.  
  758.         // StringOption
  759.         //
  760.         //    Set/get a query option.
  761.  
  762.         virtual WString GetStringOption( WULong id ) const;
  763.         virtual WBool   SetStringOption( WULong id, const WString & str );
  764.  
  765.         /***************************************************************
  766.          * Other
  767.          ***************************************************************/
  768.  
  769.         virtual WICursorProxyBase *GetICursorProxy() const;
  770.         virtual WBool              SetICursorProxy( WICursorProxyBase *p );
  771.  
  772.         /***************************************************************
  773.          * Overrides
  774.          ***************************************************************/
  775.  
  776.         WBool AddTarget( WDataTarget *target );
  777.  
  778.         WBool GetAutoEdit() const;
  779.         WBool SetAutoEdit( WBool autoEdit );
  780.  
  781.         WBool GetAutoRefresh() const;
  782.         WBool SetAutoRefresh( WBool autoRefresh );
  783.  
  784.         WBool GetBOF() const;
  785.  
  786.         WDWord GetBookmark() const;
  787.  
  788.         WShort GetColumnCount() const;
  789.  
  790.         const WDataColumn & GetColumn( WShort index ) const;
  791.         const WDataColumn & GetColumn( const WString & name ) const;
  792.  
  793.         WShort GetColumnIndex( const WString & str ) const;
  794.  
  795.         WLong GetCurrentRow() const;
  796.  
  797.         WDSEditMode GetEditMode() const;
  798.  
  799.         WBool GetEmpty() const;
  800.  
  801.         WBool GetEOF() const;
  802.  
  803.         WLong GetErrorCode( WLong *apiCode=NULL ) const;
  804.  
  805.         WBool GetForwardOnly() const;
  806.  
  807.         WBool GetNull() const;
  808.  
  809.         WBool GetOpened() const;
  810.  
  811.         WBool GetRawData( WShort index, WNativeDataType type,
  812.                           void *buffer, WLong bufferSize=0,
  813.                           WLong *bytesRemaining=NULL ) const;
  814.  
  815.         WBool GetReadOnly() const;
  816.  
  817.         WBool GetRowChanged() const;
  818.         WBool SetRowChanged( WBool changed );
  819.  
  820.         WLong GetRowCount( WBool force=TRUE ) const;
  821.  
  822.         WBool GetTargetsEnabled() const;
  823.         WBool SetTargetsEnabled( WBool enabled );
  824.  
  825.         WBool GetAlwaysReadWriteTargets() const;
  826.         WBool SetAlwaysReadWriteTargets( WBool enabled );
  827.  
  828.         WBool GetThreadSafe() const;
  829.         WBool SetThreadSafe( WBool safe );
  830.  
  831.         WBool Add( WBool copyValues=FALSE, WBool append=FALSE,
  832.                    WBool copyIntoBuffer=FALSE );
  833.  
  834.         WBool CancelUpdate( WBool notifyTargets=TRUE );
  835.  
  836.         WBool ClearTargets();
  837.  
  838.         WBool Delete( WBool triggerEvent=TRUE, WBool notifyTargets=TRUE );
  839.  
  840.         WBool Edit();
  841.  
  842.         WBool MoreResults();
  843.  
  844.         WBool Move( WLong row, WBool notifyTargets=TRUE,
  845.                     WDSMoveType type=WDSMoveAbsolute, WBool trigger=TRUE );
  846.  
  847.         WBool Refresh();
  848.  
  849.         WBool RefreshTargets( WBool multiRow=FALSE );
  850.  
  851.         WBool RestoreState( const WDataSourceState state, WBool restore=TRUE );
  852.  
  853.         WBool SaveState( WDataSourceState & state );
  854.  
  855.         WBool ThreadLock( WBool wait=TRUE, WDWord timeout=0xFFFFFFFF );
  856.  
  857.         WBool ThreadUnlock();
  858.  
  859.         WBool Update( WBool triggerEvent=TRUE, WBool notifyTargets=TRUE );
  860.  
  861.         WDataValue GetValue( WShort index, WNativeDataType type=SQL_C_DEFAULT ) const;
  862.         WBool      SetValue( WShort index, const WDataValue & val );
  863.  
  864.         /***************************************************************
  865.          * Deprecated
  866.          ***************************************************************/
  867.  
  868.         virtual WBool GetErrorInfo( WString *errorMessage,
  869.                                     WString *state=NULL,
  870.                                     WLong *nativeErrorCode=NULL ) const;
  871.  
  872.         /***************************************************************
  873.          * Internal
  874.          ***************************************************************/
  875.  
  876.     public:
  877.  
  878.         virtual WBool CountRows( WBool ensureValid=TRUE );
  879.         virtual WBool CopySettingsToDriver( WBool assumeDefaults );
  880.         virtual WBool TransactionEvent( WEventID id, WEventData *data );
  881.         virtual WBool AddClone( WQuery *clone );
  882.         virtual WBool RemoveClone( WQuery *clone );
  883.  
  884.     protected:
  885.  
  886.         virtual WBool LateBindTarget( WQuery *query, WDataTarget *target );
  887.         virtual void  EventNotice( WEventID id, WEventNotice type );
  888.  
  889.         // These are called when the transaction object connects or
  890.         // disconnects from a database.  The Connect method gets called
  891.         // before the Connect event, the Disconnect event gets called
  892.         // before the method.
  893.  
  894.         virtual WBool Connect( WEventData *data );
  895.         virtual WBool Disconnect( WEventData *data );
  896.  
  897.         WTransaction  *_transaction;
  898.         WQuery        *_queryDriver;
  899. };
  900.  
  901. class WCMCLASS WQueryFactory : public WObject {
  902.  
  903.     protected:
  904.  
  905.         WQueryFactory();
  906.  
  907.         ~WQueryFactory();
  908.  
  909.     public:
  910.  
  911.         static WQueryFactory *GetFactoryObject();
  912.  
  913.         static WQuery *Allocate( const WString & dbmsName, WQuery *proxy );
  914.  
  915.         static void Register( WQuery * WCMDEF (*func)( const WString &, WQuery * ) );
  916.         static void Deregister( WQuery * WCMDEF (*func)( const WString &, WQuery * ) );
  917.  
  918.     protected:
  919.         wllist_header                list;
  920.  
  921.     private:
  922.         static WQueryFactory *_theObject;
  923. };
  924.  
  925. #endif
  926.