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