Progress DataDirect for JDBC for Jira User's Guide · The Progress® DataDirect® for JDBC™ for...

Progress® DataDirect® forJDBC™ for Jira™

User's Guide

Release 6.0.0

Copyright

© 2019 Progress Software Corporation and/or its subsidiaries or affiliates. All rightsreserved.These materials and all Progress® software products are copyrighted and all rights are reserved by ProgressSoftware Corporation. The information in these materials is subject to change without notice, and ProgressSoftware Corporation assumes no responsibility for any errors that may appear therein. The references in thesematerials to specific platforms supported are subject to change.

Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirectXML Converters, DataDirect XQuery, DataRPM, Deliver More Than Expected, Icenium, Kendo UI, Kinvey,NativeScript, OpenEdge, Powered by Progress, Progress, Progress Software Developers Network, Rollbase,SequeLink, Sitefinity (and Design), Sitefinity, SpeedScript, Stylus Studio, TeamPulse, Telerik, Telerik (andDesign), Test Studio, and WebSpeed are registered trademarks of Progress Software Corporation or one ofits affiliates or subsidiaries in the U.S. and/or other countries. Analytics360, AppServer, BusinessEdge, DataDirectAutonomous REST Connector, DataDirect Spy, SupportLink, DevCraft, Fiddler, JustAssembly, JustDecompile,JustMock, NativeChat, NativeScript Sidekick, OpenAccess, ProDataSet, Progress Results, Progress Software,ProVision, PSE Pro, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView,SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow,and WebClient are trademarks or service marks of Progress Software Corporation and/or its subsidiaries oraffiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any othermarks contained herein may be trademarks of their respective owners.

Updated: 2019/06/28

3Progress DataDirect for JDBC for Jira: User's Guide: Version 6.0.0

Progress DataDirect for JDBC for Jira: User's Guide: Version 6.0.04

Copyright

Table of Contents

Welcome to the Progress DataDirect for JDBC for Jira Driver: Version6.0.0..............................................................................................................9

What's new in this release?..................................................................................................................10Quick start.............................................................................................................................................10Requirements........................................................................................................................................10Version string information.....................................................................................................................11Driver and DataSource classes............................................................................................................11Connection URL....................................................................................................................................11Connection properties...........................................................................................................................12Introduction to the Jira Data Model ......................................................................................................12Mapping objects to tables.....................................................................................................................15Data types.............................................................................................................................................17

getTypeInfo()..............................................................................................................................17DataDirect Tools....................................................................................................................................20Troubleshooting....................................................................................................................................21Contacting Technical Support...............................................................................................................21

Using the Driver............................................................................................23Required permissions for Java SE with the standard Security Manager enabled................................24

Permissions for establishing connections..................................................................................24Granting access to Java properties............................................................................................24Granting access to temporary files.............................................................................................25

Connecting from an application............................................................................................................25Setting the classpath .................................................................................................................25Connecting using the JDBC Driver Manager.............................................................................26Connecting using data sources..................................................................................................29

Connecting through a proxy server.......................................................................................................34IP addresses.........................................................................................................................................34Performance considerations.................................................................................................................35Data encryption.....................................................................................................................................36

Configuring SSL encryption.......................................................................................................36Configuring SSL server authentication.......................................................................................37Configuring SSL client authentication........................................................................................38

Enabling Debug Record Mode..............................................................................................................39Isolation levels......................................................................................................................................39SQL Escape Sequences.......................................................................................................................40

Supported Scalar Functions ......................................................................................................40Statement Pooling.................................................................................................................................42


Contents

Connection Pooling...............................................................................................................................42

Connection property descriptions..............................................................43ConvertNull...........................................................................................................................................47CryptoProtocolVersion..........................................................................................................................48DebugRecord........................................................................................................................................49FetchSize..............................................................................................................................................50HostNameInCertificate..........................................................................................................................51ImportStatementPool............................................................................................................................52InsensitiveResultSetBufferSize.............................................................................................................53JDBCBehavior......................................................................................................................................54KeyPassword........................................................................................................................................55KeyStore...............................................................................................................................................55KeyStorePassword...............................................................................................................................56LogConfigFile........................................................................................................................................57LoginTimeout........................................................................................................................................58MaxPooledStatements..........................................................................................................................58Password..............................................................................................................................................59PortNumber...........................................................................................................................................60ProxyHost..............................................................................................................................................61ProxyPassword.....................................................................................................................................61ProxyPort..............................................................................................................................................62ProxyUser.............................................................................................................................................62ReadAhead ..........................................................................................................................................63RegisterStatementPoolMonitorMBean..................................................................................................64ServerName..........................................................................................................................................65SpyAttributes.........................................................................................................................................66StmtCallLimit.........................................................................................................................................66StmtCallLimitBehavior...........................................................................................................................67TrustStore.............................................................................................................................................68TrustStorePassword..............................................................................................................................69User.......................................................................................................................................................69ValidateServerCertificate.......................................................................................................................70WSFetchSize........................................................................................................................................71WSPoolSize..........................................................................................................................................72WSRetryCount......................................................................................................................................73WSTimeout...........................................................................................................................................74

Supported SQL statements and extensions..............................................75Alter Session (EXT)..............................................................................................................................75Select....................................................................................................................................................76

Select clause..............................................................................................................................78SQL expressions...................................................................................................................................87


Contents

Column names...........................................................................................................................87Literals........................................................................................................................................87Operators...................................................................................................................................90Functions....................................................................................................................................94Conditions..................................................................................................................................94

Subqueries............................................................................................................................................95IN predicate................................................................................................................................95EXISTS predicate.......................................................................................................................96UNIQUE predicate.....................................................................................................................96Correlated subqueries................................................................................................................96


Contents


Contents

1Welcome to the Progress DataDirect forJDBC for Jira Driver: Version 6.0.0

The Progress® DataDirect® for JDBC™ for Jira™ Driver (Jira driver) supports SQL read-only access for JDBC applications to Atlassian Jira. To support SQL access to Jira services, the driver creates a relational map of the Jira data model and translates SQL statements to Jira REST API requests. In addition, the driver employs a SQL engine component that provides support to SQL constructs unavailable to Jira services. This functionality offers a number of advantages, including support for reporting data and metadata in a form that JDBC applications are ready to use.

The documentation set also includes the Progress DataDirect for JDBC Drivers Reference. The reference provides general reference information for all DataDirect drivers for JDBC, including content on troubleshooting, supported SQL escapes, and DataDirect tools. For the complete documentation set, refer to DataDirect Documentation.

For details, see the following topics:

• What's new in this release?

• Quick start

• Requirements

• Version string information

• Driver and DataSource classes

• Connection URL

• Connection properties

• Introduction to the Jira Data Model


https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html

https://www.progress.com/documentation/datadirect-connectors

https://www.progress.com/documentation/datadirect-connectors

• Mapping objects to tables

• Data types

• DataDirect Tools

• Troubleshooting

• Contacting Technical Support

What's new in this release?Support and certificationVisit the following web pages for the latest support and certification information.

• Release Notes

• Supported Configurations

• DataDirect Support Matrices

Highlights of 6.0.0 Release• The driver supports SQL read-only access to Atlassian Jira. See Supported SQL statements and extensions

on page 75 for details.

• The driver supports JDBC core functions. For details, refer to JDBC support in the Progress DataDirect for JDBC Drivers Reference.

• The driver supports standard JSON data types and additional data types through data type inference. See Data types on page 17 and getTypeInfo() on page 17 for details.

• The driver supports Jira custom fields, including many fields added through third-party plug-ins.

• The driver supports the handling of large result sets with paging, and the FetchSize on page 50 and WSFetchSize on page 71 connection properties.

• The driver supports SSL data encryption. See Data encryption on page 36 for more information.

Quick startThe documentation library includes a quick start that provides the basic information necessary to quickly install,configure, and connect to Jira services. The quick start for the Jira driver is available at Quick start: ProgressDataDirect for JDBC for Jira Driver.

RequirementsThe driver is compatible with JDBC 2.0, 3.0, 4.0, 4.1, and 4.2.

The driver requires a Java Virtual Machine (JVM) that is Java SE 8 or higher, including Oracle JDK, OpenJDK,and IBM SDK (Java) distributions.


Chapter 1: Welcome to the Progress DataDirect for JDBC for Jira Driver: Version 6.0.0

https://www.progress.com/jdbc/release-history/

https://www.progress.com/supported-configurations/datadirect

https://www.progress.com/matrices/datadirect

https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/jdbc_support

https://documentation.progress.com/output/DataDirect/jdbcquickstarts/jirajdbc_quickstart/index.html

https://documentation.progress.com/output/DataDirect/jdbcquickstarts/jirajdbc_quickstart/index.html

Note: To use the driver on a Java Platform with standard Security Manager enabled, certain permissions mustbe set in the security policy file of the Java Platform. See Required permissions for Java SE with the standardSecurity Manager enabled on page 24 for details.

Version string informationThe DatabaseMetaData.getDriverVersion() method returns a driver version string in the format:

M.m.s.bbbbbb(CXXXX.FYYYYYY.UZZZZZZ)

where:

M is the major version number.

m is the minor version number.

s is the service pack number.

bbbbbb is the driver build number.

XXXX is the cloud adapter build number.

YYYYYY is the framework build number.

ZZZZZZ is the utl build number.

For example:

6.0.0.000002(C0003.F000001.U000002)|____| |___| |_____| |_____|Driver Cloud Frame Utl

Driver and DataSource classesThe following are the Driver and DataSource classes used by the driver:

Driver class:

com.ddtek.jdbc.jira.JiraDriver

DataSource class:

com.ddtek.jdbcx.jira.JiraDataSource

Connection URLAfter setting the CLASSPATH, the required connection information needs to be passed in the form of aconnection URL.

jdbc:datadirect:jira:servername;User=username;Password=password_token;[property=value[;...]];


Version string information

where:

servername

specifies the base URL of the Jira service to which you want to issue requests. For example,http://mycompany.atlassian.net.

Note: Specifying an HTTPS URL for this property enables data encryption.

username

specifies the user name that is used to connect to your Jira service.

password

specifies the password or API token used to connect to your Jira service.

property=value

specifies connection property settings. Multiple properties are separated by a semi-colon.

The following example shows how to establish a connection to a Jira service:

Connection conn = DriverManager.getConnection("jdbc:datadirect:jira:http://mycompany.atlassian.net;User=jsmith;Password=secret;");

See alsoServerName on page 65User on page 69Password on page 59Connection property descriptions on page 43

Connection propertiesThe driver includes over 40 connection properties. You can use connection properties to customize the driverfor your environment. Connection properties can be used to accomplish different tasks, such as implementingdriver functionality and optimizing performance. You can specify connection properties in a connection URLor within a JDBC data source object.

See alsoConnection property descriptions on page 43

Introduction to the Jira Data ModelTo expose Jira resources to SQL applications, the driver maps the native data model to relational tables andtranslates SQL statements to REST API requests. See "Mapping Objects to Tables" for more information onrelational mapping.



Although the JIRA environment promotes customization, a similar set of resources are used by most Jiraservices. The following table documents the types of Jira API Resources you are likely to encounter in yourenvironment, along with the relational mapping of the primary and child tables. Refer to the Jira documentationfor more information on resources.

Table 1: Jira API Resource Mapping

Relational Child Table(s)Relational Parent Table(s)Jira API Resource

• ApplicationRolesDefaultGroups

• ApplicationRolesGroups

ApplicationRolesApplication roles

• AuditingAssociatedItems

• AuditingChangedValues

AuditingAudit records

DashboardSharePermissionsDashboardsDashboards

• FilterSharedUserItems

• FilterSharePermissions

• FilterSubscriptions

FiltersFilters

NAFilterDefaultColumns

GroupLabelsGroupsGroups

NAGroupUsers

NAAttachmentsIssue attachment

NAAttachmentMeta

NACommentPropertyIssue commentproperties

NACommentPropertyKeys

NACommentsIssue comments

FieldClauseNamesFieldsIssue fields

NAIssueLinkTypesIssue link types

NAResolutionsIssue resolutions

NAIssueTypesIssue types

VotersVotesIssue votes

NAWatchersIssue watchers


Introduction to the Jira Data Model


• WorklogProperties

• WorklogPropertyValues

WorklogsIssue worklogs

• IssueAttachments

• IssueComments

• IssueComponents

• IssueFixVersions

• IssueLabels

• IssueLinks

• IssueSubtasks

• IssueVersions

• IssueWorklogs

IssuesIssues

NAIssueChangeLog

NAIssueChangeLogItems

NAIssueTransitions

Comments:

• Primary table contains a record of all the Issues. Note that issuing unfiltered queriesagainst large data sources may take a long time to process. To limit the number ofrows returned, use the following statements:

SELECT TOP

or

SELECT ... LIMIT

• The IssueChangeLog tables require either an ID or a KEY, in the Where clause.

NABoardsJira expressions

NAEpics

NASprints

Comments:The Sprints table requires either an ID or a KEY, in the Where clause.




AdvancedSettingsAllowedValuesAdvancedSettingsJira settings

ApplicationPropertiesAllowedValuesApplicationProperties

NAConfiguration

NAMyPermissionsPermissions

ProjectIssueTypesProjectsProjects

NAComponentsProject components

ProjectKeyProjectVersionsProject Versions

RoleActorsRolesProject role actors

• UserApplicationRoles

• UserGroups

• Users

UserDetailsUsers

NAWorkflowsWorkflows

Mapping objects to tablesData mapping describes how elements are mapped between two distinct data models. To support SQL accessto a Jira service, Jira REST endpoints must be mapped to a relational schema. The driver automaticallygenerates a relational view of your data the first time you execute a SQL statement. When generating therelational view, the driver decompounds JSON documents stored at endpoints into parent-child tables. Thedriver handles mapping the following manner:

• Simple and nested objects are flattened and mapped to a parent table

• Arrays are mapped to related child tables

For example, the following JSON document contains nested objects in the issuetype object and an array inthe labels object.

{"id": "10000","key": "ABC-100","fields": {

"issuetype": {"id": "20003","description": "A problem that impairs the functions of the product.","name": "Bug",

},"labels": [

"Dev","Severe","v7.1"


Mapping objects to tables

],}{

"id": "10001","key": "ABC-101","fields": {

"issuetype": {"id": "20022","description": "An user story.","name": "Story",

},"labels": [

"Dev","Installer""v8.0"

],}

When generating the relational view, the driver decompounds native arrays into separate, but related tables.The mapping of the sample JSON document produced one parent table and two child tables. In the parenttable, simple objects, such as id and key, are flattened into corresponding relational columns. Nested objectsare also flattened into relational columns; however, column names are formed by concatenating the name ofthe parent and nested objects, which are joined by an underscore character. For example, theFIELDS_ISSUETYPE_NAME column contains the values of the name object that is nested in the fields andissuetype objects.

The names of parent tables are determined by the Jira REST API resource used to issue requests. For a listof common tables, refer to "Introduction to the Jira Data Model."

The parent table for our example uses the Issues API resource, and therefore, is named ISSUES. The tabletakes the following form:

Table 2: ISSUES

FIELDS_ISSUETYPE_NAMEFIELDS_ISSUETYPE_DESCRIPTIONFIELDS_ISSUETYPE_IDKEYID (PK)

BugA problem that impairs the functionsof the product

20003ABC-10010000

StoryAn user story.20022ABC-10110001

The information in the labels array normalizes to the ISSUELABELS child table. The values of the array aremapped into a single relational column that corresponds to the name of the array. For example, the values forthe labels array in the JSON sample, such as Dev and Severe, map to the ISSUELABEL column in theISSUELABELS table. A foreign key relationship to the parent table is provided by including the primary key ofthe parent in the child, in this case, ISSUES_ID. The primary key of the child table is a composite key formedby the primary key of the parent table combined with the positional information contained in the POSITIONcolumn. If the array is nested multiple layers deep, additional positional columns for parent objects are mappedto insure that a unique key is used.

The child table for the ISSUELABLES array would take the following form:



Table 3: ISSUELABELS

ISSUELABELPOSITION (PK)ISSUES_ID (PK)

Dev010000

Severe110000

v7.1210000

Dev010001

Installer110001

v7.1210001

See alsoIntroduction to the Jira Data Model on page 12

Data typesThe following table lists Jira data types supported by the driver and how they are mapped to JDBC data types.

See "getTypeInfo()" for getTypeInfo() results of data types supported by the driver.

Table 4: Jira Data Types

JDBC Data TypeJira Data Type

BIGINTBigInt

BOOLEANBoolean

DATEDate

INTEGERInteger

JSONJSON

LONGVARCHARLongVarChar

TIMESTAMPTimestamp

VARCHARVarChar

getTypeInfo()The DatabaseMetaData.getTypeInfo() method returns information about data types. The following table providesgetTypeInfo() results for supported Jira data types.


Data types

Table 5: getTypeInfo() Results

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 19

SEARCHABLE = 3

SQL_DATA_TYPE = NULL

SQL_DATETIME_SUB = NULL

UNSIGNED_ATTRIBUTE = false

TYPE_NAME = BigInt

AUTO_INCREMENT = false

CASE_SENSITIVE = false

CREATE_PARAMS = NULL

DATA_TYPE = -5 (BIGINT)

FIXED_PREC_SCALE = false

LITERAL_PREFIX = NULL

LITERAL_SUFFIX = NULL

LOCAL_TYPE_NAME = BIGINT

MAXIMUM_SCALE = 0

MINIMUM_SCALE = NULL

NULLABLE = 1

NUM_PREC_RADIX = NULL

PRECISION = 1

SEARCHABLE = 3




TYPE_NAME = Boolean




DATA_TYPE = 16 (BOOLEAN)




LOCAL_TYPE_NAME = BOOLEAN

MAXIMUM_SCALE = NULL


NULLABLE = 1


PRECISION = 10

SEARCHABLE = 3




TYPE_NAME = Date




DATA_TYPE = 91 (DATE)


LITERAL_PREFIX = DATE '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = DATE




MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 10

SEARCHABLE = 3




TYPE_NAME = Integer




DATA_TYPE = 4 (INTEGER)




LOCAL_TYPE_NAME = INTEGER

MAXIMUM_SCALE = 0


NULLABLE = 1


PRECISION = 16777215

SEARCHABLE = 3




TYPE_NAME = JSON


CASE_SENSITIVE = true


DATA_TYPE = 12 (VARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = JSON



NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 16777215

SEARCHABLE = 0




TYPE_NAME = LongVarChar




DATA_TYPE = -1 (LONGVARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = LONGVARCHAR



Data types

MINIMUM_SCALE = 0

NULLABLE = 1


PRECISION = 23

SEARCHABLE = 3




TYPE_NAME = Timestamp




DATA_TYPE = 93 (TIMESTAMP)


LITERAL_PREFIX = TIMESTAMP'

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = TIMESTAMP

MAXIMUM_SCALE = 9


NULLABLE = 1


PRECISION = 32767

SEARCHABLE = 3




TYPE_NAME = VarChar




DATA_TYPE = 12 (VARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = VARCHAR


DataDirect ToolsProgress DataDirect for JDBC drivers install the set of tools described in this section. For detailed instructionson using these tools, refer to the corresponding topics in the Progress DataDirect for JDBC Drivers Referenceat the following links:

• DataDirect Test allows you to test your JDBC applications and learn the JDBC API.

• DataDirect Connection Pool Manager allows you to pool connections when accessing databases. Whenyour applications use connection pooling, connections are reused rather than created each time a connectionis requested. Because establishing a connection is among the most costly operations an application mayperform, using Connection Pool Manager to implement connection pooling can significantly improveperformance.

• Statement Pool Monitor loads statements into and remove statements from the statement pool as well asgenerate information to help you troubleshoot statement pooling performance.

• DataDirect Spy logs detailed information about calls your driver makes that can be used for troubleshooting.



https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/datadirect_test

https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/connection_pool

https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/statement_pool

https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/datadirect_spy

TroubleshootingThe Progress DataDirect for JDBC Drivers Reference provides information on troubleshooting problems shouldthey occur. Refer to Troubleshooting for details.

Contacting Technical SupportProgress DataDirect offers a variety of options to meet your support needs. Please visit our Web site for moredetails and for contact information:

https://www.progress.com/support

The Progress DataDirect Web site provides the latest support information through our global service network.The SupportLink program provides access to support contact details, tools, patches, and valuable information,including a list of FAQs for each product. In addition, you can search our Knowledgebase for technical bulletinsand other information.

When you contact us for assistance, please provide the following information:

• Your number or the serial number that corresponds to the product for which you are seeking support, or acase number if you have been provided one for your issue. If you do not have a SupportLink contract, theSupportLink representative assisting you will connect you with our Sales team.

• Your name, phone number, email address, and organization. For a first-time call, you may be asked for fullinformation, including location.

• The Progress DataDirect product and the version that you are using.

• The type and version of the operating system where you have installed your product.

• Any database, database version, third-party software, or other environment information required to understandthe problem.

• A brief description of the problem, including, but not limited to, any error messages you have received, whatsteps you followed prior to the initial occurrence of the problem, any trace logs capturing the issue, and soon. Depending on the complexity of the problem, you may be asked to submit an example or reproducibleapplication so that the issue can be re-created.

• A description of what you have attempted to resolve the issue. If you have researched your issue on Websearch engines, our Knowledgebase, or have tested additional configurations, applications, or other vendorproducts, you will want to carefully note everything you have already attempted.

• A simple assessment of how the severity of the issue is impacting your organization.


Troubleshooting

https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/troubleshooting

https://www.progress.com/support

2Using the Driver

This section provides information on how to connect to your data store using either the JDBC Driver Manageror DataDirect JDBC data sources, as well as information on how to implement and use functionality supportedby the driver.


• Required permissions for Java SE with the standard Security Manager enabled

• Connecting from an application

• Connecting through a proxy server

• IP addresses

• Performance considerations

• Data encryption

• Enabling Debug Record Mode

• Isolation levels

• SQL Escape Sequences

• Statement Pooling

• Connection Pooling


Required permissions for Java SE with the standardSecurity Manager enabled

Using the driver on a Java platform with the standard Security Manager enabled requires certain permissionsto be set in the Java SE security policy file java.policy. The default location of this file isjava_install_dir/jre/lib/security.

Note: Security manager may be enabled by default in certain scenarios, such as running on an applicationserver or in a Web browser applet.

To run an application on a Java platform with the standard Security Manager, use the following command:

"java -Djava.security.manager application_class_name"

where application_class_name is the class name of the application.

Refer to your Java documentation for more information about setting permissions in the security policy file.

Permissions for establishing connectionsTo establish a connection to the database server, the driver must be granted the permissions as shown in thefollowing example:

grant codeBase "file:/install_dir/lib/-" {permission java.net.SocketPermission "*", "connect";

};

where:

install_dir

is the product installation directory.

Granting access to Java propertiesTo allow the driver to read the value of various Java properties to perform certain operations, permissions mustbe granted as shown in the following example:

grant codeBase "file:/install_dir/lib/-" {permission java.util.PropertyPermission "*", "read, write";

};

where:

install_dir



Chapter 2: Using the Driver

Granting access to temporary filesAccess to the temporary directory specified by the JVM configuration must be granted in the Java SE securitypolicy file to use insensitive scrollable cursors or to perform client-side sorting of DatabaseMetaData resultsets. The following example shows permissions that have been granted for the C:\TEMP directory:

grant codeBase "file:/install_dir/lib/-" {// Permission to create and delete temporary files.// Adjust the temporary directory for your environment.

permission java.io.FilePermission "C:\\TEMP\\-", "read,write,delete";};

where:

install_dir


Connecting from an applicationAfter the driver has been installed and defined on your class path, you can connect from your application toyour data in either of the following ways.

• Using the JDBC DriverManager by specifying the connection URL in theDriverManager.getConnection() method.

• Creating a JDBC data source that can be accessed through the Java Naming Directory Interface (JNDI).

Setting the classpathThe driver must be defined on your CLASSPATH before you can connect. The CLASSPATH is the searchstring your Java Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver is not definedon your CLASSPATH, you will receive a class not found exception when trying to load the driver. Set yoursystem CLASSPATH to include the jira.jar file as shown, where install_dir is the path to your productinstallation directory.

install_dir/lib/jira.jar

Windows ExampleCLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\jira.jar

UNIX ExampleCLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/jira.jar


Connecting from an application

Connecting using the JDBC Driver ManagerOne way to connect to a Jira service is through the JDBC DriverManager using theDriverManager.getConnection()method. As the following example shows, this method specifies a stringcontaining a connection URL.

Connection conn = DriverManager.getConnection("jdbc:datadirect:jira:https://mycompany.atlassian.net;User=jsmith;Password=secret;");

Passing the connection URLAfter setting the CLASSPATH, the required connection information needs to be passed in the form of aconnection URL.

Connection URL SyntaxThe connection URL takes the following form:

jdbc:datadirect:jira:servername;User=username;Password=password_token;[property=value[;...]];

where:

servername

specifies the URL of the Jira service to which you want to issue requests. For example,http://mycompany.atlassian.net.

user

specifies the user name that is used to connect to the Jira service.

password_token

specifies the password or API token used to connect to your Jira service.

property=value

specifies connection property settings. Multiple properties are separated by a semi-colon.

Connection URL ExampleConnection conn = DriverManager.getConnection("jdbc:datadirect:jira:http://mycompany.atlassian.net;User=jsmith;Password=secret;");

See alsoServerName on page 65User on page 69Password on page 59Connection property descriptions on page 43



Testing the connectionYou can also use DataDirect Test™ to establish and test a DriverManager connection. The screen shots inthis section were taken on a Windows system.

Take the following steps to establish a connection.

1. Navigate to the installation directory. The default location is:

• Windows systems: Program Files\Progress\DataDirect\JDBC_60\testforjdbc

• UNIX and Linux systems: /opt/Progress/DataDirect/JDBC_60/testforjdbc

Note: For UNIX/Linux, if you do not have access to /opt, your home directory will be used in its place.

2. From the testforjdbc folder, run the platform-specific tool:

• testforjdbc.bat (on Windows systems)• testforjdbc.sh (on UNIX and Linux systems)

The Test for JDBC Tool window appears:

3. Click Press Here to Continue.

The main dialog appears:



4. From the menu bar, select Connection > Connect to DB.

The Select A Database dialog appears:

5. Select the appropriate database template from the Defined Databases field.

6. In the Database field, specify the ServerName for your Jira service.

For example:

jdbc:datadirect:jira:http://mycompany.atlassian.net

7. Enter values for the following fields.

• In the User Name field, enter your user ID used to access your Jira service.

• In the Password field, enter your password or API token used to access your Jira service.

8. Click Connect.



If the connection information is entered correctly, the JDBC/Database Outputwindow reports that a connectionhas been established. (If a connection is not established, the window reports an error.)

For more information on using DataDirect test, refer to DataDirect Test in the Progress DataDirect for JDBCDrivers Reference.

Connecting using data sourcesA JDBC data source is a Java object, specifically a DataSource object, that defines connection informationrequired for a JDBC driver to connect to the database. Each JDBC driver vendor provides their own data sourceimplementation for this purpose. A Progress DataDirect data source is Progress DataDirect’s implementationof a DataSource object that provides the connection information needed for the driver to connect to a database.

Because data sources work with the Java Naming Directory Interface (JNDI) naming service, data sourcescan be created andmanaged separately from the applications that use them. Because the connection informationis defined outside of the application, the effort to reconfigure your infrastructure when a change is made isminimized. For example, if the database is moved to another database server, the administrator need onlychange the relevant properties of the DataSource object. The applications using the database do not needto change because they only refer to the name of the data source.

How data sources are implementedData sources are implemented through a DataSource class. A data source class implements the followinginterfaces.

• javax.sql.DataSource

• javax.sql.ConnectionPoolDataSource (allows applications to use connection pooling)

For more information, refer to Connection Pool Manager in the Progress DataDirect for JDBCDrivers Reference.



https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/datadirect_test

https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/connection_pool

See alsoDriver and DataSource classes on page 11

Creating data sourcesThe following example files provide details on creating and using Progress DataDirect data sources with theJava Naming Directory Interface (JNDI), where install_dir is the product installation directory.

• install_dir/Examples/JNDI/JNDI_LDAP_Example.java can be used to create a JDBC data sourceand save it in your LDAP directory using the JNDI Provider for LDAP.

• install_dir/Examples/JNDI/JNDI_FILESYSTEM_Example.java can be used to create a JDBCdata source and save it in your local file system using the File System JNDI Provider.

See "Example data source" for an example data source definition for the example files.

To connect using a JNDI data source, the driver needs to access a JNDI data store to persist the data sourceinformation. For a JNDI file system implementation, you must download the File System Service Provider fromthe Oracle Technology Network Java SE Support downloads page, unzip the files to an appropriate location,and add the fscontext.jar and providerutil.jar files to your CLASSPATH. These steps are notrequired for LDAP implementations because the LDAP Service Provider has been included with Java SE sinceJava 2 SDK, v1.3.

Example data sourceTo configure a data source using the example files, you will need to create a data source definition. The contentrequired to create a data source definition is divided into three sections.

First, you will need to import the data source class. For example:

import com.ddtek.jdbcx.jira.JiraDataSource;

Next, you will need to set the values and define the data source. For example, the following definition containsthe minimum properties required to establish connection:

Note: Setting the password using a data source is generally not recommended. The data source persists allproperties, including the Password property, in clear text.

JiraDataSource mds = new JiraDataSource();mds.setDescription("My Jira Data Source");mds.setServerName("http://mycompany.atlassian.net");mds.setUser("jsmith");mds.setPassword("secret");

Finally, you will need to configure the example application to print out the data source attributes. Note that thiscode is specific to the driver and should only be used in the example application. For example, you would addthe following section for the minimum properties required to establish a connection:

if (ds instanceof JiraDataSource){JiraDataSource jmds = (JiraDataSource) ds;System.out.println("description=" + jmds.getDescription());System.out.println("servername=" + jmds.getServerName());System.out.println("user=" + jmds.getUser());System.out.println("password=" + jmds.getPassword());System.out.println();}



http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html#7110-jndi-1.2.1-oth-JPR

Calling a data source in an applicationApplications can call a Progress DataDirect data source using a logical name to retrieve thejavax.sql.DataSource object. This object loads the specified driver and can be used to establish aconnection to the database.

Once the data source has been registered with JNDI, it can be used by your JDBC application as shown in thefollowing code example.

Context ctx = new InitialContext();DataSource ds = (DataSource)ctx.lookup("EmployeeDB");Connection con = ds.getConnection("domino", "spark");

In this example, the JNDI environment is first initialized. Next, the initial naming context is used to find thelogical name of the data source (EmployeeDB). The Context.lookup() method returns a reference to aJava object, which is narrowed to a javax.sql.DataSource object. Then, theDataSource.getConnection() method is called to establish a connection.

Testing a data source connectionYou can use DataDirect Test™ to establish and test a data source connection. The screen shots in this sectionwere taken on a Windows system.

Take the following steps to establish a connection.

1. Navigate to the installation directory. The default location is:

• Windows systems: Program Files\Progress\DataDirect\JDBC_60\testforjdbc

• UNIX and Linux systems: /opt/Progress/DataDirect/JDBC_60/testforjdbc

Note: For UNIX/Linux, if you do not have access to /opt, your home directory will be used in its place.

2. From the testforjdbc folder, run the platform-specific tool:

• testforjdbc.bat (on Windows systems)• testforjdbc.sh (on UNIX and Linux systems)

The Test for JDBC Tool window appears:



3. Click Press Here to Continue.

The main dialog appears:

4. From the menu bar, select Connection > Connect to DB via Data Source.

The Select A Database dialog appears:



5. Select a datasource template from the Defined Datasources field.

6. Provide the following information:

a) In the Initial Context Factory, specify the location of the initial context provider for your application.

b) In the Context Provider URL, specify the location of the context provider for your application.

c) In the Datasource field, specify the name of your datasource.

7. If you are using user ID/password authentication, enter your user ID and password in the correspondingfields.

8. Click Connect.

If the connection information is entered correctly, the JDBC/Database Outputwindow reports that a connectionhas been established. If a connection is not established, the window reports an error.



Connecting through a proxy serverIn some environments, your application may need to connect through a proxy server, for example, if yourapplication accesses an external resource such as a Web service. At a minimum, your application needs toprovide the following connection information when you invoke the JVM if the application connects through aproxy server:

• Server name or IP address of the proxy server

• Port number on which the proxy server is listening for HTTP/HTTPS requests

In addition, if authentication is required, your application may need to provide a valid user ID and password forthe proxy server. Consult with your system administrator for the required information.

For example, the following command invokes the JVM while specifying a proxy server named pserver, a portof 8888, and provides a user ID and password for authentication:

java -Dhttp.proxyHost=pserver -Dhttp.proxyPort=8888 -Dhttp.proxyUser=smith-Dhttp.proxyPassword=secret -cp jira.jar com.acme.myapp.Main

Alternatively, you can use the ProxyHost, ProxyPort, ProxyUser, and ProxyPassword connection properties.See "Connection property descriptions" for details about these properties.

See alsoConnection property descriptions on page 43

IP addressesThe driver supports Internet Protocol (IP) addresses in IPv4 and IPv6 format.

The server name specified in the connection URL, or data source, can resolve to an IPv4 or IPv6 address. Forexample, the following URL can resolve to either type of address:

jdbc:datadirect:jira:http://mycompany.atlassian.net;User=jsmith;Password=secret;

Note: The server name specifies the base Jira URL to use for logging in, for example,http://mycompany.atlassian.net.

Alternately, you can specify addresses using IPv4 or IPv6 format in the server portion of the connection URL.For example, the following connection URL specifies the server using an IPv4 address:

jdbc:datadirect:jira://123.456.78.90;User=jsmith;Password=secret;

You also can specify addresses in either format using the ServerName data source property. The followingexample shows a data source definition that specifies the server name using IPv6 format:

JiraDataSource mds = new JiraDataSource();mds.setDescription("My Jira DataSource");mds.setServerName("[ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]");...



Note: When specifying IPv6 addresses in a connection URL or data source property, the address must beenclosed by brackets.

In addition to the normal IPv6 format, the drivers support IPv6 alternative formats for compressed and IPv4/IPv6combination addresses. For example, the following connection URL specifies the server using IPv6 format,but uses the compressed syntax for strings of zero bits:

jdbc:datadirect:jira://[2001:DB8:0:0:8:800:200C:417A];User=jsmith;Password=secret

Similarly, the following connection URL specifies the server using a combination of IPv4 and IPv6:

jdbc:datadirect:jira://[0000:0000:0000:0000:0000:FFFF:123.456.78.90];User=jsmith;Password=secret

For complete information about IPv6, go to the following URL:

http://tools.ietf.org/html/rfc4291#section-2.2

See alsoServerName on page 65

Performance considerationsInsensitiveResultSetBufferSize: To improve performance when using scroll-insensitive result sets, the drivercan cache the result set data in memory instead of writing it to disk. By default, the driver caches 2 MB ofinsensitive result set data in memory and writes any remaining result set data to disk. Performance can beimproved by increasing the amount of memory used by the driver before writing data to disk or by forcing thedriver to never write insensitive result set data to disk. The maximum cache size setting is 2 GB.

FetchSize/WSFetchSize: The connection options FetchSize and WSFetchSize can be used to adjust thetrade-off between throughput and response time. In general, setting larger values forWSFetchSize and FetchSizewill improve throughput, but can reduce response time.

For example, if an application attempts to fetch 100,000 rows from the remote data source and WSFetchSizeis set to 500, the driver must make 200 Web service calls to get the 100,000 rows. If, however, WSFetchSizeis set to 1000 (the maximum), the driver only needs to make 100 Web service calls to retrieve 100,000 rows.Web service calls are expensive, so generally, minimizing Web service calls increases throughput.

For many applications, throughput is the primary performance measure, but for interactive applications, suchasWeb applications, response time (how fast the first set of data is returned) is more important than throughput.For example, suppose that you have a Web application that displays data 50 rows to a page and that, onaverage, you view three or four pages. Response time can be improved by setting FetchSize to 50 (the numberof rows displayed on a page) and WSFetchSize to 200. With these settings, the driver fetches all of the rowsfrom the remote data source that you would typically view in a single Web service call and only processes therows needed to display the first page.

Note that the values specified for the WSFetchSize and FetchSize properties provide only a suggestion as tothe number of rows to be processed. Jira will not exceed these values, but it will adjust page sizes to balancethroughput amongst all its users. This behavior can result in different page sizes for successive queries.


Performance considerations

http://tools.ietf.org/html/rfc4291#section-2.2

ReadAhead: The ReadAhead property allows you to issue multiple fetch requests in parallel. By increasingthis number, you can improve throughput and performance, but it does so with the following restrictions:

• Larger values can increase the load on the server, which may adversely affect performance of other users.If you encounter issues, decrease the value specified for this option.

• Larger values may result in unnecessary requests if your application only requires the first few rows ofresults. This may be an issue if your service places limits on the number of web requests.

Caution: Due to potential impacts to other users, we strongly recommend specifying only smaller values forthe ReadAhead property. For example, in fully optimized environments, which include exceptionally fastconnections and low latency, we recommend a setting of no higher than 5. For typical environments, this valueis sometimes lower.

WSPoolSize: WSPoolSize determines the maximum number of sessions the driver uses when there aremultiple active connections. By increasing this number, you increase the number of sessions the driver usesto distribute calls to the Jira service, thereby improving throughput and performance. For example, if WSPoolSizeis set to 1, and you have two open connections, the session must complete a call from one connection beforeit can begin processing a call from the other connection. However, if WSPoolSize is equal to 2, a secondsession is opened that allows calls from both connections to be processed simultaneously.

Note: The number specified for WSPoolSize should not exceed the amount of sessions permitted by your Jiraservice.

Data encryptionThe driver supports Secure Sockets Layer (SSL) data encryption. SSL is an industry-standard protocol forsending encrypted data over database connections. SSL works by allowing the client and server to send eachother encrypted data that only they can decrypt. SSL negotiates the terms of the encryption in a sequence ofevents known as the SSL handshake. The handshake involves the following types of authentication:

• SSL server authentication requires the server to authenticate itself to the client.

• SSL client authentication is optional and requires the client to authenticate itself to the server after the serverhas authenticated itself to the client.

Configuring SSL encryptionSSL encryption is enabled when the URL specified by the ServerName property file uses HTTPS. The followingsteps outline how to configure SSL encryption.

Note: Connection hangs can occur when the driver is configured for SSL and the database server does notsupport SSL. You may want to set a login timeout using the LoginTimeout property to avoid problems whenconnecting to a server that does not support SSL.

To configure SSL encryption:



1. Use the CryptoProtocolVersion property to specify acceptable cryptographic protocol versions (for example,TLSv1.2) supported by your server.

2. Specify the location and password of the truststore file used for SSL server authentication. Either set theTrustStore and TrustStorePassword properties or their corresponding Java system properties(javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword, respectively).

3. To validate certificates sent by the database server, set the ValidateServerCertificate property to true.

4. Optionally, set the HostNameInCertificate property to a host name to be used to validate the certificate. TheHostNameInCertificate property provides additional security against man-in-the-middle (MITM) attacks byensuring that the server the driver is connecting to is the server that was requested.

5. If your database server is configured for SSL client authentication, configure your keystore information:

a) Specify the location and password of the keystore file. Either set the KeyStore and KeyStorePasswordproperties or their corresponding Java system properties (javax.net.ssl.keyStore andjavax.net.ssl.keyStorePassword, respectively).

b) If any key entry in the keystore file is password-protected, set the KeyPassword property to the keypassword.

See alsoServerName on page 65CryptoProtocolVersion on page 48TrustStore on page 68TrustStorePassword on page 69ValidateServerCertificate on page 70KeyStore on page 55KeyStorePassword on page 56KeyPassword on page 55

Configuring SSL server authenticationWhen the client makes a connection request, the server presents its public certificate for the client to acceptor deny. The client checks the issuer of the certificate against a list of trusted Certificate Authorities (CAs) thatresides in an encrypted file on the client known as a truststore. Optionally, the client may check the subject(owner) of the certificate. If the certificate matches a trusted CA in the truststore (and the certificate’s subjectmatches the value that the application expects), an encrypted connection is established between the client andserver. If the certificate does not match, the connection fails and the driver throws an exception.

To check the issuer of the certificate against the contents of the truststore, the driver must be able to locatethe truststore and unlock the truststore with the appropriate password. You can specify truststore informationin either of the following ways:

• Specify values for the Java system properties javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword.For example:

java -Djavax.net.ssl.trustStore=C:\Certificates\MyTruststore-Djavax.net.ssl.trustStorePassword=MyTruststorePassword

This method sets values for all SSL sockets created in the JVM.

• Specify values for the connection properties TrustStore and TrustStorePassword in the connection URL.For example:

TrustStore=C:\Certficates\MyTruststore


Data encryption

and

TrustStorePassword=MyTruststorePassword

Any values specified by the TrustStore and TrustStorePassword properties override values specified by theJava system properties. This allows you to choose which truststore file you want to use for a particularconnection.

Alternatively, you can configure the drivers to trust any certificate sent by the server, even if the issuer is nota trusted CA. Allowing a driver to trust any certificate sent from the server is useful in test environments becauseit eliminates the need to specify truststore information on each client in the test environment. If the driver isconfigured to trust any certificate sent from the server, the issuer information in the certificate is ignored.

See alsoTrustStore on page 68TrustStorePassword on page 69

Configuring SSL client authenticationIf the server is configured for SSL client authentication, the server asks the client to verify its identity after theserver has proved its identity. Similar to SSL server authentication, the client sends a public certificate to theserver to accept or deny. The client stores its public certificate in an encrypted file known as a keystore.

The driver must be able to locate the keystore and unlock the keystore with the appropriate keystore password.Depending on the type of keystore used, the driver also may need to unlock the keystore entry with a passwordto gain access to the certificate and its private key.

The drivers can use the following types of keystores:

• Java Keystore (JKS) contains a collection of certificates. Each entry is identified by an alias. The value ofeach entry is a certificate and the certificate’s private key. Each keystore entry can have the same passwordas the keystore password or a different password. If a keystore entry has a password different than thekeystore password, the driver must provide this password to unlock the entry and gain access to the certificateand its private key.

• PKCS #12 keystores. To gain access to the certificate and its private key, the driver must provide thekeystore password. The file extension of the keystore must be .pfx or .p12.

You can specify this information in either of the following ways:

• Specify values for the Java system properties javax.net.ssl.keyStore and javax.net.ssl.keyStorePassword.For example:

java -Djavax.net.ssl.keyStore=C:\Certificates\MyKeystore-Djavax.net.ssl.keyStorePassword=MyKeystorePassword

This method sets values for all SSL sockets created in the JVM.

Note: If the keystore specified by the javax.net.ssl.keyStore Java system property is a JKS and the keystoreentry has a password different than the keystore password, the KeyPassword connection property must specifythe password of the keystore entry (for example, KeyPassword=MyKeyPassword).

• Specify values for the connection properties KeyStore and KeyStorePassword in the connection URL. Forexample:

KeyStore=C:\Certficates\MyKeyStore

and



KeyStorePassword=MyKeystorePassword

Note: If the keystore specified by the KeyStore connection property is a JKS and the keystore entry has apassword different than the keystore password, the KeyPassword connection property must specify the passwordof the keystore entry (for example, KeyPassword=MyKeyPassword).

Any values specified by the KeyStore and KeyStorePassword properties override values specified by the Javasystem properties. This allows you to choose which keystore file you want to use for a particular connection.

See alsoKeyStore on page 55KeyStorePassword on page 56KeyPassword on page 55

Enabling Debug Record ModeThe driver supports a debug record mode that provides a method for troubleshooting issues that occur whenaccessing data from a Jira service. When Debug Record Mode is enabled, the driver captures and recordsserver requests and responses to a set of files stored in a designated location. Technical Support can thenuse these files to analyze and reproduce the issue without requiring access to your private data source.

To generate debug record files:

1. Using the DebugRecord property, specify the location where the driver will generate the files used to recordserver requests and responses.

2. Start the JDBC application and reproduce the issue.

3. Stop the application.

The driver generates a set of files containing the server requests and responses that occurred during thesession. After generating the debug files, you can remove the location specified for the DebugRecord property.If you do not remove this value, the driver will overwrite debug files in the specified location the next time youstart the application.

Contact Technical Support for assistance analyzing the files and reproducing the issue.

Important: Debug record files may capture security-related headers, such as auth or token headers. Beforesending Technical Support debug files, review the content to remove any confidential information that mayhave been recorded.

See alsoDebugRecord on page 49

Isolation levelsBecause transactions are not supported, the Jira driver supports only the TRANSACTION_NONE isolationlevel.


Enabling Debug Record Mode

SQL Escape SequencesThe driver supports the following SQL escape sequences.

• Date, Time, and Timestamp Escape Sequences

• Scalar Functions

• Outer Join Escape Sequences

• LIKE Escape Character Sequence for Wildcards

Refer to SQL Escape Sequences for JDBC in theProgress DataDirect for JDBCDrivers Reference for informationabout SQL escape sequences supported by the driver.

Supported Scalar FunctionsThe driver supports the scalar functions in the following table. Note that your database system may not supportall these functions. Refer to the documentation for your database system to find out which functions aresupported by your database.

In addition, you can also determine the supported scalar functions by using DatabaseMetaData methods.

You can use scalar functions in SQL statements with the following syntax:

{fn scalar-function}

where:

scalar-function

is a scalar function supported by the drivers, as listed in the following table.

Example:

SELECT id, name FROM emp WHERE name LIKE {fn UCASE('Smith')}

For descriptions of scalar functions, refer to Scalar Functions in the Progress DataDirect for JDBC DriversReference.

Table 6: Supported Scalar Functions

System FunctionsTimedate FunctionsNumericFunctions

String Functions

CURSESSIONIDCURDATEABSASCII

DATABASECURRENT_DATEACOSBIT_LENGTH

IDENTITYCURRENT_TIMEASINCHAR

USERCURRENT_TIMESTAMPATANCHAR_LENGTH

CURTIMEATAN2CHARACTER_LENGTH

DATEDIFFBITANDCONCAT



https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/sql_escapes

https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/scalar_functions

System FunctionsTimedate FunctionsNumericFunctions

String Functions

DATE_ADDBITORDIFFERENCE

DATE_SUBBITXORHEXTORAW

DAYCEILINGINSERT

DAYNAMECOSLCASE

DAYOFMONTHCOTLEFT

DAYOFWEEKDEGREESLENGTH

DAYOFYEAREXPLOCATE

EXTRACTFLOORLOCATE_2

HOURLOGLOWER

MINUTELOG10LTRIM

MONTHMODOCTET_LENGTH

MONTHNAMEPIRAWTOHEX

NOWPOWERREPEAT

QUARTERRADIANSREPLACE

SECONDRANDRIGHT

SECONDS_SINCE_MIDNIGHTROUNDRTRIM

TIMESTAMPADDROUNDMAGICSOUNDEX

TIMESTAMPDIFFSIGNSPACE

TO_CHARSINSUBSTR

WEEKSQRTSUBSTRING

YEARTANUCASE

TRUNCATEUPPER


SQL Escape Sequences

Statement PoolingMost applications have a certain set of SQL statements that are executed multiple times and a few SQLstatements that are executed only once or twice during the life of the application. Similar to connection pooling,statement pooling provides performance gains for applications that execute the same SQL statements multipletimes over the life of the application.

A statement pool is a group of prepared statements that can be reused by an application. If you have anapplication that repeatedly executes the exact same SQL statements, statement pooling can improveperformance because the database server does not have to repeatedly parse and create cursors for the samestatement. In addition, the associated network round trips to the database server are avoided.

The drivers have an internal prepared statement poolingmechanism, which allows you to realize the performancebenefits of statement pooling when you are not running from within an application server or another applicationthat provides its own statement pooling. You can enable this driver-based internal statement pooling with theMaxPooledStatements connection property.

The DataDirect for JDBC drivers also support the DataDirect Statement Pool Monitor. You can use the StatementPool Monitor to load statements into and remove statements from the statement pool as well as generateinformation to help you troubleshoot statement pooling performance. The Statement Pool Monitor is an integratedcomponent of the driver, and you can manage statement pooling directly with DataDirect-specific methods. Inaddition, the Statement Pool Monitor can be enabled as a Java Management Extensions (JMX) MBean. Whenenabled as a JMXMBean, the Statement Pool Monitor can be used to manage statement pooling with standardJMX API calls, and it can easily be used by JMX-compliant tools, such as JConsole. To enable the StatementPool Monitor as a JMX MBean, you must register the Statement Pool Monitor MBean with theRegisterStatementPoolMonitorMBean connection property.

For more information, refer to Statement Pool Monitor in the Progress DataDirect for JDBC Drivers Reference.

See alsoMaxPooledStatements on page 58RegisterStatementPoolMonitorMBean on page 64

Connection PoolingProgess DataDirect for JDBC drivers support connection pooling using the DataDirect Connection Pool Manager.Typically, creating a connection is the most performance-expensive operations that an application performs.Connection pooling allows you to reuse connections rather than create a new one every time a driver needsto connect to the database. Further, connection pooling manages connection sharing across multiple userrequests to maintain performance and reduce the number of new connections to be created.

JDBC support in the Progress DataDirect for JDBC Drivers Reference guides you through using connectionpooling with the DataDirect Connection Pool Manager.




https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/jdbc_support

3Connection property descriptions

You can use connection properties to customize the driver for your environment. This section lists the connectionproperties supported by the driver and describes each property. You can use these connection properties witheither the JDBC DriverManager or a JDBC DataSource. For a DriverManager connection, a property isexpressed as a key value pair and takes the form property=value. For a data source connection, a propertyis expressed as a JDBC method and takes the form setproperty(value). Connection property names arecase-insensitive. For example, Password is the same as password.

Note: In a JDBC DataSource, string values must be enclosed in double quotation marks, for example,setUser("[email protected]").

Note: The data type listed for each connection property is the Java data type used for the property value in aJDBC data source.

The following tables provide a summary of supported connection properties by functionality, including theircorresponding data source methods, and their default values.

Required propertiesThe following table summarizes connection properties which are required to connect to a Jira data source.

Table 7: Required Properties

DefaultData Source MethodProperty

NonesetServerNameServerName on page 65



NonesetPasswordPassword on page 59

NonesetUserUser on page 69

Data encryption propertiesThe following table summarizes connection properties which can be used to enable SSL.

Table 8: Data Encryption Properties


NonesetCryptoProtocolVersionCryptoProtocolVersion on page48

NonesetKeyPasswordKeyPassword on page 55

NonesetKeyStoreKeyStore on page 55

NonesetKeyStorePasswordKeyStorePassword on page 56

NonesetHostNameInCertificateHostNameInCertificate on page51

NonesetTrustStoreTrustStore on page 68

NonesetTrustStorePasswordTrustStorePassword on page 69

truesetValidateServerCertificateValidateServerCertificate on page70

Proxy server propertiesThe following table summarizes proxy server connection properties.

Table 9: Proxy Server Properties


Empty stringsetProxyHostProxyHost on page 61

Empty stringsetProxyPasswordProxyPassword on page 61

0setProxyPortProxyPort on page 62

Empty stringsetProxyUserProxyUser on page 62

Web service propertiesThe following table summarizes Web service connection properties, including those related to timeouts.


Chapter 3: Connection property descriptions

Table 10: Web Service Properties


0 (no timeout)setLoginTimeoutLoginTimeout on page 58

0 (no limit)setStmtCallLimitStmtCallLimit on page 66

errorAlwayssetStmtCallLimitBehaviorStmtCallLimitBehavior on page67

0 (maximum of 1000 rows)setWSFetchSizeWSFetchSize on page 71

1setWSPoolSizeWSPoolSize on page 72

5setWSRetryCountWSRetryCount on page 73

120 (seconds)setWSTimeoutWSTimeout on page 74

Data type propertiesThe following table summarizes connection properties which can be used to handle data types.

Table 11: Data Type Properties


1 (data type check is performedif column value is null)

setConvertNullConvertNull on page 47

1 (data types described usingJDBC 3.0-equivalent data types)

setJDBCBehaviorJDBCBehavior on page 54

Timeout propertiesThe following table summarizes timeout connection properties.

Table 12: Timeout Properties


0 (no timeout)setLoginTimeoutLoginTimeout on page 58

0 (no retries for timed-outrequests)

setWSRetryCountWSRetryCount on page 73

120 (seconds)setWSTimeoutWSTimeout on page 74

Statement pooling propertiesThe following table summarizes statement pooling connection properties.


Table 13: Statement Pooling Properties


Empty stringsetImportStatementPoolImportStatementPool on page 52

0 (driver’s internal preparedstatement pooling is not enabled)

setMaxPooledStatementsMaxPooledStatements on page58

falsesetRegisterStatementPoolMonitorMBeanRegisterStatementPoolMonitorMBeanon page 64

Additional propertiesThe following table summarizes additional connection properties.

Table 14: Additional Properties


NonesetDebugRecordDebugRecord on page 49

100 (rows)setFetchSizeFetchSize on page 50

2048 (KB of memory)setInsensitiveResultSetBufferSizeInsensitiveResultSetBufferSize onpage 53

ddlogging.propertiessetLogConfigFileLogConfigFile on page 57

For http connections:80

For https connections:

443

setPortNumberPortNumber on page 60

0setReadAheadReadAhead on page 63

NonesetSpyAttributesSpyAttributes on page 66


• ConvertNull

• CryptoProtocolVersion

• DebugRecord

• FetchSize

• HostNameInCertificate

• ImportStatementPool

• InsensitiveResultSetBufferSize



• JDBCBehavior

• KeyPassword

• KeyStore

• KeyStorePassword

• LogConfigFile

• LoginTimeout

• MaxPooledStatements

• Password

• PortNumber

• ProxyHost

• ProxyPassword

• ProxyPort

• ProxyUser

• ReadAhead

• RegisterStatementPoolMonitorMBean

• ServerName

• SpyAttributes

• StmtCallLimit

• StmtCallLimitBehavior

• TrustStore

• TrustStorePassword

• User

• ValidateServerCertificate

• WSFetchSize

• WSPoolSize

• WSRetryCount

• WSTimeout

ConvertNullPurposeControls how data conversions are handled for null values.


ConvertNull

Valid Values0 | 1

BehaviorIf set to 0, the driver does not perform the data type check if the value of the column is null. This allows nullvalues to be returned even though a conversion between the requested type and the column type is undefined.

If set to 1, the driver checks the data type being requested against the data type of the table column that storesthe data. If a conversion between the requested type and column type is not defined, the driver generates an"unsupported data conversion" exception regardless of whether the column value is NULL.

Data Source MethodsetConvertNull

Default1

Data Typeint

See AlsoAdditional properties

CryptoProtocolVersionPurposeSpecifies a comma-separated list of the cryptographic protocols to use when accessing an HTTPS endpoint.When multiple protocols are specified, the driver uses the highest version supported by the server.

Valid Valuescryptographic_protocol [[, cryptographic_protocol ]...]

where:

cryptographic_protocol

is one of the following cryptographic protocols:

TLSv1.2 | TLSv1.1 | TLSv1 | SSLv3 | SSLv2

Caution: To avoid vulnerabilities associated with SSLv3 and SSLv2, good security practices recommendusing TLSv1 or higher.



ExampleIf your server supports TLSv1.1 and TLSv1.2, you can specify acceptable cryptographic protocols with thefollowing key-value pair:

CryptoProtocolVersion=TLSv1.1,TLSv1.2

Notes• When multiple protocols are specified, the driver uses the highest version supported by the server. If none

of the specified protocols are supported by the server, the connection fails and the driver returns an error.

• When no value has been specified for CryptoProtocolVersion, the cryptographic protocol used depends onthe highest protocol version supported by the server and the highest protocol version supported by the JDK.The driver uses the lower version of these two protocols to establish the SSL connection. Refer to the Jiradocumentation or contact your system administrator for information on which cryptographic protocols aresupported.

Data Source MethodsetCryptoProtocolVersion

DefaultNone

Data TypeString

See Also• Data encryption on page 36

• Data encryption properties

DebugRecordPurposeSpecifies the directory where the driver generates debug record files. When a value is specified, the driverrecords server requests and responses to set of files stored in this location. These files assist in troubleshootingby providing a method for Technical Support to reproduce and debug issues for Jira services.

Important: Debug record files may capture security-related headers, such as auth or token headers. Beforesending Technical Support debug files, review the content to remove any confidential information that mayhave been recorded.

Valid Valuesdebug_record_folder

where:


DebugRecord

debug_record_folder

is the location of the folder where the debeg record files are to be generated. For example,C:/Temp/MyDebug Folder.

Notes• You must have write access to the specified directory.

• Contact Technical Support for more information.

Data Source MethodsetDebugRecord

DefaultNone

See Also• Contacting Technical Support on page 21

• Enabling Debug Record Mode on page 39

FetchSizePurposeSpecifies the maximum number of rows that the driver processes before returning data to the application whenexecuting a Select. This value provides a suggestion to the driver as to the number of rows it should internallyprocess before returning control to the application. The driver may fetch fewer rows to conserve memory whenprocessing exceptionally wide rows.

Valid Values0 | x

where:

x

is a positive integer indicating the number of rows that should be processed.

BehaviorIf set to 0, the driver processes all the rows of the result before returning control to the application. When largedata sets are being processed, setting FetchSize to 0 can diminish performance and increase the likelihoodof out-of-memory errors.

If set to x, the driver limits the number of rows that may be processed for each fetch request before returningcontrol to the application.



Notes• To optimize throughput and conserve memory, the driver uses an internal algorithm to determine how many

rows should be processed based on the width of rows in the result set. Therefore, the driver may processfewer rows than specified by FetchSize when the result set contains exceptionally wide rows. Alternatively,the driver processes the number of rows specified by FetchSize when the result set contains rows ofunexceptional width.

• FetchSize and WSFetchSize can be used to adjust the trade-off between throughput and response time.Smaller fetch sizes can improve the initial response time of the query. Larger fetch sizes can improve overallresponse times at the cost of additional memory.

• The values specified for the WSFetchSize and FetchSize properties provide only a suggestion as to thenumber of rows to be processed. Jira will not exceed these values, but it will adjust page sizes to balancethroughput amongst all its users. This behavior can result in different page sizes for successive queries.

• You can use FetchSize to reduce demands onmemory and decrease the likelihood of out-of-memory errors.Simply, decrease FetchSize to reduce the number of rows the driver is required to process before returningdata to the application.

Data Source MethodsetFetchSize

Default100 (rows)

Data TypeInt

See Also• Additional properties

• Performance considerations on page 35

HostNameInCertificatePurposeA host name for certificate validation when accessing an HTTPS endpoint and validation is enabled (ValidateServer Certificate=1). This property is optional and provides additional security against man-in-the-middle(MITM) attacks by ensuring that the server the driver is connecting to is the server that was requested.

Valid valueshost_name

where:

host_name

is a valid host name.


HostNameInCertificate

BehaviorIf host_name is specified, the driver compares the specified host name to the DNSName value of theSubjectAlternativeName in the certificate. If a DNSName value does not exist in the SubjectAlternativeNameor if the certificate does not have a SubjectAlternativeName, the driver compares the host name with theCommon Name (CN) part of the certificate’s Subject name. If the values do not match, the connection fails andthe driver throws an exception.

Notes• If the HostNameInCertificate is not specified, the driver automatically uses the value of the ServerName

from the URL as the value for validating the certificate.

• If SSL encryption or certificate validation is not enabled, this property is ignored.

• If SSL encryption and validation is enabled and this property is unspecified, the driver uses the server namethat is specified in the connection URL or data source of the connection to validate the certificate.

Data source methodsetHostNameInCertificate

DefaultEmpty string

Data typeString

See also• Data encryption on page 36

• ValidateServerCertificate on page 70


ImportStatementPoolPurposeSpecifies the path and file name of the file to be used to load the contents of the statement pool. When thisproperty is specified, statements are imported into the statement pool from the specified file.

If the driver cannot locate the specified file when establishing the connection, the connection fails and the driverthrows an exception. See "Importing statements into a statement pool" for details about the import file.

Valid Valuesstring

where:

string

is the path and file name of the file to be used to load the contents of the statement pool.



Data Source MethodsetImportStatementPool

Defaultempty string

Data TypeString

See Also• Importing statements into a statement pool in the Progress DataDirect for JDBC Drivers Reference

• Statement pooling properties

InsensitiveResultSetBufferSizePurposeDetermines the amount of memory that is used by the driver to cache insensitive result set data.

Valid Values-1 | 0 | x

where:

x

is a positive integer that represents the amount of memory.

BehaviorIf set to -1, the driver caches insensitive result set data in memory. If the size of the result set exceeds availablememory, an OutOfMemoryException is generated. With no need to write result set data to disk, the driverprocesses the data efficiently.

If set to 0, the driver caches insensitive result set data in memory, up to a maximum of 2 MB. If the size of theresult set data exceeds available memory, then the driver pages the result set data to disk, which can have anegative performance effect. Because result set data may be written to disk, the driver may have to reformatthe data to write it correctly to disk.

If set to x, the driver caches insensitive result set data in memory and uses this value to set the size (in KB) ofthe memory buffer for caching insensitive result set data. If the size of the result set data exceeds availablememory, then the driver pages the result set data to disk, which can have a negative performance effect.Because the result set data may be written to disk, the driver may have to reformat the data to write it correctlyto disk. Specifying a buffer size that is a power of 2 results in efficient memory use.

Data Source MethodsetInsensitiveResultSetBufferSize


InsensitiveResultSetBufferSize

https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/importing_statement_pool

Default2048

Data Typeint

See also• Additional properties


JDBCBehaviorPurposeDetermines how the driver describes native data types that map to the following JDBC 4.0 data types: NCHAR,NVARCHAR, NLONGVARCHAR, NCLOB, and SQLXML.

Valid Values0 | 1

BehaviorIf set to 0, the driver describes the data types as JDBC 4.0 data types.

If set to 1, the driver describes the data types using JDBC 3.0-equivalent data types, regardless of JVM. Thisallows your application to continue using JDBC 3.0 types in a Java SE 8 or higher environment.

Data Source MethodsetJDBCBehavior

Default1

Data Typeint

See Also• Data type properties



KeyPasswordPurposeSpecifies the password that is used to access the individual keys in the keystore file when accessing an HTTPSendpoint and SSL client authentication is enabled on the server. This property is useful when individual keysin the keystore file have a different password than the keystore file.

Valid Valuesstring

where:

string

is a valid password.

Data Source MethodsetKeyPassword

DefaultNone

Data TypeString

See Also• Data encryption properties

KeyStorePurposeSpecifies the directory of the keystore file to be used when accessing an HTTPS endpoint and SSL clientauthentication is enabled for the server. The keystore file contains the certificates that the client sends to theserver in response to the server’s certificate request.

This value overrides the directory of the keystore file that is specified by the javax.net.ssl.keyStore Java systemproperty. If this property is not specified, the keystore directory is specified by the javax.net.ssl.keyStore Javasystem property.

Valid Valuesstring

where:


KeyPassword

string

is a valid directory of a keystore file.

Notes• The keystore and truststore files can be the same file.

Data Source MethodsetKeyStore

DefaultNone

Data TypeString


KeyStorePasswordPurposeSpecifies the password that is used to access the keystore file when accessing an HTTPS endpoint and SSLclient authentication is enabled on the server. The keystore file contains the certificates that the client sendsto the server in response to the server’s certificate request.

This value overrides the password of the keystore file that is specified by the javax.net.ssl.keyStorePasswordJava system property. If this property is not specified, the keystore password is specified by thejavax.net.ssl.keyStorePassword Java system property.

Valid Valuesstring

where:

string

is a valid password.

Notes• The keystore and truststore files can be the same file.

Data Source MethodsetKeyStorePassword



DefaultNone

Data TypeString


LogConfigFilePurposeSpecifies the file name, and optionally, the path of the properties file used to initialize driver logging.

Valid Valuesstring

where:

string

is the relative or fully qualified path of the properties file to load to initialize driver logging. If you donot specify a path, the driver looks for this file in the current working directory. If the specified filedoes not exist, the driver continues searching for an appropriate properties file as described in "UsingJava logging."

Data Source MethodsetLogConfigFile

Defaultddlogging.properties

Data TypeString

See Also• Using Java Logging in the Progress DataDirect for JDBC Drivers Reference


LogConfigFile

https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/java_logging

LoginTimeoutPurposeThe amount of time, in seconds, that the driver waits for a connection to be established before timing out theconnection request.

Valid Values0 | x

where:

x

is a positive integer that represents a number of seconds.

BehaviorIf set to 0, the driver does not time out a connection request.

If set to x, the driver waits for the specified number of seconds before returning control to the application andthrowing a timeout exception.

Data Source MethodsetLoginTimeout

Default0

Data Typeint

See Also• Timeout properties

MaxPooledStatementsPurposeThe maximum number of pooled prepared statements for this connection. Setting MaxStatements to an integergreater than zero (0) enables the driver’s internal prepared statement pooling, which is useful when the driveris not running from within an application server or another application that provides its own prepared statementpooling.

Valid Values0 | x



where

x

is a positive integer that represents a number of pooled prepared statements.

BehaviorIf set to 0, the driver’s internal prepared statement pooling is not enabled.

If set to x, the driver enables the DataDirect Statement Pool and uses the specified value to cache a certainnumber of prepared statements created by an application. If the value set for this property is greater than thenumber of prepared statements that are used by the application, all prepared statements that are created bythe application are cached. Because CallableStatement is a sub-class of PreparedStatement, CallableStatementsalso are cached.

ExampleIf the value of this property is set to 20, the driver caches the last 20 prepared statements that are created bythe application.

Data Source MethodsetMaxPooledStatements

Default0

Data Typeint

See Also• Statement pooling properties

PasswordDescriptionSpecifies the password or API token used to connect to your Jira service.

Important: Setting the password property using a data source is not recommended. The data source persistsall properties, including the Password property, in clear text.

Valid Valuespassword_token

where:

password_token

is a valid password or API token. The password is case-sensitive.


Password

Notes• For information on generating a token, refer to the Jira documentation.

Data Source MethodsetPassword

DefaultNone

Data TypeString

See Also• Required properties

PortNumberPurposeSpecifies the TCP port of the primary REST service server that is listening for connections.

Valid valuesport

where:

port

is the port number.

Data source methodsetPortNumber

DefaultFor HTTP connections:

80

For HTTPS connections:

443

Data typeInt




https://www.progress.com/jdbc/release-history/

ProxyHostDescriptionIdentifies a proxy server to use for the first connection.

Valid Valuesserver_name | IP_address

where:

server_name

is the name of the proxy server, which may be qualified with the domain name.

IP_address

is an IP address, specified in either IPv4 or IPv6 format, or a combination of the two. See "Using IPaddresses" for details about using these formats.

Data Source MethodsetProxyHost

DefaultEmpty string

See Also• IP addresses on page 34

• Connecting through a proxy server on page 34

• Proxy server properties

ProxyPasswordPurposeSpecifies the password needed to connect to a proxy server for the first connection.

Valid Valuespassword

where:

password

is a valid password for that server. Contact your system administrator to obtain a valid password.


ProxyHost

Data Source MethodsetProxyPassword

DefaultEmpty string

See Also• Connecting through a proxy server on page 34


ProxyPortPurposeSpecifies the port number where the proxy server is listening for HTTP or HTTPS requests for the first connection.

Valid Valuesport

where:

port

is the port number on which the proxy server is listening. Contact your system administrator to obtainthe correct port.

Data Source MethodsetProxyPort

Default0



ProxyUserPurposeSpecifies the specifies the user name needed to connect to a proxy server for the first connection.



Valid Valuesuser_name

where:

user_name

is a valid user ID for the proxy server.

Data Source MethodsetProxyUser

DefaultEmpty string



ReadAheadPurposeSpecifies the maximum number of fetch requests the driver issues in parallel. By default, the driver queues thenext page when processing the current page. This option allows you to fetch multiple requests simultaneously,thereby improving throughput and performance.

Caution: Due to potential impacts to other users on the network, we strongly recommend specifying onlysmaller values for this option. For example, in fully optimized environments, which include exceptionally fastconnections and low latency, we recommend a setting of no higher than 5. For typical environments, this valueis sometimes lower.

Valid Values0 | x

where:

x

is the maximum number of fetch requests the driver issues in parallel.

BehaviorIf set to 0, the driver queues the next page while processing the current page.

If set to x, the driver executes fetch requests as they are issued until the number of active parallel-requestsequals the specified value. When that threshold is met, the driver waits until a the results of a request areprocessed before requesting the next page of data.


ReadAhead

Notes• Specifying larger values for this option generally improves performance; however, with the following warnings:

• Larger values can increase the load on the server, which may adversely affect performance of otherusers. If you encounter issues, decrease the value specified for this option.

• Larger values may result in unnecessary requests if your application only requires the first few rows ofresults. This may force the Jira sever to use smaller page sizes, thereby negating the benefits.

Data Source MethodsetReadAhead

Default0

Data Typeint


RegisterStatementPoolMonitorMBeanPurposeRegisters the Statement Pool Monitor as a JMX MBean when statement pooling has been enabled withMaxPooledStatements. This allows you to manage statement pooling with standard JMX API calls and to useJMX-compliant tools, such as JConsole.

Valid Valuestrue | false

BehaviorIf set to true, the driver registers an MBean for the statement pool monitor for each statement pool. This givesapplications access to the Statement Pool Monitor through JMX when statement pooling is enabled.

If set to false, the driver does not register an MBean for the Statement Pool Monitor for any statement pool.

NotesRegistering the MBean exports a reference to the Statement Pool Monitor. The exported reference can preventgarbage collection on connections if the connections are not properly closed. When garbage collection doesnot take place on these connections, out of memory errors can occur.

Data Source MethodsetRegisterStatementPoolMonitorMBean



Defaultfalse

Data TypeBoolean

See Also• Statement Pool Monitor in the Progress DataDirect for JDBC Drivers Reference

• Statement pooling properties

• MaxPooledStatements on page 58

ServerNamePurposeSpecifies the base URL of the Jira service to which you want to issue requests.

Valid Valuesstring

where:

string

specifies the URL of the Jira service to which you want to issue requests. For example,https://mycompany.atlassian.net.

Notes• Specifying an HTTPS URL for this property enables data encryption. See "Data Encryption" for details.

Data Source MethodsetServerName

DefaultNone

Data TypeString

See Also• Data encryption on page 36

• Required properties


ServerName


SpyAttributesPurposeEnables DataDirect Spy to log detailed information about calls issued by the driver on behalf of the application.DataDirect Spy is not enabled by default.

Valid Values(spy_attribute[;spy_attribute]...)

where:

spy_attribute

is any valid DataDirect Spy attribute.

Refer to "Tracking JDBC Calls with DataDirect Spy" for a list of supported attributes.

Notes• If coding a path on Windows to the log file in a Java string, the backslash character (\) must be preceded

by the Java escape character, a backslash. For example: log=(file)C:\\temp\\spy.log.

ExampleThe following value instructs the driver to log all JDBC activity to a file using a maximum of 80 characters foreach line.

(log=(file)/tmp/spy.log;linelimit=80)

Data Source MethodsetSpyAttributes

DefaultNone

See Also• Tracking JDBC calls with DataDirect Spy in the Progress DataDirect for JDBC Drivers Reference

• Additional properties

StmtCallLimitPurposeSpecifies the maximum number of Web service calls the driver can make when executing any single SQLstatement or metadata query.



https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/datadirect_spy

Valid Values0 | x

where:

x

is a positive integer that defines the maximum number of Web service calls the driver can makewhen executing any single SQL statement or metadata query.

BehaviorIf set to 0, there is no limit.

If set to x, the driver uses this value to set the maximum number of Web service calls on a single connectionthat can be made when executing a SQL statement. This limit can be overridden by changing theSTMT_CALL_LIMIT session attribute using the ALTER SESSION statement. For example, the followingstatement sets the statement call limit to 10 Web service calls:

ALTER SESSION SET STMT_CALL_LIMIT=10

If the Web service call limit is exceeded, the behavior of the driver depends on the value specified for theStmtCallLimitBehavior property.

Data Source MethodsetStmtCallLimit

Default0 (No limit)

Data Typeint

See Also• Web service properties

StmtCallLimitBehaviorPurposeSpecifies the behavior of the driver when the maximum Web service call limit specified by the StmtCallLimitproperty is exceeded.

Valid ValueserrorAlways | returnResults

BehaviorIf set to errorAlways, the driver generates an exception if the maximum Web service call limit is exceed.


StmtCallLimitBehavior

If set to returnResults, the driver returns any partial results it received prior to the call limit being exceeded.The driver generates a warning that not all of the results were fetched.

Data Source MethodsetStmtCallLimitBehavior

DefaulterrorAlways

Data TypeString


TrustStorePurposeThe directory that contains the truststore file and the truststore file name to be used when accessing an HTTPSendpoint and server authentication is used. The truststore file contains a list of the Certificate Authorities (CAs)that the client trusts.

This value overrides the directory of the truststore file that is specified by the javax.net.ssl.trustStore Javasystem property. If this property is not specified, the truststore directory is specified by the javax.net.ssl.trustStoreJava system property.

This property is ignored if ValidateServerCertificate=false.

Valid Valuesstring

where:

string

is the directory of the truststore file.

Data Source MethodsetTrustStore

DefaultNone

Data TypeString



See Also• Performance considerations on page 35


TrustStorePasswordPurposeThe password that is used to access the truststore file when accessing an HTTPS endpoint and serverauthentication is used. The truststore file contains a list of the Certificate Authorities (CAs) that the client trusts.

This value overrides the password of the truststore file that is specified by the javax.net.ssl.trustStorePasswordJava system property. If this property is not specified, the truststore password is specified by thejavax.net.ssl.trustStorePassword Java system property.

This property is ignored if ValidateServerCertificate=false.

Valid Valuesstring

where:

string

is a valid password for the truststore file.

Data Source MethodsetTrustStorePassword

DefaultNone

Data TypeString

See Also• Performance considerations on page 35


UserPurposeSpecifies the user name that is used to connect to your Jira service.


TrustStorePassword

Valid Valuesstring

where:

string

is a valid user name. The user name is case-insensitive.

Data Source MethodsetUser

DefaultNone

Data TypeString

See Also• Required properties

ValidateServerCertificatePurposeDetermines whether the driver validates the certificate that is sent by the Jira service server when accessingan HTTPS endpoint. When using SSL server authentication, any certificate that is sent by the server must beissued by a trusted Certificate Authority (CA).

Allowing the driver to trust any certificate that is returned from the server even if the issuer is not a trusted CAis useful in test environments because it eliminates the need to specify truststore information on each client inthe test environment.

Valid valuestrue | false

BehaviorIf set to true, the driver validates the certificate that is sent by the Jira service. Any certificate from the servicemust be issued by a trusted CA in the truststore file. If the HostNameInCertificate property is specified, thedriver also validates the certificate using a host name. The HostNameInCertificate property is optional andprovides additional security against man-in-the-middle (MITM) attacks by ensuring that the service the driveris connecting to is the server that was requested.

If set to false, the driver does not validate the certificate that is sent by the server. The driver ignores anytruststore information that is specified by the TrustStore and TrustStorePassword properties or Java systemproperties.



NotesTruststore information is specified using the TrustStore and TrustStorePassword properties or by using Javasystem properties.

Data source methodsetValidateServerCertificate

Defaulttrue

Data typeBoolean

See also• Data encryption properties

WSFetchSizePurposeSpecifies the number of rows of data the driver attempts to fetch for each JDBC call when paging is enabledfor an endpoint.

Valid Values0 | x

where:

x

is a positive integer that defines a number of rows.

BehaviorIf set to 0, the driver attempts to fetch up to a maximum of 1000 rows. This value typically provides the maximumthroughput.

If set to x, the driver attempts to fetch up to the maximum of the specified number of rows. Setting the valuelower than the maximum can reduce the response time for returning the initial data. Consider using a smallerWSFetch size for interactive applications only.

Notes• WSFetchSize and FetchSize can be used to adjust the trade-off between throughput and response time.

Smaller fetch sizes can improve the initial response time of the query. Larger fetch sizes can improve overallresponse times at the cost of additional memory.

• The values specified for the WSFetchSize and FetchSize properties provide only a suggestion as to thenumber of rows to be processed. Jira will not exceed these values, but it will adjust page sizes to balancethroughput amongst all its users. This behavior can result in different page sizes for successive queries.


WSFetchSize

Data Source MethodsetWSFetchSize

Default0 (up to a maximum of 1000 rows)

Data TypeInt



WSPoolSizePurposeSpecifies the maximum number of sessions the driver uses. This allows the driver to have multiple web servicerequests active when multiple JDBC connections are open, thereby improving throughput and performance.

Valid Valuesx

where:

x

is the number of sessions the driver uses to distribute calls. This value should not exceed the numberof sessions permitted by your account.

Notes• You can improve performance by increasing the number of sessions specified by this property. By increasing

the number of sessions the driver uses, you can improve throughput by distributing calls across multiplesessions when multiple connections are active.

• The maximum number of sessions is determined by the setting of WSPoolSize for the connection thatinitiates the session. For subsequent connections to an active session, the setting is ignored and a warningis returned. To change the maximum number of sessions, close all connections using the driver; then, opena new connection with desired limit specified for this property.

Data Source MethodsetWSPoolSize

Default1



Data TypeInt

See also• Web service properties


WSRetryCountDescriptionThe number of times the driver retries a timed-out Select request. The timeout period is specified by theWSTimeout connection property.

Valid Values0 | x

where:

x

is a positive integer.

BehaviorIf set to 0, the driver does not retry timed-out requests after the initial unsuccessful attempt.

If set to x, the driver retries the timed-out request the specified number of times.

Data Source MethodsetWSRetryCount

Default5

Data TypeInt



WSRetryCount

WSTimeoutPurposeSpecifies the time, in seconds, that the driver waits for a response to a Web service request.

Valid Values0 | x

where:

x

is a positive integer that defines the number of seconds the driver waits for a response to a Webservice request.

BehaviorIf set to 0, the driver waits indefinitely for a response; there is no timeout.

If set to x, the driver uses the value as the default timeout for any statement created by the connection.

If a Select request times out and WSRetryCount is set to retry timed-out requests, the driver retries the requestthe specified number of times.

Data Source MethodsetWSTimeout

Default120 (seconds)

Data TypeInt




4Supported SQL statements and extensions

The driver provides support for the SQL statements and the SQL extensions described in this section. SQLextensions are denoted by an (EXT) in the topic title.


• Alter Session (EXT)

• Select

• SQL expressions

• Subqueries

Alter Session (EXT)PurposeChanges various attributes of a local or remote session. A local session maintains the state of the overallconnection. A remote session maintains the state that pertains to a particular remote data source connection.

SyntaxALTER SESSION SET attribute_name=value

where:


attribute_name

specifies the name of the attribute to be changed. Attributes apply to either local or remote sessions.

value

specifies the value for that attribute.

The following table lists the local and remote session attributes, and provides descriptions of each.

Table 15: Alter Session Attributes

DescriptionSession TypeAttribute Name

Sets the current schema for the local session. The current schema isthe schema used when an identifier in a SQL statement is unqualified.The string value must be the name of a schema visible in the localsession. For example:

ALTER SESSION SET CURRENT_SCHEMA=JIRA

LocalCurrent_Schema

Sets the maximum number of Web service calls the driver can makein executing a statement. Setting the Stmt_Call_Limit attribute has thesame effect as setting the StmtCallLimit connection property. It setsthe default Web service call limit used by any statement on theconnection. Executing this command on a statement overrides thepreviously set StmtCallLimit for the connection. The value specifiedmust be a positive integer or 0. The value 0 means that no call limitexists. For example:

ALTER SESSION SET STMT_CALL_LIMIT=150

LocalStmt_Call_Limit

Resets the Web service call count of a remote session to the valuespecified. The value must be 0 or a positive integer. WS_Call_Countrepresents the total number of Web service calls made to the remotedata source instance for the current session. For example:

ALTER SESSION SET jira.WS_CALL_COUNT=0

The current value of WS_Call_Count can be obtained by referring tothe System_Remote_Sessions system table (seeSYSTEM_REMOTE_SESSIONS Catalog Table for details). Forexample:

SELECT * frominformation_schema.system_remote_sessions WHEREsession_id = cursessionid()

RemoteWs_Call_Count

SelectPurposeUse the Select statement to fetch results from one or more tables.


Chapter 4: Supported SQL statements and extensions

SyntaxSELECT select_clausefrom_clause[where_clause][groupby_clause][having_clause][{UNION [ALL | DISTINCT] |{MINUS [DISTINCT] | EXCEPT [DISTINCT]} |INTERSECT [DISTINCT]} select_statement][limit_clause]

where:

select_clause

specifies the columns from which results are to be returned by the query. See "Select" for a completeexplanation.

from_clause

specifies one or more tables on which the other clauses in the query operate. See "From" for acomplete explanation.

where_clause

is optional and restricts the results that are returned by the query. See "Where clause" for a completeexplanation.

groupby_clause

is optional and allows query results to be aggregated in terms of groups. See "Group By clause" fora complete explanation.

having_clause

is optional and specifies conditions for groups of rows (for example, display only the departmentsthat have salaries totaling more than $200,000). See "Having clause" for a complete explanation.

UNION

is an optional operator that combines the results of the left and right Select statements into a singleresult. See "Union operator" for a complete explanation.

INTERSECT

is an optional operator that returns a single result by keeping any distinct values from the results ofthe left and right Select statements. See "Intersect operator" for a complete explanation.

EXCEPT | MINUS

are synonymous optional operators that returns a single result by taking the results of the left Selectstatement and removing the results of the right Select statement. See "Except and Minus operators"for a complete explanation.

orderby_clause

is optional and sorts the results that are returned by the query. See "Order By clause" for a completeexplanation.


Select

limit_clause

is optional and places an upper bound on the number of rows returned in the result. See "Limitclause" for a complete explanation.

Select clause

PurposeUse the Select clause to specify with a list of column expressions that identify columns of values that you wantto retrieve or an asterisk (*) to retrieve the value of all columns.

SyntaxSELECT [{LIMIT offsetnumber | TOP number}] [ALL | DISTINCT] {* | column_expression[[AS] column_alias] [,column_expression [[AS] column_alias], ...]}

where:

LIMIT offset number

creates the result set for the Select statement first and then discards the first number of rows specifiedby offset and returns the number of remaining rows specified by number. To not discard any ofthe rows, specify 0 for offset, for example, LIMIT 0 number. To discard the first offset numberof rows and return all the remaining rows, specify 0 for number, for example, LIMIT offset0.

TOP number

is equivalent to LIMIT 0number.

column_expression

can be simply a column name (for example, last_name). More complex expressions may includemathematical operations or string manipulation (for example, salary * 1.05). See "SQLexpressions" for details. column_expression can also include aggregate functions. See "Aggregatefunctions" for details.

column_alias

can be used to give the column a descriptive name. For example, to assign the alias department tothe column dep:

SELECT dep AS department FROM emp

DISTINCT

eliminates duplicate rows from the result of a query. This operator can precede the first columnexpression. For example:

SELECT DISTINCT dep FROM emp

Notes• Separate multiple column expressions with commas (for example, SELECT last_name, first_name,

hire_date).



• Column names can be prefixed with the table name or table alias. For example, SELECT emp.last_nameor e.last_name, where e is the alias for the table emp.

• NULL values are not treated as distinct from each other. The default behavior is that all result rows bereturned, which can be made explicit with the keyword ALL.

See alsoSQL expressions on page 87

Aggregate functionsAggregate functions can also be a part of a Select clause. Aggregate functions return a single value from a setof rows. An aggregate can be used with a column name (for example, AVG(salary)) or in combination witha more complex column expression (for example, AVG(salary * 1.07)).

The following table lists supported aggregate functions.

Note: Doubly nested aggregates, such as SUM(COUNT(col1)), are currently not permitted by the driver.

Table 16: Aggregate Functions

ReturnsAggregate

The average of the values in a numeric column expression. For example, AVG(salary)returns the average of all salary column values.

AVG

The number of values in any field expression. For example, COUNT(name) returns thenumber of name values. When using COUNT with a field name, COUNT returns thenumber of non-NULL column values. A special example is COUNT(*), which returnsthe number of rows in the set, including rows with NULL values.

Note: The driver does not support COUNT(DISTINCT *). For example, SELECTCOUNT(DISTINCT *) FROM mytable results in a syntax error.

COUNT

The maximum value in any column expression. For example, MAX(salary) returnsthe maximum salary column value.

MAX

The minimum value in any column expression. For example, MIN(salary) returnsthe minimum salary column value.

MIN

The total of the values in a numeric column expression. For example, SUM(salary)returns the sum of all salary column values.

SUM

ExampleThe following example uses the COUNT, MAX, and AVG aggregate functions:

SELECTCOUNT(amount) AS numOpportunities,MAX(amount) AS maxAmount,AVG(amount) AS avgAmount

FROM opportunity o INNER JOIN user uON o.ownerId = u.id


Select

WHERE o.isClosed = 'false' ANDu.name = 'MyName'

From clause

PurposeThe From clause indicates the tables to be used in the Select statement.

SyntaxFROM table_name [table_alias] [,...]

where:

table_name

is the name of a table or a subquery. Multiple tables define an implicit inner join among those tables.Multiple table names must be separated by a comma. For example:

SELECT * FROM emp, dep

Subqueries can be used instead of table names. Subqueries must be enclosed in parentheses. See"Subquery in a From clause" for an example.

table_alias

is a name used to refer to a table in the rest of the Select statement. When you specify an alias fora table, you can prefix all column names of that table with the table alias.

ExampleThe following example specifies two table aliases, e for emp and d for dep:

SELECT e.name, d.deptNameFROM emp e, dep dWHERE e.deptId = d.id

table_alias is a name used to refer to a table in the rest of the Select statement. When you specify an aliasfor a table, you can prefix all column names of that table with the table alias. For example, given the tablespecification:

FROM emp E

you may refer to the last_name field as E.last_name. Table aliases must be used if the Select statement joinsa table to itself. For example:

SELECT * FROM emp E, emp F WHERE E.mgr_id = F.emp_id

The equal sign (=) includes only matching rows in the results.



Join in a From clause

PurposeYou can use a Join as a way to associate multiple tables within a Select statement. Joins may be either explicitor implicit. For example, the following is the example from the previous section restated as an explicit innerjoin:

SELECT * FROM emp INNER JOIN dep ON id=empIdSELECT e.name, d.deptNameFROM emp e INNER JOIN dep d ON e.deptId = d.id;

whereas the following is the same statement as an implicit inner join:

SELECT * FROM emp, dep WHERE emp.deptID=dep.id

Note: The ON clause in a join expression must evaluate to a true or false value.

SyntaxFROM table_name {RIGHT OUTER | INNER | LEFT OUTER | CROSS | FULL OUTER} JOIN table.keyON search-condition

ExampleIn this example, two tables are joined using LEFT OUTER JOIN. T1, the first table named includes nonmatchingrows.

SELECT * FROM T1 LEFT OUTER JOIN T2 ON T1.key = T2.key

If you use a CROSS JOIN, no ON expression is allowed for the join.

Subquery in a From clauseSubqueries can be used in the From clause in place of table references (table_name).

ExampleSELECT * FROM (SELECT * FROM emp WHERE sal > 10000) new_emp, dept WHEREnew_emp.deptno = dept.deptno

See alsoSubqueries on page 95

Where clause

PurposeSpecifies the conditions that rows must meet to be retrieved.

SyntaxWHERE expr1rel_operatorexpr2

where:


Select

expr1

is either a column name, literal, or expression.

expr2

is either a column name, literal, expression, or subquery. Subqueries must be enclosed in parentheses.

rel_operator

is the relational operator that links the two expressions.

ExampleThe following Select statement retrieves the first and last names of employees that make at least $20,000.

SELECT last_name, first_name FROM emp WHERE salary >= 20000

See alsoSubqueries on page 95SQL expressions on page 87

Group By clause

PurposeSpecifies the names of one or more columns by which the returned values are grouped. This clause is usedto return a set of aggregate values.

SyntaxGROUP BY column_expression [,...]

where:

column_expression

is either a column name or a SQL expression. Multiple values must be separated by a comma. Ifcolumn_expression is a column name, it must match one of the column names specified in the Selectclause. Also, the Group By clause must include all non-aggregate columns specified in the Selectlist.

ExampleThe following example totals the salaries in each department:

SELECT dept_id, sum(salary) FROM emp GROUP BY dept_id

This statement returns one row for each distinct department ID. Each row contains the department ID and thesum of the salaries of the employees in the department.




Having clause

PurposeSpecifies conditions for groups of rows (for example, display only the departments that have salaries totalingmore than $200,000). This clause is valid only if you have already defined a Group By clause.

SyntaxHAVING expr1rel_operatorexpr2

where:

expr1 | expr2

can be column names, constant values, or expressions. These expressions do not have to match acolumn expression in the Select clause. See "SQL expressions" for details regarding SQL expressions.

rel_operator

is the relational operator that links the two expressions.

ExampleThe following example returns only the departments that have salaries totaling more than $200,000:

SELECT dept_id, sum(salary) FROM emp GROUP BY dept_id HAVING sum(salary) > 200000


Union operator

PurposeCombines the results of two Select statements into a single result. The single result is all the returned rowsfrom both Select statements. By default, duplicate rows are not returned. To return duplicate rows, use the Allkeyword (UNION ALL).

Syntaxselect_statementUNION [ALL | DISTINCT] | {MINUS [DISTINCT] | EXCEPT [DISTINCT]} | INTERSECT[DISTINCT]select_statement

Notes• When using the Union operator, the Select lists for each Select statement must have the same number of

column expressions with the same data types and must be specified in the same order.


Select

Example AThe following example has the same number of column expressions, and each column expression, in order,has the same data type.

SELECT last_name, salary, hire_date FROM empUNIONSELECT name, pay, birth_date FROM person

Example BThe following example is not valid because the data types of the column expressions are different (salaryFROM emp has a different data type than last_name FROM raises). This example does have the samenumber of column expressions in each Select statement but the expressions are not in the same order by datatype.

SELECT last_name, salary FROM empUNIONSELECT salary, last_name FROM raises

Intersect operator

PurposeIntersect operator returns a single result set. The result set contains rows that are returned by both Selectstatements. Duplicates are returned unless the Distinct operator is added.

Syntaxselect_statementINTERSECT [DISTINCT]select_statement

where:

DISTINCT

eliminates duplicate rows from the results.

Notes• When using the Intersect operator, the Select lists for each Select statement must have the same number

of column expressions with the same data types and must be specified in the same order.


SELECT last_name, salary, hire_date FROM empINTERSECT [DISTINCT]SELECT name, pay, birth_date FROM person




SELECT last_name, salary FROM empINTERSECTSELECT salary, last_name FROM raises

Except and Minus operators

PurposeReturn the rows from the left Select statement that are not included in the result of the right Select statement.

Syntaxselect_statement{EXCEPT [DISTINCT] | MINUS [DISTINCT]}select_statement

where:

DISTINCT

eliminates duplicate rows from the results.

Notes• When using one of these operators, the Select lists for each Select statement must have the same number

of column expressions with the same data types and must be specified in the same order.


SELECT last_name, salary, hire_date FROM empEXCEPTSELECT name, pay, birth_date FROM person


SELECT last_name, salary FROM empEXCEPTSELECT salary, last_name FROM raises


Select

Order By clause

PurposeThe Order By clause specifies how the rows are to be sorted.

SyntaxORDER BY sort_expression [DESC | ASC] [,...]

where:

sort_expression

is either the name of a column, a column alias, a SQL expression, or the positioned number of thecolumn or expression in the select list to use.

The default is to perform an ascending (ASC) sort.

ExampleTo sort by last_name and then by first_name, you could use either of the following Select statements:

SELECT emp_id, last_name, first_name FROM emp

ORDER BY last_name, first_name

or

SELECT emp_id, last_name, first_name FROM emp

ORDER BY 2,3

In the second example, last_name is the second item in the Select list, so ORDER BY 2,3 sorts by last_nameand then by first_name.

See alsoSQL expressions on page 87

Limit clause

PurposePlaces an upper bound on the number of rows returned in the result.

SyntaxLIMIT number_of_rows [OFFSET offset_number]

where:

number_of_rows

specifies a maximum number of rows in the result. A negative number indicates no upper bound.



OFFSET

specifies how many rows to skip at the beginning of the result set. offset_number is the numberof rows to skip.

Notes• In a compound query, the Limit clause can appear only on the final Select statement. The limit is applied

to the entire query, not to the individual Select statement to which it is attached.

ExampleThe following example returns a maximum of 20 rows.

SELECT last_name, first_name FROM emp WHERE salary > 20000 ORDER BY dept_idc LIMIT20

SQL expressionsAn expression is a combination of one or more values, operators, and SQL functions that evaluate to a value.You can use expressions in the Where, and Having of Select statements; and in the Set clauses of Updatestatements.

Expressions enable you to use mathematical operations as well as character string manipulation operators toform complex queries.

The driver supports both unquoted and quoted identifiers. An unquoted identifier must start with an ASCII alphacharacter and can be followed by zero

Quoted identifiers must be enclosed in double quotation marks (""). A quoted identifier can contain any Unicodecharacter including the space character. The driver recognizes the Unicode escape sequence \uxxxx as aUnicode character. You can specify a double quotation mark in a quoted identifier by escaping it with a doublequotation mark.

The maximum length of both quoted and unquoted identifiers is 128 characters.

Valid expression elements are:

• Column names

• Literals

• Operators

• Functions

Column namesThemost common expression is a simple column name. You can combine a column name with other expressionelements.

LiteralsLiterals are fixed data values. For example, in the expression PRICE * 1.05, the value 1.05 is a constant.Literals are classified into types, including the following:


SQL expressions

• Binary

• Character string

• Date

• Floating point

• Integer

• Numeric

• Time

• Timestamp

The following table describes the literal format for supported SQL data types.

Table 17: Literal Syntax Examples

ExampleLiteral SyntaxSQL Type

12 or -34 or 0n

wheren is any valid integer value in the range of theINTEGER data type

BIGINT

0

1

Min Value: 0

Max Value: 1

BOOLEAN

'2010-05-21'DATE'date'DATE

'2010-05-2118:33:05.025'

TIMESTAMP'ts'DATETIME

0.25

3.1415

-7.48

n.f

where:

n

is the integral part

f

is the fractional part

DECIMAL

1.2E0 or 2.5E40 or -3.45E2or 5.67E-4

n.fEx

where:

n is the integral part

f is the fractional part

x is the exponent

DOUBLE

12 or -34 or 0n

where n is a valid integer value in the rangeof the INTEGER data type

INTEGER



ExampleLiteral SyntaxSQL Type

'000482ff''hex_value'LONGVARBINARY

'This is a stringliteral'

'value'LONGVARCHAR

'2010-05-2118:33:05.025'

TIME'time'TIME

'This is a stringliteral'

'value'VARCHAR

Character string literalsText specifies a character string literal. A character string literal must be enclosed in single quotation marks.To represent one single quotation mark within a literal, you must enter two single quotation marks. When thedata in the fields is returned to the client, trailing blanks are stripped.

A character string literal can have a maximum length of 32 KB, that is, (32*1024) bytes.

Example

'Hello''Jim''s friend is Joe'

Numeric literalsUnquoted numeric values are treated as numeric literals. If the unquoted numeric value contains a decimalpoint or exponent, it is treated as a real literal; otherwise, it is treated as an integer literal.

Example+1894.1204

Binary literalsBinary literals are represented with single quotation marks. The valid characters in a binary literal are 0-9, a-f,and A-F.

Example'00af123d'

Date/Time literalsDate and time literal values are enclosed in single quotion marks ('value').

• The format for a Date literal is DATE'date'.

• The format for a Time literal is TIME'time'.

• The format for a Timestamp literal is TIMESTAMP'ts'.


SQL expressions

Integer literalsInteger literals are represented by a string of numbers that are not enclosed in quotation marks and do notcontain decimal points.

Notes• Integer constants must be whole numbers; they cannot contain decimals.

• Integer literals can start with sign characters (+/-).

Example1994 or -2

OperatorsThis section describes the operators that can be used in SQL expressions.

Note: Numeric operators are restricted to numeric types. Numeric operators do not support non-numeric types.

Unary operatorA unary operator operates on only one operand.operator operand

Binary operatorA binary operator operates on two operands.operand1 operator operand2

If an operator is given a null operand, the result is always null. The only operator that does not follow this ruleis concatenation (||).

Arithmetic operatorsYou can use an arithmetic operator in an expression to negate, add, subtract, multiply, and divide numericvalues. The result of this operation is also a numeric value. The + and - operators are also supported in date/timefields to allow date arithmetic. The following table lists the supported arithmetic operators.

Table 18: Arithmetic Operators

ExamplePurposeOperator

SELECT * FROM emp WHERE comm = -1Denotes a positive or negative expression. Theseare unary operators.

+ -




UPDATE emp SET sal = sal + sal *0.10

Multiplies, divides. These are binary operators.* /

SELECT sal + comm FROM emp WHEREempno > 100

Adds, subtracts. These are binary operators.+ -

Concatenation operatorThe concatenation operator manipulates character strings. The following table lists the only supportedconcatenation operator.

Table 19: Concatenation Operator


SELECT 'Name is' || ename FROM empConcatenates character strings.||

The result of concatenating two character strings is the data type VARCHAR.

Comparison operatorsComparison operators compare one expression to another. The result of such a comparison can be TRUE,FALSE, or UNKNOWN (if one of the operands is NULL). The driver considers the UNKNOWN result as FALSE.

The following table lists the supported comparison operators.

Table 20: Comparison Operators


SELECT * FROM emp WHERE sal =1500

Equality test.=

SELECT * FROM emp WHERE sal !=1500

Inequality test.!=<>

SELECT * FROM emp WHERE sal >1500 SELECT * FROM emp WHEREsal < 1500

"Greater than" and "less than"tests.

><

SELECT * FROM emp WHERE sal >=1500 SELECT * FROM emp WHEREsal <= 1500

"Greater than or equal to" and "lessthan or equal to" tests.

>=<=


SQL expressions


SELECT * FROM emp WHERE ENAMELIKE 'J%'

% and _ wildcards can be used tosearch for a pattern in a column.The percent sign denotes zero,one, or multiple characters, whilethe underscore denotes a singlecharacter. The right-hand side of aLIKE expression must evaluate toa string or binary.

LIKE

SELECT * FROM emp WHERE ENAMELIKE 'J%\_%' ESCAPE '\'

This matches all records with names thatstart with letter 'J' and have the '_'character in them.

The Escape clause is supported inthe LIKE predicate to indicate theescape character. Escapecharacters are used in the patternstring to indicate that any wildcardcharacter that is after the escape

ESCAPE clause in LIKEoperator

LIKE 'pattern string' ESCAPE'c'

SELECT * FROM emp WHERE ENAMELIKE 'JOE\_JOHN' ESCAPE '\'

character in the pattern stringshould be treated as a regularcharacter.

The default escape character isbackslash (\).

This matches only records with name'JOE_JOHN'.

SELECT * FROM emp WHERE job IN('CLERK','ANALYST') SELECT *FROM emp WHERE sal IN (SELECTsal FROM emp WHERE deptno =30)

"Equal to any member of" test.[NOT] IN

SELECT * FROM emp WHERE salBETWEEN 2000 AND 3000

"Greater than or equal to x" and"less than or equal to y."

[NOT] BETWEEN x AND y

SELECT empno, ename, deptnoFROM emp e WHERE EXISTS(SELECT deptno FROM dept WHEREe.deptno = dept.deptno)

Tests for existence of rows in asubquery.

EXISTS

SELECT * FROM emp WHERE enameIS NOT NULL SELECT * FROM empWHERE ename IS NULL

Tests whether the value of thecolumn or expression is NULL.

IS [NOT] NULL

Logical operatorsA logical operator combines the results of two component conditions to produce a single result or to invert theresult of a single condition. The following table lists the supported logical operators.



Table 21: Logical Operators


SELECT * FROM emp WHERE NOT (jobIS NULL)SELECT * FROM emp WHERE NOT (salBETWEEN 1000 AND 2000)

Returns TRUE if the following condition isFALSE. Returns FALSE if it is TRUE. If it isUNKNOWN, it remains UNKNOWN.

NOT

SELECT * FROM emp WHERE job ='CLERK' AND deptno = 10

Returns TRUE if both component conditions areTRUE. Returns FALSE if either is FALSE;otherwise, returns UNKNOWN.

AND

SELECT * FROM emp WHERE job ='CLERK' OR deptno = 10

Returns TRUE if either component condition isTRUE. Returns FALSE if both are FALSE;otherwise, returns UNKNOWN.

OR

ExampleIn theWhere clause of the following Select statement, the AND logical operator is used to ensure that managersearning more than $1000 a month are returned in the result:

SELECT * FROM emp WHERE jobtitle = manager AND sal > 1000

Operator precedenceAs expressions become more complex, the order in which the expressions are evaluated becomes important.The following table shows the order in which the operators are evaluated. The operators in the first line areevaluated first, then those in the second line, and so on. Operators in the same line are evaluated left to rightin the expression.You can change the order of precedence by using parentheses. Enclosing expressions inparentheses forces them to be evaluated together.

Table 22: Operator Precedence

OperatorPrecedence

+ (Positive), - (Negative)1

*(Multiply), / (Division)2

+ (Add), - (Subtract)3

|| (Concatenate)4

=, >, <, >=, <=, <>, != (Comparison operators)5

NOT, IN, LIKE6

AND7

OR8


SQL expressions

Example AThe query in the following example returns employee records for which the department number is 1 or 2 andthe salary is greater than $1000:

SELECT * FROM emp WHERE (deptno = 1 OR deptno = 2) AND sal > 1000

Because parenthetical expressions are forced to be evaluated first, the OR operation takes precedence overAND.

Example BIn the following example, the query returns records for all the employees in department 1, but only employeeswhose salary is greater than $1000 in department 2.

SELECT * FROM emp WHERE deptno = 1 OR deptno = 2 AND sal > 1000

The AND operator takes precedence over OR, so that the search condition in the example is equivalent to theexpression deptno = 1 OR (deptno = 2 AND sal > 1000).

FunctionsThe driver supports a number of functions that you can use in expressions, including String, Numeric, Timedate,and System functions, as listed and described in Scalar Functions in the Progress DataDirect for JDBC DriversReference.

ConditionsA condition specifies a combination of one or more expressions and logical operators that evaluates to eitherTRUE, FALSE, or UNKNOWN. You can use a condition in the Where clause of the Delete, Select, and Updatestatements; and in the Having clauses of Select statements. The following describes supported conditions.

Table 23: Conditions

DescriptionCondition

Specifies a comparison with expressions or subquery results.

= , !=, <>, < , >, <=, <=

Simple comparison

Specifies a comparison with any or all members in a list orsubquery.

[= , !=, <>, < , >, <=, <=] [ANY, ALL, SOME]

Group comparison

Tests for membership in a list or subquery.

[NOT] IN

Membership

Tests for inclusion in a range.

[NOT] BETWEEN

Range



https://documentation.progress.com/output/DataDirect/jdbcreferencehelp/index.html#context/JDBC/scalar_functions

DescriptionCondition

Tests for nulls.

IS NULL, IS NOT NULL

NULL

Tests for existence of rows in a subquery.

[NOT] EXISTS

EXISTS

Specifies a test involving pattern matching.

[NOT] LIKE

LIKE

Specifies a combination of other conditions.

CONDITION [AND/OR] CONDITION

Compound

SubqueriesA query is an operation that retrieves data from one or more tables or views. In this reference, a top-level queryis called a Select statement, and a query nested within a Select statement is called a subquery.

A subquery is a query expression that appears in the body of another expression such as a Select, an Update,or a Delete statement. In the following example, the second Select statement is a subquery:

SELECT * FROM emp WHERE deptno IN (SELECT deptno FROM dept)

IN predicate

PurposeThe In predicate specifies a set of values against which to compare a result set. If the values are being comparedagainst a subquery, only a single column result set is returned.

Syntaxvalue [NOT] IN (value1, value2,...)

OR

value [NOT] IN (subquery)

ExampleSELECT * FROM emp WHERE deptno IN

(SELECT deptno FROM dept WHERE dname <> 'Sales')


Subqueries

EXISTS predicate

PurposeThe Exists predicate is true only if the cardinality of the subquery is greater than 0; otherwise, it is false.

SyntaxEXISTS (subquery)

Example

SELECT empno, ename, deptno FROM emp e WHERE EXISTS(SELECT deptno FROM dept WHERE e.deptno = dept.deptno)

UNIQUE predicate

PurposeThe Unique predicate is used to determine whether duplicate rows exist in a virtual table (one returned from asubquery).

SyntaxUNIQUE (subquery)

Example

SELECT * FROM dept d WHERE UNIQUE(SELECT deptno FROM emp e WHERE e.deptno = d.deptno)

Correlated subqueries

PurposeA correlated subquery is a subquery that references a column from a table referred to in the parent statement.A correlated subquery is evaluated once for each row processed by the parent statement. The parent statementcan be a Select, Update, or Delete statement.

A correlated subquery answers a multiple-part question in which the answer depends on the value in each rowprocessed by the parent statement. For example, you can use a correlated subquery to determine whichemployees earn more than the average salaries for their departments. In this case, the correlated subqueryspecifically computes the average salary for each department.

SyntaxSELECT select_list

FROM table1 t_alias1WHERE expr rel_operator(SELECT column_list

FROM table2 t_alias2



WHERE t_alias1.columnrel_operatort_alias2.column)UPDATE table1 t_alias1

SET column =(SELECT expr

FROM table2 t_alias2WHERE t_alias1.column = t_alias2.column)

DELETE FROM table1 t_alias1WHERE column rel_operator(SELECT expr

FROM table2 t_alias2WHERE t_alias1.column = t_alias2.column)

Notes• Correlated column names in correlated subqueries must be explicitly qualified with the table name of the

parent.

Example AThe following statement returns data about employees whose salaries exceed their department average. Thisstatement assigns an alias to emp, the table containing the salary information, and then uses the alias in acorrelated subquery:

SELECT deptno, ename, sal FROM emp x WHERE sal >(SELECT AVG(sal) FROM emp WHERE x.deptno = deptno)ORDER BY deptno

Example BThis is an example of a correlated subquery that returns row values:

SELECT * FROM dept "outer" WHERE 'manager' IN(SELECT managername FROM empWHERE "outer".deptno = emp.deptno)

Example CThis is an example of finding the department number (deptno) with multiple employees:

SELECT * FROM dept main WHERE 1 <(SELECT COUNT(*) FROM emp WHERE deptno = main.deptno)

Example DThis is an example of correlating a table with itself:

SELECT deptno, ename, sal FROM emp x WHERE sal >(SELECT AVG(sal) FROM emp WHERE x.deptno = deptno)


Subqueries

Progress DataDirect for JDBC for Jira User's Guide · The Progress® DataDirect® for JDBC™ for...

Documents

Transcript of Progress DataDirect for JDBC for Jira User's Guide · The Progress® DataDirect® for JDBC™ for...