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 */ 99published 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 273