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

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