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

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