This section explains the URL syntax supported by the JDBC driver.

You must not specify any spaces within an item or between items in a URL. Note that the item names are case sensitive.

(a) URL syntax

 
  jdbc:hitachi:hirdb[://[DBID=additional-connection-information]
                    [,DBHOST=database-host-name]
                    [,ENCODELANG=conversion-character-set]
                    [,HIRDB_CURSOR=cursor-operation-mode]
                    [,STATEMENT_COMMIT_BEHAVIOR=Statement-object-status-after-commit-execution]
                    [,JDBC_IF=whether-to-obtain-JDBC-interface-method-traces]
                    [,TRC_NO=trace-entries-count]
                    [,SQLWARNING_IGNORE=whether-to-return-warning-information]
                    [,LONGVARBINARY_ACCESS=method-of-accessing-BLOB-and-BINARY-types]
                    [,SQL_IN_NUM=?-parameters-count]
                    [,SQL_OUT_NUM=output-parameters-count]
                    [,SQLWARNING_LEVEL=warning-retention-level]
                    [,LONGVARBINARY_ACCESS_SIZE=LONGVARBINARY-data-access-size]
                    [,MAXBINARYSIZE=maximum-size-of-LONGVARBINARY-data]
                    [,LONGVARBINARY_TRUNCERROR=whether-to-throw-exceptions]
                    [,STATEMENT_CLOSE_BEHAVIOR=whether-to-ignore-preprocessing-results]
                    [,HiRDB_INI=directory-path-of-HiRDB.INI-file]
                    [,USER=user-name]
                    [,PASSWORD=password]
                    [,UAPNAME=application-name]
                    [,BATCHEXCEPTION_BEHAVIOR=whether-to-set-JDBC-standard-compliant-update-count]
                    ]
 

(b) Explanation of URL items

jdbc:hitachi:hirdb

This item consists of the protocol name, subprotocol name, and subname. You must specify this item. This item is case sensitive.

DBID=additional-connection-information

Specifies the port number of the HiRDB server (corresponds to the PDNAMEPORT value in the client environment definitions). You can also specify a HiRDB environment variable group for this item.

If no port number is specified for the HiRDB server, the value specified by another method takes effect. For details about how to specify the HiRDB port number and specification priorities, see 18.11 Connection information priorities.

If neither value is specified, the getConnection method throws an SQLException when it executes.

Note that the HiRDB port number specification is ignored for an internal driver.

Notes

You should note the following points about specifying an HiRDB environment variable group for the additional connection information:

• When you specify the name of the HiRDB environment variable group, specify @HIRDBENVGRP= followed by the absolute path name. If no value is specified after the equal sign, such as @HIRDBENVGRP=,, the JDBC driver assumes that no value is specified for this item.
• Note that an environment variable group name is case sensitive. Also, the environment variable group name depends on the OS.
• If the environment variable group name contains any single-byte space or single-byte @ characters, you must enclose the name in single-byte double quotation marks ("). When an environment variable group name is enclosed in single-byte double quotation marks, the characters from the closing single-byte quotation mark to the next setting item or to the final character are ignored. Note that an environment variable group that includes a single-byte quotation mark or a single-byte comma cannot be specified.
  Below are examples of specifications that trigger an error:
  

  @HIRDBENVGRP=/HiRDB_P/Client/HiRDB.ini @HIRDBENVGRP=/HiRDB_P/Client/HiRDB.ini @HIRDBENVGRP=/HiRDB_P/Client/HiRDB.ini @HIRDBENVGRP=/HiRDB_P/Client/HiRDB.ini

  Note: represents a single-byte space character.
  

DBHOST=database-host-name

Specifies the name of the HiRDB host.

If this specification is omitted, the value set by another method takes effect. For details about how to specify the HiRDB host name and specification priorities, see 18.11 Connection information priorities.

If neither value is specified, the getConnection method throws an SQLException when it executes.

Note that this specification is ignored for an internal driver.

ENCODELANG=conversion-character-set

Specifies the conversion character set for the HiRDB character codes of the connection destination when the JDBC driver uses the String class to exchange data with HiRDB. Select a specifiable conversion character set from the encoding list shown under Internationalization in the Java^TM 2 SDK, Standard Edition documentation.

The following table lists the character codes of HiRDB and their corresponding conversion character sets.

Table 18-2 HiRDB character codes and corresponding conversion character sets

HiRDB character codes (character code set with pdntenv or pdsetup command)	Conversion character set to be specified
lang-c	ISO8859_1
sjis	SJIS or MS932#
ujis	EUC_JP
utf-8	UTF-8
chinese	EUC_CN
chinese-gb18030	GB18030

#

The specification of SJIS or MS932 depends on the handling of Windows special characters in the application.

When OFF is specified, the JDBC driver operates assuming that the conversion character set for the HiRDB character codes shown in Table 18-2 was specified. If the HiRDB character code set is sjis, the conversion character set determined by the OS running the JDBC driver is as follows:

For UNIX: SJIS

For Windows: MS932

Note that the specification is case sensitive (except for OFF).

If a conversion character set that is not supported by the Java Virtual Machine is specified, the JDBC driver throws an SQLException during connection with the HiRDB server.

If this specification is omitted, the JDBC driver converts characters using the applicable conversion character set shown in Table 18-2. However, if one of the following is specified, the JDBC driver converts characters by using the default conversion character set of the Java Virtual Machine:

• Specification value for the UAP name (value specified by the UAPNAME property)
• Authorization identifier or password (value specified by the getConnection method)
• Specification value for the client environment definition specified by EnvironmentVariables
• Specification value for an environment variable specified by the environment variable group name of the HiRDB client

HIRDB_CURSOR=cursor-operation-mode

Specifies whether objects of the ResultSet class are to be validated or invalidated after HiRDB executes commit processing.

TRUE: Validate objects of the ResultSet class even after commit processing.

FALSE: Invalidate objects of the ResultSet class after commit processing.

If this specification is omitted, FALSE is assumed.

If a value other than TRUE or FALSE is specified, the JDBC driver throws an SQLException.

If an invalidated ResultSet object executes an operation other than calling the close method, the JDBC driver throws an SQLException.

Note

For notes about specifying HIRDB_CURSOR, see (c) Notes about specification of HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR.

STATEMENT_COMMIT_BEHAVIOR=Statement-object-status-after-commit-execution

Specifies whether objects of the Statement, PreparedStatement, and CallableStatement classes (referred to hereafter collectively as Statement) are to remain in effect even after HiRDB executes commit processing.

TRUE: Validate Statement objects even after HiRDB executes commit processing.

FALSE: Invalidate Statement objects after HiRDB executes commit processing.

The objects that become invalid after commit execution are SQL statements that were precompiled by the prepareStatement or prepareCall method of the Connection class, and ResultSet class objects obtained by the executeQuery method of Statement.

If this specification is omitted, TRUE is assumed.

Note

For notes about specifying STATEMENT_COMMIT_BEHAVIOR, see (c) Notes about specification of HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR.

JDBC_IF=whether-to-obtain-JDBC-interface-method-traces

Specifies whether JDBC interface method traces are to be obtained.

ON: Obtain JDBC interface method traces.

OFF: Do not obtain JDBC interface method traces.

If this specification is omitted, OFF is assumed. If any other value is specified, the JDBC driver throws an SQLException.

For details about the specification, see 18.2.2(2)(d) JDBC_IF.

TRC_NO=trace-entries-count

Specifies the number of JDBC interface method trace entries.

For details about the specification, see 18.2.2(2)(e) TRC_NO.

SQLWARNING_IGNORE=whether-to-retain-warning-information

Specifies whether warnings returned from the database are to be retained by the Connection object.

TRUE: Do not retain warnings.

FALSE: Retain warnings.

If this specification is omitted, FALSE is assumed

If any other value is specified, the JDBC driver throws an SQLException.

For details about the specification, see 18.2.2(2)(g) SQLWARNING_IGNORE.

LONGVARBINARY_ACCESS=method-of-accessing-BLOB-and-BINARY-types

Specifies the method of accessing a JDBC SQL-type LONGVARBINARY (BLOB and BINARY types in HiRDB) database.

REAL: Access the database using real data.

LOCATOR: Access the database using HiRDB's locator facility.

If any other value is specified, the JDBC driver throws an SQLException.

For details about the specification, see 18.2.2(2)(i) LONGVARBINARY_ACCESS.

SQL_IN_NUM=?-parameters-count

Specifies the maximum number of input ? parameters in the SQL statements to be executed.

For details about the specification, see 18.2.2(2)(j) HiRDB_for_Java_SQL_IN_NUM.

SQL_OUT_NUM=output-parameters-count

Specifies the maximum number of output items for the SQL statements to be executed.

For details about the specification, see 18.2.2(2)(k) HiRDB_for_Java_SQL_OUT_NUM.

SQLWARNING_LEVEL=warning-retention-level

Specifies the retention level for warning information that is issued during execution of SQL statements. For details about the warning information retention level, see 18.4.12(2)(b) Issuing conditions for SQLWarning objects.

IGNORE: Retain warning information at the IGNORE level.

SQLWARN: Retain warning information at the SQLWARN level.

ALLWARN: Retain warning information at the ALLWARN level.

If this specification is omitted, SQLWARN is assumed.

If the specified value is invalid, the JDBC driver throws an SQLException.

LONGVARBINARY_ACCESS_SIZE=LONGVARBINARY-data-access-size

Specifies the length (in kilobytes) of JDBC SQL-type LONGVARBINARY data that can be requested at one time at the HiRDB server.

For details about the specification, see 18.2.2(2)(o) HiRDB_for_Java_LONGVARBINARY_ACCESS_SIZE.

MAXBINARYSIZE=maximum-size-of-LONGVARBINARY-data

Specifies the maximum data size (in bytes) during acquisition of JDBC SQL-type LONGVARBINARY data.

For details about the specification, see 18.2.2(2)(p) HiRDB_for_Java_MAXBINARYSIZE.

LONGVARBINARY_TRUNCERROR=whether-to-throw-exceptions

Specifies whether exceptions are to be thrown when truncation occurs during acquisition of JDBC SQL-type LONGVARBINARY data.

TRUE: Throw exceptions.

FALSE: Do not throw exceptions.

For details about the specification, see 18.2.2(2)(q) HiRDB_for_Java_LONGVARBINARY_TRUNCERROR.

STATEMENT_CLOSE_BEHAVIOR=whether-to-ignore-preprocessing-results

Specifies whether preprocessing results are to be ignored during execution of the close method of Statement (the Statement, PreparedStatement, and CallableStatement classes).

TRUE: Ignore preprocessing results.

FALSE: Do not ignore preprocessing results.

If any other value is specified, the JDBC driver throws an SQLException.

For details about the specification, see 18.2.2(2)(r) HiRDB_for_Java_STATEMENT_CLOSE_BEHAVIOR.

HiRDB_INI=directory-path-of-HiRDB.INI-file

Specifies the absolute path of the directory that contains the HiRDB.INI file. This item is applicable when the HiRDB client environment variables specified in the HiRDB.INI file are to be in effect, in which case the HiRDB client environment variables in the HiRDB.ini file located in the directory specified here will take effect. If the specified directory does not contain a HiRDB.ini file and this is an interval driver, this specification is ignored.

If this specification is omitted, the contents of the HiRDB.ini file are ignored.

USER=user-name

Specifies the user name.

For details about the specification, see 18.2.2(2)(a) user.

PASSWORD=password

Specifies the password.

For details about the specification, see 18.2.2(2)(b) password.

UAPNAME=application-name

Specifies identification information (UAP identifier) for the UAP that is to access the HiRDB server.

For details about the specification, see 18.2.2(2)(c) UAPNAME.

BATCHEXCEPTION_BEHAVIOR=whether-to-set-JDBC-standard-compliant-update-count

Specifies whether an update count that is compliant with the JDBC standard is to be set for the return value of the getUpdateCounts method of java.sql.BatchUpdateException.

For details about the specification, see 18.2.2(2)(v) HiRDB_for_Java_BATCHEXCEPTION_BEHAVIOR.

(c) Notes about specification of HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR

The notes that follow apply to specification of HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR.

When TRUE is specified in HIRDB_CURSOR or STATEMENT_COMMIT_BEHAVIOR

• If the PDDDLDEAPRPEXE and PDDDLDEAPRP client environment definitions are both set to NO and another user executes a definition SQL statement for a schema resource (table or index) to be accessed by a SELECT, INSERT, DELETE, UPDATE, PURGE TABLE, or CALL statement, the definition SQL statement remains on lock-release wait status until the connection that was accessing the schema resource is disconnected or until the Statement object that was accessing the schema resource is closed and committed (applicable when TRUE is specified in STATEMENT_CLOSE_BEHAVIOR).
• If YES is set in either the PDDDLDEAPRPEXE or the PDDDLDEAPRP client environment definition and another user executes a definition SQL statement for a schema resource (table or index) to be accessed by a SELECT, INSERT, DELETE, UPDATE, PURGE TABLE, or CALL statement, the preprocessing results of the SELECT, INSERT, DELETE, UPDATE, PURGE TABLE, or CALL statement are ignored. If an SQL statement with an invalid preprocessing result is executed, an SQLException occurs (the value obtained by the getErrorCode method is -1542).
• When TRUE is specified for HIRDB_CURSOR or STATEMENT_COMMIT_BEHAVIOR,^#1 the only precompiled SQL statements^#2 that are valid after execution of commit processing^#3 are the SELECT, INSERT, DELETE, UPDATE, PURGE TABLE, and CALL statements.

#1

This also applies to either of the following specifications:

• TRUE is set for the following items in the properties specified by the getConnection method:
  HIRDB_CURSOR
  HiRDB_for_Java_STATEMENT_COMMIT_BEHAVIOR
  
• true is specified by the following methods of the PrdbDataSource, PrdbConnectionPoolDataSource, or PrdbXADataSource class:
  setHiRDBCursorMode
  setStatementCommitBehavior
  

#2

You precompile an SQL statement by executing a prepareStatement or prepareCall method of the Connection class.

#3

In addition to explicit commit processing by the commit method, the following cases also apply:

• Implicit commit processing by the AUTO commit mode
• Execution of a definition SQL statement
• Execution of the PURGE TABLE statement
• Implicit rollback processing by the rollback method
• Implicit rollback processing because of an SQL execution error

For SQL statements other than SELECT, INSERT, DELETE, UPDATE, PURGE TABLE, and CALL, precompiled SQL statements become invalid during commit processing.

An error will occur if a PreparedStatement or CallableStatement class object that stores a precompiled SQL statement that has become invalid is used to execute the SQL statement. The following shows an example that results in an error:

PreparedStatement pstmt1 = con.prepareStatement("lock table tb1"); PreparedStatement pstmt2 = con.prepareStatement("lock table tb2"); pstmt1.execute(); //Does not trigger an error. con.commit(); pstmt2.execute(); //Triggers an error. pstmt1.close(); pstmt2.close();

Because the SQL statements to be executed in this example are LOCK statements, after commit processing is executed, PreparedStatement becomes invalid and an error occurs, even if TRUE is specified for STATEMENT_COMMIT_BEHAVIOR.

• When TRUE is specified for HIRDB_CURSOR, the JDBC driver uses the holdable cursor facility of HiRDB.
• When TRUE is specified for HIRDB_CURSOR, the cursor operation mode for the result set that is returned by a procedure by using the results-set return facility is determined by the procedure's definition. Note that because the JDBC driver cannot detect a procedure's cursor operation mode, it assumes the operation mode specified for HIRDB_CURSOR. Therefore, if TRUE is specified for HIRDB_CURSOR, but the cursor operation mode for the result set returned by the procedure is not a holdable cursor, a database access performed after commit processing will result in SQLException. The following shows the status of the ResultSet object after commit processing:
  

  Result set returned by procedure	HIRDB_CURSOR setting
  	TRUE	FALSE
  Holdable cursor	Usable after commit processing.	If an operation performed after commit processing involves a database access, an error will result.#
  Non-holdable cursor	If an operation performed after commit processing involves a database access, an error will result.	If an operation performed after commit processing involves a database access, an error will result.

#

Because the cursor is not closed during commit processing, it remains open until the ResultSet object is closed or the CallableStatement or Connection object that created the ResultSet object closes.

Combinations of HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR specification values

The following table shows specification values for the combinations of HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR whether ResultSet and Statement objects become valid after commit processing is executed.

Table 18-3 Status of ResultSet objects and Statement objects after commit execution

STATEMENT_COMMIT_BEHAVIOR specification value	HIRDB_CURSOR specification value
	TRUE	FALSE
TRUE	ResultSet object: Valid Statement object: Valid	ResultSet object: Invalid Statement object: Valid
FALSE		ResultSet object: Invalid Statement object: Invalid

The following table shows the return value of the DatabaseMetaData method depending on the HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR specification values.

Table 18-4 Return values of the DatabaseMetaData method

STATEMENT_COMMIT_BEHAVIOR specification value	HIRDB_CURSOR specification value
	TRUE	FALSE
TRUE	supportsOpenStatementsAcrossCommit: true supportsOpenCursorsAcrossCommit: true	supportsOpenStatementsAcrossCommit: true supportsOpenCursorsAcrossCommit: false
FALSE		supportsOpenStatementsAcrossCommit: false supportsOpenCursorsAcrossCommit: false

Examples of JDBC driver operation during COMMIT execution

The operation of the JDBC driver during COMMIT execution depends on the specification values of HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR.

Specification examples

[A] pstmt1=con.prepareStatement("select c1 from tb1"); [1] [B] rs1=pstmt1.executeQuery(); [2] [C] rs1.next() [3] [D] v1=rs1.getInt(1) [4] [E] rs1.next() [5] [F] v1=rs1.getInt(1) [6] [G] rs1.close() [7]

Driver operation at COMMIT execution

COMMIT timing	H=T and S=T#1	H=F and S=T#2	H=F and S=F#3
[A]	[1]-[7]: Operates normally.
[B]	[1]-[7]: Operates normally.		[1], [2], and [7]: Operates normally. [3]-[6]: Throws an SQLException.
[C]	[1]-[7]: Operates normally.	[1], [2], and [7]: Operates normally. [3]-[6]: Throws an SQLException.
[D]	[1]-[7]: Operates normally.	[1]-[3] and [7]: Operates normally. [4]-[6]: Throws an SQLException.
[E]	[1]-[7]: Operates normally.	[1]-[4] and [7]: Operates normally. [5] and [6]: Throws an SQLException.
[F]	[1]-[7]: Operates normally.	[1]-[5] and [7]: Operates normally. [6]: Throws an SQLException.
[G]	[1]-[7]: Operates normally.

#1: This represents the case when TRUE is specified for both HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR.

#2: This represents the case when FALSE is specified for HIRDB_CURSOR and TRUE is specified for STATEMENT_COMMIT_BEHAVIOR.

#3: This represents the case when FALSE is specified for both HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR.

Other notes

For notes about the PDDDLDEAPRP client environment definition, see 6.6.4 Environment definition information.

For details about the rules for the DECLARE CURSOR holdable cursor, see the manual HiRDB Version 9 SQL Reference.

The table below shows the properties that you can specify in the getConnection method of the DriverManager class. If the null value is specified for a property, the JDBC driver assumes that specification was omitted.

Table 18-5 Properties that can be specified in the getConnection method

(a) user

Specifies the authorization identifier.

If the null value is specified, the JDBC driver assumes that no authorization identifier was specified. If the character string has a length of 0, the JDBC driver throws an SQLException.

If this specification is omitted, either the PDNAMEPORT HiRDB client environment definition specified by HiRDB_for_Java_ENV_VARIABLES in the Properties argument of the getConnection method, or the PDUSER value in the HiRDB environment variable group specified for DBID in the URL takes effect. For details about the specification priorities, see 18.11 Connection information priorities.

If neither value is specified, the JDBC driver throws an SQLException when the getConnection method is executed.

Note that this property specification is ignored for an internal driver.

(b) password

Specifies the password.

If the specification value is the null or has a length of 0, the JDBC driver assumes that no password was specified.

For details about when this specification is omitted, see 18.11 Connection information priorities.

Note that this property specification is ignored for an internal driver.

(c) UAPNAME

Specifies UAP identification information (UAP identifier) for accessing the HiRDB server.

In the following cases, the JDBC driver assumes that no authorization identifier was specified:

• The null value is specified.
• A character string with a length of 0 or a character string of only single-byte space characters is specified.

For details about character strings that can be specified, see the description of the PDCLTAPNAME client environment definition in 6.6.4 Environment definition information.

For details about when this specification is omitted, see 18.11 Connection information priorities.

Note that this property specification is ignored for an internal driver.

Note

The UAP specified by this property is encoded in the conversion character set specified by ENCODELANG, and the first 30 bytes of the encoded UAP identifier are transferred to the HiRDB server (if the UAP identifier consists of more than 30 bytes, it is truncated to the first 30 bytes). Therefore, the UAP identifier that the HiRDB server can obtain is up to the first 30 bytes after the identifier has been encoded.

(d) JDBC_IF

Specifies whether or not a JDBC interface method trace is to be obtained.

ON: Obtain a JDBC interface method trace.

OFF: Do not obtain a JDBC interface method trace.

If this specification is omitted, OFF is assumed.

If any other value is specified, the JDBC driver throws an SQLException.

This property is ignored in the following cases:

• A valid log writer is not specified in the setLogWriter method.
• This is an internal driver.

For details about the JDBC interface method trace, see 18.14 JDBC interface method trace.

(e) TRC_NO

~<unsigned integer>((10-1000))<<500>>

Specifies the number of entries in the JDBC interface method trace.

The specification of this property is enabled when both of the following conditions are satisfied:

• The setLogWriter method has set valid log data.
• ON is specified for JDBC_IF.

Note that this property specification is ignored for an internal driver.

If the specification of this property is enabled but the specification value is invalid, the JDBC driver throws an SQLException.

For details about a JDBC interface method trace, see 18.14 JDBC interface method trace.

(f) ENCODELANG

Specifies the conversion character set for the HiRDB character codes of the connection destination when the JDBC driver uses the String class to exchange data with HiRDB.

Select a specifiable conversion character set from the encoding list shown under Internationalization in the Java^TM 2 SDK, Standard Edition documentation.

For the character codes of HiRDB and their corresponding conversion character sets, see Table 18-2 HiRDB character codes and corresponding conversion character sets.

If OFF is specified, the JDBC driver operates assuming that the applicable conversion character set for the HiRDB character codes, as shown in Table 18-2 HiRDB character codes and corresponding conversion character sets, was specified. If the HiRDB character codes are sjis, the conversion characters determined by the OS running the JDBC driver are as follows:

For UNIX: SJIS

For Windows: MS932

Note that the specification is case sensitive (except for OFF).

If a conversion character set that the Java Virtual Machine does not support is specified, the JDBC driver throws an SQLException during connection with the HiRDB server.

If this specification is omitted, the JDBC driver converts characters using the conversion character set specified by ENCODELANG in the URL.

(g) SQLWARNING_IGNORE

Specifies whether warnings returned from the database are to be retained by the Connection object.

TRUE: Do not retain warnings.

FALSE: Retain warnings.

If this specification is omitted, the value specified for SQLWARNING_IGNORE in the URL takes effect. If the specified value is neither TRUE nor FALSE, the JDBC driver throws an SQLException.

Retention of warnings for the Connection object is determined by the value of HiRDB_for_Java_SQLWARNING_LEVEL. For details about the warning retention levels, see 18.4.12(2)(b) Issuing conditions for SQLWarning objects. Note that the value of this property is not case sensitive.

(h) HIRDB_CURSOR

Specifies whether objects of the ResultSet class are to be validated or invalidated after HiRDB executes commit processing.

TRUE: Validate objects of the ResultSet class even after commit processing.

FALSE: Invalidate objects of the ResultSet class after commit processing.

If this specification is omitted, the value specified by HIRDB_CURSOR in the URL becomes valid. If a value other than TRUE or FALSE is specified, the JDBC driver throws an SQLException.

If an invalidated ResultSet object executes an operation other than calling the close method, the JDBC driver throws an SQLException.

Note

For notes about specifying this property, see (1)(c) Notes about specification of HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR.

(i) LONGVARBINARY_ACCESS

Specifies the method of accessing a JDBC SQL-type LONGVARBINARY (BLOB and BINARY types, which are HiRDB data types) database.

REAL: Access the database using real data.

LOCATOR: Access the database using the locator facility of HiRDB.

Note that real data is assumed for an access to a BINARY column with a definition length of 1,024 bytes or less.

If this specification is omitted, REAL is assumed.

If any other value is specified, the JDBC driver throws an SQLException.

Note

The following notes apply to specification of LONGVARBINARY_ACCESS:

When LONGVARBINARY_ACCESS is specified together with HiRDB_for_Java_LONGVARBINARY_ACCESS_SIZE

The following table describes the differences in how the JDBC driver gets BLOB and BINARY data (HiRDB data types) based on the specifications of HiRDB_for_Java_LONGVARBINARY_ACCESS_SIZE and LONGVARBINARY_ACCESS.

Table 18-6 Differences in how the HiRDB driver gets BLOB and BINARY data (HiRDB data types)

Execution method		LONGVARBINARY_ACCESS specification value#
		REAL	LOCATOR
CallableStatment.execute ResultSet.next		Acquires all the BLOB or BINARY data from the connected database.	Acquires the locator that indicates the BLOB or BINARY data in the connected database, instead of the actual BLOB or BINARY data.
CallableStatement.getBytes CallableStatement.getString CallableStatement.getObject ResultSet.getBytes ResultSet.getString ResultSet.getObject		Uses the BLOB or BINARY data obtained by ResultSet.next.	Acquires from the connected database all BLOB or BINARY data in segments of ACCESSSIZE x 1024 bytes.
Blob.getBytes		Extracts the range of data specified by the argument from the BLOB or BINARY data obtained by ResultSet.next.	Acquires from the connected database the range of BLOB or BINARY data specified by the argument in segments of ACCESSSIZE x 1024 bytes.
CallableStatement.getBinaryStream ResultSet.getBinaryStream ResultSet.getAsciiStream ResultSet.getUnicodeStream Blob.getBinaryStream		When the InputStream read method obtained by the executed method is executed, the JDBC driver extracts data from the BLOB or BINARY data obtained by ResultSet.next.	When the InputStream read method obtained by the executed method is executed, the JDBC driver acquires data from the connected database.
Blob.length		Acquires the data length from the BLOB or BINARY data obtained by ResultSet.next.	Acquires the data length from the connected database.
Blob.position		Acquires the position of the data matching the search pattern from the BLOB or BINARY data obtained by ResultSet.next.	Acquires the position of the data matching the search pattern from the connected database.
InputStream obtained by CallableStatement.getBinaryStream, ResultSet.getBinaryStream, or Blob.getBinaryStream	InputStream.available	Returns a value equal to or less than the length of the actual data indicated by the locator.	Returns a value equal to or less than ACCESSSIZE x 1024 bytes.
	InputStream.skip	Skips reading data up to the range equal to or less than the length of the actual data indicated by the locator.	Skips reading data up to the maximum range of ACCESSSIZE x 1024 bytes.
CallableStatement.getCharcterStream ResultSet.getCharcterStream		When the Reader read method obtained by getCharcterStream is executed, the JDBC driver extracts data from the BLOB or BINARY data obtained by ResultSet.next.	When the Reader read method obtained by getCharcterStream is executed, the JDBC driver acquires data from the connected database.

Legend:

ACCESSSIZE: Specification value of HiRDB_for_Java_LONGVARBINARY_ACCESS_SIZE

InputStream and Reader: Classes of objects returned by getBinaryStream, getAsciiStream, or getCharacterStream of the JDBC driver

#: Note that REAL is assumed for an access to a BINARY column with a definition length of 1,024 bytes or less.

Notes about execution performance

When LOCATOR is specified for LONGVARBINARY_ACCESS, execution performance might drop compared to when REAL is specified.

When REAL is specified, the JDBC driver accesses the connected database once during processing of ResultSet.next or CallableStatment.execute to obtain the locator. On the other hand, when LOCATOR is specified, in addition to the one access during processing of ResultSet.next or CallableStatment.execute, the JDBC driver accesses the connected database once to obtain the data length and once to obtain the data during execution of a data acquisition method (such as getBytes).

Notes about auto-commit

Even when auto-commit is enabled, commit processing does not occur in the following cases:

• Execution of a stored procedure in which LOCATOR is specified for LONGVARBINARY_ACCESS and an output parameter that satisfies either of the following conditions is specified:
  Output parameter is BINARY type with a size greater than 1,024 bytes
  Output parameter is BLOB type
  
• Execution of a stored procedure using the results-set return facility

Notes about data manipulation after the transaction terminates

When LOCATOR is specified for LONGVARBINARY_ACCESS, data manipulation cannot be performed if the transaction terminates during the period between acquisition of the SQL execution results (ResultSet.next or CallableStatement.execute) and the data manipulation (such as Blob.getBytes or InputStream.read). Data manipulation cannot be executed after the transaction terminates even if the HIRDB_CURSOR specification is TRUE.

Thus, you must ensure that all data manipulation will be performed before the transaction terminates.

(j) HiRDB_for_Java_SQL_IN_NUM

~<unsigned integer>((1-30000))<<300>>

Specifies the maximum number of input ? parameters in the SQL statements to be executed.

This specification becomes the number of input ? parameters that are obtained during SQL preprocessing. If the actual number of input ? parameters is greater than the specification value of this property, the JDBC driver gets the input ? parameter information from the HiRDB server after SQL preprocessing.

If the specification value is invalid, the JDBC driver throws an SQLException.

Note

If you will not be executing SQL statements that have input ? parameters, you should specify 1.

(k) HiRDB_for_Java_SQL_OUT_NUM

~<unsigned integer>((1-30000))<<300>>

Specifies the maximum number of output items for the SQL statements that are to be executed.

This specification becomes the number of output items obtained during SQL preprocessing. If the actual number of output items is greater than the specification value of this property, the JDBC driver gets output item information from the HiRDB server after SQL preprocessing.

If the specification value is invalid, the JDBC driver throws an SQLException.

Note

If you will not be executing SQL statements that have output items, you should specify 1.

(l) HiRDB_for_Java_SQLWARNING_LEVEL

Specifies the retention level for warning information that is issued during execution of SQL statements. For details about the retention levels for warning information, see 18.4.12(2)(b) Issuing conditions for SQLWarning objects.

IGNORE: Retain warning information at the IGNORE level.

SQLWARN: Retain warning information at the SQLWARN level.

ALLWARN: Retain warning information at the ALLWARN level.

If this specification is omitted, SQLWARN is assumed.

If the specification value is invalid, the JDBC driver throws an SQLException.

(m) HiRDB_for_Java_ENV_VARIABLES

Specifies HiRDB client environment definitions in the following format:

 
  variable-name=value;variable-name=value;...;variable-name=value
 

For details about client environment definitions supported by the JDBC driver, see 18.10 Supported client environment definitions. If a client environment definition that is not supported by the JDBC driver is specified in a variable name, the JDBC driver ignores the specification. Note that variable names are case sensitive.

For details about the priorities for connection information that can be specified in multiple ways, see 18.11 Connection information priorities.

Specification example

java.util.Properties prop;
prop=new java.util.Properties();
prop.setProperty("HiRDB_for_Java_ENV_VARIABLES",
 "PDFESHOST=FES1;PDCWAITTIME=0");
 

(n) HiRDB_for_Java_STATEMENT_COMMIT_BEHAVIOR

Specifies whether Statement objects are to be validated or invalidated after HiRDB executes commit processing.

TRUE: Validate Statement objects after commit processing.

FALSE: Invalidate Statement objects after commit processing.

The objects that become invalid after commit execution are SQL statements that were precompiled by the prepareStatement or prepareCall method of the Connection class, and ResultSet class objects obtained by the executeQuery method of Statement.

If this specification is omitted, the value specified for STATEMENT_COMMIT_BEHAVIOR in the URL becomes effective.

Note

For notes about specification of this property, see (1)(c) Notes about specification of HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR.

(o) HiRDB_for_Java_LONGVARBINARY_ACCESS_SIZE

~<unsigned integer>((0-2097151))<<0>> (kilobytes)

Specifies the length of JDBC SQL-type LONGVARBINARY data to be requested at one time to the HiRDB server. If LONGVARBINARY_ACCESS specifies data other than LOCATOR data, this specification is invalid.

For example, suppose that 20 is specified for this property and the getBytes method of ResultSet attempts to get 100 kilobytes of JDBC SQL-type LONGVARBINARY data stored in the database. In such a case, the JDBC driver gets and returns the data by dividing the operation into five executions of 20 kilobytes each. If 0 is specified, the JDBC driver requests the data all at once.

If the specification value is invalid, the JDBC driver throws an SQLException.

Note

For notes about specification of this property, see (i) LONGVARBINARY_ACCESS.

(p) HiRDB_for_Java_MAXBINARYSIZE

~<unsigned integer>((0-2147483647)) (bytes)

Specifies the maximum data size during acquisition of JDBC SQL-type LONGVARBINARY data.

When the JDBC driver is getting JDBC SQL-type LONGVARBINARY data, it allocates memory of the defined length because it cannot determine the actual data length until it actually gets the data. Therefore, to get the value of a string for which the specified size is large (for example, 2,147,483,647 bytes, which is the maximum length for HiRDB's BINARY and BLOB data types), the JDBC driver attempts to allocate 2,147,483,647 bytes of memory, because that is the defined length. Consequently, a memory shortage may occur, depending on the execution environment.

You should specify for this property the maximum length of the data that is actually stored. If the data length of the BINARY or BLOB data to be acquired is larger than the size specified by this property, the JDBC driver truncates the acquired data to the specified size. When the JDBC driver does truncate data, it receives a warning from the HiRDB server when it executes the next method of ResultSet. In response to the received warning, the JDBC driver throws an SQLException or generates (or ignores) an SQLWarning, as determined by the specification of setLONGVARBINARY_TruncError.

If no upper limit is set by this property, the defined length of the target acquisition data becomes the upper limit.

If the specification value is invalid, the JDBC driver throws an SQLException.

Note

This property value is ignored when a BLOB column or a BINARY column whose definition length is greater than 1,024 bytes is accessed with LOCATOR specified for LONGVARBINARY_ACCESS. The JDBC driver allocates an area based on the actual data length and gets the entire data.

(q) HiRDB_for_Java_LONGVARBINARY_TRUNCERROR

Specifies whether an exception is or is not to be thrown if truncation occurs during acquisition of JDBC SQL-type LONGVARBINARY data.

TRUE: Throw an exception if truncation occurs.

FALSE: Do not throw an exception if truncation occurs.

If this specification is omitted, TRUE is assumed.

If IGNORE is specified for HiRDB_for_Java_SQLWARNING_LEVEL, the JDBC driver operates as if FALSE were specified for this property.

Any truncation that occurs during acquisition of JDBC SQL-type LONGVARBINARY data indicates that the following condition is satisfied:

 
Actual length of JDBC SQL-type LONGVARBINARY data obtained during SQL execution > data length specified by HiRDB_for_Java_MAXBINARYSIZE
 

(r) HiRDB_for_Java_STATEMENT_CLOSE_BEHAVIOR

Specifies whether preprocessing results are to be ignored during execution of the close method of Statement (Statement, PreparedStatement, and CallableStatement classes) when the Statement or ResultSet object is specified to remain valid after commit processing.^#1

This specification can be made by using the HiRDB_for_Java_STATEMENT_CLOSE_BEHAVIOR system property.

If the server is XDM/RD E2, this specification is ignored.

TRUE: Ignore preprocessing results.

FALSE: Do not ignore preprocessing results.

If the specified value is invalid, the JDBC driver throws an SQLException.

The value of this property is not case sensitive.

If this specification is omitted, the value of the STATEMENT_CLOSE_BEHAVIOR item in the URL takes effect. If this item is omitted in the URL, FALSE is assumed as the value of the property.

If NO is set in both the PDDDLDEAPRP and the PDDDLDEAPRPEXE client environment definitions and another user executes a definition SQL statement for a schema resource (table or index) to be accessed by an SQL statement (SELECT, INSERT, DELETE, UPDATE, PURGE TABLE, or CALL statement), the definition SQL statement is placed on lock-release wait status. This lock-release wait status is released at the times described below. Note that if you specify TRUE, you can release this status during commit processing.

• If Statement or ResultSet object is specified to remain valid after commit processing
  
  • If TRUE is specified
    When commit processing is performed after Statement close^#2 or when the connection is closed.
    
  • If FALSE is specified
    When the connection is closed.
    
• Other
  When commit processing is performed^#2 or when the connection is closed.
  

#1

One of the following applies:

1. TRUE is specified for the following items in the properties that are specified by the getConnection method:
   HIRDB_CURSOR
   HiRDB_for_Java_STATEMENT_COMMIT_BEHAVIOR
   
2. TRUE is specified for the following items in the URL that is specified by the getConnection method:
   HIRDB_CURSOR
   STATEMENT_COMMIT_BEHAVIOR
   
3. true is specified in the following methods of the PrdbDataSource, PrdbConnectionPoolDataSource, or PrdbXADataSource class:
   setHiRDBCursorMode
   setStatementCommitBehavior
   
4. The Connection.setHoldability method (with ResultSet.HOLD_CURSORS_OVER_COMMIT specified in the argument) is executed.
5. The following methods of the Connection class (with ResultSet.HOLD_CURSORS_OVER_COMMIT specified in the resultSetHoldability argument) are executed:
   createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)
   prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
   prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
   

#2

In addition to explicit commit using the commit method, the following also apply:

• Implicit commit by automatic commit
• Execution of a definition SQL statement
• Execution of a PURGE TABLE statement
• Explicit rollback by rollback method
• Implicit rollback by an SQL execution error

If TRUE is specified and the Statement or ResultSet object is specified to remain valid after commit processing, HiRDB creates a transaction and executes DEALLOCATE PREPARE processing when the Statement is closed. Therefore, if the PDSWAITTIME client environment variable is specified, the interval monitoring specified in PDSWAITTIME begins. If automatic commit is disabled and neither an SQL execution, nor commit, nor disconnection is performed by another statement for an extended period after the Statement was closed, HiRDB closes the connection based on the interval monitoring.

If Cosminexus is connected and the connection pooling function is used by using the Type4 JDBC driver from DB Connector, you must specify FALSE. When the connection pooling function is used, connection returns to the pool and the transaction remains even if a close method for connection is called from the application. Therefore, you must execute commit processing after Statement is closed.

If you use the statement pooling facility, you must either omit this specification or specify FALSE.

(s) HiRDB_for_Java_DBID

Specifies the port number of HiRDB (information corresponding to PDNAMEPORT) or the HiRDB client's environment variable group file name. For details about the specification, see the explanation about DBID in 18.2.2(1)(b) Explanation of URL items.

(t) HiRDB_for_Java_DBHOST

Specifies the host name of HiRDB. For details about the specification, see the explanation about DBHOST in 18.2.2(1)(b) Explanation of URL items.

(u) HiRDB_for_Java_HiRDB_INI

Specifies the absolute path of the directory that contains the HiRDB.INI file. This property is applicable when the HiRDB client environment variables specified in the HiRDB.INI file are to be in effect, in which case the HiRDB client environment variables in the HiRDB.ini file located in the specified directory will take effect. If the specified directory does not contain a HiRDB.ini file and this is an interval driver, this specification is ignored.

If this specification is omitted, the value specified for the HiRDB_INI item in the URL is assumed. If the HiRDB_INI item is omitted in the URL, the contents of this file are ignored.

(v) HiRDB_for_Java_BATCHEXCEPTION_BEHAVIOR

Specifies whether an update count that is compliant with the JDBC standard is to be set for the return value of the getUpdateCounts method of java.sql.BatchUpdateException.

This property is applicable when the version of the connection-target HiRDB is 08-02 or later.

TRUE: Set an update count that is compliant with the JDBC standard.

FALSE: Set a HiRDB-specific update count.

The value of this property is not case sensitive.

If this specification is omitted, the BATCHEXCEPTION_BEHAVIOR value in the URL items takes effect. If this specification is omitted in the URL, the JDBC driver assumes that TRUE is specified.