xref: /trunk/main/offapi/com/sun/star/sdbc/XClob.idl (revision d1766043)
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_XClob_idl__
24#define __com_sun_star_sdbc_XClob_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29
30 module com {  module sun {  module star {  module io {
31 published interface XInputStream;
32};};};};
33
34#ifndef __com_sun_star_sdbc_SQLException_idl__
35#include <com/sun/star/sdbc/SQLException.idl>
36#endif
37
38 module com {  module sun {  module star {  module sdbc {
39
40
41/** is the mapping for the SQL
42	<code>CLOB</code>
43	type.
44
45
46	<p>
47	A SQL
48	<code>CLOB</code>
49	is a built-in type
50	that stores a Character Large Object as a column value in a row of
51	a database table.
52	The driver implements a
53	<code>Clob</code>
54	object using a SQL
55	<code>locator(CLOB)</code>
56	, which means that a
57	<code>Clob</code>
58	object
59	contains a logical pointer to the SQL
60	<code>CLOB</code>
61	data rather than
62	the data itself. A
63	<code>Clob</code>
64	object is valid for the duration
65	of the transaction in which it was created.
66	</p>
67	<p>
68	The
69	<code>Clob</code>
70	interface provides methods for getting the
71	length of a SQL
72	<code>CLOB</code>
73	(Character Large Object) value,
74	for materializing a
75	<code>CLOB</code>
76	value on the client, and for
77	searching for a substring or
78	<code>CLOB</code>
79	object within a
80	<code>CLOB</code>
81	value.
82	</p>
83	<p>
84	Methods in the interfaces
85	<type scope="com::sun::star::sdbc">XResultSet</type>
86	,
87	and
88	<type scope="com::sun::star::sdbc">XPreparedStatement</type>
89	, such as
90	<code>getClob</code>
91	and
92	<code>setClob</code>
93	allow a programmer to
94	access the SQL
95	<code>CLOB</code>
96	.
97	</p>
98 */
99published interface XClob: com::sun::star::uno::XInterface
100{
101	//-------------------------------------------------------------------------
102
103	/** returns the number of characters in the
104		<code>CLOB</code>
105		value
106		designated by this
107		<code>Clob</code>
108		object.
109		@returns
110			the length of the CLOB object
111		@throws SQLException
112			if a database access error occurs.
113	 */
114	hyper length() raises (SQLException);
115
116  	//-------------------------------------------------------------------------
117
118	/** returns a copy of the specified substring in the
119		<code>Clob</code>
120		value
121		designated by this
122		<code>Clob</code>
123		object.
124
125
126		<p>
127		The substring begins at position <code>pos</code> and has up
128		to
129		<code>length</code>
130		consecutive characters.
131		</p>
132		@param pos
133			the starting position
134		@param length
135			the length of the substring
136		@returns
137			the substring
138		@throws SQLException
139			if a database access error occurs.
140	 */
141	string getSubString([in]hyper pos, [in]long length) raises (SQLException);
142
143	//-------------------------------------------------------------------------
144
145	/** gets the
146		<code>Clob</code>
147		contents as a stream.
148		@returns
149			the stream
150		@throws SQLException
151			if a database access error occurs.
152	 */
153	com::sun::star::io::XInputStream getCharacterStream() raises (SQLException);
154
155	//-------------------------------------------------------------------------
156
157	/** determines the character position at which the specified substring
158		<code>searchstr</code>
159		appears in the
160		<code>Clob</code>
161		. The search begins at position
162		<code>start</code>
163		.
164		@param searchstr
165			the string to search
166		@param start
167			the starting position
168		@returns
169			the length of the CLOB object
170		@throws SQLException
171			if a database access error occurs.
172	 */
173	hyper position([in]string searchstr, [in]long start)
174		raises (SQLException);
175
176  	//-------------------------------------------------------------------------
177
178	/** determines the position at which the specified
179		<code>Clob</code>
180		object
181		<code>pattern</code>
182		appears in this
183		<code>Clob</code>
184		object. The search begins at position
185		<code>start</code>
186		.
187		@param pattern
188			the CLOB to search
189		@param start
190			the starting position
191		@returns
192			the position of the CLOB inside
193		@throws SQLException
194			if a database access error occurs.
195	 */
196	hyper positionOfClob([in]XClob pattern, [in]hyper start)
197		raises (SQLException);
198};
199
200//=============================================================================
201
202}; }; }; };
203
204/*===========================================================================
205===========================================================================*/
206#endif
207