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