IfxCblob
Date: 2015-03-03

com.informix.jdbc

## Class IfxCblob

- java.lang.Object
- - com.informix.jdbc.IfxCblob

- All Implemented Interfaces:
    java.sql.Clob

      public class IfxCblob
      extends java.lang.Object
      implements java.sql.Clob

  By default, a CLOB is a transaction duration reference to a character large object.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `IfxCblob()` Creates an IfxCblob instance.
    `IfxCblob(java.sql.Connection c, byte[] buffer)` Creates an IfxCblob instance with the given connection and a buffer containing data.
    `IfxCblob(java.sql.Connection conn, java.io.InputStream fin, int length)` Creates an IfxCblob instance with a given connection, an inputStream and number of bytes to write.
    `IfxCblob(java.sql.Connection conn, java.io.InputStream fin, int length, IfxLobDescriptor loDesc)` Creates an IfxCblob instance with a given connection, an inputStream, number of bytes to write and a specified lob descriptor.
    `IfxCblob(java.sql.Connection conn, java.io.InputStream fin, int length, java.lang.String sbspaceName)` Creates an IfxCblob instance with a given connection, an inputStream and number of bytes to write to a specified smart blob space.
    `IfxCblob(java.sql.Connection conn, java.lang.String str)` Creates an IfxCblob instance with a given connection and a string of data.
    `IfxCblob(java.sql.Connection conn, java.lang.String str, IfxLobDescriptor loDesc)` Creates an IfxCblob instance with a given connection and a string of data and a specified lob descriptor.
    `IfxCblob(java.sql.Connection conn, java.lang.String str, java.lang.String sbspaceName)` Creates an IfxCblob instance with a given connection and a string of data and a specified smart blob space.
    `IfxCblob(com.informix.jdbc.IfxConnection connection, IfxLocator locator)` Creates an IfxCblob instance with a given connection and a locator.
    `IfxCblob(com.informix.jdbc.IfxConnection connection, IfxLocator locator, int mode)` Creates an IfxCblob instance with a given connection and a locator.
    `IfxCblob(IfxLocator locator)` Creates an IfxCblob instance with the given locator.
    `IfxCblob(java.io.InputStream fin)` Creates an IfxCblob instance with the given input stream.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` This method will release the resources used by the object.
    `void` | `free()`
    `java.io.InputStream` | `getAsciiStream()` Gets the smart large object contents as an ASCII stream.
    `java.io.Reader` | `getCharacterStream()` Gets the smart large object contents as a Unicode stream.
    `java.io.Reader` | `getCharacterStream(long pos, long length)`
    `IfxLocator` | `getLocator()` Gets the smart large object locator from the clob object.
    `IfxLoStat` | `getLoStat()` This method returns an IfxLoStat object, which provides statistical information, such as the last access time, the last update status time, the last modification time, and the reference count of the smart large object.
    `java.lang.String` | `getSubString(long position, int length)` Returns a copy of the substring of the smart large object at the requested position.
    `long` | `length()` Gets the length of the character smart large object in characters.
    `long` | `position(java.sql.Clob searchstr, long start)` Determines the character position at which the given substring occurs.
    `long` | `position(java.lang.String searchstr, long start)` Determines the character position at which the given substring occurs.
    `long` | `seek(long offset, int whence)` This method sets the position for the next read and write operation of the smart large object.
    `java.io.OutputStream` | `setAsciiStream(long pos)` Retrieves a stream to be used to write Ascii characters to the CLOB value that this Clob object represents, starting at position pos.
    `void` | `setAsciiStream(long position, java.io.InputStream fin, int length)` Writes ascii stream of data from an InputStream to an already existing smart large blob object.
    `java.io.Writer` | `setCharacterStream(long pos)` Retrieves a stream to be used to write a stream of Unicode characters to the CLOB value that this Clob object represents, at position pos.
    `int` | `setString(long pos, java.lang.String str)` Writes the given Java String to the CLOB value that this Clob object designates at the position pos.
    `int` | `setString(long pos, java.lang.String str, int offset, int len)` Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents.
    `void` | `setSubString(long position, java.lang.String str, int length)` Writes data from a string to an already existing smart large blob object.
    `void` | `truncate(long size)` This method truncates the smart large object at the given position.
    `long` | `where()` This method returns the current seek position within the large object.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### IfxCblob

          public IfxCblob()

      Creates an IfxCblob instance. An IfxCblob object created using this constructor cannot be used for accessing the Clob.

    - #### IfxCblob

          public IfxCblob(IfxLocator locator)

      Creates an IfxCblob instance with the given locator. An IfxCblob object created using this constructor cannot be used for accessing the Clob.
      Parameters:
        `locator` - The locator that references the smart large object

    - #### IfxCblob

          public IfxCblob(com.informix.jdbc.IfxConnection connection,
                  IfxLocator locator,
                  int mode)
                   throws java.sql.SQLException

      Creates an IfxCblob instance with a given connection and a locator. The object will be opened in the database using the given mode.
      Parameters:
        `connection` - The IfxConnection object
        `locator` - The locator that references the smart large object
      Throws:
        `java.sql.SQLException`

    - #### IfxCblob

          public IfxCblob(com.informix.jdbc.IfxConnection connection,
                  IfxLocator locator)
                   throws java.sql.SQLException

      Creates an IfxCblob instance with a given connection and a locator. The object will be opened in the database in RDWR mode.
      Parameters:
        `connection` - The IfxConnection object
        `locator` - The locator that references the smart large object
      Throws:
        `java.sql.SQLException`

    - #### IfxCblob

          public IfxCblob(java.sql.Connection c,
                  byte[] buffer)
                   throws java.sql.SQLException

      Creates an IfxCblob instance with the given connection and a buffer containing data.
      Parameters:
        `conn` - the Connection object
        `buffer` - the data buffer
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated

    - #### IfxCblob

          public IfxCblob(java.io.InputStream fin)

      Creates an IfxCblob instance with the given input stream. An IfxCblob object created using this constructor cannot be used for accessing the Clob.
      Parameters:
        `fin` - The input stream for this smart large object

    - #### IfxCblob

          public IfxCblob(java.sql.Connection conn,
                  java.io.InputStream fin,
                  int length)
                   throws java.sql.SQLException

      Creates an IfxCblob instance with a given connection, an inputStream and number of bytes to write.
      Parameters:
        `conn` - The IfxConnection object.
        `fin` - The input stream from which the data will be written into the smart large object.
        `length` - Number of bytes to be written.
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated.

    - #### IfxCblob

          public IfxCblob(java.sql.Connection conn,
                  java.io.InputStream fin,
                  int length,
                  java.lang.String sbspaceName)
                   throws java.sql.SQLException

      Creates an IfxCblob instance with a given connection, an inputStream and number of bytes to write to a specified smart blob space.
      Parameters:
        `conn` - The IfxConnection object.
        `fin` - The input stream from which the data will be written into the smart large object.
        `length` - Number of bytes to be written.
        `sbspaceName` - specified smart blob space name.
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated.

    - #### IfxCblob

          public IfxCblob(java.sql.Connection conn,
                  java.io.InputStream fin,
                  int length,
                  IfxLobDescriptor loDesc)
                   throws java.sql.SQLException

      Creates an IfxCblob instance with a given connection, an inputStream, number of bytes to write and a specified lob descriptor.
      Parameters:
        `conn` - The IfxConnection object.
        `fin` - The input stream from which the data will be written into the smart large object.
        `length` - Number of bytes to be written.
        `loDesc` - user created lob descriptor.
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated.

    - #### IfxCblob

          public IfxCblob(java.sql.Connection conn,
                  java.lang.String str)
                   throws java.sql.SQLException

      Creates an IfxCblob instance with a given connection and a string of data.
      Parameters:
        `conn` - The IfxConnection object.
        `str` - The String from which the data will be written to smart blob.
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated.

    - #### IfxCblob

          public IfxCblob(java.sql.Connection conn,
                  java.lang.String str,
                  java.lang.String sbspaceName)
                   throws java.sql.SQLException

      Creates an IfxCblob instance with a given connection and a string of data and a specified smart blob space.
      Parameters:
        `conn` - The IfxConnection object.
        `str` - The String from which the data will be written to smart blob.
        `sbspaceName` - specified smart blob space name.
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated.

    - #### IfxCblob

          public IfxCblob(java.sql.Connection conn,
                  java.lang.String str,
                  IfxLobDescriptor loDesc)
                   throws java.sql.SQLException

      Creates an IfxCblob instance with a given connection and a string of data and a specified lob descriptor.
      Parameters:
        `conn` - The IfxConnection object.
        `str` - The string from which the data will be written to smart blob.
        `loDesc` - user defined lob descriptor.
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated.

  - ### Method Detail

    - #### getLocator

          public IfxLocator getLocator()
                                throws java.sql.SQLException

      Gets the smart large object locator from the clob object.
      Returns:
        The smart large object locator.
      Throws:
        `java.sql.SQLException` - if the object type is not a BLOB or CLOB.

    - #### length

          public long length()

      Gets the length of the character smart large object in characters.
      Specified by:
        `length` in interface `java.sql.Clob`
      Returns:
        The length of the smart large object in characters.

    - #### getSubString

          public java.lang.String getSubString(long position,
                                      int length)

      Returns a copy of the substring of the smart large object at the requested position. This method can be used to fetch data from a blob. If the IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)
      Specified by:
        `getSubString` in interface `java.sql.Clob`
      Parameters:
        `position` - The position at which to start searching.
        `length` - The number of consecutive characters to be copied.
      Returns:
        A byte array containing a substring of the smart large object.

    - #### getCharacterStream

          public java.io.Reader getCharacterStream()
                                            throws java.sql.SQLException

      Gets the smart large object contents as a Unicode stream. Characters are converted from database encoding to unicode.
      Specified by:
        `getCharacterStream` in interface `java.sql.Clob`
      Returns:
        A Unicode stream containing the smart large object data.
      Throws:
        `java.sql.SQLException`

    - #### getAsciiStream

          public java.io.InputStream getAsciiStream()
                                             throws java.sql.SQLException

      Gets the smart large object contents as an ASCII stream. This method can be used to fetch data from a blob. If the IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)
      Specified by:
        `getAsciiStream` in interface `java.sql.Clob`
      Returns:
        An ASCII stream containing the smart large object data.
      Throws:
        `java.sql.SQLException` - if there is a problem getting the stream.

    - #### position

          public long position(java.lang.String searchstr,
                      long start)
                        throws java.sql.SQLException

      Determines the character position at which the given substring occurs. This method can be used to find a match for a pattern within a clob. In case IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)
      Specified by:
        `position` in interface `java.sql.Clob`
      Parameters:
        `searchstr` - The substring for which you want to search.
        `start` - The position at which searching begins.
      Returns:
        The position at which the substring appears, or -1 if the string does not appear in the smart large object.
      Throws:
        `java.sql.SQLException` - if the string cannot be read or the the index is out of bounds.

    - #### position

          public long position(java.sql.Clob searchstr,
                      long start)
                        throws java.sql.SQLException

      Determines the character position at which the given substring occurs. This method can be used to find a match for a pattern within a clob. If the IfxCblob object is created with the following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)
      Specified by:
        `position` in interface `java.sql.Clob`
      Parameters:
        `searchstr` - The substring for which you want to search.
        `start` - The position at which searching begins.
      Returns:
        The position at which the substring appears, or -1 if the string does not appear in the smart large object.
      Throws:
        `java.sql.SQLException` - if there is an error accessing the CLOB

    - #### setAsciiStream

          public void setAsciiStream(long position,
                            java.io.InputStream fin,
                            int length)
                              throws java.sql.SQLException

      Writes ascii stream of data from an InputStream to an already existing smart large blob object. Characters are written without any codeset conversion This method can be used to fetch data from a blob. If the IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)
      Parameters:
        `postion` - Position at which smart large object will be written.
        `fin` - InputStream
        `length` - Number of bytes to be written from the input stream.
      Throws:
        `java.sql.SQLException` - if the type is not a CLOB, the large object is invalid or the large object cannot be opened.

    - #### setSubString

          public void setSubString(long position,
                          java.lang.String str,
                          int length)
                            throws java.sql.SQLException

      Writes data from a string to an already existing smart large blob object. This method can be used to fetch data from a blob. If the IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)
      Parameters:
        `postion` - Position at which smart large object will be written.
        `str` - The string which the data will be written.
        `length` - Number of bytes to be written into smart large object.
      Throws:
        `java.sql.SQLException` - if the type is not a CLOB, the large object is invalid or the large object cannot be opened.

    - #### close

          public void close()
                     throws java.sql.SQLException

      This method will release the resources used by the object.
      Throws:
        `java.sql.SQLException` - if there was an error closing the large object.

    - #### seek

          public long seek(long offset,
                  int whence)
                    throws java.sql.SQLException

      This method sets the position for the next read and write operation of the smart large object. In case IfxClob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.
      Parameters:
        `offset` - Number of bytes from the location specified in the whence parameter.
        `whence` - defines the offset value more specifically; LO_SEEK_SET, from begining; LO_SEEK_CUR, relative from current position; LO_SEEK_END, from the end.
      Throws:
        `java.sql.SQLException` - if the object is not a smart large object.

    - #### where

          public long where()
                     throws java.sql.SQLException

      This method returns the current seek position within the large object. In case IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.
      Returns:
        The current position within the smart large object.
      Throws:
        `java.sql.SQLException` - if the object is not a smart large object.

    - #### getLoStat

          public IfxLoStat getLoStat()
                              throws java.sql.SQLException

      This method returns an IfxLoStat object, which provides statistical information, such as the last access time, the last update status time, the last modification time, and the reference count of the smart large object. In case IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.
      Returns:
        IfxLoStat Object containing information about the smart large object.
      Throws:
        `java.sql.SQLException` - if the object is not a smart large object.

    - #### truncate

          public void truncate(long size)
                        throws java.sql.SQLException

      This method truncates the smart large object at the given position. If the position given is beyond the length of the smart large object it ignores the request. In case IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.
      Specified by:
        `truncate` in interface `java.sql.Clob`
      Parameters:
        `size` - Position at which the truncation will occur.
      Throws:
        `java.sql.SQLException` - if the object is not a smart large object.

    - #### setString

          public int setString(long pos,
                      java.lang.String str)
                        throws java.sql.SQLException

      Writes the given Java String to the CLOB value that this Clob object designates at the position pos. The Unicode string is always conveted to database codeset before writing to clob.
      Specified by:
        `setString` in interface `java.sql.Clob`
      Parameters:
        `str` - the string to be written to the CLOB value that this Clob designates
      Returns:
        the number of characters written
      Throws:
        `java.sql.SQLException` - if there is an error accessing the CLOB value

    - #### setString

          public int setString(long pos,
                      java.lang.String str,
                      int offset,
                      int len)
                        throws java.sql.SQLException

      Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents. The characters are always conveted to database locale codeset before writing to clob. In case IfxClob object is created with following constructors, IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. The Unicode characters are always conveted to database codeset before writing to clob.
      Specified by:
        `setString` in interface `java.sql.Clob`
      Parameters:
        `pos` - the position at which to start writing to this CLOB object
        `str` - the string to be written to the CLOB value that this Clob object represents
        `offset` - the offset into str to start reading the characters to be written
        `len` - the number of characters to be written
      Returns:
        the number of characters written
      Throws:
        `java.sql.SQLException`

    - #### setAsciiStream

          public java.io.OutputStream setAsciiStream(long pos)
                                              throws java.sql.SQLException

      Retrieves a stream to be used to write Ascii characters to the CLOB value that this Clob object represents, starting at position pos. Characters are written without any codeset conversion In case IfxClob object is created with following constructors, IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.
      Specified by:
        `setAsciiStream` in interface `java.sql.Clob`
      Parameters:
        `pos` - the position at which to start writing to this CLOB object
      Returns:
        the stream to which ASCII encoded characters can be written
      Throws:
        `java.sql.SQLException` - if there is an error accessing the CLOB value

    - #### setCharacterStream

          public java.io.Writer setCharacterStream(long pos)
                                            throws java.sql.SQLException

      Retrieves a stream to be used to write a stream of Unicode characters to the CLOB value that this Clob object represents, at position pos. The Unicode characters are always conveted to database codeset before writing to clob. In case IfxClob object is created with following constructors, IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.
      Specified by:
        `setCharacterStream` in interface `java.sql.Clob`
      Parameters:
        `pos` - the position at which to start writing to the CLOB value
      Returns:
        a stream to which Unicode encoded characters can be written
      Throws:
        `java.sql.SQLException` - if there is an error accessing the CLOB value

    - #### free

          public void free()
                    throws java.sql.SQLException

      Specified by:
        `free` in interface `java.sql.Clob`
      Throws:
        `java.sql.SQLException`

    - #### getCharacterStream

          public java.io.Reader getCharacterStream(long pos,
                                          long length)
                                            throws java.sql.SQLException

      Specified by:
        `getCharacterStream` in interface `java.sql.Clob`
      Throws:
        `java.sql.SQLException`