offapi/com/sun/star/sdbc/XClob.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27 #ifndef __com_sun_star_sdbc_XClob_idl__
  28 #define __com_sun_star_sdbc_XClob_idl__
  29
  30 #ifndef __com_sun_star_uno_XInterface_idl__
  31 #include <com/sun/star/uno/XInterface.idl>
  32 #endif
  33
  34  module com {  module sun {  module star {  module io {
  35  published interface XInputStream;
  36 };};};};
  37
  38 #ifndef __com_sun_star_sdbc_SQLException_idl__
  39 #include <com/sun/star/sdbc/SQLException.idl>
  40 #endif
  41
  42  module com {  module sun {  module star {  module sdbc {
  43
  44
  45 /** is the mapping for the SQL
  46     <code>CLOB</code>
  47     type.
  48
  49
  50     <p>
  51     A SQL
  52     <code>CLOB</code>
  53     is a built-in type
  54     that stores a Character Large Object as a column value in a row of
  55     a database table.
  56     The driver implements a
  57     <code>Clob</code>
  58     object using a SQL
  59     <code>locator(CLOB)</code>
  60     , which means that a
  61     <code>Clob</code>
  62     object
  63     contains a logical pointer to the SQL
  64     <code>CLOB</code>
  65     data rather than
  66     the data itself. A
  67     <code>Clob</code>
  68     object is valid for the duration
  69     of the transaction in which it was created.
  70     </p>
  71     <p>
  72     The
  73     <code>Clob</code>
  74     interface provides methods for getting the
  75     length of a SQL
  76     <code>CLOB</code>
  77     (Character Large Object) value,
  78     for materializing a
  79     <code>CLOB</code>
  80     value on the client, and for
  81     searching for a substring or
  82     <code>CLOB</code>
  83     object within a
  84     <code>CLOB</code>
  85     value.
  86     </p>
  87     <p>
  88     Methods in the interfaces
  89     <type scope="com::sun::star::sdbc">XResultSet</type>
  90     ,
  91     and
  92     <type scope="com::sun::star::sdbc">XPreparedStatement</type>
  93     , such as
  94     <code>getClob</code>
  95     and
  96     <code>setClob</code>
  97     allow a programmer to
  98     access the SQL
  99     <code>CLOB</code>
 100     .
 101     </p>
 102  */
 103 published interface XClob: com::sun::star::uno::XInterface
 104 {
 105     //-------------------------------------------------------------------------
 106
 107     /** returns the number of characters in the
 108         <code>CLOB</code>
 109         value
 110         designated by this
 111         <code>Clob</code>
 112         object.
 113         @returns
 114             the length of the CLOB object
 115         @throws SQLException
 116             if a database access error occurs.
 117      */
 118     hyper length() raises (SQLException);
 119
 120       //-------------------------------------------------------------------------
 121
 122     /** returns a copy of the specified substring in the
 123         <code>Clob</code>
 124         value
 125         designated by this
 126         <code>Clob</code>
 127         object.
 128
 129
 130         <p>
 131         The substring begins at position <code>pos</code> and has up
 132         to
 133         <code>length</code>
 134         consecutive characters.
 135         </p>
 136         @param pos
 137             the starting position
 138         @param length
 139             the length of the substring
 140         @returns
 141             the substring
 142         @throws SQLException
 143             if a database access error occurs.
 144      */
 145     string getSubString([in]hyper pos, [in]long length) raises (SQLException);
 146
 147     //-------------------------------------------------------------------------
 148
 149     /** gets the
 150         <code>Clob</code>
 151         contents as a stream.
 152         @returns
 153             the stream
 154         @throws SQLException
 155             if a database access error occurs.
 156      */
 157     com::sun::star::io::XInputStream getCharacterStream() raises (SQLException);
 158
 159     //-------------------------------------------------------------------------
 160
 161     /** determines the character position at which the specified substring
 162         <code>searchstr</code>
 163         appears in the
 164         <code>Clob</code>
 165         . The search begins at position
 166         <code>start</code>
 167         .
 168         @param searchstr
 169             the string to search
 170         @param start
 171             the starting position
 172         @returns
 173             the length of the CLOB object
 174         @throws SQLException
 175             if a database access error occurs.
 176      */
 177     hyper position([in]string searchstr, [in]long start)
 178         raises (SQLException);
 179
 180       //-------------------------------------------------------------------------
 181
 182     /** determines the position at which the specified
 183         <code>Clob</code>
 184         object
 185         <code>pattern</code>
 186         appears in this
 187         <code>Clob</code>
 188         object. The search begins at position
 189         <code>start</code>
 190         .
 191         @param pattern
 192             the CLOB to search
 193         @param start
 194             the starting position
 195         @returns
 196             the position of the CLOB inside
 197         @throws SQLException
 198             if a database access error occurs.
 199      */
 200     hyper positionOfClob([in]XClob pattern, [in]hyper start)
 201         raises (SQLException);
 202 };
 203
 204 //=============================================================================
 205
 206 }; }; }; };
 207
 208 /*===========================================================================
 209 ===========================================================================*/
 210 #endif