Nonstop Database, HiRDB Version 9 UAP Development Guide
![[Contents]](FIGURE/CONTENT.GIF)
![[Index]](FIGURE/INDEX.GIF)
![[Back]](FIGURE/FRONT.GIF)
(1) Overview
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.
(2) Methods
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
(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.
(3) Package and class names
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
All Rights Reserved. Copyright (C) 2011, Hitachi, Ltd.