JDBC connection properties

The JDBC driver supports the following connection properties. If the same property occurs more than once in the connection string, the last entry takes precedence. Property names are not case sensitive.

Table 1. JDBC connection properties
Property names Description
AdabasColumnNameCorrelationIds

Alias: ABCN

Support ADABAS column name correlation IDs.

Required: false

Default value: false

Valid values: [true, false]

ApplicationName

Alias: APNA

Application name that is sent to the host as part of logon for connection tracking.

Required: false (maximum of 16 characters in length)

AuthenticationMechanism

Alias: ATHM

Mechanism for encrypting passwords.

Required: false

Default value: DEFAULT

Valid values: [DEFAULT, AES]

BindInetSocketAddressList

Alias: BISAL

A single local name or IP address to bind a socket, or a comma-separated IP address list (used with MapReduce), or AutoDetect to detect NIC IP addresses automatically.

Required: false

Default value: No

CatalogPrefix

Alias: CPFX

Database catalog prefix, SYSPROC for DB2, SQLENG for DVS, SDBMAP for the others.

Required: false

Default value: SYSPROC

Valid values: [SYSIBM, SYSPROC, SDBMAP, SQLENG]

CertificateHostName

Alias: HostNameInCertificate

Host name for certificate validation when SSL encryption and validation is enabled.

Required: false

Charset

Alias: CS, CodePage, CP, Encoding, ENC

The database character encoding.

To get a complete list the charsets that are available on a particular JVM, call the Charset.availableCharsets() API, where charsetName is one of the available Java character sets.

The list of available character sets that are returned depends on the specific version and supplier of Java, as well as the availability of the ICU jar files on the classpath.

Names with the 'x-' prefix indicate that a charset is not registered at the Internet Assigned Numbers Authority (IANA). For more information, see Class Charset and ICU Converter Explorer.

Use the IBM JRE for proper data translation when Charset specifies a Japanese Code page such as; 930, 939, 1390, 1399 or 5026.

IBM JRE 1.8 or 1.7 is recommended when accessing IBM-1390 and IBM-1399 mainframe data, and using or exchanging that data in a Unicode environment.

IBM JRE 1.8 is recommended when accessing IBM-930 and IBM-939 mainframe data, if you do not experience issues using the IBM-conversion-table-based conversion of the following EBCDIC characters:
  • X'4260' (Minus sign)
  • X'444A' (EM Dash)
  • X'43A1' (Wave Dash)
  • X'447C' (Double vertical line)
  • X'426A' (Broken bar)

Required: false

Default value: IBM037

Valid values: For a list of supported character sets, see Character sets.

CicsTransactionName

Alias: TRNA

CICS transaction name.

Required: false

Default value: (maximum of eight characters in length)

CompressionLevel Compression level (ZLib only), -1 (default), 1 (best speed) ... 9 (best compression).

Required: false

Default value: -1

Valid values: [-1, 1, 2, 3, 4, 5, 6, 7, 8, 9]

CompressionThresholdBytes Compression threshold in bytes. The driver compresses data for buffers larger than this size. This value can be post-fixed with a unit like KB (K) or MB (M). For example, the following values are all equal: 1048576, 1024 K, 1024 KB, 1 MB.

Required: false

Default value: 0

CompressionType The type of compression used.

Required: false

Default value: UNCOMPRESSED

Valid values: [ZLIB_NO_WRAP, CMBU, CMBV, UNCOMPRESSED]

ConnectionType Connection wire type.

Required: false

Default value: SOCKET

Valid values: [SOCKET, SOCKET_CHANNEL]

CountTraceEnter Counts JDBC API calls.

Required: false

Default value: false

Valid values: [true, false]

DatabaseRequestModule

Alias: DBRM

Database request module.

Required: false

Default value: OPRXSQ (maximum of eight characters in length)

DatabaseType

Alias: DBTY

The database type to connect to after connecting to the server.

Required: false

Default value: DRDAorDB2

Valid values:
  • DRDAorDB2 (the data source type is DB2 on a z/OS subsystem or DB2 LUW database)
  • DVS (the data source type is determined by the virtual table map definition, and no value is specified for SUBSYS)
EncodeUserName When set to true, the user name is encoded when establishing the server connection. Support of this feature can be controlled using server parameters USERIDENCODEREQUIRE and USERIDENCODEALLOW.

Required: false

Default value: false

Valid values: [true, false]

EncryptionMethod Encryption method.

Required: false

Default value: NONE

Valid values: [NOENCRYPTION, NONE, SSL]

GetTablesSchemaFilter

Alias: DP

Filter to use for getTables() DB2 metadata schema.

Required: false

HexDumpBytesPerLine Bytes per line in the hexadecimal dump.

Required: false

Default value: 16

HexDumpBytesPerWord Bytes per word in the hexadecimal dump.

Required: false

Default value: 4

Host Host name or IP address.

Required: true

IniFile

Alias: INI

Loads properties from this INI file (overrides IniFileEnvVar).

Required: false.

IniFileCharset

Alias: INICS

The INI file Charset.

Required: false

Default value: UTF-8.

IniFileDataSourceName

Alias: DSN

Loads properties from a section name to an INI file.

Required: false.

IniFileEnvVar

Alias: INIEV

Loads properties from the INI file to this environment variable.

Required: false.

Default value: DV_INI

InitialCurrentDegree

Alias: SEDG

Initial current degree (DB2).

Required: false

Valid values: [ANY, 1]

InitialCurrentPackageSet

SEPK

Initial current package set (DB2).

Required: false

InitialCurrentRules

Alias: SERL

Initial current rules (DB2).

Required: false

Valid values: [DB2, STD]

InitializationString Initialization string, use ';' to separate statements, wrap the string in '(' and ')' when used in a connection string.

Required: false

KeyPassword

Alias: KP

The SSL key password.

Required: false

KeyStore

Alias: KS

The SSL keystore.

Required: false

KeyStorePassword

Alias: KSP

The SSL keystore password.

Required: false

LegacySqlPrepareEnabled

Alias: WRPR

This flag controls the behavior of SQLPrepare for non-DB2 data sources such as ADABAS, VSAM, IMSDB, and VSAM CICS. When this keyword is set to true (which is the default), a request is always sent to the host at SQLPrepare time to obtain metadata for the SQL statement. For applications that access non-DB2 data sources and do NOT require metadata after the SQLPrepare, it is recommended to set WRPR to false for better performance since this will eliminate a network roundtrip whenever a SQLPrepare is executed.

Required: false

Default value: true

Valid values: [true, false]

LGID

Alias: LanguageID

This setting is for backward compatibility. It is recommended to use Charset instead.

Each language code corresponds to a charset used for byte conversion. If a key has no value, the driver will use the default. The mappings are as follows:

{ARB=IBM420, CHS=, CHT=, DAN=IBM01142, DEU=IBM01141, DFT=IBM037, ENC=IBM1047, ENG=IBM285, ENU=IBM037, ESN=IBM01145, ESP=IBM284, FIN=IBM01143, FRA=IBM01147, FRC=IBM037, ISL=IBM01149, ITA=IBM01144, JNL=IBM1390, JNX=IBM1399, JPL=IBM5026, JPX=IBM5035, KOR=IBM037, KRN=x-IBM833, MDI=, NGN=IBM01142, NLD=IBM037, NOR=IBM01142, PPS=, PTG=IBM037, SVE=IBM278, SWE=IBM01143, TUR=IBM1026}

Required: false

Default value: ENU

Valid values (31): [ARB, CHS, CHT, DAN, DEU, DFT, ENC, ENG, ENU, ESN, ESP, FIN, FRA, FRC, ISL, ITA, JNL, JNX, JPL, JPX, KOR, KRN, MDI, NGN, NLD, NOR, PPS, PTG, SVE, SWE, TUR]

LogConfiguration

Alias: LOGCONFIG

Sets the Log4j 2 configuration file.

Required: false

LogThreadsState

Alias: LTS

Logs the state of a thread.

Required: false

Default value: false

Valid values: [true, false]

LogThreadsStatePeriodMillis Logs the state period for a thread in milliseconds.

Required: false

Default value: 1000

LoginTimeoutMillis Login timeout in milliseconds (0 = system default if there is one, or no limit.)

Required: false

Default value: 0

LoginTimeoutSeconds

Alias: LOGINTIMEOUT

Login timeout in seconds.

Required: false

Default value: 0

MapReduceClient

Alias: MRC, MapReduce

Use MapReduceClient (MRC) to read query results in parallel from different connections. When enabled, the driver creates one master connection and N worker connections (instances of JDBC connections).

Required: false

Default value: false

Valid values: [true, false, list]

To distribute MapReduce on a single server, select from the following methods:
  • Set MapReduceClient to true (MRC=true). The MapReduceConnectionCount defaults to the number of CPU cores discovered (for example: MRCC=10)
  • Set MRC=(host, port, taskCount)

To distribute MapReduceClient over multiple servers, set MapReduceClient: MCR=(host1, port1, taskCount1), (host2, port2, taskCount2),...

If you are using MapReduceClient with RDBMS or IMS, you must complete the metadata repository configuration requirements. See "MapReduce" in the Administrator's Guide.

MapReduceClientCount

Alias: MRCC

The single-connection MapReduceClientCount. This value is only set for use with MRCN. The MRCC default setting is 0.

Required: false

Default value: 0

MapReduceClientNumber

Alias: MRCN

To enable highly-parallel client applications to control concurrent MapReduce connections, from which queries are executed as a single thread, set the MapReduceClientCount (MRCN) value for each MapReduceClientCount (MRCC).

The following example shows a connection string used to connect to the first of four available connections:

jdbc:rs:dv://host:port;DBTY=DVS;
PWD=xxx;UID=xxx;
MXBU=4MB;
MapReduceClientCount=4;
MapReduceClientNumber=1

To disable this feature, set MapReduceClientCount to 0 (MRCC=0) and set MapReduceClient to false (MRC=false).

MapReduceFillValueMaximumInitialSize

Alias: MRFVMIS

This value specifies the initial capacity of the result row pre-fetch cache for a given buffer that is used after the MapReduce or Parallel IO read queue exceeds the value set for MapReduceFillValueThreshold.

Required: false

Default value: 20,000 (rows per buffer)

MapReduceFillValueThreshold

Alias: MRFVT

When using Parallel IO or MapReduce, this value specifies the number of buffers on the parallel IO thread that must be exceeded before pre-filling the column values (converting mainframe row bytes to Java object representations).

Required: false

Default value: -1 (off).

MapReducePollTimeOutMillis

Alias: MRPTO

The MapReduce and Parallel IO inter-thread poll timeout, in milliseconds.

Required: false

Default value: 50

MapReduceQueueStats

Alias: MRQS

Gathers statistics for MapReduce result sets.

Required: false

Default value: false

Valid values: [true, false]

MaximumBufferSize

Alias: MXBU

Maximum server-side communication buffer size in bytes. This value can be post-fixed with a unit like KB (K) or MB (M). For example, the following values are all equal: 1048576, 1024 K, 1024 KB, 1 MB. The minimum value is 40960.

Required: false

Default value: 262144

MaximumFieldSize

Aliases: MFS, MaxFieldSize

Maximum field size to return.

Required: false

Default value: 2147483647

MaximumRows

Alias: MR

Maximum number of rows to return.

Required: false

Default value: 0

MetaDataCharset

Alias: MDCS

The database metadata character encoding. Available encodings depends on the runtime. See the Charset property.

Required: false

Default value: IBM037

NetworkTimeoutMillis

Alias: NTOM

Network timeout in milliseconds.

Required: false

Default value: 0

NetworkTimeoutSeconds

Alias: NETWORKTIMEOUT

Network timeout in seconds.

Required: false

Default value: 0

ParrallelIoBufferCount

Alias: PIOBC

When the value of the Parallel IO buffer count is > 0 (where the buffer size = MXBU), a background thread reads the rows from the server as the main thread consumes them. This memory is re-usable.

For example, if MXBU is set to 4 MB and PIOBC is set to 10, the driver uses 40 MB of memory as the read-ahead buffer (10 x 4 MB buffers).

Required: false. Default value: 0.

Password

Alias: PWD, PassPhrase

Password or password phrase.

Required: false

PasswordToUpperCase

Alias: UCLC

Converts passwords to uppercase. This property is ignored when a password phrase has been specified.

Required: false

Default value: true

Valid values: [true, false]

Plan The DB2 plan name used for a DB2 connection. This is used when the subsystem is set to a valid DB2 subsystem name.

Required: false

Default value: SDBC1010 (maximum of eight characters in length)

Port Server port.

Required: false

Default value: 1200

PrepareMetadataSQL Determines how the SQL statement metadata calls are handled.

Required: false

Default value: true

Valid values: [true, false]

If set to true, the driver prepares the SQL statements for metadata calls.

If set to false, the driver builds and executes the SQL statements for metadata calls dynamically, which can be susceptible to SQL injection attacks.

QueryTimeoutMillis

Alias: QTOM

Query timeout in milliseconds.

Required: false

Default value: 0

QueryTimeoutSeconds

Alias: QUERYTIMEOUT

Query timeout in seconds.

Required: false

Default value: 0

SelectForReadOnly

Alias: RO

Appends FOR FETCH ONLY to JDBC read-only SQL query statements.

Required: false

Default value: true

Valid values: [true, false]

ServerCertificateStrategy Server certificate strategy.

Required: false

Default value: Validate

Valid values: [Validate, AcceptSelfSigned, Trust]

SocketKeepAlive

Alias: SKA

Socket keep alive.

Required: false

Default value: false

Valid values: [true, false]

SocketReceiveBufferSize

Alias: SRBS

Socket receive buffer size hint in bytes. This value can be post-fixed with a unit like KB (K) or MB (M). For example, the following values are all equal: 1048576, 1024 K, 1024 KB, 1 MB.

Required: false

Default value: 0

SocketSendBufferSize

Alias: SSBS

Socket send buffer size hint in bytes. This value can be post-fixed with a unit like KB (K) or MB (M). For example, the following values are all equal: 1048576, 1024 K, 1024 KB, 1 MB.

Required: false

Default value: 0

SocketTcpNoDelay

Alias: STCPND

Socket TCP NoDelay.

Required: false

Default value: false

Valid values: [true, false]

SqlAuthorizationId

Alias: ALUS

SQL authorization ID.

Required: false

SslContextProtocol

Alias: SSLPROTOCOL

SSL context protocol.

Required: false

Default value: TLS

StrictJdbcCompliance Indicates whether the driver complies strictly with the JDBC spec.

Required: false

Default value: false

Valid values: [true, false]

SubSystem

Alias: SUBSYS

The database subsystem name.

If the data source is DB2 (DatabaseType=DRDAorDB2), enter the DB2 subsystem name as it exists on the mainframe.

If the data source is a non-DB2 database (where TYPE must be Member, Group, or LUW), enter the name as it exists in the NAME field of the DEFINE entry in the server configuration member, AZKSIN00.

If the data source is DVS, the subsystem name should be set to NONE.

Required: false

Default value: NONE

Valid values: 1 - 4 alphanumeric characters

ThrowUnsupportedAll [Development tool] Throws an exception when an API is not supported.

Required: false

Default value: true

Valid values: [true, false]

TraceBrowseAppender To collect JDBC driver server trace log information, add the name of the collection appender to the log4j configuration file.
The following example shows the collection name tag:
<Appenders>
    ... other appenders here ...
    <Collection name="TB">
      <PatternLayout>
        <Pattern>%d %-5level [%t][%logger]
         %msg%n%throwable</Pattern>
      </PatternLayout>
    </Collection>
  </Appenders>
  <Loggers>
    <Root level="...">
     ... other appenders here ...
      <AppenderRef ref="TB" />
    </Root>
Where the name of the collection appender (TB in this example) is the name you choose.

Add the TraceBrowseAppender setting to the JDBC connect string to provide the collection appender name in the log4j2.xml config file to the server. For example, TraceBrowseAppender=TB.

The server parameter TRACE EXTERNAL TRACE DATA (TRACEEXTERNTRACEDATA) must also be enabled.

Required: false

TruncateCallLiteral

Alias: TRLT

Truncate CALL string.

Required: false

Default value: true

Valid values: [true, false]

TrustStore The SSL trust store.

Required: false

TrustStorePassword The SSL trust store password.

Required: false

UpperCaseAllCharacters

This field controls if all character data sent to the host should be converted to upper case or not. If this field is set to true, then all character data will be converted to upper case. If this field is set to false, then character data will not be converted to upper case.

Required: false

Default value: false

Valid values: [true, false]

UpperCaseNonLiterals

This flag controls if all non-literal values in SQL statements passed to the driver should be converted to upper case or not. If this flag is set to true, then strings not in single or double quotes will be converted to upper case.

Required: false

Default value: true

Valid values: [true, false]

URL Use to specify connection properties.

Required: false

user

Alias: UID

The user name or identifier.
UserParm

Alias: UserParm

Sent in the logon information to complete logon to a host security system and/or database. Maximum of 100 characters in length.
ValidateServerCertificate Validate server certificate or not.

Required: false

Default value: true

Valid values: [true, false]

VpdGroupMemberCount Virtual Parallel Data group member count.

Required: false

Default value: 0-255

VpdGroupName Virtual Parallel Data group name. Maximum of eight characters in length.

Required: false

Default value:

VpdGroupOpenTimeoutSeconds Virtual Parallel Data group open timeout in seconds.

Required: false

Default value: 0

VpdIoThreadCount Virtual Parallel Data I/O thread count.

Required: false

Default value: 0-255

XaEnabled

Alias: XAEN

Set to true to enable XA transactions.

Required: false

Default value: false

Valid values: [true, false]

XaTransactionManager

Alias: XAOP

The type of transaction manager used for XA operations.

Required: false

Valid value: JTS

Character sets

The list of available character sets that are returned depends on the specific version and supplier of Java, as well as the availability of the ICU jar files on the classpath.

The following Charsets (CS) are supported:

Charsets

Adobe-Standard-Encoding,

Big5, Big5-HKSCS, BOCU-1,

CESU-8, cp1363, cp851,

EUC-JP, EUC-KR,

GB18030, GB2312, GB_2312-80, GBK,

hp-roman8, HZ-GB-2312,

IBM-Thai, IBM00858, IBM01140, IBM01141, IBM01142, IBM01143, IBM01144, IBM01145, IBM01146, IBM01147, IBM01148, IBM01149, IBM037, IBM1026, IBM1047, IBM273, IBM277, IBM278, IBM280, IBM284, IBM285, IBM290, IBM297, IBM420, IBM424, IBM437, IBM500, IBM775, IBM850, IBM852, IBM855, IBM857, IBM860, IBM861, IBM862, IBM863, IBM864, IBM865, IBM866, IBM868, IBM869, IBM870, IBM871, IBM918, ISO-2022-CN, ISO-2022-CN-EXT, ISO-2022-JP, ISO-2022-JP-1, ISO-2022-JP-2, ISO-2022-KR, ISO-8859-1, ISO-8859-10, ISO-8859-13, ISO-8859-14, ISO-8859-15, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9,

JIS_X0201, JIS_X0212-1990,

KOI8-R, KOI8-U, KSC_5601,

macintosh,

SCSU, Shift_JIS,

TIS-620,

US-ASCII, UTF-16, UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, UTF-8,

windows-1250, windows-1251, windows-1252, windows-1253, windows-1254, windows-1255, windows-1256, windows-1257, windows-1258, windows-31j,

x-Big5-HKSCS-2001, x-Big5-Solaris, x-compound-text, x-ebcdic-xml-us, x-euc-jp-linux, x-EUC-TW, x-euc-tw-2014, x-eucJP-Open, x-ibm-1047-s390, x-ibm-1125_P100-1997, x-ibm-1129_P100-1997, x-ibm-1130_P100-1997, x-ibm-1131_P100-1997, x-ibm-1132_P100-1998, x-ibm-1133_P100-1997, x-ibm-1137_P100-1999, x-ibm-1140-s390, x-ibm-1141-s390, x-ibm-1142-s390, x-ibm-1143-s390, x-ibm-1144-s390, x-ibm-1145-s390, x-ibm-1146-s390, x-ibm-1147-s390, x-ibm-1148-s390, x-ibm-1149-s390, x-ibm-1153-s390, x-ibm-1154_P100-1999, x-ibm-1155_P100-1999, x-ibm-1156_P100-1999, x-ibm-1157_P100-1999, x-ibm-1158_P100-1999, x-ibm-1160_P100-1999, x-ibm-1162_P100-1999, x-ibm-1164_P100-1999, x-ibm-1250_P100-1995, x-ibm-1251_P100-1995, x-ibm-1252_P100-2000, x-ibm-1253_P100-1995, x-ibm-1254_P100-1995, x-ibm-1255_P100-1995, x-ibm-1256_P110-1997, x-ibm-1257_P100-1995, x-ibm-1258_P100-1997, x-ibm-12712-s390, x-ibm-12712_P100-1998, x-ibm-1373_P100-2002, x-ibm-1386_P100-2001, x-ibm-16684_P110-2003, x-ibm-16804-s390, x-ibm-16804_X110-1999, x-ibm-25546, x-ibm-33722_P12A_P12A-2009_U2, x-ibm-37-s390, x-ibm-4517_P100-2005, x-ibm-4899_P100-1998, x-ibm-4909_P100-1999, x-ibm-4971_P100-1999, x-ibm-5123_P100-1999, x-ibm-5351_P100-1998, x-ibm-5352_P100-1998, x-ibm-5353_P100-1998, x-ibm-803_P100-1999, x-ibm-813_P100-1995, x-ibm-8482_P100-1999, x-ibm-901_P100-1999, x-ibm-902_P100-1999, x-ibm-9067_X100-2005, x-ibm-916_P100-1995, x-IBM1006, x-IBM1025, x-IBM1046, x-IBM1097, x-IBM1098, x-IBM1112, x-IBM1122, x-IBM1123, x-IBM1124, x-IBM1153, x-IBM1363, x-IBM1364, x-IBM1371, x-IBM1381, x-IBM1383, x-IBM1388, x-IBM1390, x-IBM1399, x-IBM300, x-IBM33722, x-IBM720, x-IBM737, x-IBM833, x-IBM834, x-IBM856, x-IBM867, x-IBM874, x-IBM875, x-IBM921, x-IBM922, x-IBM930, x-IBM933, x-IBM935, x-IBM937, x-IBM939, x-IBM942, x-IBM942C, x-IBM943, x-IBM943C, x-IBM948, x-IBM949, x-IBM949C, x-IBM950, x-IBM954, x-IBM964, x-IBM970, x-IBM971, x-IMAP-mailbox-name, x-iscii-be, x-iscii-gu, x-iscii-ka, x-iscii-ma, x-iscii-or, x-iscii-pa, x-iscii-ta, x-iscii-te, x-ISCII91, x-ISO-2022-CN-CNS, x-ISO-2022-CN-GB, x-iso-8859-11, x-JIS0208, x-JIS7, x-JIS8, x-JISAutoDetect, x-Johab, x-LMBCS-1, x-mac-centraleurroman, x-mac-cyrillic, x-mac-greek, x-mac-turkish, x-MacArabic, x-MacCentralEurope, x-MacCroatian, x-MacCyrillic, x-MacDingbat, x-MacGreek, x-MacHebrew, x-MacIceland, x-MacRoman, x-MacRomania, x-MacSymbol, x-MacThai, x-MacTurkish, x-MacUkraine, x-MS932_0213, x-MS950-HKSCS, x-MS950-HKSCS-XP, x-mswin-936, x-PCK, x-SJIS_0213, x-UnicodeBig, x-UTF-16LE-BOM, X-UTF-32BE-BOM, X-UTF-32LE-BOM, x-UTF16_OppositeEndian, x-UTF16_PlatformEndian, x-UTF32_OppositeEndian, x-UTF32_PlatformEndian, x-windows-50220, x-windows-50221, x-windows-874, x-windows-949, x-windows-950, x-windows-iso2022jp]