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