IMS Java Workshop. Simplifying IMS application development using Java Copyright IBM Corporation 2009, All rights reserved.

Transcription

1 IMS Java Workshop 1 of 210

2 ...3 Abstract...3 About this tutorial...3 Objectives...4 System requirements for the tutorial:...5 Checklist for first-time implementation...5 Task 1. Install the tutorial sample project IMS Universal DL/I and JDBC drivers...6 Task 2 Access IMS data with the IMS Universal DL/I driver Task 3 - Access IMS data with the IMS Universal JDBC driver Task 4 Access IMS data from a Java batch processing region on System z Task 5 Access IMS data from a Java message processing region on System z Resources About the authors COBOL/Java Interoperability Abstract About this tutorial Objectives System requirements for the tutorial: Checklist for first-time implementation Task 1. Install the tutorial sample project Task 2 Create an IMS Java transaction that accesses IMS and DB2 Data Task 3 Create COBOL Modules and call them from the IMS Java transaction Task 4 Create a COBOL Transaction that calls a Java class (optional) Resources About the authors DLI Model Utility Lab - Generating IMS DB Metadata Java Class Use Data Perspective with IMS Universal JDBC Driver XMLDB Sample Use the IMS DB Open Database Driver with Hibernate of 210

3 3 of 210

4 Simplifying IMS application development using Java Skill Level: Beginner to Intermediate Richard Tran - Software Developer, IBM Kiran Challapalli - Software Developer, IBM Evgueni Liakhovitch - Software Developer, IBM Kevin Hite - Software Developer, IBM Quddus Chong - Information Developer, IBM Shahin Mohammadi-Rashedi - IMS SOA Demonstration Team Lead IBM Corporation 1 February 2010 Abstract This tutorial takes you through the steps of using Rational Developer for System z Version 7.6 to write a Java application to access IMS databases through the IMS Universal DL/I driver and the IMS Universal JDBC driver. About this tutorial This tutorial will take you through the steps of writing a Java application to access IMS databases using the IMS Universal DL/I driver and the IMS Universal JDC driver. Customers who store business data in IMS databases want an easy way to access their data. They also want to be able to develop applications for IMS using modern and standardized programming solutions. The IMS Universal drivers, part of the IMS Version 11 Open Database solution, are software components that provide Java applications with connectivity to IMS databases from z/os and from distributed environments through TCP/IP. The IMS Universal drivers are built on industry standards and open specifications. Java applications that use the IMS Universal drivers can reside on the same logical partition (LPAR) or on a different LPAR from the IMS subsystem. Two types of connectivity are supported by the IMS Universal drivers: local connectivity to IMS databases on the same LPAR (type-2 connectivity) and distributed connectivity through TCP/IP (type-4 connectivity). This tutorial will help to familiarize you with using two of the IMS Universal drivers: IMS Universal DL/I driver, which provides a stand-alone Java application programming interface (API) for writing granular queries to IMS databases using programming semantics similar to traditional IMS DL/I calls IMS Universal JDBC driver, which provides a stand-alone Java Database Connectivity (JDBC) 3.0 driver for making structured query language (SQL)-based database calls to IMS databases. In the first half of this tutorial, you will run Java applications in a Windows environment and connect to the IMS database using type-4 connectivity mode. In the second half of the tutorial, you will run Java application in a z/os environment and connect to IMS using type-2 connectivity. 4 of 157

5 Distributed and local connectivity with the IMS Universal drivers The IMS Universal drivers support distributed (type-4) and local (type-2) connectivity to IMS databases. The connectivity type is specified in the drivertype connection property. In this tutorial exercise, you will use type-4 connectivity. Type-4 connectivity: With type-4 connectivity, the IMS Universal drivers can run on any platform that supports TCP/IP and a Java Virtual Machine (JVM), including z/os. To access IMS databases using type-4 connectivity, the IMS Universal drivers first establish a TCP/IP-based socket connection to IMS Connect. IMS Connect is responsible for routing the request to the IMS databases using the Open Database Manager (ODBM), and sending the response back to the client application. The DRDA protocol is used internally in the implementation of the IMS Universal drivers. You do not need to know DRDA to use the IMS Universal drivers. Type-2 connectivity: Local (or type-2) connectivity with the IMS Universal drivers is targeted for the z/os platform and runtime environments. Use type-2 connectivity when connecting to IMS subsystems in the same logical partition (LPAR). Figure 1: Distributed (type-4) connectivity Figure 2: Local (type-2) connectivity Objectives To understand and gain hands-on experience creating Java applications to access and manipulate enterprise data residing on the IMS database. Upon completion of this study, you will be able to perform these tasks: Create a Java application to access IMS data by issuing IMS DL/I calls to the IMS database through the IMS Universal DL/I driver Create a Java application to access IMS data by issuing SQL calls to the IMS database through the IMS Universal JDBC driver Deploy and run a Java application in a Windows environment Deploy and run a Java application in IMS Java batch processing (JBP) region that runs directly on the System z mainframe Deploy and run a Java application in IMS Java message processing (JMP) region that runs directly on the System z mainframe 5 of 157

6 System requirements for the tutorial: Software installed on Windows Rational Developer for System z Version 7.6 (RDz) IMS Universal drivers libraries o o imsudb.jar imsutm.jar Sample Java project o IMSDBJavaApplicationLab.zip System software installed on IBM z/os IMS Version 11 configured with Open Database Manager (ODBM) IMS Connect Version 11 Checklist for first-time implementation You may find it helpful have the following information and resources ready before proceeding with your first implementation of the Java applications using the IMS Universal drivers. The information and resources to run this tutorial is provided in the checklist below. Information or resource IMS Connect host name (or IP address) and DRDA port number IMS data store name (IMS ID) Userid and password to connect to IMS Connect MetadataURL pointing to the Java database metadata file generated by the IMS Enterprise Suite DLIModel utility plug-in Workspace directory and project name to be used by RDz when generating artifacts Table 1: Implementation checklist Your environment For this tutorial Obtain this information from IMS system programmers. Obtain this information from IMS system programmers. Obtain this information from IMS system programmers. Obtain this information from IMS application programmers. A naming standard is recommended. Host name: ZSERVEROS.DEMOS.IBM.COM DRDA port number: 7001 Datastore name: IMSD Userid: Will be provided by the workshop instructor Password: Will be provided by the workshop instructor MetadataURL: class:\\com.ibm.ims.db.databaseviews.dfs SAM09DatabaseView Workspace directory: C:\Workspaces7.6\SANDBOX 6 of 157

7 Task 1. Install the tutorial sample project IMS Universal DL/I and JDBC drivers In this section, you will launch a workspace in the Rational Developer for System z, import the tutorial sample project, and verify that the Java library with the code to run the IMS Universal DL/I and JDBC drivers is installed. Step 1: Launch Rational Developer for System z and the Java perspective 1.1. Launch the Rational Developer for System z workspace Start Rational Developer for System z if it is not already started. 1. Select Start > Programs > IBM Software Development Platform > IBM Rational Developer for System z > IBM Rational Developer for System z 2. Specify C:\Workspaces7.6\SANDBOX as your workspace. What is a workspace? A workspace is a directory that stores files for your projects. You can select your own directory or accept the default directory. Artifacts created by RDz will be stored in this directory. Figure 3: Launching a workspace in Rational Developer for System z 7 of 157

8 1.2. Switch to the Java perspective Switch from the default z/os Projects perspective to the Java perspective. Within Eclipse, there are several ways to change perspectives. 1. From the Window menu, select Open Perspective > Other. Figure 4: Opening a perspective in Rational Developer for System z 2. Scroll down and select Java from the Open Perspective dialog box. Figure 5: Choosing the Java perspective 3. Press OK to switch to the Java Perspective. What is a perspective? A perspective defines the initial set and layout of views in the Workbench window. Within the window, each perspective shares the same set of editors. Each perspective provides a set of functionality aimed at accomplishing a specific type of task or works with specific types of resources. For example, the Java perspective combines views that you would commonly use while editing Java source files, while the Debug perspective contains the views that you would use while debugging Java programs. 8 of 157

9 Step 2: Import the sample project The IMSDBJavaApplicationLab sample project The sample project includes all the Java libraries required for this tutorial. The sample also includes sample Java application code that you will customize to connect to an IMS database and issue database access calls Creating a Connection to the z/os mainframe 1. Click Window > Show View > Other to open the Show View dialog box. 2. Scroll down and expand Remote Systems and select Remote Systems and click OK. 9 of 157

10 3. Drag the Remote Systems view next to the Outline view. Moving Views Views can be dragged and placed anywhere within a perspective. Existing views can be closed and additional views can be added at any time. To restore back to the default view layout of a perspective, click on Window > Reset Perspective. 4. In the Remote Systems view, click on the plus at 5. Right click on z/os and select New Connection 10 of 157

11 6. In the New Connection dialog, specify zserveros.demos.ibm.com as the Host name and dallas as the Connection name. The Connection name is a way of referring to a specific connection in the Rational Develop for System z environment. You may be connected to multiple z/os systems at the same time. In this lab, you will be connecting to an actual IMS V11 system that resides in Dallas. 7. Click on Finish to complete creating the connection to the Dallas system. 8. Right click on dallas and click on Connect 11 of 157

12 9. Enter the username and password provided by the workshop instructor in the Enter Password dialog and click OK 12 of 157

13 2.2. Copy the IMSDBJAVAApplicationLab to the Local System 1. Expand,, and 2. Expand /usr/lpp/ims/java/projects folder and copy the IMSDBJavaApplicationLab.zip by selecting it and pressing Ctrl + C. 13 of 157

14 3. Expand,, and. 4. Paste the IMSDBJavaApplicationLab.zip file into the C:\ drive by pressing Ctrl + V Import the IMSDBJavaApplicationLab sample project 1. Click File > Import to open the Import dialog box. Figure 6: Launching the Import dialog box 14 of 157

15 2. From the Import dialog box, select General > Existing Projects into Workspace. Figure 7: Launching the Import Existing Projects into Workspace wizard 3. From the Import Projects page, select Select archive file and click Browse. 4. Browse to the archive C:\IMSDBJavaApplicationLab.zip and click OK. 5. Select the project IMSDBJavaApplicationLab and click Finish. The sample project IMSDBJavaApplicationLab should appear in the Package Explorer view. 15 of 157

16 Figure 8: Package Explorer view after successfully importing the sample project What is a view? Views support editors and provide alternative presentations as well as ways to navigate the information in your Workbench. For example, the Project Explorer and other navigation views display projects and other resources that you are working with. Views also have their own menus. To open the menu for a view, click the icon at the left end of the view's title bar. Some views also have their own toolbars. The actions represented by buttons on view toolbars only affect the items within that view. A view might appear by itself, or stacked with other views in a tabbed notebook. You can change the layout of a perspective by opening and closing views and by docking them in different positions in the Workbench window. 16 of 157

17 Step 3: Verify that the IMS Universal drivers library is located on the build path 1. Right click on the project in the Package Explorer view and select Build Path > Configure Build Path Figure 9: Opening the Java Build Path properties page 2. From the Java Build Path properties page, under the Libraries tab, verify that the file imsudb.jar IMSDBJavaApplicationLab is present. The imsudb.jar library The imsudb.jar file contains the Java classes, interfaces, and metadata required to use the IMS Universal DL/I driver and the IMS Universal JDBC driver. 17 of 157

18 Figure 10: Verifying that the imsudb.jar library is in the build path 3. Click Cancel to exit the properties page. 18 of 157

19 Task 2 Access IMS data with the IMS Universal DL/I driver In this task, you will write a Java application to connect to an IMS database and manipulate data using a DL/Ibased syntax with the IMS Universal DL/I driver. Step 1: Connect to the IMS database through the IMS Universal DL/I driver Before you can execute DL/I calls from your IMS Universal DL/I driver application, you must connect to an IMS database. 1.1 Open the DLIAPIAssigment.java sample application The DLIApiAssignment.java sample application This sample application contains skeleton Java code for connecting to the IMS database and issuing DL/I data access calls using the IMS Universal DL/I driver. 1. From the Package Explorer view, expand IMSDBJavaApplicationLab > src > com.ibm.ims.db.exercises > DLIApiAssignment.java Figure 11: Navigating to the DLIApiAssignment.java sample application 2. From the Package Explorer view, double click on the file DLIApiAssignment.java to open the sample application in the Java editor. Maximizing a view is the ability to increase a view to the maximum possible size on the screen. This can be accomplished by double-clicking on the view tab. To go back to the original view size, doubleclick on the view tab again. 19 of 157

20 Figure 12: The opened DLIApiAssignment.java sample application in the Java editor The Java editor The Java editor provides specialized features for editing Java code. The editor includes the following features: Syntax highlighting Content/code assist Code formatting Import assistance Quick fix Integrated debugging features 1.2 Set the connection properties 1. In the Java editor, scroll down the application source code until you find the Java main method shown in the screenshot below. Figure 13: Java main method in the DLIApiAssignment sample application 2. In line 44 of the code, delete the string REPLACE_THIS and replace it with IMSConnectionSpec.DRIVER_TYPE_4. 20 of 157

21 Moving your cursor to a specific line number RDz provides a shortcut to move your cursor directly to a specific line in an editor. To go to a specific line, press Ctrl + L from the editor. Enter the line number and press OK. Displaying line numbers in the editor Line numbers can be displayed directly in the editor by going to Windows > Preferences. In the Preferences Dialog Menu navigate to General > Editors > Text Editors and check the box next to Show line numbers. Figure 14: Configuring the editor to display line numbers Java code assist RDz provides code assist for Java applications. By pressing CTRL + space, the Java editor will display a list of possible commands variables for that line. Try specifying the driver type by typing IMS and pressing CTRL + space and scrolling to the constant IMSConnectionSpec. Alternatively, when you type a period (.) after a class, the Java code assist displays a menu of methods and variables that the class can invoke. Try it after IMSConnectionSpec and select DRIVER_TYPE_4. 3. In line 56 of the code, specify zserveros.demos.ibm.com as the IMS Connect host name. The datastoreserver property This connection property contains the name or IP address of the data store server (IMS Connect). You can provide either the host name (for example, dev123.svl.ibm.com) or the IP address (for example, ). This property is not required when using type-2 connectivity. 21 of 157

22 Figure 15: Setting the datastoreserver, datastorename, user, password, and portnumber connection properties 4. In line 57 of the code, specify IMSD as the IMS data store name. The datastorename property This connection property contains the name of the IMS data store to access. When using type-4 connectivity, the datastorename property must match either the name of the data store defined to ODBM or be blank. The data store name is defined in the ODBM CSLDCxxx PROCLIB member using either the DATASTORE(NAME=name) or DATASTORE(NAME=name, ALIAS(NAME=aliasname)) parameter. If an alias is specified, you must specify the aliasname as the value of the datastorename property. If the datastorename value is left blank (or not supplied), IMS Connect connects to any available instance of ODBM as it is assumed that data sharing is enabled among all datastores defined to ODBM. 5. In line 58 of the code, specify the z/os user ID for the user name (in double quotation marks). The user ID is provided by the workshop instructor. The user and password properties The user and password connection properties are the user name and password used for the connection to IMS Connect. This information can be obtained from your RACF administrator. The user and password properties are not required when using type-2 connectivity. 6. In line 59 of the code, specify the z/os password for the password (in double quotation marks). The password is provided by the workshop instructor. 7. In line 60 of the code, specify 7001 as the IMS Connect DRDA port number. The portnumber property This connection property is the TCP/IP server port number to be used to communicate with IMS Connect. The port number is defined using the DRDAPORT parameter on the ODACCESS statement in the integrated IMS Connect configuration PROCLIB member. The default port number is The portnumber property is not required when using type-2 connectivity. 8. In line 82 of the code, specify class://com.ibm.ims.db.databaseviews.dfssam09databaseview for the metadataurl property. 22 of 157

23 The metadataurl property This connection property is the location of the database metadata representing the target IMS database. The metadataurl property is the fully qualified name of the Java metadata class generated by the IMS Enterprise Suite DLIModel utility plug-in, based on the PSB and DBD source files of the target IMS database. The format of the metadataurl is: class://packagename.classname Figure 16: Setting the metadataurl connection property The Parts Order sample database This tutorial uses the Parts Order database that is provided in the IMS Installation Verification Program (IVP). You can refer to this diagram when working on the exercises in this tutorial. The diagram below shows the hierarchical structure of the segments in the Parts Order database. Each rectangle represents a database segment. PARTROOT is the root segment of this database, and STANINFO and STOKSTAT are its child segments. STOKSTAT has CYCCOUNT and BACKORDR as its child segments. Each segment contains one or more fields that contain data. For example, PARTKEY is a field in the PARTROOT segment. Figure 17: Segments of the Parts Order database 23 of 157

24 24 of 157

25 Step 2: Issue DL/I calls to access the IMS database The following exercises in this section will show you how to issue DL/I calls in your Java application to retrieve data from the IMS database using the IMS Universal DL/I driver. Lab exercises This task contains several programming exercises for you to complete. These exercises will help to familiarize you with basic data access operations using the IMS Universal DL/I driver. At certain points indicated in the instructions, you will be asked to provide the correct code. For your reference, we have provided the exercise solutions. You can find the code with the exercise solutions from the Package Explorer view by opening IMSDBJavaApplicationLab > com.ibm.ims.db.exercise.solution > DLIApiAssignment.java Exercise 1 - Retrieve data in an IMS database In this exercise, you will retrieve data in an IMS database by issuing Get Unique and Get Next calls through the IMS Universal DL/I driver. Get Unique (GU) This DL/I call retrieves a specific segment or collection of segments on a hierarchic path from an IMS database. The GU call also establishes the position in the database from which additional segments can be processed in a forward direction. Exercise 1 begins on line 103 of the DLIApiAssignment.java sample application, where the function displaypartroot(psb) is invoked. To go to the start of the function, scroll down to line 138, or hold Ctrl and click on the line with the displaypartroot(psb)function invocation. Figure 18: Navigating to the start of Exercise 1 Exercise 1 - Step 1: Define an unqualified SSAList to specify the segments to retrieve 1. In line 146 of the code, specify the SSAList containing the PARTROOT segment by changing the string REPLACE_THIS. The SSAList should be generated based on the PCB. Hint: Using the defined PCB (partspcb1), select the PCB method getssalist(). The SSAList interface The com.ibm.ims.dli.ssalist interface represents a list of segment search arguments (SSAs) 25 of 157

26 used to specify the segments to target in a particular database call. Use the SSAList interface to construct each segment search argument in the list, and to set the command codes and lock class for the segment search arguments. Each SSA in the SSAList can be qualified or unqualified. A SSA qualification can be used to filter the segments to update or retrieve on a hierarchic path. Figure 19: Defining the unqualified segment search argument list Exercise 1 - Step 2: Issue a Get Unique DL/I call to retrieve segments 1. In line 164 of the code, issue a Get Unique DL/I call by changing REPLACE_THIS. Hint: Using the PCB (partspcb1), select the getunique() method. Set the 3 rd parameter to false to indicate that this is not a Get Hold Unique call. Figure 20: Insert code to issue the Get Unique call Exercise 1 Step 3: Issue a Get Next DL/I call 1. In line 178 of the code, issue a Get Next DL/I call by changing REPLACE_THIS. Hint: Using the PCB (partspcb1), select the getnext() method. 26 of 157

27 Figure 21: Insert code to issue a Get Next call Get Next (GN) This DL/I call retrieves the next segment or collection of segments on a hierarchic path from an IMS database. The GN call usually proceeds forward along the hierarchy of a database from the current database position to the next required segment. To modify the GN call to start at an earlier position than the current position in the database, use an IMS command code. Exercise 1 Step 4: Run the application and verify the output results 1. Press Ctrl + S to save your changes to the files. 2. Right click on the Java editor and select Run As > Java Application, as shown in Figure 29. Figure 22: Running the Java application 3. An Errors in Workspace dialog box will appear. Click on Proceed. 27 of 157

28 4. In the Console view, verify that the output results look like the screenshots below. Figure 23: Exercise 1 output results in the Console view (beginning of the results) Figure 24: Exercise 1 output results in the Console view (end of the results) Exercise 2: Retrieve batch data in an IMS database In this exercise, you will retrieve batch data from an IMS database by issuing a Batch Retrieve call through the IMS Universal DL/I driver. Batch Retrieve Use the batch retrieve call to retrieve multiple segments from an IMS database in a single call. Instead of a client application making multiple GU and GN calls, IMS performs all the GU and GN processing and returns the results back to the client in a single batch network operation. The fetch size property determines how much data is returned on each batch network operation. Exercise 2 begins on line 110 of the DLIApiAssignment.java sample application. At the beginning of Exercise 2, the code for this exercise has been commented out. Exercise 2 Step 1: Uncomment the code for Exercise 2 1. In the Java editor, highlight lines 112 to 114 of the DLIApiAssignment.java sample application and press Ctrl + / to uncomment the code. 28 of 157

29 Figure 25: Code for Exercise 2 (before uncommenting) Code comments allows comment statements that will not be compiled and executed to be inserted directly into the application source code. In RDz, blocks of code can be commented and uncommented by highlighting that block and pressing Ctrl + /. Figure 26: Code for Exercise 2 (after uncommenting) 2. The function displaypartrootusingbatchretrieve contains the code for the batch retrieval operation. In the Java editor, move your mouse to the displaypartrootusingbatchretrieve(psb)function invocation and press F3 to open the function declaration. Exercise 2 Step 2: Issue a Batch Retrieve call to retrieve multiple segments 1. In line 210 of the code, issue a Batch Retrieve call by changing REPLACE_THIS. Hint: Using the PCB (partspcb1), select the batchretrieve() method. Figure 27: Insert code to issue a batch retrieve call Exercise 2 Step 3: Commit the unit of work 1. In line 227 of the code, commit your unit of work by changing REPLACE_THIS. Hint: Using the psb, select the commit() method. Committing and rolling back DL/I transactions 29 of 157

30 The IMS Universal DL/I driver provides support for local transactions with the commit and rollback methods. A local transaction consists of a unit of work with several units of recovery. An IMS Universal DL/I driver application can commit or roll back changes to the database within a unit of recovery. In the IMS Universal DL/I driver, the local transaction is scoped to the PSB instance. No explicit call is needed to begin a local transaction. After the unit of work starts, the application makes DL/I calls to access the database and create, replace, insert, or delete data. The application commits the current unit of recovery by using the PSB.commit() method. The commit operation instructs the database to commit all changes to the database that are made from the point when the unit of work started, or from the point after the last commit or rollback method call, whichever was most recent. Figure 28: Insert code to issue a commit call Exercise 2 Step 4: Run the application and verify the output results 1. Press Ctrl + S to save your changes to the files. 2. Right click on the Java editor and select Run As > Java Application, as shown in Figure An Errors in Workspace dialog box will appear. Click on Proceed. 4. In the Console view, verify that the output results look like the screenshots below. Figure 29: Exercise 2 output results in the Console view (beginning of the results) Figure 30: Exercise 2 output results in the Console view (end of the results) 30 of 157

31 Exercise 3: Create SSALists with multiple segments, specify qualifications, and mark specific fields for retrieval In this exercise, you will mark specific segment fields for retrieval from the IMS database. You will also specify the number of rows of data for the IMS Universal DL/I driver to retrieve. Marking segment fields for retrieval with the IMS Universal DL/I driver In your Java application, you can specify which segment fields are to be returned from a database retrieve call by using the markfieldforretrieval or the markallfieldsforretrieval methods. Following the IMS default, all of the fields in the lowest level segment specified by the SSAList are initially marked for retrieval. The markfieldforretrieval method This SSAList method is used to mark a specific field for retrieval from the database. The markfieldforretrieval method is used together with getpathforretrievereplace() and with the data retrieval methods in the PCB interface. When a retrieve call is made, the resulting Path object will contain all the fields that have been marked for retrieval. The markallfieldsforretrieval method This method is used to mark all fields in the specified segment for retrieval from the database. The markallfieldsforretrieval method is used together with getpathforretrievereplace() and with the data retrieval methods in the PCB interface. When a retrieve call is made the resulting Path object will contain only the fields marked for retrieval. Following the IMS default, all of the fields in the lowest level segment specified by the SSAList are initially marked for retrieval. Exercise 3 begins on line 116 of the DLIApiAssignment.java sample application. At the beginning of Exercise 3, the code for this exercise has been commented out. Exercise 3 Step 1: Uncomment the code for Exercise 3 1. In the Java editor, highlight lines 118 to 120 of the DLIApiAssignment.java sample application and press Ctrl + / to uncomment the code. Figure 31: Code for Exercise 3 (before uncommenting) Figure 32: Code for Exercise 3 (after uncommenting) 31 of 157

32 2. The function displaybackorder contains the code for the retrieval. In the Java editor, move your mouse over the displaybackorder(psb)function invocation and press F3 to open the function declaration. Exercise 3 Step 2: Build an unqualified SSAList 1. In line 246 of the code, build an unqualified SSAList containing a range of segments (PARTROOT, BACKORDR) by changing REPLACE_THIS. Hint: Using the PCB (partspcb1), select the getssalist() method. Figure 33: Insert code to build the unqualified SSAList Exercise 3 - Step 3: Mark the fields to retrieve 1. In line 262 of the code, mark the fields to retrieve from the segments specified in the SSAList by changing REPLACE_THIS. Hint: Using the SSAList (ssalist), select the markfieldforretrieval() method. Set the 3 rd parameter to true to indicate that the field should be retrieved from the database. Hint: You will need to call the method twice, once for each field. Figure 34: Insert code to mark the segment fields to retrieve Exercise 3 Step 4: Specify the number of rows to fetch per network call 1. In line 274 of the code, set the fetch size by changing REPLACE_THIS. Hint: Using the PCB (partspcb1), select the setfetchsize() method. 32 of 157

33 Fetch size property The fetch size is the number of rows physically retrieved from the IMS database per network call. A list of rows is represented by a Path instance containing one or more segments that match the segment search argument criteria specified by an SSAList. This is set for you internally. You can also set the fetch size using the setfetchsize method from the PCB interface. Setting the fetch size allows a single request to return multiple rows at a time, so that each application request to retrieve the next row does not always result in a network request. Figure 35: Insert code to change the fetch size Exercise 3 Step 5: Print the retrieved segment fields from the path 1. On line 287, change the System.out.println statement to print the values of the WORKORDER and ORDERQTY fields returned by IMS. Exercise 3 Step 6: Run the application and verify the output results 1. Press Ctrl + S to save your changes to the files. 2. Right click on the Java editor and select Run As > Java Application, as shown in Figure A Errors in Workspace dialog box will appear. Click on Proceed. 4. In the Console view, verify that the output results look like the screenshots below. Figure 36: Exercise 3 output result in the Console view 33 of 157

34 Exercise 4: Utilize command codes for DL/I In this exercise, you will add a command code in the SSAList to retrieve a sequence of segments. Command codes for DL/I SSAs can also include one or more command codes, which can change and extend the functions of DL/I calls. For example, you can use the D command code to retrieve or insert a sequence of segments in a hierarchic path with one call rather than retrieving or inserting each segment with a separate call. A call that uses the D command code is called a path call. Exercise 4 begins on line 122 of the DLIApiAssignment.java sample application. At the beginning of Exercise 4, the code for this exercise has been commented out. Exercise 4 Step 1: Uncomment the code for Exercise 4 1. In the Java editor, highlight lines 123 to 125 of the DLIApiAssignment.java sample application and press Ctrl + / to uncomment the code. Figure 37: Code for Exercise 4 (before uncommenting) Figure 38: Code for Exercise 4 (after uncommenting) 2. The function displaypartrootandbackorder contains the code for the batch retrieval operation. In the Java editor, the displaypartrootandbakcorder(psb)function invocation and press F3 to open the function declaration. Exercise 4 Step 2: Add a command code to the SSAList 1. In line 333 of the code, add an IMS command code by changing REPLACE_THIS. Starting with the SSAList (ssalist), select the addcommandcode() method. The command code D can be specified with SSAList.CC_D 34 of 157

35 Figure 39: Insert the code to add a IMS command code Exercise 4 Step 3: Run the application and verify the output results 1. Press Ctrl + S to save your changes to the files. 2. Right click on the Java editor and select Run As > Java Application, as shown in Figure A Errors in Workspace dialog box will appear. Click on Proceed. 4. In the Console view, verify that the output results look like the screenshots below. Figure 40: Exercise 4 output result in the Console view 35 of 157

36 Task 3 - Access IMS data with the IMS Universal JDBC driver In this task, you will write a Java application to connect to an IMS database and manipulate data using structured query language (SQL) with the IMS Universal JDBC driver. What is JDBC? Java Database Connectivity (JDBC) is an application programming interface (API) that Java applications use to access relational databases or tabular data sources. The JDBC API is the industry standard for database-independent connectivity between the Java programming language and any database that has implemented the JDBC interface. The client uses the interface to query and update data in a database. IMS support for JDBC lets you write Java applications that can issue dynamic SQL calls to access IMS data and process the result set that is returned in tabular format. The IMS Universal JDBC driver is designed to support a subset of the SQL syntax with functionality that is limited to what the IMS database management system can process natively. Its DBMS-centric design allows the IMS Universal JDBC driver to fully leverage the high performance capabilities of IMS. The IMS Universal JDBC driver also provides aggregate function support, and ORDER BY and GROUP BY support. The JDBC programming model The IMS Universal JDBC driver supports the standard programming model for using JDBC drivers. For more information about the JDBC programming model, see the JDBC Basics tutorial by SUN. Step 1: Connect to the IMS database through the IMS Universal JDBC driver Before you can execute SQL calls from your IMS Universal JDBC driver application, you must connect to an IMS database. 1.1 Open the JDBCApiAssignment.java sample application The JDBCApiAssignment.java sample application This sample application contains skeleton Java code for connecting to the IMS database and issuing SQL data access calls using the IMS Universal JDBC driver. 1. In the Package Explorer view, expand IMSDBJavaApplicationLab > src > com.ibm.ims.db.exercise > JDBCApiAssignment.java 36 of 157

37 Figure 41: Navigating to the JDBCApiAssignment.java sample application 2. From the Package Explorer view, double click on JDBCApiAssignment.java to open the sample application in the Java editor. Figure 42: The opened JDBCApiAssignment.java sample application in the Java editor 1.2 Set the connection properties 1. In line 22 of the code, specify that this application will connect using type-4 connectivity. 2. In line 31, specify zserveros.demos.ibm.com as the host for IMS Connect. 3. In line 32, specify IMSD as the datastore name. 4. In line 33, specify the z/os user ID for the user name (in double quotation marks). The user ID is provided by the workshop instructor. 5. In line 34, specify the z/os password for the password (in double quotation marks). The password is provided by the workshop instructor. 6. In line 35, specify 7001 as the IMS Connect DRDA port number. Step 2: Issue SQL calls to access the IMS database The following exercises in this section will show you how to issue SQL calls in your Java application to retrieve data from the IMS database using the IMS Universal JDBC driver. 37 of 157

38 How do IMS database elements map to relational database elements? The IMS Universal JDBC driver performs the necessary translation between IMS and relational database elements. The table below summarizes the database element mappings. Hierarchical database elements in IMS Segment name Segment instance Segment field name Segment unique key Virtual foreign key field Equivalent relational database elements Table name Table row Column name Table primary key Table foreign key Exercise 1 - Retrieve all fields of a segment In this exercise, you will retrieve all the fields of a segment by issuing a SELECT statement using the IMS Universal JDBC driver. Using the SELECT keyword Use the SELECT statement to retrieve data from one or more tables. The result is returned in a tabular result set. The syntax for a simple SELECT query is: SELECT column_name(s) FROM table_name An asterisk * can be used in place of column_name to represent all columns of that table. Because IMS is a hierarchical database, column_name maps to field_name and table_name maps to segment_name. When using the SELECT statement with the IMS Universal JDBC driver: If you are selecting from multiple tables and the same column name exists in one or more of these tables, you must table-qualify the column or an ambiguity error will occur. The FROM clause must list all the tables you are selecting data from. The tables listed in the FROM clause must be in the same hierarchic path in the IMS database. In Java applications using the IMS JDBC drivers, connections are made to PSBs. Because there are multiple database PCBs in a PSB, queries must specify which PCB in a PSB to use. To specify which PCB to use, always qualify segments that are referenced in the FROM clause of an SQL statement by prefixing the segment name with the PCB name. You can omit the PCB name only if the PSB contains only one PCB. 1. Move your cursor to line 20 of the sample application. You will modify this statement to issue different SQL queries in this task. 38 of 157

39 Figure 43: Modify the query string to issue different SQL queries in the sample application 2. Construct a SQL query to retrieve all of the fields of the partspcb1.partroot segment. Note that the segment name must start with the PCB qualifier. 3. Run and verify the output of the SQL query. Some SQL query examples to help you get started: SELECT part, partdesc FROM partroot WHERE partkey='02106b1293p009 ' SELECT * FROM stokstat SELECT * FROM stankey WHERE PARTROOT_PARTKEY='02N51P3003F000 ' Exercise 2 - Retrieve fields of a segment based on a conditional statement In this exercise, you will retrieve specific fields of a segment based on a conditional statement by issuing a SELECT statement with a WHERE clause using the IMS Universal JDBC driver. Using the WHERE keyword Use the WHERE keyword in SQL to select data conditionally. The syntax for a conditional select query is: SELECT column_name(s) FROM table_name WHERE column_name operator value Note that for text values, the value must be enclosed in quotes. Operators on text values perform binary comparisons. The IMS Universal JDBC driver converts the WHERE clause in an SQL query to a segment search argument (SSA) list when querying a database. SSA rules restrict the type of conditions you can specify in the WHERE clause. 1. Construct a SQL query that will display all fields of the partspcb1.partroot segment where the partkey field is greater than a specific value. 2. Run and verify the output of the SQL query. 39 of 157

40 Exercise 3 - Order SQL query output by field values In this exercise, you will retrieve data from a segment in sorted order issuing a SELECT statement with a ORDER BY clause using the IMS Universal JDBC driver. Using the ORDER BY keyword Use the ORDER BY clause in SQL to sort the results of a SQL query in ascending or descending order. The syntax for a ordered select query is: SELECT column_name(s) FROM table_name ORDER BY column_name ASC DESC Note that ASC is used for ascending order and DESC is used for descending order. The field names that are specified in a ORDER BY clause must match exactly the field name that is specified in the SELECT statement. 1. Construct a SQL query that will retrieve all fields of the partspcb1.partroot segment and sort the results by the part field in descending order. 2. Run and verify the output of the SQL query. Exercise 4 - Retrieve a specific field of a segment In this exercise, you will retrieve a specific field in a segment. By querying only specific fields instead of selecting all of the fields in a particular segment, you can reduce network overhead when using the IMS Universal JDBC driver. 1. Construct a SQL query that will display only the part field from the partspcb1.partroot segment. 2. Run and verify the output of the SQL query. Exercise 5 Retrieve multiple fields from multiple segments In this exercise, you will issue a SELECT query to retrieve data from segments that are on the same and on different hierarchical paths in the IMS database. The PARTROOT and the BACKORDR segments are on the same hierarchic path, while the CYCCOUNT segment is on a separate hierarchic path. Retrieving fields from multiple segments In SQL queries to relational databases, the JOIN keyword is typically used to query data from multiple tables based on a relationship between the tables. IMS does not support using the JOIN keyword explicitly, because IMS is a hierarchical database and it is possible that two segments are unrelated to each other. However, an implicit join will be performed if the segments fall within the same hierarchical path. The syntax for this is the same as for a SELECT query. Note that multiple column names and table names can be specified as long as a comma is used to separate them. IMS allows issuing a SELECT call to retrieve data from segments that are not on the same hierarchical path, if a logical relationship has been defined between them. 1. Construct a SQL query that will display the part field from the partspcb1.partroot segment and the backkey field from the partspcb1.backordr segment. 2. Run and verify the output of the SQL query. 3. Construct a SQL query that will display the physicalcount field from the partspcb1.cyccount segment and the workorder field form the partspcb1.backordr segment. 4. Run and verify that the query fails. 40 of 157

41 Task 4 Access IMS data from a Java batch processing region on System z In this task, you will write a Java application to run from a Java batch processing region, connect to an IMS database using type-2 connectivity, and manipulate data using structured query language (SQL) with the IMS Universal JDBC driver. Java batch processing region A Java batch processing (JBP) region is a type of IMS dependent region that provides a Java Virtual Machine (JVM) environment for running Java applications. Use the JBP region to run flexible programs that perform batch-type processing online and can access the IMS message queues for output, like non-message-driven batch message processing (BMP) applications. JBP applications are started by submitting a job with JCL or from TSO. JBP applications are like BMP applications, except that they cannot read input messages from the IMS message queue. JBP applications can access IMS data in a DB/DC or DBCTL environment Step1: Switch to the z/os Projects perspective z/os Projects In RDz, a z/os project allows a set of resources (contained in MVS or z/os UNIX System Services subprojects) to be gathered and handled as a unit. z/os projects serve primarily as a tool for organizing and working with multiple load modules. A z/os project is essentially a folder that contains one or more related subproject. Subprojects contain the files and programs for a single load module. They are created under a particular remote system, and the properties of that system act as the defaults for subproject properties. 1. From the menu, select Window > Open Perspective > Other. Figure 44: Opening a perspective in Rational Developer for System z 2. From the Open Perspective dialog box, select z/os Projects. 41 of 157

42 Figure 45: Choosing the z/os Projects perspective 3. Press OK to switch to the z/os Projects Perspective. Step 2: Create the z/os Project To develop a Java application that resides and run on z/os, you must define a z/os project and one or more MVS subprojects or z/os UNIX subprojects. 1. In the z/os Projects view, right click to bring up the context menu and select New > z/os Project Figure 46: Launching the Create New z/os Project wizard 42 of 157

43 2. In the New z/os Project Name page, enter IMS as the Project name and select Create an MVS subproject. Click Finish. Figure 47: Specifying the new z/os project name 3. In the MVS Subproject Name and Location page, enter IMS MVS as the subproject name. Select the Do not associate the subproject with a property group radio button and click on Finish. Note that you must be successfully connected to the remote z/os system to complete this step. 43 of 157

44 Figure 48: Specifying the MVS subproject properties 44 of 157

45 Step 3: Create a z/os UNIX subproject 1. Right click on the IMS project in the z/os Projects view and select New > z/os UNIX Subproject. Figure 49: Launching the Create New z/os UNIX Subproject wizard 2. In the Parent project page, select IMS as the parent project and click on Next. Figure 50: Specifying the parent z/os project 3. In the New z/os UNIX Subproject page, specify IMS USS as the subproject name. Figure 51: Specifying the z/os UNIX subproject name 4. Click on the Browse button next to the Remote Working Directory field. 45 of 157

46 Figure 52: Specifying the remote working directory 5. In the browse dialog box, expand dallas > z/os UNIX files and select My Home. Click OK. Figure 53: Selecting the home directory as the remote working directory 6. In the New z/os UNIX Subproject wizard, check the Default Target Environment box and click on Finish. Figure 54: Specifying the target environment 46 of 157

47 Step 4: Add JCL files to the z/os subprojects To run the sample JBP application, you will use Job Control Language (JCL) scripts. For this tutorial, the JCL scripts have been created for you. The JCL files are stored in the dallas remote z/os system and you will need to transfer the files to your z/os project. 4.1 Add data sets to the MVS subproject 1. In the Remote Systems view, expand dallas > MVS Files > My Data Sets > IMPOTxx.Java.JCL, where xx is the last two digits of the z/os user ID provided by the workshop instructor. IMPOTxx should be replaced with your z/os user ID. For the screenshots in this task, the user ID is IMPOT In the Remote Systems view, select and drag these files to the IMS MVS project folder in the z/os Projects view: DFSJBP.jcl DFSJVMAP.jcl DFSJVMEV.jcl DFSJVMMS.jcl JBPRUN1.jcl Figure 55: Selecting the data sets from the remote z/os system Transferring files In RDz, you can easily transfer files between MVS, USS, and your local file system by using cut and paste or drag and drop from the Remote Systems view. 4.2 Add files to the UNIX subproject 1. In the Remote Systems view, expand z/os UNIX Files, then select and drag the My Home directory to the IMS USS project folder in the z/os Projects view. 47 of 157

48 Figure 56:Selecting the z/os UNIX files in the home directory 2. In the z/os Projects view, right click on IMS USS and select New > z/os UNIX File Filter. Figure 57: Launching the New z/os UNIX File Filter wizard What is a file filter? In RDz, file filters can be used to alter the host items that are displayed in the Remote Systems or z/os Projects view to only show resources with names that match a filter string. Filtering makes the data sets within a file system easier to navigate. 3. In the New z/os UNIX File Filter page, specify impotxx as the filter name field and click Next. IMPOTxx should be replaced with your z/os user ID. For the screenshots in this task, the user ID is IMPOT of 157

49 Figure 58: Specifying the file filter name 4. In the New Filter String page, click Add to add a new filter string. Figure 59: Adding a new filter string 5. In the Browse dialog box, expand dallas > z/os UNIX Files and select My Home. Click OK. Figure 60: Specifying the file filter name pattern 6. Click Finish to create the z/os UNIX file filter. 49 of 157

50 Step 5: Modify the JBPApplication.java sample application Modify the JBP sample application to issue a SQL call to retrieve data from the IMS database using the IMS Universal JDBC driver in type-2 connectivity mode. 5.1 Switch to the Java Perspective 1. Click on Java in the top right corner of the Rational Developer for System z workspace to change to the Java perspective. Figure 61: Switching to the Java perspective 5.2 Open the JBPApplication.java sample application 1. In the Package Explorer view, expand IMSDBJavaApplicationLab > src > com.ibm.ims.db.exercise. Figure 62: Finding the JBPApplication.java sample application 2. Double click on JBPApplication.java to open the sample application in the Java editor. 50 of 157

51 Figure 63:The opened JBPApplication.java sample application in the Java editor 3. In line 37 of the code, change the SQL query to retrieve all fields from the PARTROOT segment of the PCB PARTSPCB1. Notice in line 38 that this Java application uses type-2 connectivity. 4. Press Ctrl + S to save your changes. Step 6: Generate a JAR file You must generate a JAR file for the JBP application, in order to easily deploy the application on the remote z/os system. What is a JAR file? A Java Archive (JAR) file enables you to package multiple files into a single archive file. In this tutorial, you will use RDz to generate a JAR file containing the class and metadata files of the sample application. 6.1 Generate a JAR file containing the JBP application 1. In the Project Explorer view, right click on IMSDBJavaApplicationLab and select Export. 51 of 157

52 Figure 64: Launching the Export wizard 2. In the Export dialog box, expand Java and select JAR file, then click Next. Figure 65: Choosing to export the Java project as a JAR file 3. In the JAR File Specification page, set the JAR file field to C:\Documents and Settings\Administrator\Desktop\lab.jar. Make sure the IMSDBJavaApplicationLab,.classpath, and.project checkboxes are selected. Click Finish. 52 of 157

53 Figure 66: Specifying resources to export to the JAR File 4. If you get a Jar Export dialog box as shown below, click OK. Figure 67: JAR export warning message. Press OK to continue. 53 of 157

54 6.2 Move the JAR file to the z/os UNIX file system 1. Click on z/os Projects in the top right corner of the Rational Developer for System z workspace to change to the z/os Projects perspective. Figure 68: Switching to the z/os Projects perspective 2. In the Remote Systems view, expand Local > Local Files > Drives > Documents and Settings > Administrator > Desktop. 3. Select the lab.jar file that you generated in the previous step. Copy and paste (or drag and drop) to transfer the JAR file to the impotxx folder under the IMS USS project in the z/os Projects view. IMPOTxx should be replaced with your z/os user ID. For the screenshots in this task, the user ID is IMPOT27. Figure 69: Transferring the lab.jar file to the IMS USS subproject Step 7: Update the JCL files Update the JCL files to run the JBP application. 7.1 Update the JBPRUN1.JCL file 1. In the z/os Projects view, expand IMS > IMS MVS. Double click on IMPOTxx.JAVA.JCL(JBPRUN1).jcl to open the JCL file in the editor. 54 of 157

55 Figure 70: Selecting the JBPRUN1.jcl file 2. In the opened JBPRUN1.jcl file, find and replace all references to IMPOTxx with the z/os user ID provided by the workshop instructor. Figure 71: Updating references to IMPOTxx in JBPRUN1.jcl Find/Replace RDz provides a Find and Replace tool to search for and replace specific statements or portions of statements. To bring up the Find/Replace dialog box, in the editor view, click on the file to edit. From the menu, select Edit > Find/Replace. Alternatively, press Ctrl + F. 3. In the opened JBPRUN1.jcl file, set the Password field to the z/os password provided by the workshop instructor. 55 of 157

56 Figure 72: Updating the password in the JBPRUN1.jcl file 4. Press Ctrl + S to save your changes to the file. 7.2 Update the DFSJBP.JCL file 1. In the z/os Projects view, expand IMS > IMS MVS. Double click on IMPOTxx.JAVA.JCL(DFSJBP).jcl to open the file in the editor. Figure 73: Selecting the DFSJBP.jcl file 2. In the opened DFSJBP.jcl file, look for the PROCLIB section and replace the reference to IMPOTxx with the z/os user ID provided by the workshop instructor. Figure 74: Updating references to IMPOTxx in DFSJBP.jcl 56 of 157

57 3. Press Ctrl + S to save your changes to the file. 7.3 Update the DFSJVMMS.JCL file What is the DFSJVMMS.jcl file? The DFSJVMMS.jcl file specifies the Java classpath. The classpath contains the location of the lab.jar file that you created previously, along with the location of the IMS Universal driver libraries (imsudb.jar and imsutm.jar). To enable remote debugging, you can edit the last 3 lines: -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address= In the z/os Projects view, expand IMS > IMS MVS. Double click on IMPOTxx.JAVA.JCL(DFSJVMMS).jcl to open the file in the editor. Figure 75: Selecting the DFSJVMMS.jcl file 2. In the opened DFSJVMMS.jcl file, replace the reference to impotxx with the z/os user ID provided by the workshop instructor. Figure 76: Updating the reference to impotxx in DFSJVMMS.jcl 3. Press Ctrl + S to save your changes to the file. Step 8: Run the JBP application You are now ready to submit the job to the z/os system and run the JBP application. 8.1 Submit the job for the JBP application 1. In the z/os Projects view, expand IMS > IMS MVS. Right click on IMPOTxx.JAVA.JCL(JBPRUN1).jcl and select Submit. 57 of 157

58 Figure 77: Submitting the job for the JBP application 2. In the Remote Systems view, expand dallas > z/os UNIX Files > My Home. Double click on the JVM.OUT file and verify the output from your SQL query. Figure 78: Navigating to the JVM.OUT file 58 of 157

59 Task 5 Access IMS data from a Java message processing region on System z In this task, you will write a Java application to run from a Java message processing region, connect to an IMS database using type-2 connectivity, and manipulate data using structured query language (SQL) with the IMS Universal JDBC driver. For this task, the workshop instructor will provide you with a unique class level number and a unique transaction code. Java message processing region A Java message processing (JMP) region is a type of IMS dependent region that provides a Java Virtual Machine (JVM) environment for running Java applications. JMP regions are like message processing program (MPP) regions, but JMP regions allow the scheduling only of Java programs. A JMP application is started when there is a message in the queue for the JMP application and IMS schedules the message to be processed. JMP applications, like MPP applications, are executed through transaction codes submitted by users at terminals and from other applications. Each transaction code represents a transaction that the JMP application processes. Step 1: Add JCL files to the z/os subproject To run the sample JMP application, you will use Job Control Language (JCL) scripts. For this tutorial, the JCL scripts have been created for you. The JCL files are stored in the dallas remote z/os system. 1.1 Add the MVS datasets to the IMS MVS subproject 1. In the Remote Systems view, expand dallas > MVS Files > My Data Sets > IMPOTxx.Java.JCL, where xx is the last two digits of the z/os user ID provided by the workshop instructor. IMPOTxx should be replaced with your z/os user ID. For the screenshots in this task, the user ID is IMPOT In the Remote Systems view, select and drag these files to the IMS MVS project folder in the z/os Projects view: DFSJMP.jcl JMPRUN1.jcl 59 of 157

60 Figure 79: Selecting the MVS datasets from the remote z/os system Step 2: Update the JCL files Update the JCL files to run the JMP application. 2.1 Update the JMPRUN1.JCL file 1. In the z/os Projects view, expand IMS > IMS MVS. Double click on IMPOTxx.JAVA.JCL(JMPRUN1).jcl to open the JCL file in the editor. Figure 80: Selecting the JMPRUN1.jcl file 2. In the opened JMPRUN1.jcl file, find and replace all references to IMPOTxx with your z/os user ID. 60 of 157

61 Figure 81: Updating references to IMPOTxx in JMPRUN1.jcl 3. In the opened JMPRUN1.jcl file, set the Password field to your z/os password. Figure 82: Updating the password in the JMPRUN1.jcl file 4. In the opened JMPRUN1.jcl file, change JMPCLXX to the class level number provided by the workshop instructor. For example, if the class number is 14 then change JMPCLXX to JMPCL14. Also change the CL1= parameter to the class number, e.g. 014! 61 of 157

62 Figure 83: Changing JMPCLXX 5. Press Ctrl + S to save your changes to the file. 2.2 Update the DFSJMP.JCL file 1. In the z/os Projects view, expand IMS > IMS MVS. Double click on IMPOTxx.JAVA.JCL(DFSJMP).jcl to open the file in the editor.. Figure 84: Selecting the DFSJMP.jcl file 2. In the opened DFSJMP.jcl file, look for the PROCLIB section and replace the reference to IMPOTxx with your z/os user ID. 3. Set the CL1 field to the class level number provided by the workshop instructor. For example, if the class number is 14, change CL1=XXX to CL1=014. Figure 85: Changing the CL1 field 4. Hit Ctrl + S to save your changes to the file. 62 of 157

63 Step 3: Run the JMP application You are now ready to submit the job to the z/os system and run the JMP application. Once the JMP region is running, you can invoke the JMP application. 3.1 Submit the job for the JMP Application 1. In the z/os Projects view, expand IMS > IMS MVS. Right click on IMPOTxx.JAVA.JCL(JMPRUN1).jcl and select Submit. Figure 86: Submitting the job for the JMP application 3.2 Verify that the JMP application is running 1. In the Remote Systems view, right click on dallas and select Host Connection Emulator. The Host Connection Emulator The host connection emulator is a terminal emulator that automatically connects to a remote z/os system for which you have an active connection in the Remote Systems view. You can use this 63 of 157

64 feature to log on and send commands to a remote z/os system. Figure 87: Launching the Host Connection Emulator 2. In the Host Connection Emulator, type in TSO and press Ctrl. 64 of 157

65 Figure 88: Welcome screen of the dallas remote z/os system 3. In the TSO/E logon screen, enter the z/os user ID provided by the workshop instructor and hit Ctrl. IMPOTxx should be replaced with your z/os user ID. For the screenshots in this task, the user ID is IMPOT27. Figure 89: Entering your z/os user ID in the terminal emulator 4. In the TSO/E logon screen, enter the z/os password provided by the workshop instructor and hit Ctrl. 65 of 157

66 Figure 90: The TSO/E logon screen 5. Press Ctrl to continue. Figure 91: Welcome message after successful login 6. In the ISPF Primary Option Menu, at the Option prompt, type in log and press Ctrl. 66 of 157

67 Figure 92: ISPF Primary Option Menu 7. In the log, locate the 3 digit identifier next to IMSD. For example, in the following figure, this identifier is At the Command Input prompt, type /###/DISPLAY ACTIVE REGION, where ### is the 3 digit identifier from the previous step. 67 of 157

68 Figure 93: Entering the DISPLAY ACTIVE REGION command 9. In the terminal display, verify the region is running by scrolling down and to the right using the F8 and F11 keys. The JMP region with the job name JMPCL## (where ## is the class level number provided by the workshop instructor) should be in WAITING status. Figure 94: Verifying that the JMP region is running Step 4: Invoke the JMP application The JMP application is now ready to process incoming messages on the message queue. To invoke the JMP application, you will run the InvokeJMP.java that is provided in the sample project. The InvokeJMP.java application This Java application uses the IMS Enterprise Suite Connect API for Java to send a input message to IMS through IMS Connect. In this tutorial, you will set a SQL query as the input message data. The input message contains a transaction code that causes the JMP application to execute and process the input message. 4.1 Switch to the Java perspective 1. Click on Java in the top right of Rational Developer for System z to switch to the Java Perspective. 68 of 157

69 4.2 Modify the InvokeJMP.java application 1. In the Package Explorer view, expand IMSDBJavaApplicationLab > src > com.ibm.ims.iconapi Figure 95: Finding the InvokeJMP.java application 2. Double click on InvokeJMP.java to open the file in the Java editor. Figure 96: The opened InvokeJMP.java application in the Java editor 3. In line 24 of the code, set the host name to zserveros.demos.ibm.com. Figure 97: Setting the host name property 4. In line 26, set the IMS Connect port number to of 157

70 5. In line 47, set the RACF user ID to the z/os User ID provided by the workshop instructor. Figure 98: Setting the IMS Connect connection properties 6. In line 48, set the RACF password to the z/os password provided by the workshop instructor. 7. In line 49, set the RACF group name to ADMIN. 8. In line 53, set the transaction code to the transaction code provided by the workshop instructor. Make sure to include a blank space at the end of the transaction code. Figure 99: Setting the trancode property 9. In line 54, set the IMS Datastore Name to IMSD. 10. In line 63, construct a SQL query to retrieve all fields from the PARTROOT segment. Set the SQL query string as the input message data. Select * from PARTROOT. 11. Press Ctrl + S to save your changes to the file. 70 of 157

71 4.3 Run the InvokeJMP.java application 1. In the Java editor, right click to bring up the context menu and select Run As > Java Application. Figure 100: Running the InvokeJMP.java application 2. Verify the output in the Console view. 71 of 157

72 Figure 101: Output results in the Console view Step 5: Stop the JMP region 1. Switch to the z/os Projects perspective by clicking z/os Projects in the top right of Rational Developer for System z. 2. In the Remote Systems view, right click on dallas and select Host Connection Emulator. 3. In the Host Connection Emulator, type in TSO and press Ctrl. 4. In the TSO/E logon screen, enter the z/os user ID provided by the workshop instructor and press Ctrl. 5. In the TSO/E logon screen, Enter the z/os password provided by the workshop instructor and press Ctrl. 6. Press Ctrl to continue. 7. In the ISPF Primary Option Menu, at the Option prompt, type in log and press Ctrl. 8. In the log, locate the 3 digit identifier next to IMSD. 9. At the Command Input prompt, type /###/DISPLAY ACTIVE REGION, where ### is the 3 digit identifier from the previous step. 10. In the terminal display, verify the region is running by scrolling down and to the right using the F8 and F11 keys. The JMP region with the job name JMPCL## (where ## is the class level number provided by the workshop instructor) should be in WAITING status. 11. Identify the region identifier (REGID) associated with the JMPCL## region. For example, in the figure below, the REGID is 3. Figure 102: Finding the region identifier for the running JMP region 12. In the terminal display, scroll back to the right using the F10 key and scroll to the bottom with F Identify the three digit identifier next to IMSD. For example, in the figure below, this number is of 157

73 Figure 103: Preparing to stop the JMP region 14. At the Command Input prompt, type in /###/STOP REGION X and press Ctrl, where ### is the three digit number from the previous step and X is the REGID you identified earlier. Figure 104: Stopping the JMP region 73 of 157

74 Resources Learn View the Information Management Software for z/os Solutions Information Center for the latest information and educational resources available for Information Management System (IMS), including the Java API reference for the IMS Universal drivers. Visit the Rational software area on developerworks for technical resources and best practices for Rational Software Delivery Platform products. Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge. Subscribe to the Rational Edge e-zine for articles on the concepts behind effective software development. Check out the Information Management IMS zone on developerworks. Subscribe to the IBM developerworks newsletter, a weekly update on the best of developerworks tutorials, articles, downloads, community activities, webcasts and events. Browse the technology bookstore for books on these and other technical topics. Get products and technologies Download trial versions of IBM Rational software. Download a trial version of IBM Rational Developer for system z. Discuss Participate in the discussion forum. Check out developerworks blogs and get involved in the developerworks community. About the authors Richard Tran is a Software Developer at IBM for IMS SOA Solutions Kiran Challapalli is an Advisory Software Developer at IBM for IMS SOA Solutions Evgueni Liakhovitch is a Software Developer at IBM Kevin Hite is a Software Developer at IBM Quddus Chong is an Information Developer at IBM Shahin Mohammadi-Rashedi is an IMS SOA Demonstration Team Lead at IBM 74 of 157

75 Simplifying IMS application development using Java COBOL/Java Interoperability Skill Level: Beginner to Intermediate Denis Gaebler IT Specialist, IBM Richard Tran - Software Developer, IBM Kiran Challapalli - Software Developer, IBM Evgueni Liakhovitch - Software Developer, IBM Kevin Hite - Software Developer, IBM Quddus Chong - Information Developer, IBM Shahin Mohammadi-Rashedi - IMS SOA Demonstration Team Lead IBM Corporation 1 February 2010 Abstract This tutorial takes you through the steps of using Rational Developer for System z Version 7.6 to write an IMS Java application that accesses the IMS Message Queue, an IMS Database and DB2. Enhance this application to call an existing COBOL module. Last but not least a COBOL application that calls an existing Java class. About this tutorial This tutorial will take you through the steps of writing a COBOL application that accesses IMS DB and DB2 and will call a Java class that accesses IMS DB and DB2. There is an increasing need in the industry to integrate existing applications (e.g. COBOL) with Java. There are several reasons for that, e.g. that Java is becoming the most versatile programming languages and companies already have started to deliver business functionality in Java only. This tutorial will help to familiarize you with two interoperability scenarios: An IMS Java transaction will be extended to call logic from a existing COBOL subroutine running in an IMS Java Message Region (JMP). An existing IMS COBOL transaction will be extended to call logic from a Java class as subroutine running in a traditional IMS region. In this tutorial, you will run IMS applications as transactions in IMS, either as Java main program in a Java Message Region (JMP) or as a COBOL main program in a Message Processing Region for traditional languages (MPR). COBOL/Java Interoperability 75 of 162

76 COBOL Java Interoperability per example Attached are the pictures of the two scenarios that are going to be implemented in this tutorial. Java calls COBOL: The transaction JC0xTRAN is implemented with the JC0xJavaCobol.java class, which has a sample implementation on accessing the IVPDB2 IMS sample database and creates, populates and deletes a sample database in DB2. There is a requirement to dynamically call a COBOL subroutine which is a traditional NODLL COBOL program (JC0xMAIN). Since Java is compiled with DLL and z/os language environment does not allow dynamic switches between DLL and NODLL, a wrapper module (JC0xKPM) which is DLL compiled will be statically linked with JC0xMAIN in order for the dynamic call to work. The JC0xCOB is an OO COBOL class with does the mapping between Java and COBOL (call the procedural COBOL and the COBOL compiler generates a JNI compliant shared library JC0xCob.so plus the JNI wrapper Java class JC0xCob.java). COBOL calls Java: The transaction CJ0xTRAN is implemented by having a traditional NODLL Cobol program (CJ0xMAIN) which accesses the IVPDB2 IMS sample database and the SYSIBM.SYSDATABASE table. It should dynamically call the CJ0xHello.java class which also accesses the IMS and DB2 databases. The dll compiled Cobol module (CJ0xJAVA) implements the calls to the Java class. In order to be dynamically callable by CJ0xMAIN it requires a wrapper to be statically linked with (CJ0xKAPS). Java in a traditional IMS region requires special runtime options (e.g. XPLINK(ON), therefore a CEEUOPT module is required. Figure 105: Java calls COBOL scenario JC0xJavaCobol.java in JC0ximsdb2.jar JC0xCob.java in JC0ximsdb2.jar Figure 106: COBOL calls Java scenario CJ0xMAIN NODLL, DB2: SYSDATABASES, IMS: IVPDB2 JC0xCOB DLL, Cobol Class JC0xCob.so JC0xKPM DLL JC0xMAIN NODLL, DB2: SYSDATABASES, IMS: IVPDB2 CJ0xKAPS NODLL CJ0xJAVA LIB, DLL init(string) display() CJ0xHello.java in CJ0ximsdb2.jar COBOL/Java Interoperability 76 of 162

77 Objectives To understand and gain hands-on experience creating mixed language COBOL and Java applications to access and manipulate enterprise data residing on IMS database and DB2. Upon completion of this study, you will be able to perform these tasks: Create a Java application to access IMS and DB2 data Deploy and run this application Enhance this Java application to call a COBOL module as subroutine, which also accesses IMS and DB2 data Deploy and run this application Create a COBOL application to access IMS and DB2 data Deploy and run this application Enhance this COBOL application to call a Java class, which also accesses IMS and DB2 data System requirements for the tutorial: Software installed on Windows Rational Developer for System z Version 7.6 (RDz) IMS and DB2 drivers libraries o o imsjavabase.jar, imsjavatm.jar, imsjdbc.jar db2jcc.jar, db2jcc_javax.jar, db2jcc_license_cisuz.jar Sample Java project o COBOLJavaApplicationLab.zip System software installed on IBM z/os IMS Version 11 configured with Java and DB2 access IMS Connect Version 11 Sample COBOL and JCL libraries o o o JCL library: IMPOT6x.COBJAVA.JCL Procedure library: IMPOT6x.COBJAVA.PROCLIB Source library: IMPOT6x.COBJAVA.SOURCE Checklist for first-time implementation You may find it helpful have the following information and resources ready before proceeding with your first implementation of the Java applications using the IMS Universal drivers. The information and resources to run this tutorial is provided in the checklist below. Information or resource IMS Connect host name (or IP address) and port IMS Connect Port Number for Transactions Table 1: Implementation checklist Your environment For this tutorial Obtain this information from IMS system Host name: ZSERVEROS.DEMOS.IBM.COM COBOL/Java Interoperability 77 of 162

78 IMS data store name (IMS ID) DB2 Subsystem Name Userid and password to connect to IMS Connect Workspace directory and project name to be used by RDz when generating artifacts programmers. Obtain this information from IMS system programmers. Obtain this information from IMS system programmers. Obtain this information from IMS system programmers. A naming standard is recommended. Port number: 7000 Datastore name: IMSD DB2 SSID: DSNA Userid: Will be provided by the workshop instructor Password: Will be provided by the workshop instructor Workspace directory: C:\Workspaces7.6\SANDBOX Java calls COBOL scenario COBOL calls Java scenario Transaction Class for Java and IMS Regions and group number for the lab Obtain this information from IMS system programmers. Obtain this information from IMS system programmers. Obtain this information from IMS system programmers. Trancode: JC0xTRAN Program Name: JC0xTRAN DB2 Plan: JC0xTRAN Trancode: CJ0xTRAN Program Name: CJ0xTRAN DB2 Plan: CJ0xTRAN Class: 00x Group Number: x (will be assigned by the instructors) Please remember to rename all occurrences of x throughout the lab with the group number you are assigned to. COBOL/Java Interoperability 78 of 162

79 Task 1. Install the tutorial sample project In this section, you will launch a workspace in the Rational Developer for System z, import the tutorial sample project, and verify that the Java librarys with the code to run the IMS Java samples is installed. Step 1: Launch Rational Developer for System z and the Java perspective 1.3. Launch the Rational Developer for System z workspace Start Rational Developer for System z if it is not already started. 3. Select Start > Programs > IBM Software Development Platform > IBM Rational Developer for System z > IBM Rational Developer for System z 4. Specify C:\Workspaces7.6\SANDBOX as your workspace. What is a workspace? A workspace is a directory that stores files for your projects. You can select your own directory or accept the default directory. Artifacts created by RDz will be stored in this directory. Figure 107: Launching a workspace in Rational Developer for System z COBOL/Java Interoperability 79 of 162

80 1.4. Switch to the Java perspective Switch from the default z/os Projects perspective to the Java perspective. Within Eclipse, there are several ways to change perspectives. 4. From the Window menu, select Open Perspective > Other. Figure 108: Opening a perspective in Rational Developer for System z 5. Scroll down and select Java from the Open Perspective dialog box. Figure 109: Choosing the Java perspective 6. Press OK to switch to the Java Perspective. What is a perspective? A perspective defines the initial set and layout of views in the Workbench window. Within the window, each perspective shares the same set of editors. Each perspective provides a set of functionality aimed at accomplishing a specific type of task or works with specific types of resources. For example, the Java perspective combines views that you would commonly use while editing Java source files, while the Debug perspective contains the views that you would use while debugging Java programs. COBOL/Java Interoperability 80 of 162

81 Step 2: Import the sample project The IMSDBJavaApplicationLab sample project The sample project includes all the Java libraries required for this tutorial. The sample also includes sample Java application code that you will customize to connect to an IMS database and issue database access calls Creating a Connection to the z/os mainframe 10. Click Window > Show View > Other to open the Show View dialog box. 11. Scroll down and expand Remote Systems and select Remote Systems and click OK. COBOL/Java Interoperability 81 of 162

82 12. Drag the Remote Systems view next to the Outline view. Moving Views Views can be dragged and placed anywhere within a perspective. Existing views can be closed and additional views can be added at any time. To restore back to the default view layout of a perspective, click on Window > Reset Perspective. 13. In the Remote Systems view, click on the plus at 14. Right click on z/os and select New Connection COBOL/Java Interoperability 82 of 162

83 15. In the New Connection dialog, specify zserveros.demos.ibm.com as the Host name and dallas as the Connection name. The Connection name is a way of referring to a specific connection in the Rational Develop for System z environment. You may be connected to multiple z/os systems at the same time. In this lab, you will be connecting to an actual IMS V11 system that resides in Dallas. 16. Click on Finish to complete creating the connection to the Dallas system. 17. Right click on dallas and click on Connect COBOL/Java Interoperability 83 of 162

84 18. Enter the username and password provided by the workshop instructor in the Enter Password dialog and click OK 19. Click OK if there is any message saying that the connection is not SSL secured. This security warning can be ignored. Feel free to check the box for not showing this message again. COBOL/Java Interoperability 84 of 162

85 2.2. Copy the COBOLJAVAApplicationLab to the Local System 5. Expand,, and 6. Expand /usr/lpp/ims/java/projects folder and copy the COBOLJavaApplicationLab.zip by selecting it and pressing Ctrl + C.???Bild ändern COBOL/Java Interoperability 85 of 162

86 7. Expand,, and. 8. Paste the COBOLJavaApplicationLab.zip file into the C:\ drive by pressing Ctrl + V Import the COBOLJavaApplicationLab sample project 6. Click File > Import to open the Import dialog box. Figure 110: Launching the Import dialog box COBOL/Java Interoperability 86 of 162

87 7. From the Import dialog box, select General > Existing Projects into Workspace. Figure 111: Launching the Import Existing Projects into Workspace wizard 8. From the Import Projects page, select Select archive file and click Browse. 9. Browse to the archive C:\COBOLJavaApplicationLab.zip and click OK. 10. Select the project COBOLJavaApplicationLab and click Finish. The sample project COBOLJavaApplicationLab should appear in the Package Explorer view. It might be required to switch to the Java perspective to see that imported project. COBOL/Java Interoperability 87 of 162

88 Figure 112: Package Explorer view after successfully importing the sample project What is a view? Views support editors and provide alternative presentations as well as ways to navigate the information in your Workbench. For example, the Project Explorer and other navigation views display projects and other resources that you are working with. Views also have their own menus. To open the menu for a view, click the icon at the left end of the view's title bar. Some views also have their own toolbars. The actions represented by buttons on view toolbars only affect the items within that view. A view might appear by itself, or stacked with other views in a tabbed notebook. You can change the layout of a perspective by opening and closing views and by docking them in different positions in the Workbench window. COBOL/Java Interoperability 88 of 162

89 Step 3: Verify that the IMS libraries are located on the build path 4. Right click on the project in the Package Explorer view and select Build Path > Configure Build Path Figure 113: Opening the Java Build Path properties page 5. From the Java Build Path properties page, under the Libraries tab, verify that the files imsjavabase.jar, imsjavatm.jar, imsjdbc.jar COBOLJavaApplicationLab is present. The ims??.jar libraries The ims??.jar files contain the Java classes, interfaces, and metadata required to compile IMS Java applications that use the IMS Universal DL/I driver. COBOL/Java Interoperability 89 of 162

90 Figure 114: Verifying that the jar libraries are in the build path 6. Click Cancel to exit the properties page. COBOL/Java Interoperability 90 of 162

91 Task 2 Create an IMS Java transaction that accesses IMS and DB2 Data In this task, you will write a Java application to connect to an IMS database and query data using a DL/I based syntax with the IMS Universal DL/I driver. In addition you will connect to a DB2 database and query data using a JDBC based syntax with the DB2 Universal Database Driver. Lab steps This task contains several programming steps for you to complete. These steps will help to familiarize you with Cobol/Java interoperability. At certain points indicated in the instructions, you will be asked to provide the correct code. For your reference, we have provided the exercise solutions. You can find the code with the exercise solutions from the Package Explorer view by opening COBOLJavaApplicationLab > com.ibm.cjlab.exercise.solution > JC0xJavaCobol.java (as an example for the sample code for JC0xJavaCobol.java) Step 1: Update the dlimethod() method to connect to the IMS database through the IMS Universal DL/I driver and issue DLI statements to it Before you can execute DL/I calls from your IMS Universal DL/I driver application, you must connect to an IMS database. The connect inside an IMS Java application is done implicit, but it is required to create a connection to the DL/I Database and some other Java objects 1.1 Rename the JC0xJavaCobol.java sample application The JC0xJavaCobol.java sample application This sample application contains skeleton Java code for connecting to the IMS database and issuing SQL data access calls using the IMS Universal DL/I driver as well as connecting to the DB2 database and issuing SQL data access calls using the DB2 Universal Database driver. 3. From the Package Explorer view, expand COBOLJavaApplicationLab > src > com.ibm.cjlab > JC0xJavaCobol.java COBOL/Java Interoperability 91 of 162

92 Figure 115: Navigating to the JC0xJavaCobol.java sample application 4. Right click the JC0xJavaCobol.java file and select the Refactor > Rename menu option to rename the class source file according to the naming conventions such as that x is replaced with the group number you were assigned to. Figure 116: Select the rename menu option on the JC0xJavaCobol.java file 5. In the Rename Compilation Unit window rename the JC0xJavaCobol.java file by replacing the x with your assigned group number and click Finish. COBOL/Java Interoperability 92 of 162

93 Figure 117: Renaming the JC0xJavaCobol.java sample application with group 2 as an example 6. In the next Window, you are being told that the file has a main method and since it will be renamed, it might not be accessible by other classes anymore. Ignore this and click Finish. Group Assignment number and instructions The following instructions will contain an x for all file, transaction, plan, userids, high level qualifiers, path names, etc. Please keep in mind, that all the time you will have to replace the x with the group number that was assigned to you. Otherwise you might not run your own samples. So most of the following screenshots will be based on group number Open the JC0xJavaCobol.java sample application The JC0xJavaCobol.java sample application This sample application contains skeleton Java code for connecting to the IMS database and issuing SQL data access calls using the IMS Universal DL/I driver as well as connecting to the DB2 database and issuing SQL data access calls using the DB2 Universal Database driver. 1. From the Package Explorer view, expand COBOLJavaApplicationLab > src > com.ibm.cjlab > JC0xJavaCobol.java COBOL/Java Interoperability 93 of 162

94 Figure 118: Navigating to the JC0xJavaCobol.java sample application 2. From the Package Explorer view, double click on the file JC0xJavaCobol.java to open the sample application in the Java editor. Maximizing a view is the ability to increase a view to the maximum possible size on the screen. This can be accomplished by double-clicking on the view tab. To go back to the original view size, doubleclick on the view tab again. Figure 119: The opened JC0xJavaCobol.java sample application in the Java editor COBOL/Java Interoperability 94 of 162

95 The Java editor The Java editor provides specialized features for editing Java code. The editor includes the following features: Syntax highlighting Content/code assist Code formatting Import assistance Quick fix Integrated debugging features 1.3 Update the dlimethod() for the DL/I calls to IMS DB IVPDB2 9. In the Java editor, scroll down the application source code until you find the dlimethod() method shown in the screenshot below. Solutions Folder The coded SQL can be found in the JC0xJavaCobol.java file in the solutions folder. Figure 120: dlimethod() method in the JC0xJavaCobol sample application 10. In line 96 of the code, delete the string REPLACE_THIS and replace it with new IVPDB2DatabaseView(); in order to create an instance of the DLIDatabaseView we can work with. Moving your cursor to a specific line number RDz provides a shortcut to move your cursor directly to a specific line in an editor. To go to a specific line, press Ctrl + L from the editor. Enter the line number and press OK. Displaying line numbers in the editor Line numbers can be displayed directly in the editor by going to Windows > Preferences. In the Preferences Dialog Menu navigate to General > Editors > Text Editors and check the box next to Show line numbers. COBOL/Java Interoperability 95 of 162

96 Figure 121: Configuring the editor to display line numbers Java code assist RDz provides code assist for Java applications. By pressing CTRL + space, the Java editor will display a list of possible commands variables for that line. Try selecting the IVPDB2Databaseview by replacing REPLACE_THIS with new + space and pressing CTRL + space and scrolling to the class IVPDB2DatabaseView com.ibm.cjlab. Now to conform to Java syntax you need to add the paranthesis and the semicolon. 11. In line 98 of the code, specify create an connection instance of DLIConnection by using the dbview object as input for createinstance. So change REPLACE_THIS to dbview. 12. In line 103 of the code, create the workarea instance of the database segment to be queried, by coding the clonesegment method of the dbview object instance. The clonesegment method of the dbview object This method takes two input parameters. The first one is of type String and represents the name of the IMS database PCB and the second parameter is of type String and takes the segment name for which an DLISegment instance is to be created. This workarea can then be used to retrieve segments from DL/I calls to the IMS Database. 13. In line 109 of the code, create the SSA object for the A segment. This segment has a key name of A The SSA should select the database entry of the LAST2 database record. So in order to do that, code the SSA.createInstance() method. The createinstance method of the SSA object This method takes four input parameters. The first one is of type String and takes the segment name as input. The second one is of type String and takes the key name of the segment as input. The third one codes the SSA Operator values, which are predefined constants within the SSA object, e.g. SSA.EQUALS for the equals operator. Fourth parameter is of type String and is the actual key value that should be searched for. 14. In line 113 of the code, create the workarea instance of the SSAList object, which is required to store all SSA instances for the IMS database call to be executed. The createinstance method of the SSAList object This method takes one input parameter, which is of type string and represents the name of the COBOL/Java Interoperability 96 of 162

97 database PCB for which the SSAList should be created. In other words, it creates an SSAList for the database that should be accessed with DL/I. 15. In line 116 store the SSA created earliear in the SSAList object by using the addssa method. 16. Now you are done with the changes for the DL/I call to the IMS database and the rest of the code which will execute the DL/I call and in case a database record is found, it will be displayed and sent to the caller of the transaction by inserting an outputmessage to the IOPCB using the messagequeue object. 17. Save the changes by using the menu File > Save or by pressing the <STRG>-S key combination. Figure 122: Complete dlimethod() method source Step 2: Update the db2method() method to connect to the DB2 database using the DB2 Universal Database Driver and to issue SQL statements to it The following exercises in this section will show you how to issue DB2 SQL calls in your Java application to work with DB2 using the DB2 Universal Database driver. Solutions Folder The coded SQL can be found in the JC0xJavaCobol.java file in the solutions folder. COBOL/Java Interoperability 97 of 162

98 2.1 Update the db2method() for the SQL calls to a DB2 database 1. In the Java editor, scroll down the application source code until you find the db2method() method shown in the screenshot below. Figure 123: db2method() method in the JC0xJavaCobol sample application 2. In line 195 of the code, delete the string REPLACE_THIS and replace it with the String that is required to create a new table, that has a name of TEST_TABLE and two columns; one named CHAR_COL with type CHAR(20) and one named INT_COL with type INT. CREATE TABLE syntax reminder CREATE TABLE tablename (COLUMN1 TYPE1, COLUMN2 TYPE2) As an example a fixed length string of length 5 would be CHAR(5). The Integer Type in a database can be reflected by the data type INT. 3. In line 210 of the code, delete the string REPLACE_THIS and replace it with the string that would be required to create a prepared Statement that has two parameter markers for the use of inserting multiple rows with different values. COBOL/Java Interoperability 98 of 162

99 INSERT TABLE syntax for prepared Statements The parameter markers are?. So the syntax for inserting a row into a database with four columns looks like this: INSERT INTO tablename VALUES (?,?,?,?) 4. In line 223 of the code, delete the string REPLACE_THIS and replace it with the string that would be required to create a select Statement for the two columns (CHAR_COL and INT_COL) with an additional ORDER BY clause to order by INT_COL. SELECT syntax reminder SELECT column1, column2, column3 FROM dbname ORDER BY column1 5. In line 243 of the code, the UPDATE Sql statement that was coded in the previous lines should be executed. Delete the string REPLACE_THIS and replace it with the string object that represents the SQL for updating the table. 6. In line 265 of the code, the DELETE Sql statement that was coded in the previous lines should be executed. Delete the string REPLACE_THIS and replace it with the string object that represents the SQL for deleting some rows of the table. 7. In line 284 of the code, delete the string REPLACE_THIS and replace it with the string that would be required to remove/drop the table that we were working with during the last couple of SQL calls. DROP TABLE syntax reminder DROP TABLE tablename 8. In line 286 of the code, the DROP TABLE statement that was coded in the previous step should be executed. Delete the string REPLACE_THIS and replace it with the string object that represents the SQL for removing/dropping the table. 9. Save the changes by using the menu File > Save or by pressing the <STRG>-S key combination. All syntax errors in the java class should now be gone and the red x symbol on the left top of the editor window should have disappeared. COBOL/Java Interoperability 99 of 162

100 Figure 124: Complete saved db2method() method and JC0xJavaCobol class source without errors Step 3: Compile the JC0xJavaCobol.java sample application and upload the jar file to the host Before you can execute DL/I calls from your IMS Universal DL/I driver application, you must connect to an IMS database. The connect inside an IMS Java application is done implicit, but it is required to create a connection to the DL/I Database and some other Java objects 3.1 Compile the JC0xJavaCobol.java sample Compile using Ant script Ant is a script language for similar tasks as makefiles or Job Control (JCL) is doing. It basically can automate a sequence of steps, which would have led going through wizards or multiple manual steps. 1. From the Package Explorer view, expand COBOLJavaApplicationLab > src > scripts > build_jc0ximsdb2_jar.xml COBOL/Java Interoperability 100 of 162

101 Figure 125: Navigating to the build_jc0ximsdb2_jar.xml ant script 2. Double click the file build_jc0ximsdb2_jar.xml and replace all occurrences of x with your assigned group number. As an example the file name for group two will be changed to JC02imsdb2.jar 3. Save the changes by using the menu File > Save or by pressing the <STRG>-S key combination. 4. Right click the build_jc0ximsdb2_jar.xml file and select the Run As > Ant Build menu option to execute the script. Figure 126: Sucessful execution of build_jc0ximsdb2_jar.xml ant script 3.2 Upload the jar file to the host Upload with the Export to Remote site wizard The next sample shows how to use the Export wizard to upload the jar file to the zserveros host into your userids home HFS directory. 1. From the Package Explorer view, click on COBOLJavaApplicationLab > src > scripts. COBOL/Java Interoperability 101 of 162

102 Figure 127: Navigating to the build_jc0ximsdb2_jar.xml ant script 2. Choose menu option File > Refresh or press F5. This will refresh the view and the JC0ximsdb2.jar file should appear. 3. Right click the JC0ximsdb2.jar file and select the Export menu option to start the export wizard. Figure 128: Start the export wizard with the jar file 4. In the export wizard select Other > Remote File System and Click Next. COBOL/Java Interoperability 102 of 162

103 Figure 129: Start the export wizard with the jar file 5. On the next page the JC0ximsdb2.jar should be already preselected. COBOL/Java Interoperability 103 of 162

104 Figure 130: Export wizard with the selected jar file 6. For selecting the destination folder click Browse. 7. In the Browse for Folder Window select Dallas (or the connection name that you choose to use for the zserveros.dfw.ibm.com host). Figure 131: Export wizard with the selected connection name 8. In the Browse for Folder Window select Root > / > u > impot6x according to your group settings and click OK. The remote folder name should now appear as in the screenshot below were it is shown as example for group 2 pointing to impot62 directory and prefixed with your computers name (CL33213K in the example here). Figure 132: Export wizard with the selected remote destination folder for the jar file 9. Leave all other settings as they are and click Finish. 10. The wizard ends without an error message. Now check for the jar file being on the mainframe. Switch to the z/os Projects perspective, go to the Remote Systems view and expand dallas > z/os Unix Files > My Home and check that the JC0ximsdb2.jar file is there. COBOL/Java Interoperability 104 of 162

105 Figure 133: Uploaded jar file in the Remote Systems View Step 4: Start an IMS Java Message Region, run the sample application and check the output Before we can run the IMS Java transaction that accesses both IMS DB and DB2, it is required to adjust the environment settings, job control, define the transactions and programs to IMS and start the java message region. 4.1 Change the settings for the IMS Java Message Region Settings and JCL for the IMS Java Message region The message region for Java programs has to be started, but first its settings have to be changed to suit the needs for your group id (e.g. name, transaction class, etc.) The following steps will be described based on userid IMPOT62, so make sure that you use 6x for all the steps, where x is your assigned group id. 1. Switch to the z/os projects perspective. 2. On the left hand side go to the z/os projects explorer, click the right mouse button and select File -> New -> Project. 3. The new project wizard will open. Select z/os > z/os Project. COBOL/Java Interoperability 105 of 162

106 Figure 134: New z/os Project 4. Click Next and enter COBOLJavazosproject as the project name. Make sure the Create an MVS subproject is selected too and click Finish. Figure 135: New z/os Project 5. The New MVS Subproject wizard will appear. Enter MVSSubproject as name, Select Do not associate the subproject with a property group and click Finish. COBOL/Java Interoperability 106 of 162

107 Figure 136: MVS subproject name and location Figure 137: MVS subproject property group association 6. Expand the COBOLJavazosproject in the project explorer. Figure 138: MVS subproject property group association 7. In the Remote Systems view expand the dallas > MVS Files > My Data Sets (IMPOTxx) view and Select the following datasets: IMPOT6x.CJLAB.SOURCE IMPOT6x.CJLAB.PROCLIB IMPOT6x.CJLAB.JCL COBOL/Java Interoperability 107 of 162

108 Figure 139: MVS subproject property group association 8. Drag the selected files over to the MVSSubproject. The should then appear under MVSSubproject. Figure 140: MVS subproject property group association 9. Expand the CJLAB.PROCLIB dataset and Double click the DFSJVMAP proclib member to adjust the mapping from the transaction code. Figure 141: Opened DFSJVMAP member in the MVSSubproject of COBOLJavazosproject 10. Replace the x with your assigned group number. Save the changes. 11. Double click the DFSJVMEV proclib member to adjust the path environment variables. COBOL/Java Interoperability 108 of 162

109 Figure 142: Opened DFSJVMEV member in the MVSSubproject of COBOLJavazosproject 12. Replace the x with your assigned group number (line 15). Save the changes. 13. Double click the DFSJVMMS proclib member to adjust the CLASSPATH. Figure 143: Opened DFSJVMMS member in the MVSSubproject of COBOLJavazosproject 14. Replace the x with your assigned group number (line 8). Save the changes. COBOL/Java Interoperability 109 of 162

110 15. Double click the DFSJMP proclib member to adjust the transaction classes and the proclib member name to take the modified proclib members from. Figure 144: Opened DFSJMP member in the MVSSubproject of COBOLJavazosproject 16. Replace the x with your assigned group number (line 2 plus line 32). Save the changes. 4.2 Create the Transaction Codes and Program Names for the sample transactions by using DRD with the Batch SPOC utility DRD and Batch SPOC Dynamic Resource Definition (DRD) allows the dynamic addition and removal of certain IMS control blocks which used to have been created using IMS System Generations. DRD also provides a batch utility that allows to issue DRD or Type 2 IMS Commands using JCL. This Batch SPOC utility will be used to create the Program Name and the Transaction codes that we are using. The PSBs are already in the ACBLIB to avoid multiple people doing online change at the same time, since currently the online change is still required to activate the new ACBLIB where the new PSB have been added. 1. Expand the CJLAB.JCL dataset and Double click the DEFTRAN jcl member to adjust the naming conventions for the transaction codes and program names. COBOL/Java Interoperability 110 of 162

111 Figure 145: Opened DEFTRAN JCL member in the MVSSubproject of COBOLJavazosproject 2. Replace the x with your assigned group number (lines 2, 10, 11, 12, 14, 15 and 16). Save the changes. Please note that lines 12 and 15 require two changes (remember to also change the x in the CLASS(x) parameters in lines 12 and 15). 3. Right click the DEFTRAN job control member and click on Submit to execute the JCL. COBOL/Java Interoperability 111 of 162

112 Figure 146: Submit DEFTRAN job control 4. The following window will display the successful submit of the job. Figure 147: Job submission confirmation 5. To view the job output and check successful execution of the job, go to the Remote Systems View on the right hand side, scroll down to JES and expand JES > My Jobs. COBOL/Java Interoperability 112 of 162

113 Figure 148: Expanded JES > My Jobs view 6. To view the job output double click on the first DEFTRAN job output in the list. The job output will open. Figure 149: DEFTRAN Job Output view COBOL/Java Interoperability 113 of 162

114 7. Make sure that the Return code is 00 (check the DEFTRAN row in line 9 column RC). Scroll downwards and for each of the four commands make sure that CC is 0. Figure 150: Job submission confirmation 8. The transactions and programs are now successfully defined to IMS. The required PSBs have been pre created to avoid the required Online Changes. 4.3 Create the DBRM dataset, bind the plan for the DB2 access and grant execution rights on the plan Create DBRM dataset, Bind the plan and Grand Execution rights In order to avoid User 3056 abends when executing an IMS transaction that accesses DB2, it is required to bind a plan. In addition, for the later COBOL/Java interoperability samples, when a plan is required that includes the package(s) for the Cobol modules that issue SQL calls, it is necessary for the user to create a DBRM partitioned dataset, which contains the precompiler generated DBRM member for the packages to be bound. 1. Double click the JC0XBIND member from the JCL library. COBOL/Java Interoperability 114 of 162

115 Figure 151: Opened JC0XBIND member 2. Replace the x with your assigned group number (lines 12, 17, 27, 49 and 65). Save the changes. 3. Right click the JC0XBIND JCL member and click Submit. 4. The Job submission confirmation window will appear. To view the job output and check successful execution of the job and all job steps, go to the Remote Systems View on the right hand side, scroll down to JES and expand JES > My Jobs. 5. To view the job output double click on the first JX0XBIND job output in the list. The job output will open. COBOL/Java Interoperability 115 of 162

116 Figure 152: JC0XBIND Job Output 6. Make sure that all fourc Job steps ended with RC = 00. In addition please check if the correct plans were bound in order to successfully execute the IMS Java transaction. Keep in mind, that the x had to be replaced with the assigned group number. 4.4 Start the IMS Java Message Region 1. Double click the JC0XJMP member from the JCL library. COBOL/Java Interoperability 116 of 162

117 Figure 153: Opened JC0XJMP member 2. Replace the x with your assigned group number (lines 4, 12, 15 and 19). Save the changes. 3. Right click the JC0XJMP JCL member and click Submit. 4. The job submission confirmation will appear. In the Remote Systems explorer expand JES > My Jobs. If it is already expanded, select My Jobs, click the right mouse button and click Refresh (as an alternative the F5 butten can be pressed instead using the context menu option). Figure 154: Refresh JES > My Jobs view in the Remote Systems Explorer 5. Double click the JC0xJMP Job Output to check that the message region is running. A running job will be marked by a slightly different icon than a finished job. COBOL/Java Interoperability 117 of 162

118 Figure 155: Verification of running JC0xJMP Java Message Processing Region 6. Verify the job output of the running Java Message Processing Region. Figure 156: Job output of running Java Message Processing Region 4.5 Test the transaction using a 3270 client Test the transaction For a quick test, the IMS transaction will be tested using a 3270 client. Later during the lab, a J2C Client application will be created, that can also be used to test the IMS transactions from the workspace without logging on to IMS using a 3270 client. 1. At the desktop, double click the Personal Communications icon for the connection to zserveros. Figure 157: Shortcut to zserveros Personal Communications session 2. At the Welcome screen, enter IMSD and use the <STRG> key to send the data to the mainframe. COBOL/Java Interoperability 118 of 162

119 Figure 158: zserveros application selection screen 3. At the IMS Signon Screen, enter your userid and password, again use the <STRG> key to send the data to the mainframe. COBOL/Java Interoperability 119 of 162

120 Figure 159: IMS Signon Screen 4. After successful signon to IMS enter the transaction code (JC0xTRAN) which includes to replace the x with your assigned group number to adhere to the naming conventions, followed by a space and at least one more character which serves as input message to the IMS Java transaction. Figure 160: IMS Transaction code with input data COBOL/Java Interoperability 120 of 162

121 5. Double click the JC0xJMP Job Output to check that the message region is running. A running job will be marked by a slightly different icon than a finished job. Figure 161: IMS Transaction output data 4.6 Check the JAVAOUT and JAVAERR output files 1. Go back to Rational Developer for System z, into the z/os Projects perspective, Remote Systems view at the right hand side and expand z/os Unix Files > My Home. Figure 162: Expanded z/os Unix Files > My Home 2. Double click the JJVM.ERR file to see if there were any errors. Figure 163: JJVM.ERR output file on successful execution COBOL/Java Interoperability 121 of 162

122 3. Double click the JJVM.OUT file to see if there were any errors. Figure 164: JJVM.OUT file on successful execution The IMS Java Transaction with access to IMS DB and DB2 now successfully runs. Task 3 Create COBOL Modules and call them from the IMS Java transaction In this task, you will enhance the existing IMS Java transaction to call a COBOL module that accesses IMS DB and DB2. Lab steps This task contains several programming steps for you to complete. These steps will help to familiarize you with Cobol/Java interoperability. At certain points indicated in the instructions, you will be asked to provide the correct code. For your reference, we have provided the exercise solutions. You can find the code with the exercise solutions from the Package Explorer view by opening COBOLJavaApplicationLab > com.ibm.cjlab.exercise.solution > JC0xJavaCobol.java (as an example for the sample code for JC0xJavaCobol.java) Keep in mind, that most of the screenshot were done using the IMPOT62 userid, so make sure that you use the assigned group id for your lab work. Step 1: Modify COBOL module naming conventions Before the COBOL modules can be compiled, the names of the modules have to be adjusted to make sure that every group runs with its own copies of the modules. COBOL/Java Interoperability 122 of 162

123 1.1 Rename the JC0x modules 1. In the z/os projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.SOURCE Figure 165: Expanded IMPOT6x.CJLAB.SOURCE 2. Rename all the modules that start with JC0x with the x being replaced by your assigned group id. To do the renaming select one module, click the right mouse button and click Rename. Figure 166: Renamed JC0x modules 3. The modules now have been renamed. 1.1 Change the JC0x references in the COBOL source 2. If not already done, in the z/os projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.SOURCE COBOL/Java Interoperability 123 of 162

124 Figure 167: Expanded IMPOT6x.CJLAB.SOURCE 3. Double click the JC0xCOB source and it will open for editing. JC0xCOB This module is pretty much the wrapper between the Java Caller and the traditional COBOL. It is written mixed case and as OO COBOL class. With those attributes, the COBOL compiler is able to create a C-Style shared library, which can be accessed through the Java Native Interface (JNI) to access native code from Java. In addition, the COBOL compiler is also able generate a Java class, which implements the methods of the OO COBOL class, for an easy integration with the Java caller (the main Java transaction you have just written). Figure 168: JC0xCOB Opened for editing. 4. Replace all occurrences of JC0x according the naming conventions such as that x is replaced with your assigned group number (lines 3, 9, 10, 16, 42, 92 and 97). 5. Save the changes. 6. Double click the JC0xKPM source and it will open for editing. JC0xKPM This module is just the wrapper such that JC0xCOB can dynamically call JC0xMAIN. It is required COBOL/Java Interoperability 124 of 162

125 due to the fact, that Java requires lib,dll linkage and traditional COBOL modules like JC0xMAIN are using nodll linkage. z/os Language Environment does not support dynamic calls between DLL and NODLL linked modules. Dynamic calls are only possible on a DLL compiled calls DLL compiled plus NODLL compiled calls NODLL compiled basis. Nethertheless it is possible to statically link DLL and NODLL modules together, so JC0xMAIN has to be compiled first and during linkage of JC0xKPM it will be statically linked with JC0xMAIN. Figure 169: JC0xKPM Opened for editing. 7. Replace all occurrences of JC0x according the naming conventions such as that x is replaced with your assigned group number (lines 3, 27, 29 and 30). 8. Save the changes. 9. Double click the JC0xMAIN source and it will open for editing. JC0xMAIN This module serves as an example for a traditional COBOL application that accesses both IMS DB through the AIB interface and DB2 thru ESAF. It can be run unchanged as an existing module for a traditional COBOL application. COBOL/Java Interoperability 125 of 162

126 Figure 170: JC0xMAIN Opened for editing. 10. Replace all occurrences of JC0x according the naming conventions such as that x is replaced with your assigned group number (line 3). 11. Save the changes. Step 2: Modify Job Control Before the COBOL modules can be compiled, the names of the modules have to be adjusted to make sure that every group runs with its own copies of the modules. 2.1 Change the JC0x and IMPOT6x references in the Job Control 1. In the z/os projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.JCL COBOL/Java Interoperability 126 of 162

127 Figure 171: Expanded IMPOT6x.CJLAB.JCL 2. Double click the JC0xJAVA.jcl and replace all references of x with your assigned group id (lines 1, 12, 33, 36, 49, 53 and 56). 3. Save the changes. 4. Double click the JC0xKPM.jcl and replace all references of x with your assigned group id (lines 1, 12, 33, 35 and 41). 5. Save the changes. 6. Double click the JC0xMAIN.jcl and replace all references of x with your assigned group id (lines 1, 12, 29, 32, 34, 43, 54, 55, 56, 57 and 73). Don t change the suffix x for Output JC0xCob.x, the ending.x is required for the linker to recognize, that it is an export for the methods, that the.so shared library implements. 7. Save the changes. Step 3: Submit Job Control and check for errors Now its time to compile to COBOL modules that should be called. 3.1 Submit the JC0xMAIN.jcl and check for errors JC0xMAIN.jcl This job control is to create the called NODLL COBOL subroutine that used to run called by a COBOL IMS transaction. It will use the DB2 precompiler to filter all EXEC SQL statements in the cobol source and pass it to the cobol compiler and link edit the application with the DFSLI000 and DSNRLI stub, which is required in order to use RRSAF for accessing DB2 using the same connection as the DB2 JDBC COBOL/Java Interoperability 127 of 162

128 Driver in the upper Java layer. 1. If not already done, in the z/os projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.JCL Figure 172: Expanded IMPOT6x.CJLAB.JCL 2. Double click the JC0xMAIN.jcl, click the right mouse button and select Submit. Wait for the Job Submission confirmation. 3. In the remote systems explorer on the right side, expand JES > My Jobs. If it is already expanded, right click My Jobs and select Refresh (or use F5 key while My jobs is selected as an alternative. Figure 173: Expanded JES > My Jobs in the Remote Systems Explorer 4. Double click the JC0xMAIN job output on top of the list to open the job output. COBOL/Java Interoperability 128 of 162

129 Figure 174: JC0xMAIN job output 5. Make sure that the return codes (RC column) are 04 or lower for PROCSTEPS PC, PLKED, LKED and BINDJDBC and 00 for COB and DB2GRANT. 3.2 Submit the JC0xKPM.jcl and check for errors JC0xKPM.jcl This job control is to create the called DLL compiled COBOL subroutine that is linked together with the JC0xMAIN module to allow it dynamically being called by the shared library, which will be created in the next step. 1. If not already done, in the z/os projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.JCL 2. Double click the JC0xKPM.jcl, click the right mouse button and select Submit. Wait for the Job Submission confirmation. 3. In the remote systems explorer on the right side, expand JES > My Jobs. If it is already expanded, right click My Jobs and select Refresh (or use F5 key while My jobs is selected as an alternative. Figure 175: Expanded JES > My Jobs in the Remote Systems Explorer 4. Double click the JC0xKPM job output on top of the list to open the job output. COBOL/Java Interoperability 129 of 162

130 Figure 176: JC0xKPM job output 5. Make sure that the return codes (RC column) are 04 or lower for PROCSTEP PLKED and 00 for PROCSTEPS COBOL and LKED. 3.3 Submit the JC0xJAVA.jcl and check for errors JC0xJAVA.jcl This job control is to create shared library which is called through the Java Native Interface (JNI) out from the OO COBOL source.of JC0xJAVA. The Java class that implements the JNI calls will also be generated by the COBOL compiler. 1. If not already done, in the z/os projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.JCL 2. Double click the JC0xJAVA.jcl, click the right mouse button and select Submit. Wait for the Job Submission confirmation. 3. In the remote systems explorer on the right side, expand JES > My Jobs. If it is already expanded, right click My Jobs and select Refresh (or use F5 key while My jobs is selected as an alternative. Figure 177: Expanded JES > My Jobs in the Remote Systems Explorer 4. Double click the JC0xKPM job output on top of the list to open the job output. COBOL/Java Interoperability 130 of 162

131 Figure 178: JC0xKPM job output 5. Make sure that the return codes (RC column) are 00 for PROCSTEPS COBOL and LKED. Step 4: Copy and adjust the generated Java source The JC0xJAVA.jcl job just generated a Java source file which implements the JNI calls that the shared library that was created by the COBOL compiler, supports. 4.1 Copy the generated Java Source into the Java project 1. In the z/os projects perspective, from the Remote Systems Explorer view, expand dallas > z/os Unix Files > My Home Figure 179: Expanded IMPOT6x.CJLAB.JCL 2. As you can see the JC0xCob.java source file was created, in addition to the libjc02cob.so shared library plus the libjc02cob.x stub file. COBOL/Java Interoperability 131 of 162

132 3. Go to the z/os Project Explorer on the left hand side, select COBOLJavazosproject, click the right mouse button and select New > z/os Unix Subproject. Figure 180: New z/os Unix Subproject menu selection 4. As parent project, select COBOLJavazosproject and click Next. Figure 181: New z/os Unix subproject Wizard 5. As the subproject name enter UNIXSubproject, and for the remote working directory click browse. Figure 182: New z/os Unix subproject Wizard COBOL/Java Interoperability 132 of 162

133 6. Select dallas > z/os UNIX Files > My Home and click OK. Figure 183: Select Remote File System Wizard 7. For Target Environments, check Default Target Environment and click Next. Figure 184: New z/os UNIX Subproject Wizard 8. On the next page, specify UnixFileFilter as the name for the new z/os UNIX File Filter. COBOL/Java Interoperability 133 of 162

134 Figure 185: New z/os UNIX File Filter 9. Click Next. In the new File Filter String Window click Add. 10. Make sure that your home folder /u/impot6x is selected. Figure 186: New File Filter Folder selection 11. Make sure as the file name pattern an asterisks (*) is selected. Figure 187: New File Filter File Name Pattern 12. Click OK. 13. Make sure that the File Filter folder and pattern selection appears in the list. Figure 188: New File Filter File Name Pattern 14. Click Finish. 15. In the z/os Projects Explorer, expand UnixFileFilter and it should list all remote files in your home directory /u/impot6x. COBOL/Java Interoperability 134 of 162

135 Figure 189: Expanded COBOLJavazosproject > UNIXSubproject > UnixFileFilter 16. Switch to the Java Perspective, if not already done expand COBOLJavaApplicationLab > src > com.ibm.cjlab. 17. Select COBOLJavaApplicationLab > src > com.ibm.cjlab, click the right mouse button and in the context menu select Import. 18. In the Import Wizard select Other > Remote file System and click Next. 19. For the From Directory click on Browse, change the connection from Local to dallas, select Root > / > u > impot6x and click OK. 20. Unselect all Files except JC0xCob.java. The Import Remote File System wizard should look like this. COBOL/Java Interoperability 135 of 162

136 Figure 190: Import Remote File System Wizard 21. Click Finish. The file JC0xCob.java should now appear in the Java package explorer. Figure 191: Java Project Explorer with the imported JC0xCob.java file. COBOL/Java Interoperability 136 of 162

137 4.2 Modify the generated Java source 1. In the Java Project Explorer from the Java Perspective, double click COBOLJavaApplicationLab > src > com.ibm.cjlab > JC0xCob.java. Figure 192: JC0xCob.java opened for editing 2. In line 26 (System.loadLibrary) change the Name from com_ibm_cjlab_jc0xcob to JC0xCob. Save the changes. 4.2 Modify the IMS Java transaction source 1. In the Java Project Explorer from the Java Perspective, double click COBOLJavaApplicationLab > src > com.ibm.cjlab > JC0xJavaCobol.java. 2. In the opened editor window, scroll down to the main method right after the dlimethod() call. Line 55. COBOL/Java Interoperability 137 of 162

138 Figure 193: JC0xJavaCobol.java opened for editing 3. Remove all comments (//) in lines 55, 57, 58, 60, 62 and Change CJ0xCob according to your assigned group number. Figure 194: JC0xJavaCobol.java after editing 5. Save the changes. Step 4: Compile the JC0xJavaCobol.java sample application and upload the jar file to the host Before you can execute DL/I calls from your IMS Universal DL/I driver application, you must connect to an IMS database. The connect inside an IMS Java application is done implicit, but it is required to create a connection to the DL/I Database and some other Java objects COBOL/Java Interoperability 138 of 162

139 4.1 Compile the JC0xJavaCobol.java sample 1. Do the same as described in 3.1 Compile the JC0xJavaCobol.java sample at page Upload the jar file to the host 1. Do the same as described in 3.2 Upload the jar file to the host at page 101. Step 5: Restart the IMS Java Message Region, run the sample application and check the output Before we can run the IMS Java transaction that accesses both IMS DB and DB2 and does calls to COBOL, it is required to restart the IMS Java message region we have used so far. 5.1 Change the jcl to restart the IMS Java region 1. Go to the z/os Projects Perspective to the z/os Project Explorer, Expand the CJLAB.JCL dataset and Double click the JC0xSTOP JCL member to adjust the naming conventions according to your group id. Figure 195: Opened JC0xSTOP jcl member in the MVSSubproject of COBOLJavazosproject 2. Replace the x with your assigned group number (line 1, 10). Save the changes. 3. Submit the job. It will stop the currently running IMS region. 4. Submit the JC0xJMP job as described in 4.4 Start the IMS Java Message Region at page Test the transaction using a 3270 client 1. Refer to 4.5 Test the transaction using a 3270 client at page 118 to do that. 2. The output this time will look like this. COBOL/Java Interoperability 139 of 162

140 Figure 196: IMS Transaction output data 5.3 Check the JAVAOUT and JAVAERR output files 1. Check the JAVAOUT and JAVAERR output files as described in Check the JAVAOUT and JAVAERR output files at page 121. The JJVM.ERR file should be empty and JJVM.OUT looks exactly the same as in the sample described earlier. 2. The JC0xJMP job output now has the additional output from COBOL in the joblog. The numbers on top of the job output is the counter that was used to insert records into the temporary DB2 table and the SQL code (should be 0) that was the result of the SQL call. COBOL/Java Interoperability 140 of 162

141 Figure 197: JC0xJMP job output file on successful execution (top) Figure 198: JC0xJMP job output file on successful execution (bottom) 5.4 Test the IMS Java transaction using J2C Bean (Optional) 1. Switch to the Java perspective and go to the Java Project Explorer, expand and select COBOLJavaApplicationLab > src. 2. Click the right mouse button and select menu option New > Package. Figure 199: New package menu selection 3. In the New Java Package Wizard, enter com.ibm.cjlab.client as the package name and click Finish. COBOL/Java Interoperability 141 of 162

142 4. Select the resources package > inputoutputcpy copybook file, click the right mouse button and select menu option New > Other. 5. In the Select a wizard window, scroll down to J2C, expand J2C and select CICS/IMS Java Data Binding. Figure 200: Select the J2C CICS/IMS Java Data Binding Wizard 6. Click Next. In the Data Input Wizard, choose COBOL to Java as the mapping type and make sure that there is the COBOL input file referenced that was selected before clicking the right mouse button. Figure 201: Data Input for CICS/IMS Java Data Binding Wizard 7. Click Next, change the Platform to z/os, click on the Query button and select the 01 structure INPUT-MSG. COBOL/Java Interoperability 142 of 162

143 Figure 202: COBOL Importer Structure Selection 8. Click Next and for the saving properties, make sure that the package name resources is selected. Leave all other values as the have been prefilled. Figure 203: Saving properties 9. Click Finish. The just created INPUTMSG.java should have opened in the editor window. COBOL/Java Interoperability 143 of 162

144 Figure 204: Newly created INPUTMSG.java source 10. Repeat steps 4 thru 9 for the OUTPUTAREA COBOL structure. The just created OUTPUTAREA.java should have opened in the editor window. Figure 205: Newly created OUTPUTAREA.java source 11. Select the com.ibm.cjlab.client package, click the right mouse button and select menu option New > Other. In the appearing Wizard selection window, select J2C > J2C Bean. COBOL/Java Interoperability 144 of 162

145 Figure 206: Select J2C > J2C Bean 12. Click Next. In the Resource Adapter Selection Window, expand IMS TM and select IMS TM Resource Adapter (or higher if available). Figure 207: Resource Adapter Selection 13. Click Next. In the connector import wizard, select Websphere Application Server V7.0, or if not available a lower level version. Figure 208: Connector Import page 14. Click Next. In the Adapter Style Selection page, select Outbound and click Next. 15. In the Scenario Selection page, select IMS COBOL, PL/I or C-based applications and click Next. 16. In the connection properties page uncheck Managed Connection, check Nonmanaged Connection, fill in the host name (e.g. zserveros.dfw.ibm.com), the port number (e.g. 7000), the datastore (e.g. IMSD). COBOL/Java Interoperability 145 of 162

146 Figure 209: Connection properties page 17. Scroll down to the Advanced properties and enter your assigned userid and password. Figure 210: Connection properties Advanced properties 18. Click Next. In the Java Bean Output Properties page, click on Browse and select the package com.ibm.cjlab.client, for the Interface Name type COBOLJavaJ2CBean as the name and the implementation name will automatically filled with COBOLJavaJ2CBeanImpl. COBOL/Java Interoperability 146 of 162

147 Figure 211: Java Bean Output Properties page 19. Click Next. In the Java Methods page, click add. The Add Java Method wizard will open. 20. As the name enter execute, for the input type, click on browse. The empty Select a data type window will appear. Type the first character of the Input Message (which is I) and the INPUTMSG java class will appear. Figure 212: New package menu selection 21. Select INPUTMSG and click OK. 22. Do the same thing for the output message. Click Browse. The empty Select a data type window will appear. Type the first character of the Onput Message (which is O) and the OUTPUTAREA java class will appear. 23. Select OUTPUTMSG and click OK. COBOL/Java Interoperability 147 of 162

148 Figure 213: Add Java Method Wizard 24. Click Finish. Back in the Java Methods page it should now be populated. Click on Advanced. Scroll down and uncheck Use Conversation ID. Figure 214: Unchecked Use conversation ID from the Advanced Properties 25. Click Finish. The bean should now be generated and open in the editor window. 26. Copy the COBOLJavaJ2CTestApp. Expand the solutions folder, select the COBOLJavaJ2CTestApp, click the right mouse button, select copy, select the com.ibm.cjlab.client package, click the right mouse button and select Paste. COBOL/Java Interoperability 148 of 162

149 Figure 215: Copied COBOLJavaJ2CTestApp 27. Next we have to check, if all required libraries are in the classpath of the project workspace. Select COBOLJavaApplicationLab, click the right mouse button and select menu option Properties. 28. Select Java Build Path on the left side and Libraries on the right side. Figure 216: Java Build Path 29. If the WebSphere Application Server runtime is not in the Java Build Path, click on Add Library, Select Server Runtime, click Next and select WebSphere Application Server V7.0 (or an earlier version if not available) and click Finish. 30. Click Finish at the Properties Window to close it and save the changes. 31. Double click the COBOLJavaTestApp.java source file to open it for editing. COBOL/Java Interoperability 149 of 162

150 32. Replace the Trancode JC0xTRAN with the correct trancode according to the naming conventions (your assigned group id). Save the changes. Figure 217: Edited COBOLJavaJ2CTestApp 33. To execute the test application, select COBOLJavaJ2CTestApp.java in the package explorer, click the right mouse button and select Run As > Java Application. 34. There might be a question that there are errors on the workspace, which you can ignore, click Proceed. 35. On successful execution you can see the transaction output in the console view at the bottom of the RD/z window. Figure 218: Console Output on successful invokation Task 4 Create a COBOL Transaction that calls a Java class (optional) In this task, you will compile a COBOL application that accesses IMS DB and DB2, which will then call a Java class that accesses IMS DB and DB2. Lab steps COBOL/Java Interoperability 150 of 162

151 This task contains several programming steps for you to complete. These steps will help to familiarize you with Cobol/Java interoperability. At certain points indicated in the instructions, you will be asked to provide the correct code. For your reference, we have provided the exercise solutions. You can find the code with the exercise solutions from the Package Explorer view by opening COBOLJavaApplicationLab > com.ibm.cjlab.exercise.solution > JC0xJavaCobol.java (as an example for the sample code for JC0xJavaCobol.java) Keep in mind, that most of the screenshot were done using the IMPOT62 userid, so make sure that you use the assigned group id for your lab work. Step 1: Modify the Java source that is being called Rename and change the CJ0xHello.java First the Java class that should be called by COBOL and which accesses IMS and DB2 will have to be changed to reflect naming conventions. 1.1 Rename and change the CJ0xHello.java 1. In the Java perspective, from the Java Project Explorer view, expand COBOLJavaApplicationLab > com.ibm.cjlab 2. Right click JC0xHello.java and select Refactor > Rename. 3. Replace the x in the name with your assigned group id and click Finish. 4. Double click the JC0xHello.java (keep in mind that the x is now replaced with your group id) to open it for editing. 5. Scroll down to line 115 and in the String url for the Connection URL to DB2 replace the USERID with your userid (e.g. IMPOT6x) and password. 6. Save the changes. Step 2: Modify the COBOL source The COBOL sources will have to be changed to reflect naming conventions. 1.2 Rename and change the CJ0x COBOL Source Members 1. In the z/os Projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.SOURCE. 2. Rename all CJ0x Members and replace the x with your assigned group id. 3. Double click the CJ0xJAVA member to open it for editing and replace all occurrences of x with the with your assigned group id (lines 9, 16 and 97). Save the changes. 4. Double click the CJ0xKAPS member to open it for editing and replace all occurrences of x with the with your assigned group id (lines 5, 34, 35 and 36). Save the changes. COBOL/Java Interoperability 151 of 162

152 5. Double click the CJ0xMAIN member to open it for editing and replace all occurrences of x with the with your assigned group id (lines 8 and 91). Save the changes. Step 3: Modify the Job Control for compiling the COBOL source The job control files will have to be changed to reflect naming conventions. 1.3 Change the CJ0x job control Members 1. In the z/os Projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.JCL. 2. Double click the CJ0xJAVA member to open it for editing and replace all occurrences of x with the with your assigned group id (lines 1, 12, 23, 25, 29, 38 and 39). Save the changes. 3. Double click the CJ0xKAPS member to open it for editing and replace all occurrences of x with the with your assigned group id (lines 1, 12, 23, 25, 27 and 32). Save the changes. 4. Double click the CJ0xMAIN member to open it for editing and replace all occurrences of x with the with your assigned group id (lines 1, 12, 51 (two), 54, 56, 68, 69, 80 (two), 82, 83 (two) and 99). Save the changes. 5. Double click the CJ0xSTOP member to open it for editing and replace all occurrences of x with the with your assigned group id (lines 1 and 10). Save the changes. Step 4: Compile the COBOL modules The Job control needs to be submitted in order to compile the COBOL modules. 1.4 Submit the CJ0x job control Members 1. In the z/os Projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.JCL. 2. Right click the CJ0xJAVA member and click Submit. Wait for the job submission confirmation window to appear. Check the job output for the return codes, PROCSTEPs COBOL and LKED should end with RC=00 and PROCSTEP PLKED should end with RC=04 or less. 3. Right click the CJ0xKAPS member and click Submit. Wait for the job submission confirmation window to appear. Check the job output for the return codes, PROCSTEPs COBOL and LKED should end with RC= Right click the CJ0xMAIN member and click Submit. Wait for the job submission confirmation window to appear. Check the job output for the return codes, PROCSTEPs CEEUOPT, COB, LKED, BINDJDBC and DB2GRANT should end with RC=00 and PROCSTEPs PC and PLKED should end with RC=04 or less. COBOL/Java Interoperability 152 of 162

153 Step 5: Change and copy the JVM Property and Environment PROCLIB Members The JVM requires some environmental settings and setup. They are pretty similar to the settings that were used in the Java calls COBOL sample. 1.5 Change the proclib member for the MPP JVM settings 1. In the z/os Projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.PROCLIB. 2. Leave the DFSJVMEV JVM Environment member unchanged, it works with the same settings as for Java calls COBOL. 3. Double click the DFSJVMMC proclib member to open it for editing and replace all occurrences of x with the with your assigned group id (line 8 (two times). Save the changes. 4. Double click the DFSMPR proclib member to open it for editing and replace all occurrences of x with the with your assigned group id (line 31). Save the changes. Step 6: Create the.jar file and copy it to the HFS Home directory The Java class that needs to be called will be picked up from a jar file which needs to be put into your HFS Home Directory. 1.6 Create and copy the jar file 1. In the Java perspective, from the Java Project Explorer view, expand COBOLJavaApplicationLab > scrips. 2. Double click the build_cj0ximsdb2_jar.xml, change all occurrences of x (lines 4 and 5) and save the changes. 3. Select build_cj0ximsdb2_jar.xml, click the right mouse button and Run As > Ant Build. 4. Select the scripts folder and press F5 to refresh it. The CJ0ximsdb2.jar file should now appear in the list. 5. Copy the CJ0ximsdb2.jar file to your HFS Home Directory. Select CJ0ximsdb2.jar, click the right mouse button, select Copy, switch to the z/os projects perspective, go to the Remote Systems Explorer, expand dallas > z/os UNIX Files > My Home, select dallas > z/os UNIX Files > My Home, click the right mouse button and select Paste). Step 7: Modify the IMS MPP region JCL for the COBOL main application and start the region First the Java class that should be called by COBOL and which accesses IMS and DB2 will have to be changed to reflect naming conventions. 1.7 Modify the JCL and start the IMS region 1. In the z/os Projects perspective, from the z/os Projects Explorer view, expand COBOLJavazosproject > MVSSubproject > IMPOT6x.CJLAB.JCL. COBOL/Java Interoperability 153 of 162

154 2. Double click the CJ0xMPP member to open it for editing and replace all occurrences of x with the with your assigned group id (lines 1, 4, 33, 68 und 72). Save the changes. 3. Right click the CJ0xMPP member and click Submit. Wait for the job submission confirmation window to appear. Check the job output that the IMS MPP is running. Step 8: Test the CJ0xTRAN transaction The transaction can now be tried. 1.8 Test the CJ0xTRAN transaction 1. Use either the 3270 client method to call the transaction or use the JC2 client program. (Keep in mind that for the J2C test application, you need to change the transaction code in the Java source from JC0xTRAN to CJ0xTRAN). 2. The output will display one or multiple output segments, depending on the application mode or if there were errors. 3. The PTF for the Persistent JVM in MPP regions (APAR PM00360 V11 or PK82214 V10) is not available yet. Therefor in COBOL calls Java pattern, either the DB2 access or the IMS DB access will work. You can test both cases by either having the -Dcom.ibm.ims.jdbcenvironment=IMS property in the CJ0xENVIMSDB2 environment file uncommented (then DLI will work) or commented (then DB2 will work). The CJ0xMPP region will have to be restarted to apply the changes, CJ0xSTOP can be used to stop the CJ0xMPP region. COBOL/Java Interoperability 154 of 162

155 COBOL/Java Interoperability 155 of 162

156 Resources Learn View the Information Management Software for z/os Solutions Information Center for the latest information and educational resources available for Information Management System (IMS), including the Java API reference for the IMS Universal drivers. Visit the Rational software area on developerworks for technical resources and best practices for Rational Software Delivery Platform products. Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge. Subscribe to the Rational Edge e-zine for articles on the concepts behind effective software development. Check out the Information Management IMS zone on developerworks. Subscribe to the IBM developerworks newsletter, a weekly update on the best of developerworks tutorials, articles, downloads, community activities, webcasts and events. Browse the technology bookstore for books on these and other technical topics. Get products and technologies Download trial versions of IBM Rational software. Download a trial version of IBM Rational Developer for system z. Discuss Participate in the discussion forum. Check out developerworks blogs and get involved in the developerworks community. About the authors Denis Gaebler is an IT Specialist at IBM Richard Tran is a Software Developer at IBM for IMS SOA Solutions Kiran Challapalli is an Advisory Software Developer at IBM for IMS SOA Solutions Evgueni Liakhovitch is a Software Developer at IBM Kevin Hite is a Software Developer at IBM Quddus Chong is an Information Developer at IBM Shahin Mohammadi-Rashedi is an IMS SOA Demonstration Team Lead at IBM COBOL/Java Interoperability 156 of 162

157 COBOL/Java Interoperability 157 of 210

158 DLI Model Utility Lab - Generating IMS DB Metadata Java Class For the IMS Universal DB Drivers you will need the IMS DB Metadata in a Java Class. This class is generated by an Eclipse Plug-in called DLI Model Utility Plug-in and is part of the IMS Enterprise Suite product. It is integrated in the RDz IDE. You will need the sources of the database for the generation. Step 1: Copy the necessary source files 1.5. Switch to the z/os Perspective Switch to the default z/os Projects perspective. Within Eclipse, there are several ways to change perspectives. 7. From the Window menu, select Open Perspective > Other. 8. Scroll down and select z/os Projects from the Open Perspective dialog box Copy the IMS DB Source files. If you don t have the IMS DB source files on your workstation available, you have to download them from the specified path. 1. Open the USS Path in the Remote System View and select the following files. Right click on it and select copy. Paste it to your local directory under Drives C: c:\temp 2. Repeat the previous step for the all files. Step 2: Generate the Metadata file 2.1. Create a new DLI Model Utility Project When you create a new DLI Model Utility Project, the wizard will you lead through all necessary steps. 1. From the Menu select File-> New -> Project and select DLIModel Utility Project. 2. Insert the following values and click Next. Project name: DFSSAM09 Java package: com.ibm.ims.db.databaseviews 158 of 210

159 3. Select your directory which contains the source files. E.g. c:\temp\dfssam09source and select the DFSSAM09.psb file and click Finish. 4. You will see the Model of the Database but there are not all fields defined in the PSB and DBD as this is done in this case by the application Modify the Metadata Class As not all fields are defined in the DBD and PSB, you have to define them whether manually or if you use the DLI Model Utility with RDz you can use the Cobol Copybook Importer to add the fields. 1. Right click somewhere on the View pane and select Import Copybook fields 159 of 210

160 2. Select your path again and select the partroot.cpy file and select the partroot segment and click select. 3. Click Finish. You will see the added fields. 4. As there are 50 bytes in this segments and there are some fields used double, you have to do some corrections - Delete PARTDETAIL, CODE1 and fill_0 by clicking right on these fields and select Delete Field. 5. Repeat the previous steps (Step 1-4) for the STANINFO segment by importing the staninfo.cpy and delete FILLER1,FILLER2,FILLER3 6. Repeat the previous steps (Step 1-3) for the STOCKSTAT, CYCCOUNT, BACKORDR segment by importing the stockstat.cpy, cyccount.cpy, backorder.cpy. 7. Some fields are named differently as they are reserved words in Cobol, we rename them for later easier usage: Rename the AREA1 and UNIT1 to AREA and UNIT (in the STOCKSTAT segment) by right clicking on them and select Edit. Rename the Alias and click okay. 160 of 210

161 8. Finally delete all remaining Filler fields (starting with fill_ ) in all segments. 9. Save the changes by pressing <CTRL> +<S> (or File Save). The Java Class will be updated automatically with your changes Export the Class File as Jar For easier usage you can export the Metadata Java Class file to a JAR File (Java Archive File) 1. In the project Explorer select your java package and right-click -> Export 2. Select Jar File under the Java tab and click Next. 3. Select all resources to export, select Export Java source files and resources and type in the full qualified name of the jar file e.g. C:\temp\DFSSAM09.jar and click Finish. 161 of 210

162 162 of 210

163 Use Data Perspective with IMS Universal JDBC Driver This chapter shows you the possibilities of the IMS Open Database feature for leveraging your existing programs and tools. What is shown in this chapter should also work for other products as the IMS Universal DB drivers are building on open standards like JDBC. They should be compatible with all tools supporting that standard as long as the IMS Universal JDBC driver and the metadata class file are in the application class path available. This solution opens access to IMS data for many available products as well as open source projects. Step 1: Download necessary files You will need the IMS Universal JDBC Driver as well as the Metadata Java Class for the DFSSAM09 Database in IMS. The IMS Universal JDBC Driver is part of the IMS IVP and is mounted in the USS File System. The Metadata Java Class is generated with the help of the IMS Enterprise Suite DLI Model Utility and is already created for you. The Java Classes are packed in JAR files Switch to the z/os Perspective Switch to the default z/os Projects perspective. Within Eclipse, there are several ways to change perspectives. 9. From the Window menu, select Open Perspective > Other. Figure 219: Opening a perspective in Rational Developer for System z 10. Scroll down and select z/os Projects from the Open Perspective dialog box Copy the IMS Universal JDBC Driver and Metadata file. If you don t have the latest driver and the metadata file on your workstation available, you have to download them from the specified path. 3. Open the USS Path in the Remote System View and select the imsudb.jar. Right click on it and select copy. Paste it to your local directory under Drives C: c:\temp 163 of 210

164 4. Repeat the previous step for the DFSSAM09.jar file. Step 2: Configure Rational Developer for System z for using IMS Universal JDBC Driver 2.4. Install IMS Universal Driver You have to add the IMS Universal JDBC Driver as Generic JDBC Driver to the Eclipse workspace in order to use it. 5. From the Menu select Window -> Preferences. 6. In the Menu drill down to Data Management -> Connectivity -> Driver Definitions and select the predefined Generic JDBC 1.0 Driver. Figure 220: Generic JDBC Click on Edit... and switch in the appearing screen to the Jar List tab 8. Click the Add Jar/Zip button and select the imsudb.jar as the IMS Universal Driver on your hard disk under c:\temp 9. Repeat the previous step for the DFSSAM09.jar file which contains the Java Metadata representation of the database we want to access. 164 of 210

165 Figure 221: Jar List of Driver Definition 10. Switch to the Properties tab and click on the... in the Driver Class Value field. 11. Select Browse for class and select com.ibm.ims.jdbc.imsdriver and Click OK. Figure 222: Select Driver Implementation Class 12. You can now specify the Connection URL to jdbc:ims://zserveros.dfw.ibm.com:7001/class://com.ibm.ims.db.databaseviews.dfssam09dat abaseview:datastorename=imsd;dpsboncommit=true; as well as the Database Name and your Default User ID and Click OK and OK again. Now you can use the Data Perspective Switch to the Data Perspective To work with the features of the Data Perspective you have to select it. 10. From the Window menu, select Open Perspective > Other. 11. Scroll down and select Data from the Open Perspective dialog box Create a new Connection in the Data Perspective You have to create a new Connection to your IMS in the Data Perspective. 4. Right-click on Database Connections in the Data Source Explorer and Select New of 210

166 Figure 223: Create New Connection in the Data Perspective 5. Select Generic JDBC in the left list and choose IMS 11 JDBC Driver from the JDBC Driver Drop- Down list. Figure 224: Select IMS 11 JDBC Driver 6. Fill in the necessary information for the correct Database name, Connection URL, User name and Password. a. Database: IMS b. URL: jdbc:ims://<host>:<port>/class:// <package>.<psb>databaseview:datastorename=imsd;dpsboncommit=true; c. Username: IMPOTxx d. Password: your PW 7. Click Finish. Step 3: Using the Data Perspective 3.1. Returning Sample Data through Data Source Explorer After you have now created the connection you can use it now in the further steps. 1. You can drill down and expand the connection until you see the schemas (PCBs), the tables (segments) and columns (fields) 166 of 210

167 Figure 225: View on the Database 2. You can right-click on a table and select Data -> Return All Rows and you will see the Results of the Query in the Result tab on the bottom right. Figure 226: Return all Rows 3.2. Editing Data via the Data Source Explorer It is also possible to edit the data in a tabular form with the Data Source Explorer. 1. Therefore right-click on the PARTROOT table in the Data Source Explorer and select Data -> Edit and you will see the contents of the database in the editor view. Figure 227: Database Editor 2. Change two descriptions in two rows in the PARTDESC column. Therefore click on it and and replace the contents Attention: If you add some data to the end of a description, pay attention that you delete the white characters at the end of each entry, otherwise the update will fail, because the string is too long for the field. 3. When you have edited some values and save the table it will do automatically all updates, inserts and deletes to the IMS Database when you save the editor by pressing <CTRL> + <S> Restriction: Be aware that some columns are virtual foreign key segments and they cannot be updated, because they don t exist in the database. They are just to map the hierarchy order. Normally they have an underscore (_) in its column name. 167 of 210

168 3.3. Creating an Overview Diagram You can also create some overview diagrams for your data with the Data Source Explorer. 1. Therefore select multiple tables (by holding <CTRL>) and right-click and select Add to Overview Diagram and confirm the pop-up with OK. Figure 228: Add to Overview diagram 2. The generated Overview Diagram looks like this and help developers to see the links between the dependencies. Figure 229: Overview diagram 3.4. Working with Data Development Projects If you want to create your own queries, you can use the integrated Data Development Perspective to do this. 1. Therefore Click on File -> New... -> Data Development Project. 2. Specify the Project Name SELECT_ALL1 and click Next. 3. Select your created IMS Data Source IMS and click Finish. Now you will see a new project in the Data Project Explorer. 4. Expand the Project and right click on the SQL Scripts Folder and select New -> SQL or XQuery Script Figure 230: Create new SQL Script 5. You will be asked what type of SQL Script you want to write. Select a single SELECT statement and Click Finish. 168 of 210

169 Figure 231: Create a Select Statement Tip: The Other Option will give you the ability to write several SQL statements separated through a semicolon like a batch job. 6. You can now adding tables by right-clicking on the middle pane and selecting some tables which are in the same schema and hierarchical path for your select statement. You can also specify the Where clauses with the context help of the tool. Figure 232: Add Tables to the select statement 7. You can now save the SQL and right-click it and click Run SQL and you will get the results back. Figure 233: Run Select SQL 169 of 210

170 Figure 234: SQL Results There are a lot of more features you can do with the Data Perspective. There are of course also some functions that right now can t work with the IMS Universal Drivers like a CREATE DB statement. You can play around if you want, e.g. try right click on a table Data Extract. 170 of 210

171 XMLDB Sample This document constitutes an in-depth description of the Purchase Order(IPO) Samples for IMS. It is intended to be used as a narrative while stepping through the instructions in the walk through document. Naming conventions are a little bit difficult for this lab. Group 01 has assigned Userid IMPOT61. So the High Level Qualifier for JCL etc. is IMPOT61, but the PSB Name is IPOPSB01, the Database Name is IPODB01, but the Database High level Qualifier is IMS.IMSD, the Trancode name is IPOPGM01. So for everything that is userid, unix HFS path or High Level Qualifier the xx has to be replaced with the two digit suffix of your userid and everything that is transcode, program name, psb name or dbd name has to be suffixed with the group id The IMS Purchase Order database The sample Purchase Order database is a simple two segment database that stores simple information about a purchaser which each may have any number of dependent segments of information about the individual items being purchased. Each IMS record in the IPO PCB describes an individual purchase order. The database is described by the IPODBD DBD. The application uses only a single PCB view, containing the entire database. The application PSB source is contained in the file IPOPSB. The DBDs and PSBs have already been created. Step 1: Download project interchange and import project You will need the project interchange file IMSDBXMLDBLab.zip Switch to the z/os Perspective Switch to the default z/os Projects perspective. Within Eclipse, there are several ways to change perspectives. 171 of 210

172 11. From the Window menu, select Open Perspective > Other. Figure 235: Opening a perspective in Rational Developer for System z 12. Scroll down and select z/os Projects from the Open Perspective dialog box Copy the Project Interchange file. 5. Open the USS Path /usr/lpp/ims/java/project in the Remote System View and select the IMSDBXMLDBLab.jar. Right click on it and select copy. Paste it to your local directory under Drives C: c:\temp Step 2: Import the project The project must be imported and will be the base of the following work Switch to the Java Perspective Import of a Java project should be done from the Java perspective. 13. Switch to the Java Perspective and find the Java Package explorer Import the project The project has to be imported to the workspace in order to use it. 1. In the Java project explorer, click the right mouse button and select Import. 2. In the Import Wizard, Select Other > Project Interchange 3. For the zip file click on Browse, select the IMSDBXMLDBLab.zip file that was downloaded and stored in Step In the project selection view, check IMSDBXMLDBLab project and click Finish to Import the project into the workspace. 5. Expand src and all other subfolder in the project. 172 of 210

173 Figure 236: Expanded IMSDBXMLDBLab 6. Make sure there are no compiler errors and all Referenced Libraries are in the list. Step 3: Viewing an IMS Database as XML Starting with IMS Version 9, the DLIModel utility is also used to generate an XML Schema based off of a DBD and PCB view of that database. The generated XML Schema creates a mapping between a PCB view of a database and an XML view of that same database. The following IPOPSB-PurchaseOrder.xsd XML Schema is used in this sample. This XML Schema can be viewed as a tree of XML Schema particles as shown here: Figure 237: IPO schema diagram 173 of 210

174 The annotations (which are viewed as comments by XML parsers) align the XML Schema particles with corresponding IMS Segments and Fields. With this mapping defined and in place we can now view an IMS database as an XML Schema and likewise IMS Records as XML documents valid to the corresponding XML Schema. Figure 238: IPO schema and segments 3.1. About the sample applications and what they do There are several sample applications as part of the lab with each of the samples serving a different purpose. In this chapter the classes are described and some sample code is also included to better explain what needs to be done. Sample 1: IPOSeed Seeding the Purchase Order database using XML-DB IMS version 9 introduced IMS XML-DB, allowing the retrieval and storage of XML documents from standard IMS databases by using the provided retrievexml() and storexml() User Defined Functions within an IMS JDBC application. The IPOSeed.java application uses the storexml() UDF to insert three example purchase orders into the sample database: * purchaseorder1.xml * purchaseorder2.xml * purchaseorder3.xml Each of these XML documents is valid (meaning it matches a template for structure and value) to the generated XML Schema IPOPSB-PurchaseOrder.xsd. If an XML document is not valid to the generated XML Schema, an exception is thrown when trying to insert into IMS. 1. Obtaining a Database Connection A database connection is created using the DriverManager interface: 174 of 210

175 // Create a connection Class.forName("com.ibm.ims.db.DLIDriver"); String url = new String("jdbc:dli:demo.IPOPSBDatabaseView"); connection = DriverManager.getConnection(url); Upon calling getconnection() on the DriverManager, the DLIDriver is used to fetch a connection based on the URL prefix jdbc:dli: indicating that this is an IMS Connection and therefore why the DLIDriver must be preloaded with a Class.forName() in order to register itself as handling the jdbc:dli: prefix. The rest of the url: demo.ipopsbdatabaseview indicates where in the classpath to find the metadata describing the database. System.setProperty(" "com/ibm/ims/xmldb/sample"); A System Property is also set, indicating how and where to find the required XML Schema if needed. In this example, the XML Schema generated by the DLIModel utility, must exist as a file named IPOPSB-PurchaseOrder.xsd (the PSB and PCB names are combined into the XML Schema filename: PSB-PCB.xsd). The System property set in the statement above indicates that this file can be found in the demo directory. 2. Emptying the Database To empty the database, the JDBC connection is used to issue the following DELETE SQL call. This call will remove all purchaseorder segments from the PuchaseOrder PCB. Since purchaseorder is the root of the database and no WHERE clause is specified all IMS Records are removed. String query = "DELETE FROM PurchaseOrder.purchaseOrder"; Statement statement = connection.createstatement(); int updates = statement.executeupdate(query); The number of deleted segments are returned and printed to System out. System.out.println(" deleted " + updates + " IMS Records"); 3. Inserting the Seed Documents To seed the database with some initial data, the JDBC connection is again used, however this time we issue an INSERT call to insert segments into the database. The ordernumber key field is defined as well as an XML document defining the rest of the IMS Record (key values are selected arbitrarily in this example). String query = "INSERT INTO PurchaseOrder.purchaseOrder(orderNumber, storexml())" + "VALUES (?,?)"; PreparedStatement pstatement = connection.preparestatement(query); insertdocument(pstatement, " ", "purchaseorder1.xml"); insertdocument(pstatement, " ", "purchaseorder2.xml"); insertdocument(pstatement, " ", "purchaseorder3.xml"); 175 of 210

176 The insertdocument() method sets the preparedvalues (as a CharacterStream in the case of the XML document) and executes the statement. The number of inserted segments is returned and printed to System Out. Finally, the connection is closed, the transaction is committed, and the application ends. Sample 2: IPOQuery Querying IMS as a Virtual XML Database The Virtual XML Garden project, together with IMS XML-DB (supported in IMS Version 9), allows you to query an IMS database as a Virtual XML Database in Java. The IPOQuery.java application uses the Virtual XML Garden runtime to run XQuery expressions against an IMS database visualized as an XML database. The sample runs as a JMP, reading XQuery expressions off the message queue, and returning the result. A database connection is created just as in the POSeed application. getconnection(); XQuery expressions are retrieved from input messages, defined by com.ibm.ims.xmldb.sample.inputmessage, read off the IMS message queue using the IMSMessageQueue class. IMSMessageQueue messagequeue = new IMSMessageQueue(); while (messagequeue.getuniquemessage(inputmessage)) { // Read the query from input message String xquery = inputmessage.getstring("query").trim(); With the desired XQuery expression, we call a runquery() method where we have encapsulated the logic for query evaluation. To fully integrate the Virtual XML code into IMS, the retrievexml() UDF introduced in IMS V9 has been extended to resolve XQuery expressions. The UDF optionally takes the root segment to establish an XML context as described by the IMS V9 XMLDB documentation as well as an XQuery expression. The simplest example of established XML context is a query as follows: SELECT retrievexml() FROM PCB In this simple query, the XML context is established at the PCB level. Adding an XQuery expression to the retrievexml() UDF in this expression allows evaluation over the entire database. This is what our sample does with the passed in XQuery expression. System.out.println("Evaluating: (" + xquery + ")"); // Wrap XQuery expression in simple SQL statement String query = "SELECT retrievexml('" + xquery + "') FROM PurchaseOrder"; Using standard JDBC syntax we next use the established connection to create a statement and execute the constructed XQuery expression. 176 of 210

177 // Create JDBC statement and execute SQL with XQuery Statement statement = connection.createstatement(); ResultSet results = statement.executequery(query); The result is returned as a CLOB (Character Large Object) in the result set. From the CLOB we retrieve a Reader, and read its contents into a CharArrayWriter (this could as easily be into an XSLT transformation, a Web page, SOAP result, etc). It is only upon reading the contents of the CLOB that IMS database calls are issued and the results are generated; only enough of a result is generated to fill the amount we read. In this sense XQuery expressions are evaluated dynamically On Demand rather than all at once. This gives the programmer control over how much output is too much, able to stop the query at anytime. CharArrayWriter outputwriter = new CharArrayWriter(); while (results.next()) { Clob clob = results.getclob(1); Reader reader = clob.getcharacterstream(); char[] buffer = new char[1000]; int read = reader.read(buffer); while (read!= -1) { outputwriter.write(buffer,0,read); read = reader.read(buffer); } } Finally, the outputwriter is converted into a String and returned as the result of the XQuery expression. String result = outputwriter.tostring(); Lastly, the resulting string is inserted into an output message, defined by com.ibm.ims.xmldb.sample.outputmessage, and inserted back onto the IMS message queue. The work done in this transaction is committed using the IMSTransaction class, the connection is closed, and the application ends. // Fill and insert output message outputmessage = new OutputMessage(); outputmessage.setstring("result", result); messagequeue.insertmessage(outputmessage); // Commit work done IMSTransaction.getTransaction().commit(); // Close our connection closeconnection(); Sample 3: IPORetrieve Retrieving the XML documents in the Purchase Order database using XML-DB The IPORetrieve.java application uses the retrievexml() UDF to retrieve all the records in the Purchase Order database and displays the records as XML documents. This application obtains a database connection the same way as it is done in IPOSeed.java. Then it sets up the query statement: 177 of 210

178 String query = "SELECT retrievexml(purchaseorder) FROM PurchaseOrder.purchaseOrder"; Using standard JDBC syntax we next use the established connection to create a statement and execute the constructed XQuery expression. // Create JDBC statement and execute SQL Statement statement = connection.createstatement(); ResultSet results = statement.executequery(query); The result is returned as a CLOB and is processed the same way as it is done in IPOQuery.java. Sample 4: IPOInsertDelete Inserting and deleting an XML document using XML-DB The IPOInsertDelete.java application inserts a new XML document(containing a purchase order) into the existing Purchase Order database and displays all the records from the database as XML documents. It then deletes the newly inserted XML document and re-displays the database. The following query is used where key is a String variable containing the ordernumber of the newly inserted purchase order. String query = "DELETE FROM PurchaseOrder.purchaseOrder WHERE purchaseorder.ordernumber='"+ key +"'"; Statement statement = connection.createstatement(); int updates = statement.executeupdate(query); 3.2. Compile the Java classes 1. Expand the src > sripts folder in the project and select the build_xmldblab_jar.xml file, click the right mouse button and select Run As > Ant Build. 2. Verify the successful execution of the Ant Build. Figure 239: Successful Ant Build execution 3. Select the src > scripts folder and press F5 (or select Refresh from the context menu) to refresh the view and the xmldblab.jar should appear Upload the jar file 178 of 210

179 1. Select the xmldblab.jar file, click the right mouse button and select Copy. 2. Switch to the z/os projects perspective and go to the Remote Systems Explorer. 3. Expand dallas > z/os Unix Files > My Home, select dallas > z/os Unix Files > My Home, click the right mouse button and select Paste. 4. Verify the successful upload of the xmldblab.jar. Step 4: Run the IPOSeed application Before we can run the IMS Java batch job that loads XML documents into an IMS database, it is required to adjust the environment settings, job control, define the transaction, programs and then start the java batch region to execute the sample program. 4.1 Change the settings for the IMS Java Message Region Settings and JCL for the IMS Java Message region The message region for Java programs has to be started, but first its settings have to be changed to suit the needs for your group id (e.g. name, transaction class, etc.) The following steps will be described based on userid IMPOT62, so make sure that you use 6x for all the steps, where x is your assigned group id. 17. Switch to the z/os projects perspective. 18. On the left hand side go to the z/os projects explorer, click the right mouse button and select File -> New -> Project. 19. The new project wizard will open. Select z/os > z/os Project. Figure 240: New z/os Project 20. Click Next and enter IMSXMLDBzosproject as the project name. Make sure the Create an MVS subproject is selected too and click Finish. 179 of 210

180 21. The New MVS Subproject wizard will appear. Enter MVSSubproject as name, Select Do not associate the subproject with a property group and click Finish. Figure 241: MVS subproject name and location Figure 242: MVS subproject property group association 22. Expand the IMSXMLDBzosproject in the project explorer. 23. In the Remote Systems view expand the dallas > MVS Files > My Data Sets (IMPOTxx) view and Select the following dataset: IMPOT6x.XMLDB.JCL 24. Drag the selected files or the whole dataset over to the MVSSubproject. They should then appear under MVSSubproject. 25. Expand the XMLDB.JCL dataset and Double click the DFSJVMAP member to adjust the mapping from the transaction code. 26. Replace the xx with your assigned group number, if you are group 1 replace xx with 01. Save the changes. 27. Double click the DFSJVMMS member to adjust the path environment variables. 28. Replace the x with your assigned group number, if you are group 1 replace x with 1. Save the changes. 29. DFSJVMEV will not be changed. 180 of 210

181 4.2 Create the Transaction Code, Program Name and Database Definition for the XML DB lab by using DRD with the Batch SPOC utility DRD and Batch SPOC Dynamic Resource Definition (DRD) allows the dynamic addition and removal of certain IMS control blocks which used to have been created using IMS System Generations. DRD also provides a batch utility that allows to issue DRD or Type 2 IMS Commands using JCL. This Batch SPOC utility will be used to create the Program Name and the Transaction codes that we are using. The PSBs are already in the ACBLIB to avoid multiple people doing online change at the same time, since currently the online change is still required to activate the new ACBLIB where the new PSB have been added. 9. Expand the XMLDB.JCL dataset and Double click the DEFTRAN jcl member to adjust the naming conventions for the transaction codes and program names. 10. Replace the x or xx with your assigned group number (lines 1, 2, 10, 11, 12 and 13 ). Save the changes. Please note that line 13 requires two changes (remember to also change the x in the CLASS(x) parameters in line 13). 11. Right click the DEFTRAN job control member and click on Submit to execute the JCL. 181 of 210

182 Figure 243: Submit DEFTRAN job control 12. The following window will display the successful submit of the job. Figure 244: Job submission confirmation 13. To view the job output and check successful execution of the job, go to the Remote Systems View on the right hand side, scroll down to JES and expand JES > My Jobs. 182 of 210

183 Figure 245: Expanded JES > My Jobs view 14. To view the job output double click on the first DEFTRAN job output in the list. The job output will open. Figure 246: DEFTRAN Job Output view 183 of 210

184 15. Make sure that the Return code is 00 (check the DEFTRAN row in line 9 column RC). Scroll downwards and for each of the four commands make sure that CC is 0. Figure 247: Job submission confirmation 16. The transaction, program and database is now successfully defined to IMS. The required PSBs have been pre created to avoid the required Online Changes. 4.3 Create the IMS Database for the XML DB Sample Create the IMS DB In order to avoid any hazzles when dealing with the IMS DB creation, everything required e.g. DBRC delete define is done in one job, which needs to be changed to reflect naming conventions. 7. Double click the IPODB0X member from the JCL library. 8. Replace the x or xx with your assigned group number (lines 1, 2, 24, 26, 28, 30, 39, 47, 55, 63, 74, 95, 96, 97, 100 thru 105, 113 thru 115, 123, 125, 128, 136, 141 and 164). Save the changes. Please note, that some lines require more than one change. 9. Right click the IPODB0X JCL member and click Submit. 184 of 210

185 10. The Job submission confirmation window will appear. To view the job output and check successful execution of the job and all job steps, go to the Remote Systems View on the right hand side, scroll down to JES and expand JES > My Jobs. 11. To view the job output double click on the first IPODB0X job output in the list. The job output will open. Figure 248: IPODB0X Job Output 12. Make sure that all Job steps ended with RC = 00, except for the ALLOCATE RC=08 and the ACBGEN RC=04. If the INITRCON recon update step has anything other then 00, the DB likely already exists, so in the JCL there are commented DELETE statements (line 92 and 93) which can be used to fix that. 17. To make sure the DB and the PSB works, start commands for the PSB and the Database will be issued with the next job. 18. Double click the STARTCMD member from the jcl library to open it for editing. 19. Replace the occurrences of xx in line 1 with your userids suffix and replace all occurrences of x with your assigned group id (line 2). Replace the occurrences of xx in lines 10 and 11 with 0 followed by your assigned group id (e.g. if you are group 2 replace xx with 02). Save the changes. 185 of 210

186 20. Right click the STARTCMD job control member and click on Submit to execute the JCL. 21. Make sure that the Job step ended with RC = 00. To look for the job output search for the STRCMDxx job output. Figure 249: STRCMDxx Job Output 4.4 Change the JBP JCL and execute the Java Batch Program The IPOSeed application will be executed as batch, which will actually insert data from XML documents into the database. 7. Double click the DFSJBP proclib member from the JCL library. 8. Replace the x with your assigned group number (line 22). Save the changes. 9. Double click the JBPRUN1 member from the JCL library. 10. Replace the xx (lines 1, 2, 4, 14, 16 and 20) with your assigned group number (such as the 0 is suffixed with your group id, e.g. group 3 should replace xx with 03) and the x in line 11 with your assigned group id. As a reminder in line 14 you have to make two changes. Save the changes. 11. Right click the JBPRUN1 JCL member and click Submit. Through the JCL changes it will be submitted with XMLxxJBP as the jobname. 12. Check for the Job submission confirmation window. 13. Check the job output of the XMLxxJBP job that was just submitted. Go to the Remote Systems Explorer to do that. 186 of 210

187 Figure 250: Refresh JES > My Jobs view in the Remote Systems Explorer 14. Double click the XMLxxJBP Job Output to check for the job output. Figure 251: Job output of the successful executed JBP 4.5 Check the JAVAOUT and JAVAERR output files 4. Go back to Rational Developer for System z, into the z/os Projects perspective, Remote Systems view at the right hand side and expand z/os Unix Files > My Home. 5. Double click the JVM.ERR file to see if there were any errors. 187 of 210

188 Figure 252: JVM.ERR output file on successful execution 6. Double click the JVM.OUT file to see if there were any errors. Figure 253: JVM.OUT file on successful execution The IMS Java Batch Program that inserted XML documents as IMS Data using the decomposed XML feature finished successfully. Step 5: Run the IPOQuery application Before we can run the IMS Java Message program that allows to query XML documents from the IMS database that we created, it is required to adjust the job control and then start the java message region to execute the sample program. 5.1 Change the JCL for the IMS Java Message region The IPOQuery application will be executed as online message program, which will actually query XML documents from the segments in the IMS database. 1. Double click the DFSJMP proclib member from the JCL library. 2. Replace the x with your assigned group number (lines 2 and 25). Save the changes. 3. Double click the DFSJVMMS proclib member from the JCL library. 4. Replace the xx with your assigned group number (such as the 0 is suffixed with your group id, e.g. group 3 should replace xx with 03). 5. In addition the IPOSeed class name has to be changed to IPOQuery in order to execute the XMLDB query program. Save the changes. 188 of 210

189 6. Double click the JMPRUN1 member from the JCL library. 7. Replace the x with your assigned group number (lines 1, 2, 3, 4, 14 and 18). Do not forget to update the password. 8. Save the changes. 9. Right click the JMPRUN1 JCL member and click Submit. With the JCL changes it will be submitted as XMLxxJMP as the jobname. 10. The job submission confirmation will appear. In the Remote Systems explorer expand JES > My Jobs. If it is already expanded, select My Jobs, click the right mouse button and click Refresh (as an alternative the F5 butten can be pressed instead using the context menu option). Figure 254: Refresh JES > My Jobs view in the Remote Systems Explorer 11. Double click the XML6xJMP Job Output to check that the message region is running. A running job will be marked by a slightly different icon than a finished job. Figure 255: Verification of running XML6xJMP Java Message Processing Region 12. Verify the job output of the running Java Message Processing Region. 189 of 210

190 Figure 256: Job output of running Java Message Processing Region 5.2 Test the transaction using a 3270 client Test the transaction For a quick test, the IMS transaction will be tested using a 3270 client. Later during the lab, a J2C Client application can also be used to test the IMS transactions from the workspace without logging on to IMS using a 3270 client. 6. At the desktop, double click the Personal Communications icon for the connection to zserveros/dallas. Figure 257: Shortcut to zserveros Personal Communications session 7. At the Welcome screen, enter IMSD and use the <STRG> key to send the data to the mainframe. 190 of 210

191 Figure 258: zserveros application selection screen 8. At the IMS Signon Screen, enter your userid and password, again use the <STRG> key to send the data to the mainframe. 191 of 210

192 Figure 259: IMS Signon Screen 9. After successful signon to IMS enter the transaction code (IPOPGM0x) which includes to replace the x with your assigned group number to adhere to the naming conventions, followed by a space and at least one more character which serves as input message to the IMS Java transaction. Figure 260: IMS Transaction code with input data 10. Double click the XML6xJMP Job Output to check that the message region is running. A running job will be marked by a slightly different icon than a finished job. 192 of 210

193 Figure 261: IMS Transaction output data The output here will only be a subset of the output, since only the first 80 characters will be displayed at the 3270 screen. a. Check the JAVAOUT and JAVAERR output files 15. Go back to Rational Developer for System z, into the z/os Projects perspective, Remote Systems view at the right hand side and expand z/os Unix Files > My Home. Figure 262: Expanded z/os Unix Files > My Home 16. Double click the JVM.ERR file to see if there were any errors. Figure 263: JVM.ERR output file on successful execution 17. Double click the JVM.OUT file to see if there were any errors. 193 of 210

194 Figure 264: JVM.OUT file on successful execution The IMS Java Transaction with access to IMS DB through the IMS XML DB function runs. Feel free to scroll through JVM.OUT to see to complete output. Appended are some more suggestions on how XQuery can be used with that IOP0xPGM transaction: o IPOPGM0x /purchaseorder o IPOPGM0x for $x in /purchaseorder where $x/@orderdate > '2006' return $x/billto/name o IPOPGM0x <names>{for $x in /purchaseorder return $x/billto/name}</names> o IPOPGM0x for $x in /purchaseorder/items/item return $x o IPOPGM0x <customers>{for $x in /purchaseorder let $y := count($x/items/item) return <customer name="{$x/billto/name/text()}">{$y}</customer>}</customers> o IPOPGM0x <comment>even this is a valid XQuery expression</comment> o IPOPGM0x <calculate>{8+7}</calculate> 194 of 210

195 Use the IMS DB Open Database Driver with Hibernate This chapter shows you the possibilities of the IMS Open Database feature for leveraging your existing databases with Hibernate. Hibernate is a Java Persistence Tool that allows to map objects against databases. Since IMS DB does not support CREATE TABLE or ALTER TABLE statements, this lab shows how to map an existing IMS Database against an object hierarchy. The parts order database will be used for this example. The Parts Order sample database This tutorial uses the Parts Order database that is provided in the IMS Installation Verification Program (IVP). You can refer to this diagram when working on the exercises in this tutorial. The diagram below shows the hierarchical structure of the segments in the Parts Order database. Each rectangle represents a database segment. PARTROOT is the root segment of this database, and STANINFO and STOKSTAT are its child segments. STOKSTAT has CYCCOUNT and BACKORDR as its child segments. Each segment contains one or more fields that contain data. For example, PARTKEY is a field in the PARTROOT segment. Figure 265: Segments of the Parts Order database 195 of 210

196 Step 1: Download project interchange and import project You will need the project interchange file IMSDBHibernateLab.zip Switch to the z/os Perspective Switch to the default z/os Projects perspective. Within Eclipse, there are several ways to change perspectives. 13. From the Window menu, select Open Perspective > Other. 196 of 210

197 Figure 266: Opening a perspective in Rational Developer for System z 14. Scroll down and select z/os Projects from the Open Perspective dialog box Copy the Project Interchange file. 6. Open the USS Path /usr/lpp/ims/java/project in the Remote System View and select the IMSDBHibernateLab.jar. Right click on it and select copy. Paste it to your local directory under Drives C: c:\temp Step 2: Import the project The project must be imported and will be the base of the following work Switch to the Java Perspective Import of a Java project should be done from the Java perspective. 14. Switch to the Java Perspective and find the Java project explorer Import the project The project has to be imported to the workspace in order to use it. 7. In the Java project explorer, click the right mouse button and select Import. 8. In the Import Wizard, Select Other > Project Interchange 9. For the zip file click on Browse, select the IMSDBHibernateLab.zip file that was downloaded and stored in Step In the project selection view, check IMSDBHibernateLab project and click Finish to Import the project into the workspace. 11. Expand src and all other subfolder in the project. 197 of 210

198 Figure 267: Expanded IMSDBHibernateLab 12. Make sure it is imported correctly and all Referenced Libraries are in the list. The project contains compiler errors after the import. Step 3: Basic Hibernate configuration In this step we will configure the hibernate.cfg.xml file which contains information like connection url, jdbc driver to use and userid plus password Configure the JDBC Driver for use with Hibernate 4. Expand the src folder in the project and double click hibernate.cfg.xml to open it for editing. 198 of 210

199 Figure 268: Expanded IMSDBHibernateLab 5. Review the JDBC Connection URL in line 8, that it is complete and contains the correct Port number and hostname. 6. Replace the connection.username with the assigned userid. 7. Review the connection.password. 8. Save the changes Configure the log4j.properties for use with Hibernate 1. Expand the src folder in the project and double click log4j.properties to open it for editing. 199 of 210

200 Figure 269: Expanded IMSDBHibernateLab 2. Since for testing purposes it is very useful to see the SQL that is actually generated by the Hibernate layer, the SQL logging should be turned on. Go to line 19 and change the info value to debug. 3. Save the changes. Step 4: Hibernate mapping Map the IMS Database against an object hierarchy In this step we will do the actual hibernate mapping configuration Review of the IMS Database In order to explain how the hibernate mapping would work for existing IMS databases, the PART database is used as an example. For understanding how it works only the root segment (PARTROOT) and one dependent segment (STOKSTAT) will be reviewed. For all other segments the Java classes and mapping configuration is already completed. 1. Expand the src/samples.ivp.opendb folder in the project and double click DFSSAM09DatabaseView.java to open it for editing. 2. Scroll down such as that both the Java Metadata representation of the PARTROOT and STOKSTAT segment are visible. 200 of 210

201 Figure 270: DFSSAM09DatabaseView.java with PARTROOT and STOKSTAT segment Metadata 3. For the mapping it has to be remembered, that the SQL name for the physical PARTROOT segment is PARTROOT (see line 25 from the DLISegment definition). Furthermore PARTROOT has 3 fields: Keyfield: PARTKEY of type CHARACTER with a length of 17 starting at offset 1 Field: PART of type CHARACTER with a length of 15 starting at offset 3 Field: PARTDESC of type CHARACTER with a length of 20 starting at offset For the mapping it has to be remembered, that the SQL name for the physical STOKSTAT segment is STOKSTAT (see line 45 from the DLISegment definition). Furthermore STOKSTAT has the following fields that we actually code in this lab for the mapping: Keyfield: STOCKEY of type CHARACTER with a length of 16 starting at offset 1 Field: AREA of type CHARACTER with a length of 1 starting at offset 3 Field: DEPT of type CHARACTER with a length of 2 starting at offset 4 Field: PROJ of type CHARACTER with a length of 3 starting at offset 6 For the understanding on how to do the mapping more or all other fields do not matter Create the Java Objects from the DLIDatabaseView Definitions Since Hibernate will generate SQL for the access to IMS DB, the DLIDatabaseView should serve as input to create the Java Objects for mapping the IMS segments into Java objects. The DLIDatabaseView contains the Table and Field Names plus the data type and length definitions that are required to create a working hibernate mapping. Remember that when doing a DL/I call in the key feedback area there is always the keys of the upper level segments (if any). The JDBC Driver implementation creates the exported foreign 201 of 210

202 keys out of it, which can be used to force Hibernate to generate WHERE clauses, that reflect the actual hierarchic sequence and form well performing queries. Currently there is no tooling available to automatically generate the Hibernate classes that are required to be mapped against an existing IMS Database. 1. We have 2 segments, PARTROOT with key PARTKEY and STOKSTAT with key STOCKEY. The COBOL type character is being mapped to the Java type java.lang.string. 2. When accessing in normal DL/I mode, any access to segment STOKSTAT will have both the STOCKEY and the PARTKEY in the key feedback area of the call, such that the application knows what the upper level segments of this given segment is. 3. In order to reflect the key hierarchy, we need two Java objects for the key: a. Partkey class, which has a single data item partkey of type String. b. StocKey class, which inherits Partkey and adds a single data item stockey of type String. In addition to follow hibernate naming conventions the values in the mapping file have to start with a lower case character, whereas the getter and setter method names are expected to start with get or set followed an upper case character. Data item partkey in the part.hbm.xml would have a getter method named getpartkey and a setter method setpartkey. The actual name of the data type in the class definition does not matter, because it can or is only be accessed by the getter and setter methods. 4. So the Definition for the PartKey class should look like this: Figure 271: Definition for the PartKey class 5. Double click the PartKey.java in the com.ibm.ims.hibernate.sample package to open it for editing and replace all occurrences of XXX with the correct names. 6. Please note that the tostring() method is optional, but helpful for debugging output. 7. So the Definition for the StocKey class should look like this: 202 of 210

203 Figure 272: Definition for the StocKey class 8. Double click the StocKey.java in the com.ibm.ims.hibernate.sample package to open it for editing and replace all occurrences of XXX with the correct names. 9. Next thing to do is to map the PARTROOT segment into the Part.java class. There are several ways to do that, the simplest way is to define all the three fields as String types (including the key which for all other segments will use the Java class that implements the key as data type). 10. Double click the Part.java in the com.ibm.ims.hibernate.sample package to open it for editing and make sure that the class Part has getter and setter methods for all the three String data fields named partkey, part and partdesc. If not there, create a getter and a setter method for each of the data items. 203 of 210

204 Figure 273: Definition for the Part class 11. The definition includes a Set that is able to implement the 0-n occurrences of the object instances that map all child segments of a given segment. In case of Part these are the the Sets for the STOKSTAT and the STANINFO segments. 12. Next thing to do is to map the STOKSTAT segment into the StokStat.java class. The key is defined by using the StocKey.java class. All other data items will be defined with their respective Java data types. 13. Double click the StokStat.java in the com.ibm.ims.hibernate.sample package to open it for editing and make sure that the class StokStat has getter and setter methods for the three mentioned String data fields named area, dept and proj. If not there, create a getter and a setter method for each of the data items (feel free to use the context sensitive help move your mouse of one of the data fields e.g. area wait for the context window to appear and select Create a getter and setter method for area the encapsulate field wizard will open and ask for the names and before which of the existing methods the source code for the getter and setter methods should be placed. Then click OK to create the getter and setter methods java source code). 204 of 210

205 Figure 274: Definition for the StokStat class 14. In addition, due to the inheritance of the classes that map the concatenated keys of the IMS segments it is always possible to have a java object that points to the object instance that maps the parent segment. In case of StokStat.java this is the data item part which is right after the STOKSTAT segments Set implementation for the CYCCOUNT and the BACKORDR child segments Edit the part.hbm.xml mapping file Most of the mapping is already precreated. To not make it an editing experience, there are only parts that are required to be changed in the mapping xml. In addition only the mappings for the PARTROOT and STOKSTAT segments have to be edited, all other segments are already finished. The mapping can also be done using annotations. 1. Double click the part.hbm.xml in the com.ibm.ims.hibernate.sample package to open it for editing, scroll down to line number Start with the mapping by replacing the??? with the fully qualified java class name that maps the PARTROOT segment plus the SQL name of the PARTROOT segment. 205 of 210

206 3. In line 24 replace??? with the key field name of the PARTROOT segment. Hint: Open the DFSSAM09DatabaseView.java to look up the field names. 4. In line 31 replace??? with the field name and the data type of the PART field. 5. In line 32 replace??? with the field name and the data type of the PARTDESC field. 6. In line 40 within the mapping definition for the Set that represents the pointer to all STOKSTAT children segments replace??? with the key field name that represents the exported key from the PARTROOT segment (remember that the naming conventions for exported keys are SEGMENT_KEYNAME so for the PARTKEY of the PARTROOT segment it will be PARTROOT_PARTKEY). 7. In line 44 replace??? with the fully qualified class name for the STOKSTAT segment (fully qualified means including the package name). 8. In line 54 within the mapping definition for the Set that represents the pointer to all STANINFO children segments replace??? with the key field name that represents the exported key from the PARTROOT segment (remember that the naming conventions for exported keys are SEGMENT_KEYNAME so for the PARTKEY of the PARTROOT segment it will be PARTROOT_PARTKEY). 9. In line 56 replace??? with the fully qualified class name for the STANINFO segment (fully qualified means including the package name). 10. In line 61 replace the??? with the fully qualified java class name that maps the STOKSTAT segment plus the SQL name of the STOKSTAT segment. 11. In line 70 replace??? within the composite-id which implements the concatenated key stockey with the field name and the data type of the PARTKEY referenced key field from PARTROOT (remember that the naming conventions for exported keys are SEGMENT_KEYNAME so for the PARTKEY of the PARTROOT segment it will be PARTROOT_PARTKEY). 12. In line 71 replace??? within the composite-id which implements the concatenated key stockey with the field name and the data type of the STOCKEY field. 13. In line 76 replace??? with the field name and the data type of the AREA field. 14. In line 77 replace??? with the field name and the data type of the DEPT field. 15. In line 78 replace??? with the field name and the data type of the PROJ field. 16. In line 96 within the mapping definition for the Set that represents the pointer to all CYCCOUNT children segments replace??? with the key field name that represents the exported key from the PARTROOT segment (remember that the naming conventions for exported keys are SEGMENT_KEYNAME so for the PARTKEY of the PARTROOT segment it will be PARTROOT_PARTKEY). 17. In line 97 within the mapping definition for the Set that represents the pointer to all CYCCOUNT children segments replace??? with the key field name that represents the exported key from the STOKSTAT segment (remember that the 206 of 210

207 naming conventions for exported keys are SEGMENT_KEYNAME so for the STOCKEY of the STOKSTAT segment it will be STOKSTAT_PARTKEY). 18. In line 111 for the object references to all BACKORDR child segments replace??? with the fully qualified class name for the BACKORDR segment (fully qualified means including the package name). 19. In line 119 for the object that references the parent segment replace??? with the fully qualified class name for the PARTROOT segment (fully qualified means including the package name). 20. In line 120 within the mapping definition for the object that references the parent segment replace??? with the field name the PARTROOT segment (remember that the naming conventions for exported keys are SEGMENT_KEYNAME so for the PARTKEY of the PARTROOT segment it will be PARTROOT_PARTKEY). 21. Save the changes Change and execute the TestExample.java executable that uses Hibernate calls to access IMS Data and turn it into Java objects The TestExample.java sample programs basically implements 5 different functions: Read one objects from the database, scan through the database, create a new object and persist it to the database, change an object and persist it to the database and finally delete an object. 1. Expand the src folder in the project and double click Example.java to open it for editing. 2. In line 24 check for the code that uses the getobject method to read an object from the part segment. Figure 275: Read object and display key 3. In order to execute the code, right click TestExample.java and click Run As > Java Application. 207 of 210

208 Figure 276: Informational Output for reading the Hibernate Mapping 4. Further down the generated SQL and the System.out.printlns will be displayed. Figure 277: Generated SQL and System.out.println output 5. In order to walk through the whole database, uncomment line 29, save the changes, select TestExample.java, click the right mouse button and select Run As > Java Application. 208 of 210

209 Figure 278: Generated SQL and System.out.println output for database scan 6. Since the walkthrough takes a lot of time, it is recommended to comment line 29 again and continue with the lab. 7. In order to create a new part and persist it, uncomment lines 29 thru 36, lines 38 thru 44 and line In order to update a part and persist it, uncomment lines 49 thru 50 and 52 thru In order to delete a part and persist it, uncomment line Save the changes, select TestExample.java, click the right mouse button and select Run As > Java Application. 209 of 210