offapi/com/sun/star/sdbc/PreparedStatement.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: PreparedStatement.idl,v $
  10  * $Revision: 1.17 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_sdbc_PreparedStatement_idl__
  31 #define __com_sun_star_sdbc_PreparedStatement_idl__
  32
  33 #ifndef __com_sun_star_lang_XComponent_idl__
  34 #include <com/sun/star/lang/XComponent.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_beans_XPropertySet_idl__
  38 #include <com/sun/star/beans/XPropertySet.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_util_XCancellable_idl__
  42 #include <com/sun/star/util/XCancellable.idl>
  43 #endif
  44
  45  module com {  module sun {  module star {  module sdbc {
  46
  47  published interface XPreparedStatement;
  48  published interface XPreparedBatchExecution;
  49  published interface XParameters;
  50  published interface XWarningsSupplier;
  51  published interface XMultipleResults;
  52  published interface XResultSetMetaDataSupplier;
  53  published interface XCloseable;
  54
  55
  56 /** represents a precompiled SQL statement.
  57      <P>
  58      A SQL statement is pre-compiled and stored in a PreparedStatement object.
  59      This object can then be used to efficiently execute this statement multiple
  60      times.
  61      </P>
  62      <P>
  63      <B>
  64      Note:
  65      </B>
  66      The
  67      <code>setXXX</code>
  68      methods for setting IN parameter values
  69      must specify types that are compatible with the defined SQL type of
  70      the input parameter. For instance, if the IN parameter has SQL type
  71      Integer, then the method
  72      <member scope="com::sun::star::sdbc">XParameters::setInt()</member>
  73      should be used.
  74      </P>
  75      <p>
  76      If arbitrary parameter type conversions are required, the method
  77      <member scope="com::sun::star::sdbc">XParameters::setObject()</member>
  78      should be used with a target SQL type.
  79      </p>
  80      <p>
  81      Example of setting a parameter; <code>con</code> is an active connection.
  82      @example:StarBASIC
  83      <listing>
  84      pstmt = con.prepareStatement("UPDATE EMPLOYEES SET SALARY = ? WHERE ID = ?")
  85      pstmt.setDouble(1, 153833.00)
  86      pstmt.setLong(2, 110592)
  87      </listing>
  88      </p>
  89      <P>
  90      Only one
  91      <type scope="com::sun::star::sdbc">ResultSet</type>
  92      per
  93      <type scope="com::sun::star::sdbc">Statement</type>
  94      can be open at any point in
  95      time. Therefore, if the reading of one ResultSet is interleaved
  96      with the reading of another, each must have been generated by
  97      different Statements. All statement
  98      <code>execute</code>
  99      methods implicitly close a statement's current ResultSet if an open one exists.
 100      </p>
 101  */
 102 published service PreparedStatement
 103 {
 104
 105     /** optional for implementation, controls the releasing of resources
 106              and the notification of registered listeners.
 107      */
 108     [optional] interface com::sun::star::lang::XComponent;
 109
 110
 111     /** freeing all resources of a statement. A related resultset will be
 112              freed as well.
 113      */
 114     interface XCloseable;
 115
 116     // gives access to the properties.
 117     interface com::sun::star::beans::XPropertySet;
 118
 119     /** could be used for cancelling the execution of SQL statements, if both
 120              the DBMS and the driver support aborting an SQL statement.
 121              The implementation is optional.
 122      */
 123     [optional] interface com::sun::star::util::XCancellable;
 124
 125     /** is the interface for executing SQL prepared commands.
 126      */
 127     interface XPreparedStatement;
 128
 129
 130     /** provides access to the description of the result set which would be generated by executing the
 131         <type>PreparedStatement</type>.
 132      */
 133     interface XResultSetMetaDataSupplier;
 134
 135
 136     /** is used for setting parameters before execution of the precompiled
 137              statement.
 138      */
 139     interface XParameters;
 140
 141
 142     /** provides the ability of batch execution. This interface is optional
 143              for execution.
 144              <p>
 145              A driver implementing batch execution must return
 146              <TRUE/>
 147              for
 148              <member scope= "com::sun::star::sdbc">XDatabaseMetaData::supportsBatchUpdates()</member>
 149              </p>
 150      */
 151     [optional] interface XPreparedBatchExecution;
 152
 153
 154     /** controls the chaining of warnings, which may occur on every call
 155              to the connected database. Chained warnings from previous calls will be
 156              cleared before processing a new call.
 157      */
 158     interface XWarningsSupplier;
 159
 160
 161     /** covers the handling of multiple results after executing an SQL command.
 162      */
 163     interface XMultipleResults;
 164
 165
 166     /** retrieves the number of seconds the driver will wait for a Statement
 167               to execute. If the limit is exceeded, a SQLException is thrown.
 168               There is no limitation, if set to zero.
 169      */
 170     [property] long QueryTimeOut;
 171
 172
 173     /** returns the maximum number of bytes allowed for any column value.
 174               <p>
 175               This limit is the maximum number of bytes that can be returned
 176               for any column value. The limit applies only to
 177               <member scope= "com::sun::star::sdbc">DataType::BINARY</member>
 178               ,
 179               <member scope= "com::sun::star::sdbc">DataType::VARBINARY</member>
 180               ,
 181               <member scope= "com::sun::star::sdbc">DataType::LONGVARBINARY</member>
 182               ,
 183               <member scope= "com::sun::star::sdbc">DataType::CHAR</member>
 184               ,
 185               <member scope= "com::sun::star::sdbc">DataType::VARCHAR</member>
 186               ,
 187               and
 188               <member scope= "com::sun::star::sdbc">DataType::LONGVARCHAR</member>
 189               columns.
 190               If the limit is exceeded, the excess data is silently discarded.
 191               </p>
 192               <p>
 193               There is no limitation, if set to zero.
 194               </p>
 195      */
 196     [property] long MaxFieldSize;
 197
 198
 199     /** retrieves the maximum number of rows that a ResultSet can contain.
 200              If the limit is exceeded, the excess rows are silently dropped.
 201              <br>There is no limitation, if set to zero.
 202      */
 203     [property] long MaxRows;
 204
 205
 206     /** defines the SQL cursor name that will be used by subsequent Statement
 207              <code>execute</code>
 208              methods.
 209              <p>
 210              This name can then be used in SQL positioned update/delete statements to
 211              identify the current row in the ResultSet generated by this statement. If
 212              the database does not support positioned update/delete, this property is
 213              a noop. To insure that a cursor has the proper isolation level to support
 214              updates, the cursor's SELECT statement should be of the form
 215              'select for update ...'. If the 'for update' phrase is omitted,
 216              positioned updates may fail.
 217              </p>
 218              <P>
 219              <B>
 220              Note:
 221              </B>
 222              By definition, positioned update/delete
 223              execution must be done by a different Statement than the one
 224              which generated the ResultSet being used for positioning. Also,
 225              cursor names must be unique within a connection.
 226              </p>
 227      */
 228     [property] string CursorName;
 229
 230
 231     /** retrieves the result set concurrency.
 232              @see com::sun::star::sdbc::ResultSetConcurrency
 233      */
 234     [property] long ResultSetConcurrency;
 235
 236
 237     /** Determine the result set type.
 238              @see com::sun::star::sdbc::ResultSetType
 239      */
 240     [property] long ResultSetType;
 241
 242
 243     /** retrieves the direction for fetching rows from database tables
 244              that is the default for result sets generated from this
 245              <code>Statement</code>
 246              object.
 247              <p>
 248              If this
 249              <code>Statement</code>
 250              object has not set a fetch direction,
 251              the return value is implementation-specific.
 252              </p>
 253      */
 254     [property] long FetchDirection;
 255
 256
 257     /** retrieves the number of result set rows that is the default fetch size
 258              for result sets generated from this
 259              <code>Statement</code>
 260              object.
 261              <p>
 262              If this
 263              <code>Statement</code>
 264              object has not set a fetch size,
 265              the return value is implementation-specific.
 266              </p>
 267      */
 268     [property] long FetchSize;
 269 };
 270
 271 //=============================================================================
 272
 273 }; }; }; };
 274
 275 #endif