The Blob interface provides the following principal functions:

• Acquisition of binary data
• Acquisition of the length of binary data
• Acquisition of the pattern-matching position

The JDBC driver uses the PrdbBlob class to install the Blob interface.

The JDBC driver generates PrdbBlob class objects as return values of the getBlob method of ResultSet and CallableStatement.

The table below lists the methods of the Blob interface. The interface does not support methods that are not listed in the table. If an unsupported method is specified, the interface throws an SQLException.

Table 18-53 Blob interface methods

Subsection	Method	Function
(a)	getBinaryStream()	Returns a BLOB or BINARY value as a stream (PrdbDataStream object).
(b)	getBytes(long pos, int length)	Returns all or part of a BLOB or BINARY value as a byte array.
(c)	length()	Returns the length (in bytes) of the BLOB or BINARY value specified by this PrdbBlob object.
(d)	position(Blob pattern, long start)	Returns the byte location where pattern begins within the BLOB or BINARY value specified by the PrdbBlob object.
(e)	position(byte[] pattern, long start)	Returns the byte location where pattern begins within the BLOB value indicated by this Blob object.

(a) getBinaryStream()

Function

Returns a BLOB or BINARY value as a stream (PrdbDataStream object).

Format

 
public InputStream getBinaryStream() throws SQLException
 

Arguments

None.

Return value

Returns the PrdbDataStream from which InputStream is derived.

Functional detail

This method returns a BLOB or BINARY value as a stream (PrdbDataStream object).

If the locator facility is used, the method acquires a locator from a PrdbResultSet object and passes that locator to a PrdbDataStream class constructor to create a PrdbDataStream object.

When the locator facility is used, the method issues a data acquisition request to the HiRDB server each time data acquisition is requested because the PrdbDataStream object does not contain a BLOB or BINARY value.

If the locator facility is not used, the method acquires a BLOB or BINARY value from the PrdbResultSet object and passes that value to a PrdbDataStream class constructor to create a PrdbDataStream object. In this case, the method does not issue a data acquisition request to the HiRDB server because the PrdbResultSet object contains the BLOB or BINARY value.

Exceptions

The JDBC driver throws an SQLException in the following cases:

• The locator facility is used, but the PrdbConnection, PrdbStatement, or PrdbResultSet object related to this PrdbBlob object is closed.
• The PrdbBlob object has become invalid due to transaction settlement.
• When the locator facility is used, data acquisition failed due to a communication error.

(b) getBytes(long pos,int length)

Function

Returns all or part of a BLOB or BINARY value as a byte array. The method stores in the byte array as many consecutive bytes as is specified in length beginning at the location specified in pos.

Format

 
public byte[] getBytes(long pos,int length) throws SQLException
 

Arguments

long pos

Location of the first byte to be extracted from the BLOB value (sequence number)

The location of byte 1 is 1.

int length

Number of consecutive bytes to be copied

Return value

Array containing as many consecutive BLOB or BINARY value bytes as specified in length beginning at the location specified in pos

Functional detail

This method returns all or part of a BLOB or BINARY value as a byte array. In the byte array, the method stores as many consecutive bytes as is specified in length beginning at the location specified in pos.

The following table shows the data that is returned depending on the values of pos and length:

pos	length	Real length (X)#1	Limit value#2 and length	Limit value#2 and real length (X)#1	Data that is returned
1 < = pos < = real length (X)#1	< 0	--	--	--	SQLException
	> = 0	< = length	--	Y < limit value	BLOB or BINARY value with the real length (Y)
			--	Y > = limit value	BLOB or BINARY value with the limit value length
		Y > length	length < limit value	--	BLOB or BINARY value with the length specified for length
			length > = limit value	--	BLOB or BINARY value with the limit value length
> real length (X)#1	--	--	--	--	Data with a length of 0
Other	--	--	--	--	SQLException

Legend:

--: Not applicable

#1

Real length (X) indicates the real length of the BLOB or BINARY value that can be acquired (real length of BLOB or BINARY value - pos argument value + 1).

#2

The limit value corresponds to MaxFieldSize or HiRDB_for_JAVA_MAX_BINARY_SIZE. The following table shows the value that becomes the limit value:

MaxFieldSize	HiRDB_for_Java_MAX_BINARY_SIZE	HiRDB data type	Limit value (maximum length of data that can be acquired)
0 (default)	0 (default)	All data types	Definition length (default)
0 (default)	> 0 (specified)	BLOB or BINARY type	HiRDB_for_Java_MAX_BINARY_SIZE
		Type other than BLOB or BINARY#	Definition length (default)
> 0 (specified)	0 (default)	All data types	MaxFieldSize
> 0 (specified)	> 0 (specified)	All data types	MaxFieldSize

#

Any character type (the HiRDB data types CHAR, VARCHAR, NCHAR, NVARCHAR, MCHAR, and MVARCHAR)

Exceptions

The JDBC driver throws an SQLException in the following cases:

• The pos argument value is less than 1 or the length argument value is less than 0.
• The PrdbBlob object has become invalid due to transaction settlement.
• The locator facility is used, but the PrdbConnection, PrdbStatement, or PrdbResultSet object related to this PrdbBlob object is closed.
• When the locator facility is used, data acquisition failed due to a communication error.

(c) length()

Function

Returns the length (in bytes) of the BLOB or BINARY value specified by this PrdbBlob object.

Format

 
public long length() throws SQLException
 

Arguments

None.

Return value

Length of BLOB or BINARY value (number of bytes)

Exceptions

The JDBC driver throws an SQLException in the following cases:

• This PrdbDataStream class is closed.
• The locator facility is used, but the PrdbConnection, PrdbStatement, or PrdbResultSet object related to the PrdbDataStream object is closed.
• PrdbDataStream has become invalid due to transaction settlement.
• When the locator facility is used, data acquisition failed due to a communication error.

(d) position(Blob pattern, long start)

Function

Returns the byte location where pattern begins within the BLOB or BINARY value specified by the PrdbBlob object. This method starts searching for pattern at the location of start.

Format

 
public long position(Blob pattern, long start) throws SQLException
 

Arguments

Blob pattern

Blob object used to specify the BLOB or BINARY value to be retrieved

long start

Location in the BLOB or BINARY value at which retrieval is to begin. The start position is 1.

Return value

Location at which the data specified in pattern begins

Exceptions

The JDBC driver throws an SQLException in the following cases:

• This PrdbDataStream class is closed.
• The locator facility is used, but the PrdbConnection, PrdbStatement, or PrdbResultSet object related to the PrdbDataStream object is closed.
• PrdbDataStream has become invalid due to transaction settlement.
• When the locator facility is used, data acquisition failed due to a communication error.

(e) position(byte[] pattern, long start)

Function

Returns the byte location where pattern begins within the BLOB value indicated by this Blob object. This method starts searching for pattern at the location of start.

Format

 
public long position(byte[] pattern, long start) throws SQLException
 

Arguments

byte[] pattern

byte[] to be retrieved

long start

Location in the BLOB value at which retrieval is to begin. The start position is 1.

Return value

Location at which the data specified in pattern begins

Exceptions

The JDBC driver throws an SQLException in the following cases:

• This PrdbDataStream class is closed.
• The locator facility is used, but the PrdbConnection, PrdbStatement, or PrdbResultSet object related to the PrdbDataStream object is closed.
• PrdbDataStream has become invalid due to transaction settlement.
• When the locator facility is used, data acquisition failed due to a communication error.

The names of the package and class for installing this interface are as follows:

Package name: JP.co.Hitachi.soft.HiRDB.JDBC

Class name: PrdbBlob