1. Las Vegas, NV September 15 – September 18, 2003
JDBC Access to IMS DB from DB2, CICS, and Websphere
Christopher Holtz, Kyle Charlet
Las Vegas, NV September 15 – September 18, 2003

2. Overview IMS Java JDBC and J2EE Dealership Sample Application
What Is IMS Java
Why Use IMS Java
IMS Java Class Library Architecture
JDBC and J2EE
Dealership Sample Application
Front-end/Back-end split
Environments
Non-Managed
IMS
CICS
DB2
Managed
WebSphere

3. What is IMS Java? A new feature in IMS v7 A set of classes that...
Offers Java support to access IMS Databases from various environments (IMS, CICS, DB2, WebSphere)
Enables SQL access through the JDBC interface
Java Virtual Machine (JVM) support in dependent regions
JDK 1.3 support
JDBC 2.1 support
Just-In-Time (JIT) compilation
Resetable JVM

4. Why IMS Java? Rapid Application Development
Reduce the Total Cost of Ownership (TCO) for IT and Data Management needs and Total Time to Value (TTV)
Extend the life and scope of IMS applications
Minimum amount of impact on core applications and effort for developers, system programmers, and DBAs
Leverage existing marketplace, industry-sanctioned standards - they are the slowest changing and most persistent
JDBC and J2EE are standards – help to minimize specific back end knowledge of IMS
Leverage new and abundant skills in the marketplace and mitigate the loss of 390 skills for customers
Integrate with other products
Our response is IMS Java, Web Services, WebSphere support, CICS support, DB2 SP support

5. C Layer Interface to IMS
Java Class Library
IMS DB Metadata
Business Logic
IMS Dep. Region
Transaction and
Message Processing
IMS Java
App
DLI
Database
View
Customer Code A p DB
JDBC / SQL
IMS Java Class Library
Base
Mapping to DL/I APIs
JNI
CEETDLI Interface
C Layer Interface to IMS
JDBC, JCA
interface
Java to C
interface

6. IMS Java – The Big Picture
DB2
WebSphere
CICS
Stored
Procedure
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
IMS Java
App
Database
View
DLI
CEETDLI Interface
JNI
Base A p DB
JDBC / SQL
IMS Java
App
Database
View
DLI
EJB
JCICS
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
IMS Java
App
Database
View
DLI
Java Virtual Machine
Java Virtual Machine
Java Virtual Machine
IMS / TM
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
IMS Java
App
Database
View
DLI
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
IMS Java
App
Database
View
DLI M P B M P I F P
ODBA
DRA
JMP JBP
IMS DB
Java Virtual Machine
CEETDLI Interface
JNI
Base A p DB
JDBC / SQL
IMS Java
App
DLI
Database
View
DL/I Model
DBDs
DBDGEN
PSBGEN
ACBGEN
PSBs
COPYLIB

7. Overview IMS Java JDBC and J2EE Dealership Sample Application
What Is IMS Java
Why Use IMS Java
IMS Java Class Library Architecture
JDBC and J2EE
Dealership Sample Application
Front-end/Back-end split
Environments
Non-Managed
IMS
CICS
DB2
Managed
WebSphere

8. JDBC and J2EE Standards Evolution
Standard way to Query Database (relational)
Structured Query Language (SQL)
Communicating Query to Database
Open Database Connectivity (ODBC) – C based
Standard API to Query Database
“Java Database Connectivity” (JDBC) – Platform/DB Independent
Standard API to Establish Connection
J2EE Connection Architecture (JCA, J2C)
Standard API to Build Enterprise Applications
Java 2 Enterprise Edition (J2EE)

9. J2EE Architecture Applet Container Applet Web Container EJB Container
HTTP
SSL
Web Container
EJB Container
Servlet
JSP
EJB
JMS
JNDI
JTA
Java
Mail
RMI/IIOP
JDBC
JMS
JNDI
JTA
Java
Mail
RMI/IIOP
JDBC
Database
J2SE
HTTP
SSL
JAF
JAF
J2SE
J2SE
Application
Client Container
Application
Client
JMS
JNDI
RMI/IIOP
JDBC
J2SE

10. J2EE Connection Architecture
Proposed Java standard architecture for deploying a resource adapter in a J2EE compliant application server
Defines contracts between...
resource adapter and the application component
resource adapter and the application server

11. J2EE Connection Architecture
Container-
Component
Contract
Application Server
Application Component
JDBC
Resource Adapter
System
Contracts
WebSphere
IMS Java
EIS specific interface
Enterprise Information System
IMS

12. DataSource Factory for connections to a physical data source
Replacement to the DriverManager facility
Required when running in a managed environment (WebSphere)
Typically registered with a naming service based on the Java™ Naming and Directory (JNDI) API.
Names are associated with objects and objects are found based on their names.
DataSource objects have properties that can be modified when necessary
Code accessing the data source does not need to be changed
(Properties include: DRA Name, DLIDatabaseView)

13. DataSource Deployment
DRA:
DBView:
SYS3
TestAppDatabaseView
DataSource
AbcdefDB
DBView:
DRA:
SYS1
TestApp2DatabaseView
DataSource
EmployeeDB
JNDI
DRA:
DBView:
DataSource
Admin Tool
SYS1
AUTPSB11DatabaseView

14. DataSource Deployment
DRA:
DBView:
SYS3
TestAppDatabaseView
DataSource
AbcdefDB
DBView:
DRA:
SYS1
TestApp2DatabaseView
DataSource
EmployeeDB
JNDI
DealershipDB
DRA:
DBView:
SYS1
AUTPSB11DatabaseView
DataSource
"DealershipDB"
DRA:
DBView:
DataSource
SYS1
AUTPSB11DatabaseView
Admin Tool

15. DataSource Retrieval JNDI "DealershipDB" "DealershipDB" EJB 1 EJB 2
DRA:
DBView:
SYS3
TestAppDatabaseView
DataSource
AbcdefDB
DRA:
DBView:
SYS1
AUTPSB11DatabaseView
DataSource
DRA:
DBView:
SYS1
AUTPSB11DatabaseView
DataSource
DRA:
DBView:
SYS1
AUTPSB11DatabaseView
DataSource
DealershipDB
JNDI
DRA:
DBView:
SYS1
TestApp2DatabaseView
DataSource
EmployeeDB
"DealershipDB"
"DealershipDB"
DRA:
DBView:
DataSource
SYS1
AUTPSB11DatabaseView
EJB 1
EJB 2
DRA:
DBView:
DataSource
SYS1
AUTPSB11DatabaseView

16. Overview IMS Java JDBC and J2EE Dealership Sample Application
What Is IMS Java
Why Use IMS Java
IMS Java Class Library Architecture
JDBC and J2EE
Dealership Sample Application
Front-end/Back-end split
Environments
Non-Managed
IMS
CICS
DB2
Managed
WebSphere

17. Dealership Sample Database
SALESINF
SALESPER
STOCK
SALES
MODEL
ORDER

18. Dealership Sample Application
Performs specific queries to the database
List all models
List details of a particular model
Split into a front-end and a back-end
Front-End (Environment Specific)
Process message queue (IMS)
Invoke stored procedure (DB2)
JCICS application (CICS)
Enterprise Java Bean (WebSphere)
Back-End (Environment Independent)
Performs all query processing
Sends data back to the caller (front-end)

19. Dealership Sample (Back-End)
public class AutoDealership {
/** The database connection is created by each front-end and given
to the single back-end **/
public AutoDealership(Connection connection) {
this.connection = connection; }
public Vector listModels() throws SQLException {
SQL processing logic here...
public Vector findCar(FindCarInput input) throws
SQLException {

20. Dealership Sample (Back-End)
public Vector listModels() throws SQLException {
// Create the SQL statement - no inputs needed
String query = "SELECT * FROM Order.ModelSegment";
// Execute the query
Statement statement = connection.createStatement();
ResultSet results = statement.executeQuery(query);
process results... }

21. Dealership Sample (Back-End)
public Vector listModels() throws SQLException {
create statement and execute query...
Vector models = new Vector();
ListModelOutput output = null;
while (results.next()) {
output = new ListModelOutput();
output.setModelType(results.getString("ModelType"));
output.setMake(results.getString("Make"));
output.setModel(results.getString("Model"));
output.setYear(results.getString("Year"));
models.addElement(output); }
return models;

22. Overview IMS Java JDBC and J2EE Dealership Sample Application
What Is IMS Java
Why Use IMS Java
IMS Java Class Library Architecture
JDBC and J2EE
Dealership Sample Application
Front-end/Back-end split
Environments
Non-Managed
IMS
CICS
DB2
Managed
WebSphere

23. DB2 WebSphere CICS IMS / TM Running Environments
Non-Managed Environments
IMS TM 7.1 ( Resetable JVM)
IMS TM 8.1 (Resetable JVM)
CICS 2.1 (Resetable JVM)
DB2 V7 (Resetable JVM)
Managed Environments
WebSphere 4.01 (JVM)
DB2
WebSphere
CICS
Stored
Procedure
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
IMS Java
App
Database
View
DLI
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
IMS Java
App
Database
View
DLI
EJB
JCICS
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
IMS Java
App
Database
View
DLI
Java Virtual Machine
Java Virtual Machine
Java Virtual Machine
IMS / TM
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
IMS Java
App
Database
View
DLI
CEETDLI Interface
JNI
Base A p DB
JDBC / SQL
IMS Java
App
Database
View
DLI M P B M P I F P
ODBA
DRA
JMP JBP
IMS DB
Java Virtual Machine

24. Non-Managed Connection Establishment
Non-Managed Environment (IMS, DB2, CICS)
An application can construct a DataSource prior to its use
Alternatively, a DataSource can be bound to the namespace
Application acquires a Connection from the DataSource
IMSJdbcManagedConnectionFactory mcf = new IMSJdbcManagedConnectionFactory();
mcf.setDRAName("SYS1");
mcf.setDatabaseViewName("samples.dealership.AUTPSB11DatabaseView");
DataSource dataSource = (DataSource)mcf.createConnectionFactory();
Connection connection = dataSource.getConnection();

25. IMS TM Java Access to IMS Data
Run in JVM
IMS 7.1 or later
JDK 1.3
JDBC 2.1
Can only connect to one PSB
Synchpoints done by calls to application package

26. IMS TM Java Access to IMS Data
// Import the IMS Java packages
import com.ibm.ims.db.*;
import com.ibm.ims.application.*;
public class IMSAuto {
/* Entry point of the application. */
public static void main(String args[]) {
// setup message queue access.
IMSMessageQueue messageQueue = new IMSMessageQueue();
InputMessage inputMessage = new InputMessage();
while (messageQueue.getUniqueMessage(inputMessage)) {
create connection…
call back-end…
reply to message queue…
commit… }

27. IMS TM Java Access to IMS Data
/* Entry point of the application. */
public static void main(String args[]) {
access message queue and get message...
// Get connection
IMSJdbcManagedConnectionFactory mcf = new IMSJdbcManagedConnectionFactory();
mcf.setDatabaseViewName("samples.dealership.AUTPSB11DatabaseView");
DataSource dataSource = (DataSource)mcf.createConnectionFactory();
Connection connection = dataSource.getConnection();
// Pass connection to back-end
AutoDealership autoDealership = new AutoDealership(connection);
// Call listModels method and get results in 'output' Object
Vector output = autoDealership.listModels();
reply to message queue...
commit... }

28. IMS TM Java Access to IMS Data
/* Entry point of the application. */
public static void main(String args[]) {
access message queue and get message...
create connection...
call back-end...
// Format and insert output message
OutputMessage outputMessage = new OutputMessage(output);
messageQueue.insertMessage(outputMessage);
// Close connection and commit database before we get next Message.
connection.close();
IMSTransaction.getTransaction().commit(); }

29. CICS Java Access to IMS Data
Run in JVM
CICS TS 2.1
JCICS API
Java version of the CICS API
JDK 1.3
JDBC 2.1
Can only connect to (allocate) one PSB at a time
Only one Connection active at a time in an application
Synchpoint done at deallocate PSB

30. CICS Java Access to IMS Data
// Import the JCICS package
import com.ibm.cics.server.*;
public class CICSAuto {
private static Task task = Task.getTask();
/* Invoked when the CICS transaction corresponding to this class
is executed. */
public static void main(CommAreaHolder cah) {
CICSAuto application = new CICSAuto();
application.listModels(); }
/* The listModels method provides a collection of all automobile
models in the database */
public void listModels() {
method logic here...

31. CICS Java Access to IMS Data
/* The listModels method provides a collection of all automobile
models in the database */
public void listModels() {
// Get connection
IMSJdbcManagedConnectionFactory mcf = new IMSJdbcManagedConnectionFactory();
mcf.setDatabaseViewName("samples.dealership.AUTPSB11DatabaseView");
DataSource dataSource = (DataSource)mcf.createConnectionFactory();
Connection connection = dataSource.getConnection();
// Pass connection to back-end
AutoDealership autoDealership = new AutoDealership(connection);
// Call listModels method and get results in 'output' Object
Vector output = autoDealership.listModels();
display results... }

32. DB2 Stored Procedure Support
Run in JVM
DB2 Version 7
APAR PQ46673 (resetable JVM)
Stored Procedures that access IMS Databases
User-written structured query language (SQL) programs that are stored at the DB2 server and can be invoked by a client application
DB2 handles synchpoint (not stored procedure)
DRA table and name required

33. DB2 Stored Procedure Support
public class DB2Auto() {
public static void listModels(String[] make, String[] model) {
// Get connection
IMSJdbcManagedConnectionFactory mcf = new IMSJdbcManagedConnectionFactory();
mcf.setDRAName("SYS1");
mcf.setDatabaseViewName("samples.dealership.AUTPSB11DatabaseView");
DataSource dataSource = (DataSource)mcf.createConnectionFactory();
Connection connection = dataSource.getConnection();
// Pass connection to back-end
AutoDealership autoDealership = new AutoDealership(connection);
Vector output = autoDealership.listModels();
// Return data to client
make[0] = ((ListModelOutput)output.elementAt(0)).getMake();
model[0] = ((ListModelOutput)output.elementAt(0)).getModel(); }

34. Managed Connection Establishment
Managed Environment (WebSphere)
DataSource deployed in JNDI namespace using:
WebSphere Application Server for z/OS and OS/390 Administration tool (4.01)
Web UI tool (5.0)
Application (EJB) makes a request for the DataSource and acquires a Connection from it
Context ctx = new InitialContext();
DataSource dataSource = (DataSource)ctx.lookup("DealershipDB");
Connection con = dataSource.getConnection();

35. WebSphere 4.01, 5.0 Support Runs in JVM
JDK 1.3
JDBC 2.1
Applications run as Enterprise Java Beans (EJBs)
Access IMS databases through ODBA/DRA
J2EE Connection Architecture
Managed Environment
Connections are managed by application server

36. Enterprise Archive (EJB)
public Vector listModels() throws javax.ejb.EJBException {
InitialContext initialContext = new InitialContext();
// perform JNDI lookup to obtain the DataSource and get the Connection
DataSource dataSource = (DataSource)initialContext.lookup("DealershipDB");
Connection connection = dataSource.getConnection();
AutoDealership dealer = new AutoDealership(connection);
Vector output = dealer.listModels();
return output; }

37. Overview of Application Development Steps
Obtain Resource Adapter Archive (.rar)
Deploy Resource Adapter Archive (install into server)
Deploy DataSource (represents connection to a database)
Deploy Resource Adapter Instance
Build and Deploy Enterprise Archive (.ear)
Two main development components
Servlet
Accesses EJB and invokes methods on the EJB
EJB
Accesses deployed DataSource (resource adapter instance)
Uses DataSource to connect to database and performs business logic

38. Deploy IMS Java Resource Adapter
ra.xml A p
JDBC / SQL DB
We provide a J2EE Resource Adapter Archive (RAR) file containing:
Deployment descriptor (ra.xml)
IMS Custom Service (IMSJdbcCustomService.xml)
Handles initialization and termination of IMS
Latest information associated with installing the IMS JDBC resource adapter (howto.html)
WebSphere will provide tooling to deploy RAR file into server
Add IMS Custom Service
Set CLASSPATH and LIBPATH
Understand how to deploy an instance of an IMS Java Resource Adapter (via ra.xml)
Base
JNI
CEETDLI Interface
ra.xml is the heart of the rar file including things like which Java classes (located in the jar file) are to be used for the connection factory, that the return value will be of type DataSource, and indicating to the installation tool which values must be set (e.g. DRA Name, DatabaseView).
The IMSJdbcCustomService.xml file enables and points to a class in the Jar file with custom services, in this case the calling of CIMS INIT and CIMS TERM call.
The howto.html is a verbose description including steps on how to deploy the rar file.
When handed over to WebSphere it will do the listed steps.

39. DataSource Deployment
Use WebSphere Application Server for z/OS and OS/390 Administration tool
Shipped with WebSphere on OS/390
Create J2EE Resource Instance
Specify IMSJdbcDataSource as the J2EE Resource Type
Configure
DRA Startup Table
Generated DLIDatabaseView
Deploy
JNDI
Deploy
"DealershipDB"
Admin Tool
DataSource
DRA:
DBView:
SYS1
AUTPSB11DatabaseView

40. Build and Deploy Enterprise Archive (ear)
application.xml
JSP
HTML
Servlet
EJB
Home
Web Archive (.war)
Java Archive (.jar)
Enterprise Archive (.ear)
web.xml
Remote
ejb-jar.xml
J2EE Enterprise Application Archive
Complete J2EE application
Must contain
One or more J2EE modules (Java Archive)
Deployment descriptor (application.xml)
Represents a top level view of a J2EE application's contents
May contain
One or more Web modules (Web Archive)
Libraries referenced by J2EE modules

41. Enterprise Archive (Servlet)
Web Archive (.war)
Looks up the EJB home interface in JNDI
Using the home interface, creates the EJB remote interface
Invokes methods on the remote interface
Remote interface uses IIOP to communiate to EJB
Pass-through interface
Passes results of method to a Java Server Page (JSP) for displaying on a web browser
web.xml
HTML
Servlet
JSP

42. Enterprise Archive (EJB)
Java Archive (.jar)
Receives requests from the servlet
Obtains a connection
Looks up the deployed DataSource instance and requests a connection from it
Accesses the database(s) and performs business logic
Sends the results back to the servlet to display
ejb-jar.xml
Home
Remote
EJB

43. WebSphere Runtime Websphere z/OS Home JSP HTML Servlet EJB Home Remote
JNDI
Home
Websphere z/OS
Enterprise Archive (.ear)
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
application.xml
JSP
HTML
Servlet
Web Archive (.war)
web.xml
Java Archive (.jar)
ejb-jar.xml
EJB
Home
Remote

44. WebSphere Runtime Websphere z/OS Home EJB JSP HTML Servlet HTML
JNDI
Home
Websphere z/OS
EJB
JSP
HTML
Servlet
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
application.xml
Web Archive (.war)
Java Archive (.jar)
web.xml
ejb-jar.xml
HTML
Servlet
Home
Remote
JSP
EJB

45. WebSphere Runtime Websphere z/OS HTTP Home Servlet Home EJB HTML
JNDI
DRA:
DBView:
DataSource
SYS1
AUTPSB11DatabaseView
Home
Websphere z/OS
DRA:
DBView:
DataSource
SYS1
AUTPSB11DatabaseView
Servlet
Home
EJB
HTML
Remote
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
Connection
JSP
HTTP
After showing this, discuss plans for future support of RDS.

46. Remote Database Services
Available IMS Version 9
Ability to access IMS DL/I data from a distributed J2EE server
Complete client application deployed on distributed server
Distributed functionality is transparent to client application
Websphere Application Server 5.0 for z/OS still required (server-side)
All client-server communication is handled by new IMS Java components
IMS JDBC distributed Resource Adapter (client-side RAR)
Container Managed EJB (server-side EAR)
Bean Managed EJB (server-side EAR)

47. WebSphere Runtime Websphere z/OS, distributed Websphere z/OS Home EJB
JNDI
Home
Websphere z/OS, distributed
Websphere z/OS
BM EJB
EJB
Servlet
JCA RA
JDBC
Enterprise Archive (.ear)
Web Archive (.war)
Java Archive (.jar)
ejb-jar.xml
application.xml
web.xml
CM EJB
JSP
HTML
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
HTML
Servlet
Home
Remote
JSP
EJB

48. WebSphere Runtime Websphere z/OS, distributed Websphere z/OS IIOP HTTP
JNDI
Home
Home
DataSource
DataSource
Websphere z/OS, distributed
Websphere z/OS
Remote
BM EJB
EJB
Connection
IIOP
Servlet
JCA RA
JDBC
CM EJB
Connection
JSP
HTML
CEETDLI Interface
JNI
Base p A DB
JDBC / SQL
ORB
HTTP

49. Conclusion Managed Non-Managed IMS DB Common J2EE Application
IMS JMP/JBP
JCICS
DB2 Stored Proc
Servlet
Client
HTML
EJB
Application
Application
Stored Procedure
JSP
Common
Common
Common
Common
Application
(Query Processing)
DLI
Database
View A p
JDBC / SQL DB
Common
Base
ODBA
DRA
JNI
IMS DB
CEETDLI Interface