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(&amp;lt;structured-type&amp;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