summaryrefslogtreecommitdiffstats
path: root/offapi/com/sun/star/sdbc/XParameters.idl
blob: 6f1beca0a8c4de1575d48e97a6f2a80c54483e94 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */
#ifndef __com_sun_star_sdbc_XParameters_idl__
#define __com_sun_star_sdbc_XParameters_idl__

#include <com/sun/star/uno/XInterface.idl>

#include <com/sun/star/util/Date.idl>

#include <com/sun/star/util/DateTime.idl>

#include <com/sun/star/util/Time.idl>

 module com {  module sun {  module star {  module io {
 published interface XInputStream;
};};};};

#include <com/sun/star/sdbc/SQLException.idl>

 module com {  module sun {  module star {  module sdbc {

 published interface XRef;
 published interface XArray;
 published interface XBlob;
 published interface XClob;


/** is used for parameter setting, commonly implemented in conjunction with
    PreparedStatements.


    <p>
    <b>Note:</b> The setXXX methods for setting IN parameter values
    must specify types that are compatible with the defined SQL type of
    the input parameter. For instance, if the IN parameter has SQL type
    Integer, then the method
    com::sun::star::sdbc::XParameters::setInt()
    should be used.

    </p>
    <p>
    If arbitrary parameter type conversions are required, the method
    com::sun::star::sdbc::XParameters::setObject()
    should be used with a target SQL type.
    <br/>
    <br/>
    Example of setting a parameter;
    <code>con</code>
    is an active connection.
    </p>

    @code{.bas}
    pstmt = con.prepareStatement("UPDATE EMPLOYEES SET SALARY = ? WHERE ID = ?")
    pstmt.setDouble(1, 153833.00)
    pstmt.setLong(2, 110592)
    @endcode

    @see com::sun::star::sdbc::XPreparedStatement
 */
published interface XParameters: com::sun::star::uno::XInterface
{

    /** sets the designated parameter to SQL NULL.
     */
    void setNull([in]long parameterIndex,
                 [in]long sqlType) raises (SQLException);

    /** sets the designated parameter to SQL NULL.  This version of setNull should
        be used for user-named types and REF type parameters.  Examples
        of user-named types include: STRUCT, DISTINCT, OBJECT, and
        named array types.


        <p>
        <b>Note:</b> To be portable, applications must give the
        SQL type code and the fully-qualified SQL type name when specifying
        a NULL user-defined or REF parameter. In the case of a user-named type
        the name is the type name of the parameter itself.  For a REF
        parameter the name is the type name of the referenced type.  If
        a SDBC driver does not need the type code or type name information,
        it may ignore it.
        <br/>
        Although it is intended for user-named and Ref parameters,
        this method may be used to set a null parameter of any JDBC type.
        If the parameter does not have a user-named or REF type, the given
        typeName is ignored.
        </p>
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param sqlType
            the type of the column to set to `NULL`
        @param typeName
            the name of the type
        @throws SQLException
            if a database access error occurs.
     */
    void setObjectNull([in]long parameterIndex,
                        [in]long sqlType,
                        [in]string typeName) raises (SQLException);

    /** sets the designated parameter to a boolean value.  The driver converts this
        to a SQL BIT value when it sends it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setBoolean([in]long parameterIndex, [in]boolean x)
        raises (SQLException);

    /** sets the designated parameter to a byte value.  The driver converts this
        to a SQL TINYINT value when it sends it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setByte([in]long parameterIndex, [in]byte x) raises (SQLException);

    /** sets the designated parameter to a short value.  The driver converts this
        to a SQL SMALLINT value when it sends it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setShort([in]long parameterIndex, [in]short x) raises (SQLException);

    /** sets the designated parameter to a long value.  The driver converts this
        to a SQL INTEGER value when it sends it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setInt([in]long parameterIndex, [in]long x) raises (SQLException);

    /** sets the designated parameter to a hyper value.  The driver converts this
        to a SQL BIGINT value when it sends it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setLong([in]long parameterIndex, [in]hyper x) raises (SQLException);

    /** sets the designated parameter to a float value. The driver converts this
        to a SQL FLOAT value when it sends it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setFloat([in]long parameterIndex, [in]float x) raises (SQLException);

    /** sets the designated parameter to a double value.  The driver converts this
        to a SQL DOUBLE value when it sends it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setDouble([in]long parameterIndex, [in]double x) raises (SQLException);

    /** sets the designated parameter to a string value. The driver converts this
        to a SQL VARCHAR or LONGVARCHAR value (depending on the argument's
        size relative to the driver's limits on VARCHARs) when it sends
        it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setString([in]long parameterIndex, [in]string x) raises (SQLException);

    /** sets the designated parameter to a sequence of bytes.  The driver converts
        this to a SQL VARBINARY or LONGVARBINARY (depending on the
        argument's size relative to the driver's limits on VARBINARYs)
        when it sends it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setBytes([in]long parameterIndex, [in]sequence<byte> x)
        raises (SQLException);

    /** sets the designated parameter to a date value. The driver converts this
        to a SQL DATE value when it sends it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setDate([in]long parameterIndex, [in]com::sun::star::util::Date x)
        raises (SQLException);

    /** sets the designated parameter to a time value. The driver converts this
        to a SQL TIME value when it sends it to the database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setTime([in]long parameterIndex, [in]com::sun::star::util::Time x)
        raises (SQLException);

    /** sets the designated parameter to a datetime value.  The driver
        converts this to a SQL TIMESTAMP value when it sends it to the
        database.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setTimestamp([in]long parameterIndex,
                      [in]com::sun::star::util::DateTime x) raises (SQLException);

    /** sets the designated parameter to the given input stream, which will have
        the specified number of bytes.
        When a very large binary value is input to a LONGVARBINARY or LONGVARCHAR
        parameter, it may be more practical to send it via an
        com::sun::star::io::XInputStream
        . SDBC will read the data from the stream as needed, until it reaches end-of-file.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @param length
            the number of bytes in the stream
        @throws SQLException
            if a database access error occurs.
     */
    void setBinaryStream([in]long parameterIndex,
                            [in]com::sun::star::io::XInputStream x,
                             [in]long length) raises (SQLException);

    /** sets the designated parameter to the given input stream, which will have
        the specified number of bytes.
        When a very large binary value is input to a LONGVARCHAR
        parameter, it may be more practical to send it via a
        com::sun::star::io::XInputStream
        . SDBC will read the data from the stream as needed, until it reaches end-of-file.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @param length
            the number of characters in the stream
        @throws SQLException
            if a database access error occurs.
     */
    void setCharacterStream([in]long parameterIndex,
                             [in]com::sun::star::io::XInputStream x,
                             [in]long length) raises (SQLException);

    /** sets the value of a parameter using an any.


        <p>The given object will be converted to the targetSqlType
        before being sent to the database.
        If the object has a custom mapping (is of a class implementing SQLData),
        the SDBC driver should call its method <code>writeSQL</code> to write it
        to the SQL data stream.
        If, on the other hand, the object is of a service implementing Ref, Blob,
        Clob, Struct, or Array, the driver should pass it to the database as a
        value of the corresponding SQL type.
        </p>
        <p>Note that this method may be used to pass database-specific
        abstract data types.
        </p>
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setObject([in]long parameterIndex, [in]any x)
            raises (SQLException);

    /** set a value from the Datatype ANY for a parameter.



        <p>The given object will be converted to the targetSqlType
        before being sent to the database.
        If the object has a custom mapping (is of a class implementing SQLData),
        the SDBC driver should call its method <code>writeSQL</code> to write it
        to the SQL data stream.
        If, on the other hand, the object is of a service implementing Ref, Blob,
        Clob, Struct, or Array, the driver should pass it to the database as a
        value of the corresponding SQL type.
        </p>
        <p>Note that this method may be used to pass database-specific
        abstract data types.
        </p>
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @param targetSqlType
            the SQL type (as defined in
            com::sun::star::sdbc::DataType
            ) to be sent to the database. The scale argument may further qualify this type.
        @param scale
            for
            com::sun::star::sdbc::DataType::DECIMAL
             or
             com::sun::star::sdbc::DataType::NUMERIC
             types, this is the number of digits after the decimal point. For all other types, this value will be ignored.
        @throws SQLException
            if a database access error occurs.
     */
    void setObjectWithInfo([in]long parameterIndex,
                              [in]any x, [in]long targetSqlType, [in]long scale)
            raises (SQLException);

    /** sets a REF(&amp;lt;structured-type&amp;gt;) parameter.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setRef ([in]long parameterIndex, [in]XRef x) raises (SQLException);

    /** sets a BLOB parameter.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setBlob ([in]long parameterIndex, [in]XBlob x) raises (SQLException);

    /** sets a CLOB parameter.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setClob ([in]long parameterIndex, [in]XClob x) raises (SQLException);

    /** sets an Array parameter.
        @param parameterIndex
            the first parameter is 1, the second is 2, ...
        @param x
            the parameter value
        @throws SQLException
            if a database access error occurs.
     */
    void setArray ([in]long parameterIndex, [in]XArray x) raises (SQLException);


    /** clears the current parameter values immediately.


        <p>In general, parameter values remain in force for repeated use of a
        Statement. Setting a parameter value automatically clears its
        previous value. However, in some cases it is useful to immediately
        release the resources used by the current parameter values; this can
        be done by calling clearParameters.
        </p>
        @throws SQLException
            if a database access error occurs.
     */
    void clearParameters() raises (SQLException);
};


}; }; }; };

/*===========================================================================
===========================================================================*/
#endif

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */