update dev300-m58
[ooovba.git] / offapi / com / sun / star / sdbc / XParameters.idl
blob60a6d098068c741666407ebd518da2598ae48a8b
1 /*************************************************************************
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2008 by Sun Microsystems, Inc.
7 * OpenOffice.org - a multi-platform office productivity suite
9 * $RCSfile: XParameters.idl,v $
10 * $Revision: 1.11 $
12 * This file is part of OpenOffice.org.
14 * OpenOffice.org is free software: you can redistribute it and/or modify
15 * it under the terms of the GNU Lesser General Public License version 3
16 * only, as published by the Free Software Foundation.
18 * OpenOffice.org is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU Lesser General Public License version 3 for more details
22 * (a copy is included in the LICENSE file that accompanied this code).
24 * You should have received a copy of the GNU Lesser General Public License
25 * version 3 along with OpenOffice.org. If not, see
26 * <http://www.openoffice.org/license.html>
27 * for a copy of the LGPLv3 License.
29 ************************************************************************/
30 #ifndef __com_sun_star_sdbc_XParameters_idl__
31 #define __com_sun_star_sdbc_XParameters_idl__
33 #ifndef __com_sun_star_uno_XInterface_idl__
34 #include <com/sun/star/uno/XInterface.idl>
35 #endif
37 #ifndef __com_sun_star_util_Date_idl__
38 #include <com/sun/star/util/Date.idl>
39 #endif
41 #ifndef __com_sun_star_util_DateTime_idl__
42 #include <com/sun/star/util/DateTime.idl>
43 #endif
45 #ifndef __com_sun_star_util_Time_idl__
46 #include <com/sun/star/util/Time.idl>
47 #endif
49 module com { module sun { module star { module io {
50 published interface XInputStream;
51 };};};};
53 #ifndef __com_sun_star_sdbc_SQLException_idl__
54 #include <com/sun/star/sdbc/SQLException.idl>
55 #endif
57 module com { module sun { module star { module sdbc {
59 published interface XRef;
60 published interface XArray;
61 published interface XBlob;
62 published interface XClob;
65 /** is used for parameter setting, commonly implemented in conjunction with
66 PreparedStatements.
69 <p>
70 <b>Note:</b> The setXXX methods for setting IN parameter values
71 must specify types that are compatible with the defined SQL type of
72 the input parameter. For instance, if the IN parameter has SQL type
73 Integer, then the method
74 <member scope="com::sun::star::sdbc">XParameters::setInt()</member>
75 should be used.
77 </p>
78 <p>
79 If arbitrary parameter type conversions are required, the method
80 <member scope="com::sun::star::sdbc">XParameters::setObject()</member>
81 should be used with a target SQL type.
82 <br/>
83 <br/>
84 Example of setting a parameter;
85 <code>con</code>
86 is an active connection.
87 </p>
89 @example <listing>pstmt = con.prepareStatement("UPDATE EMPLOYEES SET SALARY = ? WHERE ID = ?")
90 pstmt.setDouble(1, 153833.00)
91 pstmt.setLong(2, 110592)
92 </listing>@see com::sun::star::sdbc::XPreparedStatement
94 published interface XParameters: com::sun::star::uno::XInterface
97 /** sets the designated parameter to SQL NULL.
99 void setNull([in]long parameterIndex,
100 [in]long sqlType) raises (SQLException);
101 //-------------------------------------------------------------------------
103 /** sets the designated parameter to SQL NULL. This version of setNull should
104 be used for user-named types and REF type parameters. Examples
105 of user-named types include: STRUCT, DISTINCT, OBJECT, and
106 named array types.
110 <b>Note:</b> To be portable, applications must give the
111 SQL type code and the fully-qualified SQL type name when specifying
112 a NULL user-defined or REF parameter. In the case of a user-named type
113 the name is the type name of the parameter itself. For a REF
114 parameter the name is the type name of the referenced type. If
115 a SDBC driver does not need the type code or type name information,
116 it may ignore it.
117 <br/>
118 Although it is intended for user-named and Ref parameters,
119 this method may be used to set a null parameter of any JDBC type.
120 If the parameter does not have a user-named or REF type, the given
121 typeName is ignored.
122 </p>
123 @param parameterIndex
124 the first parameter is 1, the second is 2, ...
125 @param sqlType
126 the type of the column to set to <NULL/>
127 @param typeName
128 the name of the type
129 @throws SQLException
130 if a database access error occurs.
132 void setObjectNull([in]long parameterIndex,
133 [in]long sqlType,
134 [in]string typeName) raises (SQLException);
135 //-------------------------------------------------------------------------
137 /** sets the designated parameter to a boolean value. The driver converts this
138 to a SQL BIT value when it sends it to the database.
139 @param parameterIndex
140 the first parameter is 1, the second is 2, ...
141 @param x
142 the parameter value
143 @throws SQLException
144 if a database access error occurs.
146 void setBoolean([in]long parameterIndex, [in]boolean x)
147 raises (SQLException);
148 //-------------------------------------------------------------------------
150 /** sets the designated parameter to a byte value. The driver converts this
151 to a SQL TINYINT value when it sends it to the database.
152 @param parameterIndex
153 the first parameter is 1, the second is 2, ...
154 @param x
155 the parameter value
156 @throws SQLException
157 if a database access error occurs.
159 void setByte([in]long parameterIndex, [in]byte x) raises (SQLException);
160 //-------------------------------------------------------------------------
162 /** sets the designated parameter to a short value. The driver converts this
163 to a SQL SMALLINT value when it sends it to the database.
164 @param parameterIndex
165 the first parameter is 1, the second is 2, ...
166 @param x
167 the parameter value
168 @throws SQLException
169 if a database access error occurs.
171 void setShort([in]long parameterIndex, [in]short x) raises (SQLException);
172 //-------------------------------------------------------------------------
174 /** sets the designated parameter to a long value. The driver converts this
175 to a SQL INTEGER value when it sends it to the database.
176 @param parameterIndex
177 the first parameter is 1, the second is 2, ...
178 @param x
179 the parameter value
180 @throws SQLException
181 if a database access error occurs.
183 void setInt([in]long parameterIndex, [in]long x) raises (SQLException);
184 //-------------------------------------------------------------------------
186 /** sets the designated parameter to a hyper value. The driver converts this
187 to a SQL BIGINT value when it sends it to the database.
188 @param parameterIndex
189 the first parameter is 1, the second is 2, ...
190 @param x
191 the parameter value
192 @throws SQLException
193 if a database access error occurs.
195 void setLong([in]long parameterIndex, [in]hyper x) raises (SQLException);
196 //-------------------------------------------------------------------------
198 /** sets the designated parameter to a float value. The driver converts this
199 to a SQL FLOAT value when it sends it to the database.
200 @param parameterIndex
201 the first parameter is 1, the second is 2, ...
202 @param x
203 the parameter value
204 @throws SQLException
205 if a database access error occurs.
207 void setFloat([in]long parameterIndex, [in]float x) raises (SQLException);
208 //-------------------------------------------------------------------------
210 /** sets the designated parameter to a double value. The driver converts this
211 to a SQL DOUBLE value when it sends it to the database.
212 @param parameterIndex
213 the first parameter is 1, the second is 2, ...
214 @param x
215 the parameter value
216 @throws SQLException
217 if a database access error occurs.
219 void setDouble([in]long parameterIndex, [in]double x) raises (SQLException);
220 //-------------------------------------------------------------------------
222 /** sets the designated parameter to a string value. The driver converts this
223 to a SQL VARCHAR or LONGVARCHAR value (depending on the argument's
224 size relative to the driver's limits on VARCHARs) when it sends
225 it to the database.
226 @param parameterIndex
227 the first parameter is 1, the second is 2, ...
228 @param x
229 the parameter value
230 @throws SQLException
231 if a database access error occurs.
233 void setString([in]long parameterIndex, [in]string x) raises (SQLException);
234 //-------------------------------------------------------------------------
236 /** sets the designated parameter to a sequence of bytes. The driver converts
237 this to a SQL VARBINARY or LONGVARBINARY (depending on the
238 argument's size relative to the driver's limits on VARBINARYs)
239 when it sends it to the database.
240 @param parameterIndex
241 the first parameter is 1, the second is 2, ...
242 @param x
243 the parameter value
244 @throws SQLException
245 if a database access error occurs.
247 void setBytes([in]long parameterIndex, [in]sequence<byte> x)
248 raises (SQLException);
249 //-------------------------------------------------------------------------
251 /** sets the designated parameter to a date value. The driver converts this
252 to a SQL DATE value when it sends it to the database.
253 @param parameterIndex
254 the first parameter is 1, the second is 2, ...
255 @param x
256 the parameter value
257 @throws SQLException
258 if a database access error occurs.
260 void setDate([in]long parameterIndex, [in]com::sun::star::util::Date x)
261 raises (SQLException);
262 //-------------------------------------------------------------------------
264 /** sets the designated parameter to a time value. The driver converts this
265 to a SQL TIME value when it sends it to the database.
266 @param parameterIndex
267 the first parameter is 1, the second is 2, ...
268 @param x
269 the parameter value
270 @throws SQLException
271 if a database access error occurs.
273 void setTime([in]long parameterIndex, [in]com::sun::star::util::Time x)
274 raises (SQLException);
275 //-------------------------------------------------------------------------
277 /** sets the designated parameter to a datetime value. The driver
278 converts this to a SQL TIMESTAMP value when it sends it to the
279 database.
280 @param parameterIndex
281 the first parameter is 1, the second is 2, ...
282 @param x
283 the parameter value
284 @throws SQLException
285 if a database access error occurs.
287 void setTimestamp([in]long parameterIndex,
288 [in]com::sun::star::util::DateTime x) raises (SQLException);
289 //-------------------------------------------------------------------------
291 /** sets the designated parameter to the given input stream, which will have
292 the specified number of bytes.
293 When a very large binary value is input to a LONGVARBINARY or LONGVARCHAR
294 parameter, it may be more practical to send it via an
295 <type scope="com::sun::star::io">XInputStream</type>
296 . SDBC will read the data from the stream as needed, until it reaches end-of-file.
297 @param parameterIndex
298 the first parameter is 1, the second is 2, ...
299 @param x
300 the parameter value
301 @param length
302 the number of bytes in the stream
303 @throws SQLException
304 if a database access error occurs.
306 void setBinaryStream([in]long parameterIndex,
307 [in]com::sun::star::io::XInputStream x,
308 [in]long length) raises (SQLException);
309 //-------------------------------------------------------------------------
311 /** sets the designated parameter to the given input stream, which will have
312 the specified number of bytes.
313 When a very large binary value is input to a LONGVARCHAR
314 parameter, it may be more practical to send it via a
315 <type scope="com::sun::star::io">XInputStream</type>
316 . SDBC will read the data from the stream as needed, until it reaches end-of-file.
317 @param parameterIndex
318 the first parameter is 1, the second is 2, ...
319 @param x
320 the parameter value
321 @param length
322 the number of characters in the stream
323 @throws SQLException
324 if a database access error occurs.
326 void setCharacterStream([in]long parameterIndex,
327 [in]com::sun::star::io::XInputStream x,
328 [in]long length) raises (SQLException);
329 //-------------------------------------------------------------------------
331 /** sets the value of a parameter using an any.
334 <p>The given object will be converted to the targetSqlType
335 before being sent to the database.
336 If the object has a custom mapping (is of a class implementing SQLData),
337 the SDBC driver should call its method <code>writeSQL</code> to write it
338 to the SQL data stream.
339 If, on the other hand, the object is of a service implementing Ref, Blob,
340 Clob, Struct, or Array, the driver should pass it to the database as a
341 value of the corresponding SQL type.
342 </p>
343 <p>Note that this method may be used to pass database-specific
344 abstract data types.
345 </p>
346 @param parameterIndex
347 the first parameter is 1, the second is 2, ...
348 @param x
349 the parameter value
350 @throws SQLException
351 if a database access error occurs.
353 void setObject([in]long parameterIndex, [in]any x)
354 raises (SQLException);
355 //-------------------------------------------------------------------------
357 /** set a value from the Datatype ANY for a parameter.
361 <p>The given object will be converted to the targetSqlType
362 before being sent to the database.
363 If the object has a custom mapping (is of a class implementing SQLData),
364 the SDBC driver should call its method <code>writeSQL</code> to write it
365 to the SQL data stream.
366 If, on the other hand, the object is of a service implementing Ref, Blob,
367 Clob, Struct, or Array, the driver should pass it to the database as a
368 value of the corresponding SQL type.
369 </p>
370 <p>Note that this method may be used to pass database-specific
371 abstract data types.
372 </p>
373 @param parameterIndex
374 the first parameter is 1, the second is 2, ...
375 @param x
376 the parameter value
377 @param targetSqlType
378 the SQL type (as defined in
379 <type scope="com::sun::star::sdbc">DataType</type>
380 ) to be sent to the database. The scale argument may further qualify this type.
381 @param scale
382 for
383 <member scope="com::sun::star::sdbc">DataType::DECIMAL</member>
385 <member scope="com::sun::star::sdbc">DataType::NUMERIC</member>
386 types, this is the number of digits after the decimal point. For all other types, this value will be ignored.
387 @throws SQLException
388 if a database access error occurs.
390 void setObjectWithInfo([in]long parameterIndex,
391 [in]any x, [in]long targetSqlType, [in]long scale)
392 raises (SQLException);
393 //-------------------------------------------------------------------------
395 /** sets a REF(&amp;lt;structured-type&amp;gt;) parameter.
396 @param parameterIndex
397 the first parameter is 1, the second is 2, ...
398 @param x
399 the parameter value
400 @throws SQLException
401 if a database access error occurs.
403 void setRef ([in]long parameterIndex, [in]XRef x) raises (SQLException);
404 //-------------------------------------------------------------------------
406 /** sets a BLOB parameter.
407 @param parameterIndex
408 the first parameter is 1, the second is 2, ...
409 @param x
410 the parameter value
411 @throws SQLException
412 if a database access error occurs.
414 void setBlob ([in]long parameterIndex, [in]XBlob x) raises (SQLException);
415 //-------------------------------------------------------------------------
417 /** sets a CLOB parameter.
418 @param parameterIndex
419 the first parameter is 1, the second is 2, ...
420 @param x
421 the parameter value
422 @throws SQLException
423 if a database access error occurs.
425 void setClob ([in]long parameterIndex, [in]XClob x) raises (SQLException);
426 //-------------------------------------------------------------------------
428 /** sets an Array parameter.
429 @param parameterIndex
430 the first parameter is 1, the second is 2, ...
431 @param x
432 the parameter value
433 @throws SQLException
434 if a database access error occurs.
436 void setArray ([in]long parameterIndex, [in]XArray x) raises (SQLException);
438 //-------------------------------------------------------------------------
440 /** clears the current parameter values immediately.
443 <p>In general, parameter values remain in force for repeated use of a
444 Statement. Setting a parameter value automatically clears its
445 previous value. However, in some cases it is useful to immediately
446 release the resources used by the current parameter values; this can
447 be done by calling clearParameters.
448 </p>
449 @throws SQLException
450 if a database access error occurs.
452 void clearParameters() raises (SQLException);
455 //=============================================================================
457 }; }; }; };
459 /*===========================================================================
460 ===========================================================================*/
461 #endif