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_XParameters_idl__ 28#define __com_sun_star_sdbc_XParameters_idl__ 29 30#ifndef __com_sun_star_uno_XInterface_idl__ 31#include <com/sun/star/uno/XInterface.idl> 32#endif 33 34#ifndef __com_sun_star_util_Date_idl__ 35#include <com/sun/star/util/Date.idl> 36#endif 37 38#ifndef __com_sun_star_util_DateTime_idl__ 39#include <com/sun/star/util/DateTime.idl> 40#endif 41 42#ifndef __com_sun_star_util_Time_idl__ 43#include <com/sun/star/util/Time.idl> 44#endif 45 46 module com { module sun { module star { module io { 47 published interface XInputStream; 48};};};}; 49 50#ifndef __com_sun_star_sdbc_SQLException_idl__ 51#include <com/sun/star/sdbc/SQLException.idl> 52#endif 53 54 module com { module sun { module star { module sdbc { 55 56 published interface XRef; 57 published interface XArray; 58 published interface XBlob; 59 published interface XClob; 60 61 62/** is used for parameter setting, commonly implemented in conjunction with 63 PreparedStatements. 64 65 66 <p> 67 <b>Note:</b> The setXXX methods for setting IN parameter values 68 must specify types that are compatible with the defined SQL type of 69 the input parameter. For instance, if the IN parameter has SQL type 70 Integer, then the method 71 <member scope="com::sun::star::sdbc">XParameters::setInt()</member> 72 should be used. 73 74 </p> 75 <p> 76 If arbitrary parameter type conversions are required, the method 77 <member scope="com::sun::star::sdbc">XParameters::setObject()</member> 78 should be used with a target SQL type. 79 <br/> 80 <br/> 81 Example of setting a parameter; 82 <code>con</code> 83 is an active connection. 84 </p> 85 86 @example <listing>pstmt = con.prepareStatement("UPDATE EMPLOYEES SET SALARY = ? WHERE ID = ?") 87 pstmt.setDouble(1, 153833.00) 88 pstmt.setLong(2, 110592) 89 </listing>@see com::sun::star::sdbc::XPreparedStatement 90 */ 91published interface XParameters: com::sun::star::uno::XInterface 92{ 93 94 /** sets the designated parameter to SQL NULL. 95 */ 96 void setNull([in]long parameterIndex, 97 [in]long sqlType) raises (SQLException); 98 //------------------------------------------------------------------------- 99 100 /** sets the designated parameter to SQL NULL. This version of setNull should 101 be used for user-named types and REF type parameters. Examples 102 of user-named types include: STRUCT, DISTINCT, OBJECT, and 103 named array types. 104 105 106 <p> 107 <b>Note:</b> To be portable, applications must give the 108 SQL type code and the fully-qualified SQL type name when specifying 109 a NULL user-defined or REF parameter. In the case of a user-named type 110 the name is the type name of the parameter itself. For a REF 111 parameter the name is the type name of the referenced type. If 112 a SDBC driver does not need the type code or type name information, 113 it may ignore it. 114 <br/> 115 Although it is intended for user-named and Ref parameters, 116 this method may be used to set a null parameter of any JDBC type. 117 If the parameter does not have a user-named or REF type, the given 118 typeName is ignored. 119 </p> 120 @param parameterIndex 121 the first parameter is 1, the second is 2, ... 122 @param sqlType 123 the type of the column to set to <NULL/> 124 @param typeName 125 the name of the type 126 @throws SQLException 127 if a database access error occurs. 128 */ 129 void setObjectNull([in]long parameterIndex, 130 [in]long sqlType, 131 [in]string typeName) raises (SQLException); 132 //------------------------------------------------------------------------- 133 134 /** sets the designated parameter to a boolean value. The driver converts this 135 to a SQL BIT value when it sends it to the database. 136 @param parameterIndex 137 the first parameter is 1, the second is 2, ... 138 @param x 139 the parameter value 140 @throws SQLException 141 if a database access error occurs. 142 */ 143 void setBoolean([in]long parameterIndex, [in]boolean x) 144 raises (SQLException); 145 //------------------------------------------------------------------------- 146 147 /** sets the designated parameter to a byte value. The driver converts this 148 to a SQL TINYINT value when it sends it to the database. 149 @param parameterIndex 150 the first parameter is 1, the second is 2, ... 151 @param x 152 the parameter value 153 @throws SQLException 154 if a database access error occurs. 155 */ 156 void setByte([in]long parameterIndex, [in]byte x) raises (SQLException); 157 //------------------------------------------------------------------------- 158 159 /** sets the designated parameter to a short value. The driver converts this 160 to a SQL SMALLINT value when it sends it to the database. 161 @param parameterIndex 162 the first parameter is 1, the second is 2, ... 163 @param x 164 the parameter value 165 @throws SQLException 166 if a database access error occurs. 167 */ 168 void setShort([in]long parameterIndex, [in]short x) raises (SQLException); 169 //------------------------------------------------------------------------- 170 171 /** sets the designated parameter to a long value. The driver converts this 172 to a SQL INTEGER value when it sends it to the database. 173 @param parameterIndex 174 the first parameter is 1, the second is 2, ... 175 @param x 176 the parameter value 177 @throws SQLException 178 if a database access error occurs. 179 */ 180 void setInt([in]long parameterIndex, [in]long x) raises (SQLException); 181 //------------------------------------------------------------------------- 182 183 /** sets the designated parameter to a hyper value. The driver converts this 184 to a SQL BIGINT value when it sends it to the database. 185 @param parameterIndex 186 the first parameter is 1, the second is 2, ... 187 @param x 188 the parameter value 189 @throws SQLException 190 if a database access error occurs. 191 */ 192 void setLong([in]long parameterIndex, [in]hyper x) raises (SQLException); 193 //------------------------------------------------------------------------- 194 195 /** sets the designated parameter to a float value. The driver converts this 196 to a SQL FLOAT value when it sends it to the database. 197 @param parameterIndex 198 the first parameter is 1, the second is 2, ... 199 @param x 200 the parameter value 201 @throws SQLException 202 if a database access error occurs. 203 */ 204 void setFloat([in]long parameterIndex, [in]float x) raises (SQLException); 205 //------------------------------------------------------------------------- 206 207 /** sets the designated parameter to a double value. The driver converts this 208 to a SQL DOUBLE value when it sends it to the database. 209 @param parameterIndex 210 the first parameter is 1, the second is 2, ... 211 @param x 212 the parameter value 213 @throws SQLException 214 if a database access error occurs. 215 */ 216 void setDouble([in]long parameterIndex, [in]double x) raises (SQLException); 217 //------------------------------------------------------------------------- 218 219 /** sets the designated parameter to a string value. The driver converts this 220 to a SQL VARCHAR or LONGVARCHAR value (depending on the argument's 221 size relative to the driver's limits on VARCHARs) when it sends 222 it to the database. 223 @param parameterIndex 224 the first parameter is 1, the second is 2, ... 225 @param x 226 the parameter value 227 @throws SQLException 228 if a database access error occurs. 229 */ 230 void setString([in]long parameterIndex, [in]string x) raises (SQLException); 231 //------------------------------------------------------------------------- 232 233 /** sets the designated parameter to a sequence of bytes. The driver converts 234 this to a SQL VARBINARY or LONGVARBINARY (depending on the 235 argument's size relative to the driver's limits on VARBINARYs) 236 when it sends it to the database. 237 @param parameterIndex 238 the first parameter is 1, the second is 2, ... 239 @param x 240 the parameter value 241 @throws SQLException 242 if a database access error occurs. 243 */ 244 void setBytes([in]long parameterIndex, [in]sequence<byte> x) 245 raises (SQLException); 246 //------------------------------------------------------------------------- 247 248 /** sets the designated parameter to a date value. The driver converts this 249 to a SQL DATE value when it sends it to the database. 250 @param parameterIndex 251 the first parameter is 1, the second is 2, ... 252 @param x 253 the parameter value 254 @throws SQLException 255 if a database access error occurs. 256 */ 257 void setDate([in]long parameterIndex, [in]com::sun::star::util::Date x) 258 raises (SQLException); 259 //------------------------------------------------------------------------- 260 261 /** sets the designated parameter to a time value. The driver converts this 262 to a SQL TIME value when it sends it to the database. 263 @param parameterIndex 264 the first parameter is 1, the second is 2, ... 265 @param x 266 the parameter value 267 @throws SQLException 268 if a database access error occurs. 269 */ 270 void setTime([in]long parameterIndex, [in]com::sun::star::util::Time x) 271 raises (SQLException); 272 //------------------------------------------------------------------------- 273 274 /** sets the designated parameter to a datetime value. The driver 275 converts this to a SQL TIMESTAMP value when it sends it to the 276 database. 277 @param parameterIndex 278 the first parameter is 1, the second is 2, ... 279 @param x 280 the parameter value 281 @throws SQLException 282 if a database access error occurs. 283 */ 284 void setTimestamp([in]long parameterIndex, 285 [in]com::sun::star::util::DateTime x) raises (SQLException); 286 //------------------------------------------------------------------------- 287 288 /** sets the designated parameter to the given input stream, which will have 289 the specified number of bytes. 290 When a very large binary value is input to a LONGVARBINARY or LONGVARCHAR 291 parameter, it may be more practical to send it via an 292 <type scope="com::sun::star::io">XInputStream</type> 293 . SDBC will read the data from the stream as needed, until it reaches end-of-file. 294 @param parameterIndex 295 the first parameter is 1, the second is 2, ... 296 @param x 297 the parameter value 298 @param length 299 the number of bytes in the stream 300 @throws SQLException 301 if a database access error occurs. 302 */ 303 void setBinaryStream([in]long parameterIndex, 304 [in]com::sun::star::io::XInputStream x, 305 [in]long length) raises (SQLException); 306 //------------------------------------------------------------------------- 307 308 /** sets the designated parameter to the given input stream, which will have 309 the specified number of bytes. 310 When a very large binary value is input to a LONGVARCHAR 311 parameter, it may be more practical to send it via a 312 <type scope="com::sun::star::io">XInputStream</type> 313 . SDBC will read the data from the stream as needed, until it reaches end-of-file. 314 @param parameterIndex 315 the first parameter is 1, the second is 2, ... 316 @param x 317 the parameter value 318 @param length 319 the number of characters in the stream 320 @throws SQLException 321 if a database access error occurs. 322 */ 323 void setCharacterStream([in]long parameterIndex, 324 [in]com::sun::star::io::XInputStream x, 325 [in]long length) raises (SQLException); 326 //------------------------------------------------------------------------- 327 328 /** sets the value of a parameter using an any. 329 330 331 <p>The given object will be converted to the targetSqlType 332 before being sent to the database. 333 If the object has a custom mapping (is of a class implementing SQLData), 334 the SDBC driver should call its method <code>writeSQL</code> to write it 335 to the SQL data stream. 336 If, on the other hand, the object is of a service implementing Ref, Blob, 337 Clob, Struct, or Array, the driver should pass it to the database as a 338 value of the corresponding SQL type. 339 </p> 340 <p>Note that this method may be used to pass database-specific 341 abstract data types. 342 </p> 343 @param parameterIndex 344 the first parameter is 1, the second is 2, ... 345 @param x 346 the parameter value 347 @throws SQLException 348 if a database access error occurs. 349 */ 350 void setObject([in]long parameterIndex, [in]any x) 351 raises (SQLException); 352 //------------------------------------------------------------------------- 353 354 /** set a value from the Datatype ANY for a parameter. 355 356 357 358 <p>The given object will be converted to the targetSqlType 359 before being sent to the database. 360 If the object has a custom mapping (is of a class implementing SQLData), 361 the SDBC driver should call its method <code>writeSQL</code> to write it 362 to the SQL data stream. 363 If, on the other hand, the object is of a service implementing Ref, Blob, 364 Clob, Struct, or Array, the driver should pass it to the database as a 365 value of the corresponding SQL type. 366 </p> 367 <p>Note that this method may be used to pass database-specific 368 abstract data types. 369 </p> 370 @param parameterIndex 371 the first parameter is 1, the second is 2, ... 372 @param x 373 the parameter value 374 @param targetSqlType 375 the SQL type (as defined in 376 <type scope="com::sun::star::sdbc">DataType</type> 377 ) to be sent to the database. The scale argument may further qualify this type. 378 @param scale 379 for 380 <member scope="com::sun::star::sdbc">DataType::DECIMAL</member> 381 or 382 <member scope="com::sun::star::sdbc">DataType::NUMERIC</member> 383 types, this is the number of digits after the decimal point. For all other types, this value will be ignored. 384 @throws SQLException 385 if a database access error occurs. 386 */ 387 void setObjectWithInfo([in]long parameterIndex, 388 [in]any x, [in]long targetSqlType, [in]long scale) 389 raises (SQLException); 390 //------------------------------------------------------------------------- 391 392 /** sets a REF(&lt;structured-type&gt;) parameter. 393 @param parameterIndex 394 the first parameter is 1, the second is 2, ... 395 @param x 396 the parameter value 397 @throws SQLException 398 if a database access error occurs. 399 */ 400 void setRef ([in]long parameterIndex, [in]XRef x) raises (SQLException); 401 //------------------------------------------------------------------------- 402 403 /** sets a BLOB parameter. 404 @param parameterIndex 405 the first parameter is 1, the second is 2, ... 406 @param x 407 the parameter value 408 @throws SQLException 409 if a database access error occurs. 410 */ 411 void setBlob ([in]long parameterIndex, [in]XBlob x) raises (SQLException); 412 //------------------------------------------------------------------------- 413 414 /** sets a CLOB parameter. 415 @param parameterIndex 416 the first parameter is 1, the second is 2, ... 417 @param x 418 the parameter value 419 @throws SQLException 420 if a database access error occurs. 421 */ 422 void setClob ([in]long parameterIndex, [in]XClob x) raises (SQLException); 423 //------------------------------------------------------------------------- 424 425 /** sets an Array parameter. 426 @param parameterIndex 427 the first parameter is 1, the second is 2, ... 428 @param x 429 the parameter value 430 @throws SQLException 431 if a database access error occurs. 432 */ 433 void setArray ([in]long parameterIndex, [in]XArray x) raises (SQLException); 434 435 //------------------------------------------------------------------------- 436 437 /** clears the current parameter values immediately. 438 439 440 <p>In general, parameter values remain in force for repeated use of a 441 Statement. Setting a parameter value automatically clears its 442 previous value. However, in some cases it is useful to immediately 443 release the resources used by the current parameter values; this can 444 be done by calling clearParameters. 445 </p> 446 @throws SQLException 447 if a database access error occurs. 448 */ 449 void clearParameters() raises (SQLException); 450}; 451 452//============================================================================= 453 454}; }; }; }; 455 456/*=========================================================================== 457===========================================================================*/ 458#endif 459