blob: 2cf6c3dddb710df9c47fc34b5044b7bcc54ca128 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.4">
<title>JDBC Type 4 Programmer&#8217;s Reference Guide</title>
<style>
/**
* @@@ START COPYRIGHT @@@
*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*
* @@@ END COPYRIGHT @@@
*/
/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
/* Remove the comments around the @import statement below when using this as a custom stylesheet */
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400";*/
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
audio,canvas,video{display:inline-block}
audio:not([controls]){display:none;height:0}
[hidden],template{display:none}
script{display:none!important}
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
body{margin:0}
a{background:transparent}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
abbr[title]{border-bottom:1px dotted}
b,strong{font-weight:bold}
dfn{font-style:italic}
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
input[type="search"]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}
input[type="search"]::-webkit-search-cancel-button,input[type="search"]::-webkit-search-decoration{-webkit-appearance:none}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,*:before,*:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Helvetica Neue",Helvetica,Arial,sans-serif,serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
#map_canvas img,#map_canvas embed,#map_canvas object,.map_canvas img,.map_canvas embed,.map_canvas object{max-width:none!important}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
.antialiased,body{-webkit-font-smoothing:antialiased}
img{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
p.lead,.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{font-size:1.21875em;line-height:1.6}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#3188ac;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:none}
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
/* Defines headings */
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-weight:bold;font-style:normal;color:#3188ac;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #ddddd8;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
/* Defines the `text` (passthru) format */
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:bold;color:#3188ac}
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol,ul.no-bullet,ol.no-bullet{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ul.no-bullet{list-style:none}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
abbr{text-transform:none}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
blockquote cite:before{content:"\2014 \0020"}
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media only screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
table thead,table tfoot{background:#f7f8f7;font-weight:bold}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.clearfix:before,.clearfix:after,.float-group:before,.float-group:after{content:" ";display:table}
.clearfix:after,.float-group:after{clear:both}
*:not(pre)>code{font-size:1.0em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
/**:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}*/
pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
.keyseq{color:rgba(51,51,51,.8)}
kbd{display:inline-block;color:rgba(0,0,0,.8);font-size:.75em;line-height:1.4;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:-.15em .15em 0 .15em;padding:.2em .6em .2em .5em;vertical-align:middle;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menu{color:rgba(0,0,0,.8)}
b.button:before,b.button:after{position:relative;top:-1px;font-weight:400}
b.button:before{content:"[";padding:0 3px 0 2px}
b.button:after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header:before,#header:after,#content:before,#content:after,#footnotes:before,#footnotes:after,#footer:before,#footer:after{content:" ";display:table}
#header:after,#content:after,#footnotes:after,#footer:after{clear:both}
#content{margin-top:1.25em}
#content:before{content:none}
/* #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} */
#header>h1:first-child{color:#3188ac;margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #ddddd8}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #ddddd8;padding-bottom:8px}
#header .details{border-bottom:1px solid #ddddd8;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span:before{content:"\00a0\2013\00a0"}
#header .details br+span.author:before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark:before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber:after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #ddddd8;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #efefed;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#3188ac;font-size:1.2em}
@media only screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #efefed;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #efefed;left:auto;right:0}}@media only screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
/* Controls width of panel */
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
#footer-text,#footer_nav{color:rgba(255,255,255,.8);line-height:1.44}
#footer a{color: #990000}
.sect1{padding-bottom:.625em}
@media only screen and (min-width:768px){.sect1{padding-bottom:1.25em}}.sect1+.sect1{border-top:1px solid #efefed}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor:before,h2>a.anchor:before,h3>a.anchor:before,#toctitle>a.anchor:before,.sidebarblock>.content>.title>a.anchor:before,h4>a.anchor:before,h5>a.anchor:before,h6>a.anchor:before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#990000;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Helvetica Neue",Helvetica,Arial,sans-serif,serif;font-size:1rem;font-weight:bold}
/* Here */
table.tableblock>caption.title{white-space:nowrap;overflow:visible;max-width:0}
.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{color:rgba(0,0,0,.85)}
table.tableblock #preamble>.sectionbody>.paragraph:first-of-type p{font-size:inherit}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8;color:rgba(0,0,0,.6)}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;padding:1em;font-size:.8125em}
.literalblock pre.nowrap,.literalblock pre[class].nowrap,.listingblock pre.nowrap,.listingblock pre[class].nowrap{overflow-x:auto;white-space:pre;word-wrap:normal}
@media only screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}@media only screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.listingblock>.content{position:relative}
.listingblock code[data-lang]:before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}
.listingblock:hover code[data-lang]:before{display:block}
.listingblock.terminal pre .command:before{content:attr(data-prompt);padding-right:.5em;color:#999}
.listingblock.terminal pre .command:not([data-prompt]):before{content:"$"}
table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0}
table.pyhltable td.code{padding-left:.75em;padding-right:0}
pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #ddddd8}
pre.pygments .lineno{display:inline-block;margin-right:.25em}
table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock blockquote p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote:before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.5em;margin-right:.5ex;text-align:right}
.quoteblock .quoteblock{margin-left:0;margin-right:0;padding:.5em 0;border-left:3px solid rgba(0,0,0,.6)}
.quoteblock .quoteblock blockquote{padding:0 0 0 .75em}
.quoteblock .quoteblock blockquote:before{display:none}
.verseblock{margin:0 1em 1.25em 1em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.05em;color:rgba(0,0,0,.6)}
.quoteblock.abstract{margin:0 0 1.25em 0;display:block}
.quoteblock.abstract blockquote,.quoteblock.abstract blockquote p{text-align:left;word-spacing:0}
.quoteblock.abstract blockquote:before,.quoteblock.abstract blockquote p:first-of-type:before{display:none}
table.tableblock{max-width:100%;border-collapse:separate}
table.tableblock td>.paragraph:last-child p>p:last-child,table.tableblock th>p:last-child,table.tableblock td>p:last-child{margin-bottom:0}
table.spread{width:100%}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all th.tableblock,table.grid-all td.tableblock{border-width:0 1px 1px 0}
table.grid-all tfoot>tr>th.tableblock,table.grid-all tfoot>tr>td.tableblock{border-width:1px 1px 0 0}
table.grid-cols th.tableblock,table.grid-cols td.tableblock{border-width:0 1px 0 0}
table.grid-all *>tr>.tableblock:last-child,table.grid-cols *>tr>.tableblock:last-child{border-right-width:0}
table.grid-rows th.tableblock,table.grid-rows td.tableblock{border-width:0 0 1px 0}
table.grid-all tbody>tr:last-child>th.tableblock,table.grid-all tbody>tr:last-child>td.tableblock,table.grid-all thead:last-child>tr>th.tableblock,table.grid-rows tbody>tr:last-child>th.tableblock,table.grid-rows tbody>tr:last-child>td.tableblock,table.grid-rows thead:last-child>tr>th.tableblock{border-bottom-width:0}
table.grid-rows tfoot>tr>th.tableblock,table.grid-rows tfoot>tr>td.tableblock{border-width:1px 0 0 0}
table.frame-all{border-width:1px}
table.frame-sides{border-width:0 1px}
table.frame-topbot{border-width:1px 0}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
td>div.verse{white-space:pre}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.unstyled,ol.unnumbered,ul.checklist,ul.none{list-style-type:none}
ul.unstyled,ol.unnumbered,ul.checklist{margin-left:.625em}
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1em;font-size:.85em}
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{width:1em;position:relative;top:1px}
ul.inline{margin:0 auto .625em auto;margin-left:-1.375em;margin-right:0;padding:0;list-style:none;overflow:hidden}
ul.inline>li{list-style:none;float:left;margin-left:1.375em;display:block}
ul.inline>li>*{display:block}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1{padding-right:.75em;font-weight:bold}
td.hdlist1,td.hdlist2{vertical-align:top}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist>table tr>td:first-of-type{padding:0 .75em;line-height:1}
.colist>table tr>td:last-of-type{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
.imageblock.left,.imageblock[style*="float: left"]{margin:.25em .625em 1.25em 0}
.imageblock.right,.imageblock[style*="float: right"]{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none}
span.footnote,span.footnoteref{vertical-align:super;font-size:.875em}
span.footnote a,span.footnoteref a{text-decoration:none}
span.footnote a:active,span.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em 0;border-width:1px 0 0 0}
#footnotes .footnote{padding:0 .375em;line-height:1.3;font-size:.875em;margin-left:1.2em;text-indent:-1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
.gist .file-data>table td.line-data{width:99%}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background-color:#00fafa}
.black{color:#000}
.black-background{background-color:#000}
.blue{color:#0000bf}
.blue-background{background-color:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background-color:#fa00fa}
.gray{color:#606060}
.gray-background{background-color:#7d7d7d}
.green{color:#006000}
.green-background{background-color:#007d00}
.lime{color:#00bf00}
.lime-background{background-color:#00fa00}
.maroon{color:#600000}
.maroon-background{background-color:#7d0000}
.navy{color:#000060}
.navy-background{background-color:#00007d}
.olive{color:#606000}
.olive-background{background-color:#7d7d00}
.purple{color:#600060}
.purple-background{background-color:#7d007d}
.red{color:#bf0000}
.red-background{background-color:#fa0000}
.silver{color:#909090}
.silver-background{background-color:#bcbcbc}
.teal{color:#006060}
.teal-background{background-color:#007d7d}
.white{color:#bfbfbf}
.white-background{background-color:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background-color:#fafa00}
span.icon>.fa{cursor:default}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]:after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
h1,h2{letter-spacing:-.01em}
dt,th.tableblock,td.content{text-rendering:optimizeLegibility}
p,td.content{letter-spacing:-.01em}
p strong,td.content strong{letter-spacing:-.005em}
p,blockquote,dt,td.content{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@media print{@page{margin:1.25cm .75cm}
*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare):after,a[href^="https:"]:not(.bare):after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]:after{content:" (" attr(title) ")"}
pre,blockquote,tr,img{page-break-inside:avoid}
thead{display:table-header-group}
img{max-width:100%!important}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #ddddd8!important;padding-bottom:0!important}
.sect1{padding-bottom:0!important}
.sect1+.sect1{border:0!important}
#header>h1:first-child{margin-top:1.25rem}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em 0}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span:before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]:before{display:block}
#footer{background:none!important;padding:0 .9375em}
#footer-text{color:rgba(0,0,0,.6)!important;font-size:.9em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
div.paragraph.indented p {padding-left: 3em;}
div.paragraph.indented2 p {padding-left: 6em;}
div.paragraph.indented3 p {padding-left: 9em;}
</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css">
<style>
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
/*pre.CodeRay {background-color:#f7f7f8;}*/
.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
table.CodeRay td{vertical-align: top;line-height:1.45}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
table.CodeRay td.code{padding:0 0 0 .5em}
table.CodeRay td.code>pre{padding:0}
.CodeRay .debug{color:#fff !important;background:#000080 !important}
.CodeRay .annotation{color:#007}
.CodeRay .attribute-name{color:#000080}
.CodeRay .attribute-value{color:#700}
.CodeRay .binary{color:#509}
.CodeRay .comment{color:#998;font-style:italic}
.CodeRay .char{color:#04d}
.CodeRay .char .content{color:#04d}
.CodeRay .char .delimiter{color:#039}
.CodeRay .class{color:#458;font-weight:bold}
.CodeRay .complex{color:#a08}
.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
.CodeRay .color{color:#099}
.CodeRay .class-variable{color:#369}
.CodeRay .decorator{color:#b0b}
.CodeRay .definition{color:#099}
.CodeRay .delimiter{color:#000}
.CodeRay .doc{color:#970}
.CodeRay .doctype{color:#34b}
.CodeRay .doc-string{color:#d42}
.CodeRay .escape{color:#666}
.CodeRay .entity{color:#800}
.CodeRay .error{color:#808}
.CodeRay .exception{color:inherit}
.CodeRay .filename{color:#099}
.CodeRay .function{color:#900;font-weight:bold}
.CodeRay .global-variable{color:#008080}
.CodeRay .hex{color:#058}
.CodeRay .integer,.CodeRay .float{color:#099}
.CodeRay .include{color:#555}
.CodeRay .inline{color:#000}
.CodeRay .inline .inline{background:#ccc}
.CodeRay .inline .inline .inline{background:#bbb}
.CodeRay .inline .inline-delimiter{color:#d14}
.CodeRay .inline-delimiter{color:#d14}
.CodeRay .important{color:#555;font-weight:bold}
.CodeRay .interpreted{color:#b2b}
.CodeRay .instance-variable{color:#008080}
.CodeRay .label{color:#970}
.CodeRay .local-variable{color:#963}
.CodeRay .octal{color:#40e}
.CodeRay .predefined{color:#369}
.CodeRay .preprocessor{color:#579}
.CodeRay .pseudo-class{color:#555}
.CodeRay .directive{font-weight:bold}
.CodeRay .type{font-weight:bold}
.CodeRay .predefined-type{color:inherit}
.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
.CodeRay .key{color:#808}
.CodeRay .key .delimiter{color:#606}
.CodeRay .key .char{color:#80f}
.CodeRay .value{color:#088}
.CodeRay .regexp .delimiter{color:#808}
.CodeRay .regexp .content{color:#808}
.CodeRay .regexp .modifier{color:#808}
.CodeRay .regexp .char{color:#d14}
.CodeRay .regexp .function{color:#404;font-weight:bold}
.CodeRay .string{color:#d20}
.CodeRay .string .string .string{background:#ffd0d0}
.CodeRay .string .content{color:#d14}
.CodeRay .string .char{color:#d14}
.CodeRay .string .delimiter{color:#d14}
.CodeRay .shell{color:#d14}
.CodeRay .shell .delimiter{color:#d14}
.CodeRay .symbol{color:#990073}
.CodeRay .symbol .content{color:#a60}
.CodeRay .symbol .delimiter{color:#630}
.CodeRay .tag{color:#008080}
.CodeRay .tag-special{color:#d70}
.CodeRay .variable{color:#036}
.CodeRay .insert{background:#afa}
.CodeRay .delete{background:#faa}
.CodeRay .change{color:#aaf;background:#007}
.CodeRay .head{color:#f8f;background:#505}
.CodeRay .insert .insert{color:#080}
.CodeRay .delete .delete{color:#800}
.CodeRay .change .change{color:#66f}
.CodeRay .head .head{color:#f4f}
</style>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>JDBC Type 4 Programmer&#8217;s Reference Guide</h1>
<div class="details">
<span id="revnumber">version 2.4.0</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_about_this_document">1. About This Document</a>
<ul class="sectlevel2">
<li><a href="#_intended_audience">1.1. Intended Audience</a></li>
<li><a href="#_new_and_changed_information">1.2. New and Changed Information</a></li>
<li><a href="#_notation_conventions">1.3. Notation Conventions</a></li>
<li><a href="#_comments_encouraged">1.4. Comments Encouraged</a></li>
</ul>
</li>
<li><a href="#introduction">2. Introduction</a>
<ul class="sectlevel2">
<li><a href="#type-4-driver-api-package">2.1. Type 4 Driver API Package</a></li>
<li><a href="#installation">2.2. Installation</a></li>
</ul>
</li>
<li><a href="#accessing-project-name-sql-databases">3. Accessing Trafodion SQL Databases</a>
<ul class="sectlevel2">
<li><a href="#data-sources">3.1. Data Sources</a>
<ul class="sectlevel3">
<li><a href="#jdbc-data-source-client-side">3.1.1. JDBC Data Source (client-side)</a></li>
</ul>
</li>
<li><a href="#security">3.2. Security</a></li>
<li><a href="#connection-by-using-the-datasource-interface">3.3. Connection by Using the DataSource Interface</a>
<ul class="sectlevel3">
<li><a href="#overview-of-tasks-to-deploy-datasource-objects">3.3.1. Overview of Tasks to Deploy DataSource Objects</a></li>
<li><a href="#datasource-object-properties">3.3.2. DataSource Object Properties</a></li>
<li><a href="#programmatically-creating-an-instance-of-the-datasource-class">3.3.3. Programmatically Creating an Instance of the DataSource Class</a></li>
<li><a href="#programmatically-registering-the-datasource-object">3.3.4. Programmatically Registering the DataSource Object</a></li>
<li><a href="#retrieving-a-datasource-instance-by-using-jndi-and-connecting-to-the-data-source">3.3.5. Retrieving a DataSource Instance by Using JNDI and Connecting to the Data Source</a></li>
<li><a href="#specifying-the-properties-file-that-configures-the-data-source">3.3.6. Specifying the Properties File that Configures the Data Source</a></li>
</ul>
</li>
<li><a href="#connection-by-using-the-drivermanager-class">3.4. Connection by Using the DriverManager Class</a>
<ul class="sectlevel3">
<li><a href="#loading-and-registering-the-driver">3.4.1. Loading and Registering the Driver</a></li>
<li><a href="#establishing-the-connection">3.4.2. Establishing the Connection</a></li>
<li><a href="#guidelines-for-connections-using-the-driver-manager">3.4.3. Guidelines for Connections Using the Driver Manager</a></li>
</ul>
</li>
<li><a href="#connection-pooling">3.5. Connection Pooling</a></li>
<li><a href="#statement-pooling">3.6. Statement Pooling</a>
<ul class="sectlevel3">
<li><a href="#guidelines-for-statement-pooling">3.6.1. Guidelines for Statement Pooling</a></li>
<li><a href="#troubleshooting-statement-pooling">3.6.2. Troubleshooting Statement Pooling</a></li>
</ul>
</li>
<li><a href="#thread-safe-database-access">3.7. Thread-Safe Database Access</a></li>
<li><a href="#update-where-current-of-operations">3.8. "Update . . . Where Current of" Operations</a></li>
<li><a href="#infostats-command-for-obtaining-query-costs">3.9. INFOSTATS Command for Obtaining Query Costs</a>
<ul class="sectlevel3">
<li><a href="#use-of-the-infostats-command">3.9.1. Use of the INFOSTATS Command</a></li>
</ul>
</li>
<li><a href="#internationalization-support">3.10. Internationalization Support</a>
<ul class="sectlevel3">
<li><a href="#when-string-literals-are-used-in-applications">3.10.1. When String Literals Are Used in Applications</a></li>
<li><a href="#controlling-string-literal-conversion-by-using-the-character-set-properties">3.10.2. Controlling String Literal Conversion by Using the Character-Set Properties</a></li>
<li><a href="#localizing-error-messages-and-status-messages">3.10.3. Localizing Error Messages and Status Messages</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#type-4-driver-properties">4. Type 4 Driver Properties</a>
<ul class="sectlevel2">
<li><a href="#summary-of-type-4-driver-properties">4.1. Summary of Type 4 Driver Properties</a>
<ul class="sectlevel3">
<li><a href="#client-side-properties">4.1.1. Client-Side Properties</a></li>
<li><a href="#server-side-properties">4.1.2. Server-Side Properties</a></li>
</ul>
</li>
<li><a href="#how-to-specify-jdbc-type-4-properties">4.2. How to Specify JDBC Type 4 Properties</a>
<ul class="sectlevel3">
<li><a href="#where-to-set-properties">4.2.1. Where to Set Properties</a></li>
<li><a href="#creating-and-using-a-properties-file">4.2.2. Creating and Using a Properties File</a></li>
<li><a href="#setting-properties-in-the-command-line">4.2.3. Setting Properties in the Command Line</a></li>
<li><a href="#precedence-of-property-specifications">4.2.4. Precedence of Property Specifications</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#type-4-driver-property-descriptions">5. Type 4 Driver Property Descriptions</a>
<ul class="sectlevel2">
<li><a href="#catalog">5.1. catalog Property</a></li>
<li><a href="#connectiontimeout">5.2. connectionTimeout Property</a></li>
<li><a href="#fetchbuffersize">5.3. fetchBufferSize Property</a></li>
<li><a href="#initialpoolsize">5.4. initialPoolSize Property</a></li>
<li><a href="#iso88591">5.5. ISO88591 Property</a></li>
<li><a href="#kanji">5.6. KANJI Property</a></li>
<li><a href="#ksc5601">5.7. KSC5601 Property</a></li>
<li><a href="#language">5.8. language Property</a></li>
<li><a href="#logintimeout">5.9. loginTimeout Property</a></li>
<li><a href="#maxidletime">5.10. maxIdleTime Property</a></li>
<li><a href="#maxpoolsize">5.11. maxPoolSize Property</a></li>
<li><a href="#maxstatements">5.12. maxStatements Property</a></li>
<li><a href="#minpoolsize">5.13. minPoolSize Property</a></li>
<li><a href="#networktimeout">5.14. networkTimeout Property</a></li>
<li><a href="#password">5.15. password Property</a></li>
<li><a href="#properties">5.16. properties Property</a></li>
<li><a href="#reservedatalocators">5.17. reserveDataLocators Property</a></li>
<li><a href="#roundingmode">5.18. roundingMode Property</a></li>
<li><a href="#schema">5.19. schema Property</a></li>
<li><a href="#t4logfile">5.20. T4LogFile Property</a></li>
<li><a href="#t4loglevel">5.21. T4LogLevel Property</a>
<ul class="sectlevel3">
<li><a href="#t4loglevel-considerations">5.21.1. T4LogLevel Considerations</a></li>
</ul>
</li>
<li><a href="#translationverification">5.22. translationVerification Property</a></li>
<li><a href="#url">5.23. url Property</a>
<ul class="sectlevel3">
<li><a href="#url-property-considerations">5.23.1. url Property Considerations</a></li>
</ul>
</li>
<li><a href="#user">5.24. user Property</a></li>
</ul>
</li>
<li><a href="#type-4-driver-compliance">6. Type 4 Driver Compliance</a>
<ul class="sectlevel2">
<li><a href="#compliance-overview">6.1. Compliance Overview</a></li>
<li><a href="#unsupported-features">6.2. Unsupported Features</a></li>
<li><a href="#deviations">6.3. Deviations</a></li>
<li><a href="#project-name-extensions">6.4. Trafodion Extensions</a>
<ul class="sectlevel3">
<li><a href="#internationalization-of-messages">6.4.1. Internationalization of Messages</a></li>
<li><a href="#additional-databasemetadata-apis">6.4.2. Additional DatabaseMetaData APIs</a></li>
</ul>
</li>
<li><a href="#conformance-of-databasemetadata-methods-handling-of-null-parameters">6.5. Conformance of DatabaseMetaData Methods' Handling of Null Parameters</a></li>
<li><a href="#type-4-driver-conformance-to-sql-data-types">6.6. Type 4 Driver Conformance to SQL Data Types</a>
<ul class="sectlevel3">
<li><a href="#jdbc-data-types">6.6.1. JDBC Data Types</a></li>
</ul>
</li>
<li><a href="#floating-point-support">6.7. Floating-Point Support</a></li>
<li><a href="#sqlj-support">6.8. SQLJ Support</a></li>
<li><a href="#jdbc-3-0-features-not-supported-by-the-type-4-driver">6.9. JDBC 3.0 Features Not Supported by the Type 4 Driver</a></li>
<li><a href="#restrictions">6.10. Restrictions</a></li>
</ul>
</li>
<li><a href="#tracing-and-logging-facilities">7. Tracing and Logging Facilities</a>
<ul class="sectlevel2">
<li><a href="#standard-jdbc-tracing-and-logging-facility">7.1. Standard JDBC Tracing and Logging Facility</a></li>
<li><a href="#the-type-4-driver-logging-facility">7.2. The Type 4 Driver Logging Facility</a>
<ul class="sectlevel3">
<li><a href="#controlling-type-4-driver-logging-output">7.2.1. Controlling Type 4 Driver Logging Output</a></li>
<li><a href="#message-format">7.2.2. Message Format</a></li>
<li><a href="#examples-of-logging-output">7.2.3. Examples of Logging Output</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#messages">8. Messages</a>
<ul class="sectlevel2">
<li><a href="#about-the-message-format">8.1. About the Message Format</a></li>
<li><a href="#getting-help">8.2. Getting Help</a></li>
<li><a href="#type-4-driver-error-messages">8.3. Type 4 Driver Error Messages</a>
<ul class="sectlevel3">
<li><a href="#_01032_08s01">8.3.1. 01032 08S01</a></li>
<li><a href="#_01056_25000">8.3.2. 01056 25000</a></li>
<li><a href="#_01118_s1008">8.3.3. 01118 S1008</a></li>
<li><a href="#_08001_hy000">8.3.4. 08001 HY000</a></li>
<li><a href="#_08004_hy000">8.3.5. 08004 HY000</a></li>
<li><a href="#_29001_hyc00">8.3.6. 29001 HYC00</a></li>
<li><a href="#_29002_08003">8.3.7. 29002 08003</a></li>
<li><a href="#_29003_hy000">8.3.8. 29003 HY000</a></li>
<li><a href="#_29004_hy024">8.3.9. 29004 HY024</a></li>
<li><a href="#_29005_hy024">8.3.10. 29005 HY024</a></li>
<li><a href="#_29006_hy000">8.3.11. 29006 HY000</a></li>
<li><a href="#_29007_07009">8.3.12. 29007 07009</a></li>
<li><a href="#_29008_24000">8.3.13. 29008 24000</a></li>
<li><a href="#_29009_hy109">8.3.14. 29009 HY109</a></li>
<li><a href="#_29010_07009">8.3.15. 29010 07009</a></li>
<li><a href="#_29011_07009">8.3.16. 29011 07009</a></li>
<li><a href="#_29012_07006">8.3.17. 29012 07006</a></li>
<li><a href="#_29013_hy024">8.3.18. 29013 HY024</a></li>
<li><a href="#_29015_hy024">8.3.19. 29015 HY024</a></li>
<li><a href="#_29017_hy004">8.3.20. 29017 HY004</a></li>
<li><a href="#_29018_22018">8.3.21. 29018 22018</a></li>
<li><a href="#_29019_07002">8.3.22. 29019 07002</a></li>
<li><a href="#_29020_07009">8.3.23. 29020 07009</a></li>
<li><a href="#_29021_hy004">8.3.24. 29021 HY004</a></li>
<li><a href="#_29022_hy010">8.3.25. 29022 HY010</a></li>
<li><a href="#_29026_hy000">8.3.26. 29026 HY000</a></li>
<li><a href="#_29027_hy011">8.3.27. 29027 HY011</a></li>
<li><a href="#_29029_hy011">8.3.28. 29029 HY011</a></li>
<li><a href="#_29031_hy000">8.3.29. 29031 HY000</a></li>
<li><a href="#_29032_23000">8.3.30. 29032 23000</a></li>
<li><a href="#_29033_23000">8.3.31. 29033 23000</a></li>
<li><a href="#_29035_hy000">8.3.32. 29035 HY000</a></li>
<li><a href="#_29036_hy000">8.3.33. 29036 HY000</a></li>
<li><a href="#_29037_hy106">8.3.34. 29037 HY106</a></li>
<li><a href="#_29038_hy107">8.3.35. 29038 HY107</a></li>
<li><a href="#_29039_hy092">8.3.36. 29039 HY092</a></li>
<li><a href="#_29040_hy000">8.3.37. 29040 HY000</a></li>
<li><a href="#_29041_hy000">8.3.38. 29041 HY000</a></li>
<li><a href="#_29042_hy000">8.3.39. 29042 HY000</a></li>
<li><a href="#_29043_hy000">8.3.40. 29043 HY000</a></li>
<li><a href="#_29044_hy000">8.3.41. 29044 HY000</a></li>
<li><a href="#_29045_01s07">8.3.42. 29045 01S07</a></li>
<li><a href="#_29046_22003">8.3.43. 29046 22003</a></li>
<li><a href="#_29047_hy000">8.3.44. 29047 HY000</a></li>
<li><a href="#_29048_hy009">8.3.45. 29048 HY009</a></li>
<li><a href="#_29049_25000">8.3.46. 29049 25000</a></li>
<li><a href="#_29050_hy107">8.3.47. 29050 HY107</a></li>
<li><a href="#_29051_01s02">8.3.48. 29051 01S02</a></li>
<li><a href="#_29053_hy000">8.3.49. 29053 HY000</a></li>
<li><a href="#_29054_hy000">8.3.50. 29054 HY000</a></li>
<li><a href="#_29056_hy000">8.3.51. 29056 HY000</a></li>
<li><a href="#_29057_hy000">8.3.52. 29057 HY000</a></li>
<li><a href="#_29058_hy000">8.3.53. 29058 HY000</a></li>
<li><a href="#_29059_hy000">8.3.54. 29059 HY000</a></li>
<li><a href="#_29060_hy000">8.3.55. 29060 HY000</a></li>
<li><a href="#_29061_hy00">8.3.56. 29061 HY00</a></li>
<li><a href="#_29063_hy00">8.3.57. 29063 HY00</a></li>
<li><a href="#_29067_07009">8.3.58. 29067 07009</a></li>
<li><a href="#_29068_07009">8.3.59. 29068 07009</a></li>
<li><a href="#_29069_hy000">8.3.60. 29069 HY000</a></li>
<li><a href="#_29100_hy000">8.3.61. 29100 HY000</a></li>
<li><a href="#_29101_hy000">8.3.62. 29101 HY000</a></li>
<li><a href="#_29102_hy000">8.3.63. 29102 HY000</a></li>
<li><a href="#_29103_hy000">8.3.64. 29103 HY000</a></li>
<li><a href="#_29104_hy000">8.3.65. 29104 HY000</a></li>
<li><a href="#_29105_hy000">8.3.66. 29105 HY000</a></li>
<li><a href="#_29106_hy000">8.3.67. 29106 HY000</a></li>
<li><a href="#_29107_hy000">8.3.68. 29107 HY000</a></li>
<li><a href="#_29108_hy000">8.3.69. 29108 HY000</a></li>
<li><a href="#_29109_hy000">8.3.70. 29109 HY000</a></li>
<li><a href="#_29110_hy000">8.3.71. 29110 HY000</a></li>
<li><a href="#_29111_hy000">8.3.72. 29111 HY000</a></li>
<li><a href="#_29112_hy000">8.3.73. 29112 HY000</a></li>
<li><a href="#_29113_hy000">8.3.74. 29113 HY000</a></li>
<li><a href="#_29114_hy000">8.3.75. 29114 HY000</a></li>
<li><a href="#_29115_hy000">8.3.76. 29115 HY000</a></li>
<li><a href="#_29116_hy000">8.3.77. 29116 HY000</a></li>
<li><a href="#_29117_hy000">8.3.78. 29117 HY000</a></li>
<li><a href="#_29118_hy000">8.3.79. 29118 HY000</a></li>
<li><a href="#_29119_hy000">8.3.80. 29119 HY000</a></li>
<li><a href="#_29120_hy000">8.3.81. 29120 HY000</a></li>
<li><a href="#_29121_hy000">8.3.82. 29121 HY000</a></li>
<li><a href="#_29122_hy000">8.3.83. 29122 HY000</a></li>
<li><a href="#_29123_hy000">8.3.84. 29123 HY000</a></li>
<li><a href="#_29124_hy000">8.3.85. 29124 HY000</a></li>
<li><a href="#_29125_hy000">8.3.86. 29125 HY000</a></li>
<li><a href="#_29126_hy000">8.3.87. 29126 HY000</a></li>
<li><a href="#_29127_hy000">8.3.88. 29127 HY000</a></li>
<li><a href="#_29128_hy000">8.3.89. 29128 HY000</a></li>
<li><a href="#_29129_hy000">8.3.90. 29129 HY000</a></li>
<li><a href="#_29130_hy000">8.3.91. 29130 HY000</a></li>
<li><a href="#_29131_hy000">8.3.92. 29131 HY000</a></li>
<li><a href="#_29132_hy000">8.3.93. 29132 HY000</a></li>
<li><a href="#_29133_hy000">8.3.94. 29133 HY000</a></li>
<li><a href="#_29134_hy000">8.3.95. 29134 HY000</a></li>
<li><a href="#_29135_hy000">8.3.96. 29135 HY000</a></li>
<li><a href="#_29136_hy000">8.3.97. 29136 HY000</a></li>
<li><a href="#_29137_hy000">8.3.98. 29137 HY000</a></li>
<li><a href="#_29138_hy000">8.3.99. 29138 HY000</a></li>
<li><a href="#_29139_hy000">8.3.100. 29139 HY000</a></li>
<li><a href="#_29140_hy000">8.3.101. 29140 HY000</a></li>
<li><a href="#_29141_hy000">8.3.102. 29141 HY000</a></li>
<li><a href="#_29142_hy000">8.3.103. 29142 HY000</a></li>
<li><a href="#_29143_hy000">8.3.104. 29143 HY000</a></li>
<li><a href="#_29144_hy000">8.3.105. 29144 HY000</a></li>
<li><a href="#_29145_hy000">8.3.106. 29145 HY000</a></li>
<li><a href="#_29146_hy000">8.3.107. 29146 HY000</a></li>
<li><a href="#_29147_hy000">8.3.108. 29147 HY000</a></li>
<li><a href="#_29148_hy000">8.3.109. 29148 HY000</a></li>
<li><a href="#_29149_hy000">8.3.110. 29149 HY000</a></li>
<li><a href="#_29150_hy000">8.3.111. 29150 HY000</a></li>
<li><a href="#_29151_hy000">8.3.112. 29151 HY000</a></li>
<li><a href="#_29152_hy000">8.3.113. 29152 HY000</a></li>
<li><a href="#_29153_hy000">8.3.114. 29153 HY000</a></li>
<li><a href="#_29154_hy000">8.3.115. 29154 HY000</a></li>
<li><a href="#_29155_hy000">8.3.116. 29155 HY000</a></li>
<li><a href="#_29156_hy000">8.3.117. 29156 HY000</a></li>
<li><a href="#_29157_hy000">8.3.118. 29157 HY000</a></li>
<li><a href="#_29158_hy000">8.3.119. 29158 HY000</a></li>
<li><a href="#_29159_hy000">8.3.120. 29159 HY000</a></li>
<li><a href="#_29160_hy000">8.3.121. 29160 HY000</a></li>
<li><a href="#_29161_s1000">8.3.122. 29161 S1000</a></li>
<li><a href="#_29162_s1000">8.3.123. 29162 S1000</a></li>
<li><a href="#_29163_08001">8.3.124. 29163 08001</a></li>
<li><a href="#_29164_08001">8.3.125. 29164 08001</a></li>
<li><a href="#_29165_hy000">8.3.126. 29165 HY000</a></li>
<li><a href="#_29166_hy000">8.3.127. 29166 HY000</a></li>
<li><a href="#_29167_hy000">8.3.128. 29167 HY000</a></li>
<li><a href="#_29168_hy000">8.3.129. 29168 HY000</a></li>
<li><a href="#_29169_hy000">8.3.130. 29169 HY000</a></li>
<li><a href="#_29170_hy000">8.3.131. 29170 HY000</a></li>
<li><a href="#_29172_hy000">8.3.132. 29172 HY000</a></li>
<li><a href="#_29173_hy000">8.3.133. 29173 HY000</a></li>
<li><a href="#_29174_hy000">8.3.134. 29174 HY000</a></li>
<li><a href="#_29175_hy000">8.3.135. 29175 HY000</a></li>
<li><a href="#_29177_hy000">8.3.136. 29177 HY000</a></li>
<li><a href="#_29178_hy000">8.3.137. 29178 HY000</a></li>
<li><a href="#_29182_hy000">8.3.138. 29182 HY000</a></li>
<li><a href="#_s1000_hy000">8.3.139. S1000 HY000</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#avoiding-driver-server-version-mismatch">9. Avoiding Driver-Server Version Mismatch</a>
<ul class="sectlevel2">
<li><a href="#compatible-versions">9.1. Compatible Versions</a></li>
<li><a href="#considerations-for-mixed-version-jdbc-clients-connecting-to-project-name-platforms">9.2. Considerations for Mixed-Version JDBC Clients Connecting to Trafodion Platforms</a></li>
<li><a href="#version-mismatch-error-message">9.3. Version Mismatch Error Message</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p><strong>License Statement</strong></p>
</div>
<div class="paragraph">
<p>Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at <a href="http://www.apache.org/licenses/LICENSE-2.0" class="bare">http://www.apache.org/licenses/LICENSE-2.0</a></p>
</div>
<div class="paragraph">
<p>Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.</p>
</div>
<div style="page-break-after: always;"></div>
<div class="paragraph">
<p><strong>Acknowledgements</strong></p>
</div>
<div class="paragraph">
<p>Microsoft®, Windows®, Windows NT®, Windows® XP, and Windows Vista® are
U.S. registered trademarks of Microsoft Corporation. Intel® and Intel®
Itanium® are trademarks of Intel Corporation in the U.S. and other
countries. Java® is a registered trademark of Oracle and/or its
affiliates. Motif, OSF/1, UNIX®, X/Open®, and the X device is a
trademark of X/Open Company Ltd. in the UK and other countries.</p>
</div>
<div class="paragraph">
<p>OSF, OSF/1, OSF/Motif, Motif, and Open Software Foundation are trademarks of
the Open Software Foundation in the U.S. and other countries.
© 1990, 1991, 1992, 1993 Open Software Foundation, Inc.</p>
</div>
<div class="paragraph">
<p>The OSF documentation and the OSF software to which it relates are derived in
part from materials supplied by the following: © 1987, 1988, 1989
Carnegie-Mellon University. © 1989, 1990, 1991 Digital Equipment
Corporation. © 1985, 1988, 1989, 1990 Encore Computer Corporation. © 1988 Free
Software Foundation, Inc. © 1987, 1988, 1989, 1990, 1991 Hewlett-Packard
Company. © 1985, 1987, 1988, 1989, 1990, 1991, 1992 International
Business Machines Corporation. © 1988, 1989 Massachusetts Institute of
Technology. © 1988, 1989, 1990 Mentat Inc. © 1988 Microsoft Corporation.
© 1987, 1988, 1989, 1990, 1991,
1992 SecureWare, Inc. © 1990, 1991 Siemens Nixdorf Informations systeme
AG. © 1986, 1989, 1996, 1997 Sun Microsystems, Inc. © 1989, 1990, 1991
Transarc Corporation.</p>
</div>
<div class="paragraph">
<p>OSF software and documentation are based in part
on the Fourth Berkeley Software Distribution under license from The
Regents of the University of California. OSF acknowledges the following
individuals and institutions for their role in its development: Kenneth
C.R.C. Arnold, Gregory S. Couch, Conrad C. Huang, Ed James, Symmetric
Computer Systems, Robert Elz. © 1980, 1981, 1982, 1983, 1985, 1986,
1987, 1988, 1989 Regents of the University of California. OSF MAKES NO
WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED HEREIN,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE. OSF shall not be liable for errors
contained herein or for incidental consequential damages in connection
with the furnishing, performance, or use of this material.</p>
</div>
<div style="page-break-after: always;"></div>
<div class="paragraph">
<p><strong>Revision History</strong></p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Version</th>
<th class="tableblock halign-left valign-top">Date</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">2.2.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TBD</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">2.1.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">May 1, 2017</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">2.0.1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">July 7, 2016</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">2.0.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">June 6, 2016</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">1.3.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">January, 2016</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect1">
<h2 id="_about_this_document">1. About This Document</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This document describes how to use the Trafodion JDBC Type 4 Driver (subsequently called the Type 4 driver).
This driver provides Java applications running on a foreign platform with JDBC access to Trafodion.</p>
</div>
<div class="sect2">
<h3 id="_intended_audience">1.1. Intended Audience</h3>
<div class="paragraph">
<p>This Trafodion JDBC Type 4 Driver Programmer&#8217;s Reference Guide is for
experienced Java programmers who want to access Trafodion SQL
databases.</p>
</div>
<div class="paragraph">
<p>This document assumes you are already familiar with the Java
documentation, which is located at <a href="http://docs.oracle.com/en/java/" class="bare">http://docs.oracle.com/en/java/</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_new_and_changed_information">1.2. New and Changed Information</h3>
<div class="paragraph">
<p>This is a new manual.</p>
</div>
</div>
<div class="sect2">
<h3 id="_notation_conventions">1.3. Notation Conventions</h3>
<div class="paragraph">
<p>This list summarizes the notation conventions for syntax presentation in this manual.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>UPPERCASE LETTERS</p>
<div class="paragraph">
<p>Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">SELECT</code></pre>
</div>
</div>
</li>
<li>
<p>lowercase letters</p>
<div class="paragraph">
<p>Lowercase letters, regardless of font, indicate variable items that you supply. Items not enclosed in brackets are required.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">file-name</code></pre>
</div>
</div>
</li>
</ul>
</div>
<div style="page-break-after: always;"></div>
<div class="ulist">
<ul>
<li>
<p>&#91; &#93; Brackets</p>
<div class="paragraph">
<p>Brackets enclose optional syntax items.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">DATETIME [start-field TO] end-field</code></pre>
</div>
</div>
<div class="paragraph">
<p>A group of items enclosed in brackets is a list from which you can choose one item or none.</p>
</div>
<div class="paragraph">
<p>The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">DROP SCHEMA schema [CASCADE]
DROP SCHEMA schema [ CASCADE | RESTRICT ]</code></pre>
</div>
</div>
</li>
<li>
<p>{ } Braces</p>
<div class="paragraph">
<p>Braces enclose required syntax items.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">FROM { grantee [, grantee ] ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>A group of items enclosed in braces is a list from which you are required to choose one item.</p>
</div>
<div class="paragraph">
<p>The items in the list can be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">INTERVAL { start-field TO end-field }
{ single-field }
INTERVAL { start-field TO end-field | single-field }</code></pre>
</div>
</div>
</li>
<li>
<p>| Vertical Line</p>
<div class="paragraph">
<p>A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces.</p>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">{expression | NULL}</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>&#8230; Ellipsis</p>
<div class="paragraph">
<p>An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">ATTRIBUTE[S] attribute [, attribute] ...
{, sql-expression } ...</code></pre>
</div>
</div>
<div class="paragraph">
<p>An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">expression-n ...</code></pre>
</div>
</div>
</li>
<li>
<p>Punctuation</p>
<div class="paragraph">
<p>Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">DAY (datetime-expression)
@script-file</code></pre>
</div>
</div>
<div class="paragraph">
<p>Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must type as shown.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">&quot;{&quot; module-name [, module-name] ... &quot;}&quot;</code></pre>
</div>
</div>
</li>
</ul>
</div>
<div style="page-break-after: always;"></div>
<div class="ulist">
<ul>
<li>
<p>Item Spacing</p>
<div class="paragraph">
<p>Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">DAY (datetime-expression) DAY(datetime-expression)</code></pre>
</div>
</div>
<div class="paragraph">
<p>If there is no space between two items, spaces are not permitted. In this example, no spaces are permitted between the period and any other items:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">myfile.sh</code></pre>
</div>
</div>
</li>
<li>
<p>Line Spacing</p>
<div class="paragraph">
<p>If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line.</p>
</div>
<div class="paragraph">
<p>This spacing distinguishes items in a continuation line from items in a vertical list of selections.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">match-value [NOT] LIKE _pattern
[ESCAPE esc-char-expression]</code></pre>
</div>
</div>
</li>
</ul>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect2">
<h3 id="_comments_encouraged">1.4. Comments Encouraged</h3>
<div class="paragraph">
<p>We encourage your comments concerning this document. We are committed to providing documentation that meets your
needs. Send any errors found, suggestions for improvement, or compliments to <a href="mailto:user@trafodion.apache.org">user@trafodion.apache.org</a>.</p>
</div>
<div class="paragraph">
<p>Include the document title and any comment, error found, or suggestion for improvement you have concerning this document.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="introduction">2. Introduction</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This document describes how to use the Trafodion JDBC Type 4
Driver. This driver provides Java applications running on a foreign
platform with JDBC access to Trafodion SQL databases on the
Trafodion.</p>
</div>
<div class="paragraph">
<p><strong>Supported Java Releases:</strong> The Type 4 driver requires Java enabled
platforms that support JDK 1.7 or higher.</p>
</div>
<div class="sect2">
<h3 id="type-4-driver-api-package">2.1. Type 4 Driver API Package</h3>
<div class="paragraph">
<p>The Type 4 driver package, <code>org.trafodion.jdbc.t4</code>, is shipped with the
driver software. For class and method descriptions, see the
<em>Trafodion JDBC Type 4 Driver API Reference</em>.</p>
</div>
<div class="paragraph">
<p>The Trafodion JDBC Type 4 Driver (hereafter, Type 4 driver)
implements JDBC technology that conforms to the standard JDBC 3.0 Data
Access API.</p>
</div>
<div class="paragraph">
<p>To obtain detailed information on the standard JDBC API, download the
JDBC API documentation: <a href="http://docs.oracle.com/en/java/" class="bare">http://docs.oracle.com/en/java/</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="installation">2.2. Installation</h3>
<div class="paragraph">
<p>Refer to the <a href="http://trafodion.apache.org/docs/client_install/index.html">Trafodion Client Installation Guide</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="accessing-project-name-sql-databases">3. Accessing Trafodion SQL Databases</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="data-sources">3.1. Data Sources</h3>
<div class="paragraph">
<p>The term <strong>data source</strong> logically refers to a database or other data
storage entity. A JDBC (client) data source is physically a Java object that
contains properties such as the URL of the physical database, the
catalog to use when connecting to this database, and the schema to use
when connecting to this database. The JDBC data source also contains
methods for obtaining a JDBC connection to the underlying database.</p>
</div>
<div class="sect3">
<h4 id="jdbc-data-source-client-side">3.1.1. JDBC Data Source (client-side)</h4>
<div class="paragraph">
<p>All JDBC data source classes implement either the <code>javax.sql.DataSource</code>
interface or the <code>javax.sql.ConnectionPoolDataSource</code> interface. The Type
4 driver data source classes are <code>org.trafodion.jdbc.t4.TrafT4DataSource</code> and
<code>org.trafodion.jdbc.t4.TrafT4ConnectionPoolDataSource</code>. (These classes are
defined by the JDBC 3.0 specification.)</p>
</div>
<div class="paragraph">
<p>Typically, a user or system administrator uses a tool to create a data
source, and then registers the data source by using a JNDI service
provider. At run time, a user application typically retrieves the data
source through JNDI, and uses the data source&#8217;s methods to establish a
connection to the underlying database.</p>
</div>
<div class="paragraph">
<p>A DataSource object maps to an instance of a database. In the Type 4
driver product, the DataSource object acts as an interface between the
application code and the database and enables connection with a DCS
(Data Connectivity Services) data source.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="security">3.2. Security</h3>
<div class="paragraph">
<p>Clients connect to the Trafodion platform with a valid user name
and password, using standard JDBC 3.0 APIs. An application can make multiple
connections using different user IDs, and creating different Connection
objects.</p>
</div>
<div class="paragraph">
<p>The Type 4 driver provides for user name and password authentication.
The password is encrypted.</p>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect2">
<h3 id="connection-by-using-the-datasource-interface">3.3. Connection by Using the DataSource Interface</h3>
<div class="paragraph">
<p>The <code>javax.sql.DataSource</code> interface is the preferred way to establish a
connection to the database because this interface enhances the application
portability. Portability is achieved by allowing the application to use a
logical name for a data source instead of providing driver-specific information
in the application. A logical name is mapped to a <code>javax.sql.DataSource</code>
object through a naming service that uses the Java Naming and Directory
Interface (JNDI). Using this DataSource method is particularly recommended
for application servers.</p>
</div>
<div class="paragraph">
<p>When an application requests a connection by using the <code>getConnection</code> method
in the <code>DataSource</code>, then the method returns a <code>Connection</code> object.</p>
</div>
<div class="paragraph">
<p>A <code>DataSource</code> object is a factory for <code>Connection</code> objects. An object that
implements the <code>DataSource</code> interface is typically registered with a JNDI
service provider.</p>
</div>
<div class="sect3">
<h4 id="overview-of-tasks-to-deploy-datasource-objects">3.3.1. Overview of Tasks to Deploy DataSource Objects</h4>
<div class="paragraph">
<p>Before an application can connect to a <code>DataSource</code> object, typically
the system administrator deploys the <code>DataSource</code> object so that
the application programmers can start using it.</p>
</div>
<div class="paragraph">
<p>Data source properties are usually set by a system administrator using
a GUI tool as part of the installation of the data source. Users to
the data source do not get or set properties. Management tools can get
at properties by using introspection.</p>
</div>
<div class="paragraph">
<p>Tasks involved in creating and registering a database object are:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Creating an instance of the <code>DataSource</code> class.</p>
</li>
<li>
<p>Setting the properties of the <code>DataSource</code> object.</p>
</li>
<li>
<p>Registering the <code>DataSource</code> object with a naming service that uses
the Java Naming and Directory Interface (JNDI) API.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>An instance of the <code>DataSource</code> class and the <code>DataSource</code> object
properties are usually set by an application developer or system
administrator using a GUI tool as part of the installation of the
data source. If you are using an installed data source, then see
<a href="#programmatically-creating-an-instance-of-the-datasource-class">Programmatically Creating an Instance of the DataSource Class</a>.</p>
</div>
<div class="paragraph">
<p>The subsequent topics show an example of performing these tasks programmatically.</p>
</div>
<div class="paragraph">
<p>For more information about using data sources, see <a href="https://docs.oracle.com/javase/tutorial/jdbc/basics/sqldatasources.html">Connecting with DataSource Objects</a>
in the <a href="https://docs.oracle.com/javase/tutorial/jdbc/TOC.html">JDBC&#8482; Database Access: Table of Contents</a> documentation
or other information available in the field.</p>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect3">
<h4 id="datasource-object-properties">3.3.2. DataSource Object Properties</h4>
<div class="paragraph">
<p>A <code>DataSource</code> object has properties that identify and describe the actual
data source that the object represents. These properties include such
information as the URL (the primary IP address or host name of the database),
the database schema and catalog names, the location of the database server,
the name of the database, and so forth.</p>
</div>
<div class="paragraph">
<p>For details about Type 4 driver properties that you can use with the <code>DataSource</code> object, see <a href="#type-4-driver-properties">Type 4 Driver Properties</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="programmatically-creating-an-instance-of-the-datasource-class">3.3.3. Programmatically Creating an Instance of the DataSource Class</h4>
<div class="paragraph">
<p>A JDBC application can set <code>DataSource</code> properties programmatically and
register with a DataSource object. To get or set <code>DataSource</code> object properties programmatically, use the
appropriate getter or setter methods on the <code>TrafT4DataSource</code> object or
the <code>TrafT4ConnectionPoolDataSource</code> object.</p>
</div>
<div class="paragraph">
<p><strong>Example</strong></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">TrafT4DataSource temp = <span class="keyword">new</span> TrafT4DataSource() ;
temp.setCatalog( <span class="string"><span class="delimiter">&quot;</span><span class="content">TRAFODION</span><span class="delimiter">&quot;</span></span> ) ;</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the following example, the code fragment illustrates the methods that a
<code>DataSource</code> object <code>ds</code> needs to include if the object supports the
<code>serverDataSource</code> property <code>ds.setServerDataSource( "my_server_datasource" )</code>.
In this example, the code shows setting properties for the <code>TrafT4DataSource</code> object
to use the Type 4 driver to access a Trafodion database:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">TrafT4DataSource ds = <span class="keyword">new</span> TrafT4DataSource() ;
ds.setUrl( <span class="string"><span class="delimiter">&quot;</span><span class="content">jdbc:t4jdbc://&lt;primary IP addr or host name&gt;:23400/</span><span class="delimiter">&quot;</span></span> );
ds.setSchema( <span class="string"><span class="delimiter">&quot;</span><span class="content">myschema</span><span class="delimiter">&quot;</span></span> ) ;
ds.setUser( <span class="string"><span class="delimiter">&quot;</span><span class="content">gunnar</span><span class="delimiter">&quot;</span></span> ) ;
ds.setPassword( <span class="string"><span class="delimiter">&quot;</span><span class="content">my_userpassword</span><span class="delimiter">&quot;</span></span> ) ;
<span class="comment">// Properties relevant for Type 4 connection pooling.</span>
<span class="comment">// Set ds.setMaxPoolSize(-1) for turning OFF connection pooling</span>
ds.setMaxPoolSize( <span class="string"><span class="delimiter">&quot;</span><span class="content">100</span><span class="delimiter">&quot;</span></span> ) ;
ds.setMinPoolSize( <span class="string"><span class="delimiter">&quot;</span><span class="content">10</span><span class="delimiter">&quot;</span></span> ) ;
<span class="comment">// Properties relevant for Type 4 statement pooling.</span>
<span class="comment">// Set ds.setMaxStatement(0) for turning statement pooling OFF</span>
<span class="comment">// Statement pooling is enabled only when connection pooling is</span>
<span class="comment">// enabled.</span>
ds.setMaxStatements( <span class="string"><span class="delimiter">&quot;</span><span class="content">7000</span><span class="delimiter">&quot;</span></span> ) ;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This technique essentially builds a properties file. For more information,
see <a href="#creating-and-using-a-properties-file">Creating and Using a Properties File</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="programmatically-registering-the-datasource-object">3.3.4. Programmatically Registering the DataSource Object</h4>
<div class="paragraph">
<p>In the following example, the code shows how to register, programmatically,
the <code>TrafT4DataSource</code> object <code>ds</code> that was created using the preceding code with JNDI.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">java.util.Hashtable env = <span class="keyword">new</span> java.util.Hashtable() ;
env.put( <span class="predefined-type">Context</span>.INITIAL_CONTEXT_FACTORY, <span class="string"><span class="delimiter">&quot;</span><span class="content">Factory class name here</span><span class="delimiter">&quot;</span></span> ) ;
javax.naming.Context ctx = <span class="keyword">new</span> javax.naming.InitialContext( env ) ;
ctx.rebind( <span class="string"><span class="delimiter">&quot;</span><span class="content">myDataSource</span><span class="delimiter">&quot;</span></span>, ds ) ;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="retrieving-a-datasource-instance-by-using-jndi-and-connecting-to-the-data-source">3.3.5. Retrieving a DataSource Instance by Using JNDI and Connecting to the Data Source</h4>
<div class="paragraph">
<p>Typically, the JDBC application looks up the data source JNDI name from a
context object. Once the application has the <code>DataSource</code> object, then the application
does a <code>getConnection()</code> call on the data source and gets a connection.</p>
</div>
<div class="paragraph">
<p>The steps that JDBC application does to connect to and use the data source associated
with the database are listed below together with the application code to perform the
operation.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Import the packages.</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">javax.naming</span>.* ;
<span class="keyword">import</span> <span class="include">java.sql</span>.* ;
<span class="keyword">import</span> <span class="include">javax.sql.DataSource</span> ;</code></pre>
</div>
</div>
</li>
<li>
<p>Create the initial context.</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Hashtable</span> env = <span class="keyword">new</span> <span class="predefined-type">Hashtable</span>() ;
env.put( <span class="predefined-type">Context</span>.INITIAL_CONTEXT_FACTORY, <span class="string"><span class="delimiter">&quot;</span><span class="content">com.sun.jndi.fscontext.RefFSContextFactory</span><span class="delimiter">&quot;</span></span> ) ;
<span class="keyword">try</span>
{
<span class="predefined-type">Context</span> ctx = <span class="keyword">new</span> <span class="predefined-type">InitialContext</span>( env ) ;
}
<span class="keyword">catch</span>( ... )
{
...
}</code></pre>
</div>
</div>
<div style="page-break-after: always;"></div>
</li>
<li>
<p>Look up the JNDI name associated with the data source <code>myDataSource</code>, where <code>myDataSource</code>
is the logical name that will be associated with the real-world data source - server.</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">DataSource</span> ds = (<span class="predefined-type">DataSource</span>)ctx.lookup( <span class="string"><span class="delimiter">&quot;</span><span class="content">myDataSource</span><span class="delimiter">&quot;</span></span> ) ;</code></pre>
</div>
</div>
</li>
<li>
<p>Create the connection using the data source.</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">con = ds.getConnection() ;</code></pre>
</div>
</div>
</li>
<li>
<p>Do work with the connection. The following statements are just a simple example.</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">stmt = con.createStatement() ;
<span class="keyword">try</span>
{
stmt.executeUpdate( <span class="string"><span class="delimiter">&quot;</span><span class="content">drop table tdata</span><span class="delimiter">&quot;</span></span> ) ;
}
<span class="keyword">catch</span> ( <span class="exception">SQLException</span> e ) {}</code></pre>
</div>
</div>
</li>
</ol>
</div>
</div>
<div class="sect3">
<h4 id="specifying-the-properties-file-that-configures-the-data-source">3.3.6. Specifying the Properties File that Configures the Data Source</h4>
<div class="paragraph">
<p>To use the properties file method to configure a <code>DataSource</code> object, the properties
file must exist on disk and contain the <code>property_name=property_value</code> pairs that
configure the data source.
See <a href="#creating-and-using-a-properties-file">Creating and Using a Properties File</a>
for more information about creating this file.</p>
</div>
<div class="paragraph">
<p>When the JDBC application makes the connection, then the application should
pass the properties file as a command-line parameter:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">java -Dt4jdbc.properties=&lt;path of properties file on disk&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="connection-by-using-the-drivermanager-class">3.4. Connection by Using the DriverManager Class</h3>
<div class="paragraph">
<p>The <code>java.sql.DriverManager</code> class is widely used to get a connection, but
is less portable than the <code>DataSource</code> class. The <code>DriverManager</code> class
works with the Driver interface to manage the set of drivers loaded.
When an application issues a request for a connection using the
<code>DriverManager.getConnection</code> method and provides a URL, the <code>DriverManager</code>
finds a suitable driver that recognizes this URL and obtains a database
connection using that driver.</p>
</div>
<div class="paragraph">
<p><code>org.trafodion.jdbc.t4.T4Driver</code> is the Type 4 driver class that
implements the <code>java.sql.Driver</code> interface.</p>
</div>
<div style="page-break-after: always;"></div>
<div class="sect3">
<h4 id="loading-and-registering-the-driver">3.4.1. Loading and Registering the Driver</h4>
<div class="paragraph">
<p>Before connecting to the database, the application loads the Driver
class and registers the Type 4 driver with the DriverManager class in
one of the following ways:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Specifies the Type 4 driver class in the <code>-Djdbc.drivers</code> option in the
command line of the Java program:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">-Djdbc.drivers=org.trafodion.jdbc.t4.T4Driver</code></pre>
</div>
</div>
</li>
<li>
<p>Uses the <code>Class.forName</code> method programmatically within the application:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Class</span>.forName(<span class="string"><span class="delimiter">&quot;</span><span class="content">org.trafodion.jdbc.t4.T4Driver</span><span class="delimiter">&quot;</span></span>)</code></pre>
</div>
</div>
</li>
<li>
<p>Adds the Type 4 driver class to the <code>java.lang.System</code> property
<code>jdbc.drivers</code> property within the application:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">jdbc.drivers=org.trafodion.jdbc.t4.T4Driver</code></pre>
</div>
</div>
</li>
</ul>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect3">
<h4 id="establishing-the-connection">3.4.2. Establishing the Connection</h4>
<div class="paragraph">
<p>The <code>DriverManager.getConnection</code> method accepts a string containing a
Type 4 driver URL. The JDBC URL for the Type 4 driver is</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">jdbc:t4jdbc://&lt;ip addr or host name&gt;:23400/[:][property=value[;property2=value2]...]</code></pre>
</div>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 40%;">
<col style="width: 60%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>&lt;ip addr or host name&gt;</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The primary IP address or host name for the Trafodion database.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>23400</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The port number for the Trafodion SQL database.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>property = value</code> and <code>property2=value2</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies a Type 4 driver property name-property value pair. The pairs must be separated by a
semicolon (<code>;</code>). For example, <code>T4LogLevel=ALL;T4LogFile=temp1.log</code>.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>For information about the properties file, see <a href="#type-4-driver-properties">Type 4 Driver Properties</a>.</p>
</div>
<div class="paragraph">
<p>To establish a connection, the JDBC application can use this code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Class</span>.forName( <span class="string"><span class="delimiter">&quot;</span><span class="content">org.trafodion.jdbc.t4.T4Driver</span><span class="delimiter">&quot;</span></span> ) ; <span class="comment">//loads the driver</span>
<span class="predefined-type">String</span> url = <span class="string"><span class="delimiter">&quot;</span><span class="content">jdbc:t4jdbc://&lt;database primary IP address&gt;:23400/</span><span class="delimiter">&quot;</span></span>
<span class="predefined-type">Connection</span> con = <span class="predefined-type">DriverManager</span>.getConnection( url, <span class="string"><span class="delimiter">&quot;</span><span class="content">userID</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">Passwd</span><span class="delimiter">&quot;</span></span> ) ;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The variable con represents a connection to the data source that can be
used to create and execute SQL statements.</p>
</div>
</div>
<div class="sect3">
<h4 id="guidelines-for-connections-using-the-driver-manager">3.4.3. Guidelines for Connections Using the Driver Manager</h4>
<div class="ulist">
<ul>
<li>
<p>The Type 4 driver defines a set of properties that you can use to
configure the driver. For detailed information about these properties,
see <a href="#type-4-driver-properties">Type 4 Driver Properties</a>.</p>
</li>
<li>
<p>Java applications can specify the properties in these ways (listed in
the order of precedence):</p>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Using the <code>java.util.Properties</code> parameter in the <code>getConnection</code> method of DriverManager class.</p>
</li>
<li>
<p>Using the database URL in the <code>DriverManager.getconnection</code> method, where the URL is:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">jdbc:t4jdbc://&lt;ip addr or host name&gt;:23400/:property=value</code></pre>
</div>
</div>
<div class="paragraph">
<p><code>&lt;ip addr or host name&gt;</code> is the primary IP address or host name for the Trafodion database.</p>
</div>
<div style="page-break-after: always;"></div>
</li>
<li>
<p>Using a properties file for the JDBC driver. The properties file is
passed as a command-line parameter. The format to enter the properties
file in the command line is:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">-Dt4jdbc.properties=&lt;path of properties file on disk&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>For example, <code>-Dt4jdbc.properties=C:\temp\t4props</code></p>
</div>
<div class="paragraph">
<p>For information about the properties file, see <a href="#creating-and-using-a-properties-file">Creating and Using a Properties File</a>.</p>
</div>
</li>
<li>
<p>Using JDBC properties with the <code>-D</code> option in the command line. If
used, this option applies to all JDBC connections using the
<code>DriverManager</code> within the Java application. The format in the command
line is:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">-Dt4jdbc.property_name=&lt;property value&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>For example, <code>-Dt4jdbc.maxStatements=1024</code></p>
</div>
</li>
</ol>
</div>
</li>
</ul>
</div>
<div style="page-break-after: always;"></div>
</div>
</div>
<div class="sect2">
<h3 id="connection-pooling">3.5. Connection Pooling</h3>
<div class="paragraph">
<p>The Type 4 driver provides an implementation of connection pooling,
where a cache of physical database connections are assigned to a client
session and reused for the database activity. If connection pooling is
active, connections are not physically closed. The connection is
returned to its connection pool when the <code>Connection.close()</code> method is
called. The next time a connection is requested by the client, the
driver will return the pooled connection, and not a new physical
connection.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The connection pooling feature is available when the JDBC application
uses either the <code>DriverManager</code> class or <code>DataSource</code> interface to obtain a
JDBC connection. The connection pool size is determined by the
<code>maxPoolSize</code> property value and <code>minPoolSize</code> property value.</p>
</li>
<li>
<p>By default, connection pooling is disabled. To enable connection
pooling, set the maxPoolSize property to an integer value greater than 0
(zero).</p>
</li>
<li>
<p>Manage connection pooling by using these Type 4 driver properties:</p>
<div class="ulist">
<ul>
<li>
<p><code>maxPoolSize</code> under <a href="#maxpoolsize-property">maxpoolsize Property</a></p>
</li>
<li>
<p><code>minPoolSize</code> under <a href="#minpoolsize-property">minPoolSize Property</a></p>
</li>
<li>
<p><code>initialPoolSize</code> under <a href="#initialpoolsize-property">initialPoolSize Property</a></p>
</li>
<li>
<p><code>maxStatements</code> under <a href="#maxstatements-property">maxStatements Property</a></p>
</li>
</ul>
</div>
</li>
<li>
<p>When used with the DriverManager class, the Type 4 driver has a
connection-pool manager that determines which connections are pooled
together by a unique value for these combination of properties:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">url
catalog
schema
username
password</code></pre>
</div>
</div>
<div class="paragraph">
<p>Therefore, connections that have the same values for the combination of
a set of properties are pooled together.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The connection-pooling property values used at the first
connection of a given combination are effective throughout the life of
the process. An application cannot change any of these property values
after the first connection for a given combination.
</td>
</tr>
</table>
</div>
</li>
</ul>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect2">
<h3 id="statement-pooling">3.6. Statement Pooling</h3>
<div class="paragraph">
<p>The statement pooling feature allows applications to reuse the
PreparedStatement object in the same way that they can reuse a
connection in the connection pooling environment. Statement pooling is
completely transparent to the application.</p>
</div>
<div class="sect3">
<h4 id="guidelines-for-statement-pooling">3.6.1. Guidelines for Statement Pooling</h4>
<div class="ulist">
<ul>
<li>
<p>To enable statement pooling, set the <code>maxStatements</code> property to an
integer value greater than 0 and enable connection pooling. For more
information, see <a href="#initialpoolsize-property">initialPoolSize Property</a> and
<a href="#connection-pooling">Connection Pooling</a>.</p>
</li>
<li>
<p>Enabling statement pooling for your JDBC applications might
dramatically improve the performance.</p>
</li>
<li>
<p>Explicitly close a prepared statement by using the <code>Statement.close</code>
method because <code>PreparedStatement</code> objects that are not in scope are also
not reused unless the application explicitly closes them.</p>
</li>
<li>
<p>To ensure that your application reuses a <code>PreparedStatement</code>, call
either of these methods:</p>
<div class="ulist">
<ul>
<li>
<p><code>Statement.close method</code>: called by the application.</p>
</li>
<li>
<p><code>Connection.close method</code>: called by the application. All the
<code>PreparedStatement</code> objects that were in use are ready to be reused when
the connection is reused.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="troubleshooting-statement-pooling">3.6.2. Troubleshooting Statement Pooling</h4>
<div class="paragraph">
<p>Note the following Type 4 driver implementation details if you are
troubleshooting statement pooling:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The Type 4 driver looks for a matching <code>PreparedStatement</code> object in the
statement pool and reuses the <code>PreparedStatement</code>. The matching criteria
include the SQL string, catalog, current schema, current transaction
isolation, and result set holdability.</p>
<div class="paragraph">
<p>If the Type 4 driver finds the matching <code>PreparedStatement</code> object, then the
driver returns the same <code>PreparedStatement</code> object to the application for reuse
and marks the <code>PreparedStatement</code> object as in use.</p>
</div>
</li>
<li>
<p>The algorithm, <em>earlier used are the first to go</em>, is used to make
room for caching subsequently generated <code>PreparedStatement</code> objects when
the number of statements reaches the <code>maxStatements</code> limit.</p>
</li>
<li>
<p>The Type 4 driver assumes that any SQL CONTROL statements in effect at
the time of execution or reuse are the same as those in effect at the time
of SQL compilation.</p>
<div class="paragraph">
<p>If this condition is not true, then reuse of a <code>PreparedStatement</code> object might
result in unexpected behavior.</p>
</div>
</li>
<li>
<p>Avoid recompiling to yield performance improvements from statement
pooling. The SQL executor automatically recompiles queries when certain conditions are met.
Some of these conditions are:</p>
<div class="ulist">
<ul>
<li>
<p>A run-time version of a table has a different redefinition timestamp
than the compile-time version of the same table.</p>
</li>
<li>
<p>An existing open operation on a table was eliminated by a DDL or SQL
utility operation.</p>
</li>
<li>
<p>The transaction isolation level and access mode at execution time is
different from that at the compile time.</p>
</li>
</ul>
</div>
</li>
<li>
<p>When a query is recompiled, then the SQL executor stores the recompiled query;
therefore, the query is recompiled only once until any of the previous conditions
are met again.</p>
</li>
<li>
<p>The Type 4 driver does not cache <code>Statement</code> objects.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="thread-safe-database-access">3.7. Thread-Safe Database Access</h3>
<div class="paragraph">
<p>In the Type 4 driver, API layer classes are implemented as
instance-specific objects to ensure thread safety:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>TrafT4DataSource.getConnection()</code> is implemented as a synchronized method
to ensure thread safety in getting a connection.</p>
</li>
<li>
<p>Once a connection is made, the <code>Connection</code> object is instance-specific.</p>
</li>
<li>
<p>If multiple statements are run on different threads in a single
connection, then statement objects are serialized to prevent data corruption.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="update-where-current-of-operations">3.8. "Update . . . Where Current of" Operations</h3>
<div class="paragraph">
<p>The fetch size on a <code>ResultSet</code> must be 1 when performing an
<code>update . . . where current of</code> <em>cursor</em> SQL statement.</p>
</div>
<div class="paragraph">
<p>If the value of the fetch size is greater than 1, the result of the
<code>update . . . where current</code> of operation might be one of the following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>An incorrect row might be updated based on the actual cursor position.</p>
</li>
<li>
<p>An SQLException might occur because the cursor being updated might
have already been closed.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The following is an example of setting a result set&#8217;s fetch size to 1
and executing an <code>update . . . where current</code> of <em>cursor</em> SQL statement.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">ResultSet</span> rs ;
...
rs.setFetchSize( <span class="integer">1</span> ) ;
<span class="predefined-type">String</span> st1 = rs.getCursorName() ;
<span class="predefined-type">Statement</span> stmt2 =
connection.createStatement( <span class="predefined-type">ResultSet</span>.TYPE_FORWARD_ONLY
, <span class="predefined-type">ResultSet</span>.CONCUR_UPDATABLE
) ;
stmt2.executeUpdate( <span class="string"><span class="delimiter">&quot;</span><span class="content">UPDATE cat2.sch2.table1
SET j = 'update row' WHERE CURRENT OF </span><span class="delimiter">&quot;</span></span>
+ st1
) ;</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="infostats-command-for-obtaining-query-costs">3.9. INFOSTATS Command for Obtaining Query Costs</h3>
<div class="paragraph">
<p>The INFOSTATS command reports the roll-up costs of a particular query.
INFOSTATS is a pass-through command that collects statistics for a
prepared statement. Statistics are returned to the JDBC application as a
result set as soon as the prepare is finished. The result set has these
columns:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 30%;">
<col style="width: 70%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Column</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>Query ID (SQL_CHAR)</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The unique identifier for the query.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>CPUTime (SQL_DOUBLE)</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An estimate of the number of seconds of processor time it might take to execute the instructions for this query. A value of 1.0 is 1 second.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>IOTime (SQL_DOUBLE)</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An estimate of the number of seconds of I/O time (seeks plus data transfer) to perform the I/O for this query.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>MsgTime (SQL_DOUBLE)</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An estimate of the number of seconds it takes for the messaging for this query. The estimate includes the time for the number of local and remote
messages and the amount of data sent.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>IdleTime (SQL_DOUBLE)</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An estimate of the maximum number of seconds to wait for an event to happen for this query. The estimate includes the amount of time to open
a table or start an ESP process.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>TotalTime (SQL_DOUBLE)</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Estimated cost associated to execute the query.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>Cardinality (SQL_DOUBLE)</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Estimated number of rows that will be returned.</p></td>
</tr>
</tbody>
</table>
<div style="page-break-after: always;"></div>
<div class="sect3">
<h4 id="use-of-the-infostats-command">3.9.1. Use of the INFOSTATS Command</h4>
<div class="paragraph">
<p>The INFOSTATS command can only be used with PreparedStatement objects.
The syntax is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">INFOSTATS cursor_name</code></pre>
</div>
</div>
<div class="paragraph">
<p>where <code>cursor_name</code> is the name of the prepared statement. If the cursor name is case-sensitive,
then enclose it in single quotes.</p>
</div>
<div class="paragraph">
<p>To get the cursor name, use the <code>getStatementLabel()</code> method that is
defined for the Trafodion JDBC Type 4 driver with class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">org.trafodion.jdbc.t4.T4PreparedStatement: <span class="directive">public</span> <span class="predefined-type">String</span>
getStatementLabel() ;</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Considerations</strong></p>
</div>
<div class="ulist">
<ul>
<li>
<p>You can use INFOSTATS in these methods only:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">java.sql.Statement.executeQuery(<span class="predefined-type">String</span> sql)
java.sql.Statement.execute(<span class="predefined-type">String</span> sql)</code></pre>
</div>
</div>
</li>
<li>
<p><code>setCursorName</code> is not supported with INFOSTATS.</p>
</li>
<li>
<p>If you invoke INFOSTATS incorrectly, the Type 4 driver issues this error:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">Message: INFOSTATS command can only be executed
by calling execute(String sql) method.
Sqlstate HY000
Sqlcode 29180</code></pre>
</div>
</div>
</li>
</ul>
</div>
<div style="page-break-after: always;"></div>
<div class="paragraph">
<p><strong>Example of INFOSTATS</strong></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Statement</span> s = conn.createStatement( ) ;
TrafT4PreparedStatement p =
(TrafT4PreparedStatement)conn.prepareStatement(
<span class="string"><span class="delimiter">&quot;</span><span class="content">SELECT * FROM t WHERE i = ?</span><span class="delimiter">&quot;</span></span> ) ;
<span class="type">boolean</span> results = s.execute( <span class="string"><span class="delimiter">&quot;</span><span class="content">INFOSTATS </span><span class="delimiter">&quot;</span></span> + p.getStatementLabel() ) ;
<span class="keyword">if</span> ( results )
{
<span class="predefined-type">ResultSet</span> rs = s.getResultSet( ) ;
<span class="keyword">while</span> ( rs.next( ) )
{
<span class="comment">//process data</span>
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Sample Output</strong></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text">QueryID: MXID001001128212016369912348191_16_SQL_CUR_9829657
CPUTime: 0.09975778464794362
IOTime: 0.10584000146627659
MsgTime: 0.09800000134418951
IdleTime: 0.09800000134418951
TotalTime: 0.10584000146627659
Cardinality: 100.0</code></pre>
</div>
</div>
<div style="page-break-after: always;"></div>
</div>
</div>
<div class="sect2">
<h3 id="internationalization-support">3.10. Internationalization Support</h3>
<div class="sect3">
<h4 id="when-string-literals-are-used-in-applications">3.10.1. When String Literals Are Used in Applications</h4>
<div class="paragraph">
<p>Internationalization support in the driver affects the handling of
string literals. The Type 4 driver handles string literals in two
situations.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>When the driver processes an SQL statement. For example,</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Statement</span> stmt = connection.getStatement() ;
stmt.execute( <span class="string"><span class="delimiter">&quot;</span><span class="content">SELECT * FROM table1 WHERE col1 = 'abcd'</span><span class="delimiter">&quot;</span></span> ) ;</code></pre>
</div>
</div>
</li>
<li>
<p>When the driver processes JDBC parameters. For example,</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">PreparedStatement</span> pStmt = connection.prepareStatement(
<span class="string"><span class="delimiter">&quot;</span><span class="content">SELECT * FROM table1 WHERE col1 = ?</span><span class="delimiter">&quot;</span></span> ) ;
pStmt.setString( <span class="integer">1</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">abcd</span><span class="delimiter">&quot;</span></span> ) ;</code></pre>
</div>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<p>To convert a string literal from the Java to an array of bytes for
processing by the Trafodion, the Type 4 driver uses
the column type in the database.</p>
</div>
</div>
<div class="sect3">
<h4 id="controlling-string-literal-conversion-by-using-the-character-set-properties">3.10.2. Controlling String Literal Conversion by Using the Character-Set Properties</h4>
<div class="paragraph">
<p>The Type 4 driver provides character-set mapping properties. These
properties allow you to explicitly define the translation of internal
SQL character-set formats to and from the Java string Unicode (<code>UnicodeBigUnmarked</code>)
encoding.</p>
</div>
<div class="paragraph">
<p>The Type 4 driver provides character-set mapping properties through key
values as shown in the following table.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Key</th>
<th class="tableblock halign-left valign-top">Default Value</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ISO88591</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ISO88591_1</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>KANJI</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>SJIS</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>KSC5601</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>EUC_KR</code></p></td>
</tr>
</tbody>
</table>
<div style="page-break-after: always;"></div>
<div class="paragraph">
<p>A description of these character sets appears in table below, which
summarizes the character sets supported by Trafodion.</p>
</div>
<table class="tableblock frame-all grid-all spread">