Performing Operations on Smart Large Objects

Home | Previous Page | Next Page Working With Informix Types > Smart Large Object Data Types >

Performing Operations on Smart Large Objects

In the database server, you can store a smart large object directly in a column that has one of the following data types:

The CLOB data type holds text data.
The BLOB data type can store any kind of binary data in an undifferentiated byte stream.

The CLOB or BLOB column holds an LO handle for the smart large object. Therefore, when you select a CLOB or BLOB column, you do not obtain the actual data of the smart large object, but the LO handle that identifies this data. Columns for smart large objects have a theoretical limit of 4 terabytes and a practical limit determined by your disk capacity.

You can use either of the following ways to store a smart large object in a column:

For direct access to the smart large object, create a column of the CLOB or BLOB data type.
To hide the smart large object within an atomic data type, create an opaque type that holds a smart large object.

In a client application, the IfxBblob and IfxCblob classes are bridges between the way of handling smart large object data described in the Sun Microsystem JDBC 3.0 specification and the Informix extensions. The IfxBblob class implements the java.sql.Blob interface, and the IfxCblob class implements the java.sql.Clob interface. The Informix extensions require an IfxLocator object to identify the smart large object in the database server.

When you query a table containing a column of type BLOB or CLOB, an object of type Blob or Clob is returned, depending upon the column type. You can then use the JDBC 3.0 supporting methods for objects of type Blob or Clob to access the smart large object.

The constructors create an IfxBblob or IfxCblob object from the IfxLocator object loPtr:

public IfxBblob(IfxLocator loPtr)
public IfxCblob(IfxLocator loPtr)

The following locator method returns an IfxLocator object from an IfxBblob or IfxCblob object. You can then open, read, and write to the smart large object using the IfxSmartBlob.IfxLoOpen(), IfxLoRead(), and IfxLoWrite() methods:

public IfxLocator getLocator() throws SQLException

Opening a Smart Large Object

The following methods in the IfxSmartBlob class open an existing smart large object in the database server:

public int IfxLoOpen(IfxLocator loPtr, int flag) throws 
   SQLException
public int IfxLoOpen(IfxBblob blob, int flag) throws SQLException
public int IfxLoOpen(IfxCblob clob, int flag) throws SQLException

The first version opens the smart large object that is referenced by the locator pointer loPtr. The second and third versions open the smart large objects that are referenced by the specified IfxBblob and IfxCblob objects, respectively. The flag parameter is a value from the table in Creating an IfxSmartBlob Object.

Positioning Within a Smart Large Object

The IfxLoTell() method in the IfxSmartBlob class returns the current seek position, which is the offset for the next read or write operation on the smart large object. The IfxLoSeek() method in the IfxSmartBlob class sets the read or write position within an already opened large object.

public long       IfxLoTell(int lofd)
public long IfxLoSeek(int lofd, long offset, int whence) throws 
   SQLException

The absolute position depends on the value of the second parameter, offset, and the value of the third parameter, whence.

The lofd parameter is the locator file descriptor returned by the IfxLoCreate() or IfxLoOpen() method. The offset parameter is an offset from the starting seek position.

The whence parameter identifies the starting seek position. Use the whence values in the following table to define the position within a smart large object to start a seek operation.

Starting Seek Position: Whence Value
Beginning of the smart large object: IfxSmartBlob.LO_SEEK_SET
Current location in the smart large object: IfxSmartBlob.LO_SEEK_CUR
End of the smart large object: IfxSmartBlob.LO_SEEK_END

The return value is a long integer representing the absolute position within the smart large object.

The following example shows how to use a LO_SEEK_SET whence value:

IfxLobDescriptor loDesc = new IfxLobDescriptor(myConn);
IfxLocator loPtr = new IfxLocator();
IfxSmartBlob smb = new IfxSmartBlob(myConn);
int loFd = smb.IfxLoCreate(loDesc, smb.LO_RDWR, loPtr);
int n = smb.IfxLoWrite(loFd, fin, fileLength);
smb.IfxLoClose(loFd);
loFd = smb.IfxLoOpen(loPtr, smb.LO_RDWR);
long m = smb.IfxLoSeek(loFd, 200, smb.LO_SEEK_SET);

The writing position is set at an offset of 200 bytes from the beginning of the smart large object.

Reading from a Smart Large Object

You can read data from a smart large object in the following ways:

Read the data from the object into a byte[ ] buffer.
Read the data from the object into a file output stream.
Read the data from the object into a file.

Use the IfxLoRead() method in the IfxSmartBlob class, which has the following signatures, to read from a smart large object into a buffer or file output stream:

public byte[] IfxLoRead(int lofd, int nbytes) throws SQLException
public int IfxLoRead(int lofd, byte[] buffer, int nbytes) throws 
   SQLException
public int IfxLoRead(int lofd, FileOutputStream fout, int nbytes
   throws SQLException
public int IfxLoRead(int lofd, byte[] buffer, int nbytes, int 
   offset throws SQLException

The lofd parameter is a locator file descriptor returned by the IfxLoCreate() or IfxLoOpen() method.

The first version returns nbytes bytes of data into a byte buffer. This version of the method allocates the memory for the buffer. The second version reads nbytes bytes of data into an already allocated buffer. The third version reads nbytes bytes of data into a file output stream. The fourth version reads nbytes bytes of data into a byte buffer starting at the current seek position plus offset into the smart large object. The return values for the last three versions indicate the number of bytes read.

Use the IfxLoToFile() method in the IfxSmartBlob class, which has the following signatures, to read from a smart large object into a file:

public int IfxLoToFile(IfxLocator loPtr, String filename, int flag 
   , int whence) throws SQLException
public int IfxLoToFile(IfxBblob blob, String filename, int flag , 
   int whence) throws SQLException
public int IfxLoToFile(IfxCblob clob, String filename, int flag , 
   int whence) throws SQLException

The first version reads the smart large object that is referenced by the locator pointer loPtr. The second and third versions read the smart large objects that are referenced by the specified IfxBblob and IfxCblob objects, respectively.

The flag parameter indicates whether the file is on the client or the server. The value is either IfxSmartBlob.LO_CLIENT_FILE or IfxSmartBlob.LO_SERVER_FILE. The whence parameter identifies the starting seek position. For the values, see Positioning Within a Smart Large Object.

Tip:

There has been a change in the signature of the following function:

 IfxSmartBlob.IfxLoToFile().

This function used to accept four parameters, but now only accepts three parameters. All three overloaded functions for IfxLoToFile() accept three parameters.

Writing to a Smart Large Object

You can write data to a smart large object in the following ways:

Write the data from a byte[ ] buffer to the object.
Write the data from a file input stream to the object.
Write the data from a file to the object.

Use the IfxLoWrite() methods in the IfxSmartBlob class to write to a smart large object from a byte[ ] buffer or file input stream:

public int IfxLoWrite(int lofd, byte[] buffer) throws SQLException
public int IfxLoWrite(int lofd, InputStream fin, int length) 
   throws SQLException

The first version of the method writes buffer.length bytes of data from the buffer into the smart large object. The second version writes length bytes of data from an InputStream object into the smart large object.

The lofd parameter is a locator file descriptor returned by the IfxLoCreate() or IfxLoOpen() method. The buffer parameter is the byte[] buffer where the data is read. The fin parameter is the InputStream object from which data is written into the smart large object. The length parameter is the number of bytes written into the smart large object. The driver returns the number of bytes written.

Use the IfxLoFromFile() method in the IfxSmartBlob class to write data to a smart large object from a file:

public int IfxLoFromFile (int lofd, String filename, int flag, int 
   offset, int amount) throws SQLException

The lofd parameter is a locator file descriptor returned by the IfxLoCreate() or IfxLoOpen() method. The flag parameter indicates whether the file is on the client or the server. The value is either IfxSmartBlob.LO_CLIENT_FILE or IfxSmartBlob.LO_SERVER_FILE.

The driver returns the number of bytes written.

Truncating a Smart Large Object

Use the IfxLoTruncate() method in the IfxSmartBlob class to truncate a large object at an offset you specify. The method signature is as follows:

public void IfxLoTruncate(int lofd, long offset) throws 
   SQLException

The offset parameter is the absolute position at which the smart large object is truncated.

Measuring a Smart Large Object

Use the IfxLoSize() method in the IfxSmartBlob class to return the size of a smart large object. This method returns a long integer representing the size of the large object.

The method signature is as follows:

public long IfxLoSize(int lofd) throws SQLException

Closing and Releasing a Smart Large Object

After you have performed all the operations your application needs, you must close the object and then release the resources in the server. The methods in the IfxSmartBlob class that perform these tasks are as follows:

public void IfxLoClose(int lofd) throws SQLException
public void IfxLoRelease(IfxLocator loPtr) throws SQLException
public void IfxLoRelease(IfxBblob blob) throws SQLException
public void IfxLoRelease(IfxCblob clob) throws SQLException

For any further access to the same large object, you must reopen it with the IfxLoOpen() method.

Converting IfxLocator to a Hexadecimal String

Some applications, for example, Web browsers, can only process ASCII data; they require IfxLocator to be converted to hexadecimal string format. In a typical Web-based application, the Web server queries the database table and sends the results to the browser. Instead of sending the entire smart large object, the Web server converts the locator into hexadecimal string format and sends it to the browser. If the user requests the browser to display the smart large object, the browser sends the locator in hexadecimal format back to the Web server. The Web server then reconstructs the binary locator from the hexadecimal string and sends the corresponding smart large object data to the browser.

To convert between the IfxLocator byte array and a hexadecimal number, use the methods listed in the following table.

Task Performed	Method Signature	Notes
Converts a byte array to a hexadecimal character string	public static String toHexString( byte[] byteBuf);	Works on data other than IfxLocator Provided in the com.informix.util.stringUtil class
Converts a hexadecimal character string to a byte array	public static byte[] fromHexString( String str) throws NumberFormatException;	Works on data other than IfxLocator Provided in the com.informix.util.stringUtil class
Constructs an IfxLocator object using a byte array	public IfxLocator(byte[] byteBuf) throws SQLException;	Provided in the IfxLocator class
Converts an IfxLocator byte array to a hexadecimal character string	public String toString();	Provided in the IfxLocator class
Converts a hexadecimal character string to an IfxLocator byte array	public byte[] toBytes();	Provided in the IfxLocator class

The following example uses the toString() and toBytes() methods to fetch the locator from a smart large object and then convert it into a hexadecimal string:

...

String hexLoc = "";
byte[] blobBytes;
byte[] rawLocA = null;
IfxLocator loc;
try
{
     ResultSet rs = stmt.executeQuery("select b1 from btab");
     while(rs.next())
     {
         IfxBblob b=(IfxBblob)rs.getBlob(1);
         loc =b.getLocator();
         hexLoc = loc.toString();
         rawLocA = loc.toBytes();
     }
}
catch(SQLException e)
{}

The following example uses the IfxLocator() method to construct an IfxLocator, which is then used to read a smart large object:

...

try
{
     IfxLocator loc2 = new IfxLocator(rawLoc);
     IfxSmartBlob b2 = new IfxSmartBlob((IfxConnection)myConn);
     int lofd = b2.IfxLoOpen(loc2, b2.LO_RDWR);
     blobBytes = b2.IfxLoRead(lofd, fileLength);
}
catch(SQLException e)
  {}